groff.texinfo revision 151497
1111314Snyan\input texinfo @c -*-texinfo-*- 2111314Snyan 3111314Snyan@c 4111314Snyan@c Please convert this manual with `texi2dvi -e groff.texinfo' due to 5111314Snyan@c problems in texinfo regarding expansion of user-defined macros. 6111314Snyan@c 7111314Snyan@c You need texinfo 4.6 or newer to format this document! 8111314Snyan@c 9111314Snyan 10111314Snyan@c %**start of header (This is for running Texinfo on a region.) 11@setfilename groff 12@settitle The GNU Troff Manual 13@setchapternewpage odd 14@footnotestyle separate 15@c %**end of header (This is for running Texinfo on a region.) 16 17@documentlanguage en 18@documentencoding ISO-8859-1 19 20 21@smallbook 22 23@finalout 24 25 26@copying 27This manual documents GNU @code{troff} version 1.19.2. 28 29Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005 30Free Software Foundation, Inc. 31 32@quotation 33Permission is granted to copy, distribute and/or modify this document 34under the terms of the GNU Free Documentation License, Version 1.1 or 35any later version published by the Free Software Foundation; with no 36Invariant Sections, with the Front-Cover texts being `A GNU Manual,'' 37and with the Back-Cover Texts as in (a) below. A copy of the 38license is included in the section entitled `GNU Free Documentation 39License.'' 40 41(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify 42this GNU Manual, like GNU software. Copies published by the Free 43Software Foundation raise funds for GNU development.'' 44@end quotation 45@end copying 46 47 48@c We use the following indices: 49@c 50@c cindex: concepts 51@c rqindex: requests 52@c esindex: escapes 53@c vindex: registers 54@c kindex: commands in font files 55@c pindex: programs and files 56@c tindex: environment variables 57@c maindex: macros 58@c stindex: strings 59@c opindex: operators 60@c 61@c tindex and cindex are merged. 62 63@defcodeindex rq 64@defcodeindex es 65@defcodeindex ma 66@defcodeindex st 67@defcodeindex op 68@syncodeindex tp cp 69 70 71@c To avoid uppercasing in @deffn while converting to info, we define 72@c our special @Var{}. 73 74@macro Var{arg} 75@r{@slanted{\arg\}} 76@end macro 77 78 79@c To assure correct HTML translation, some ugly hacks are necessary. 80@c While processing a @def... request, the HTML translator looks at the 81@c next line to decide whether it should start indentation or not. If 82@c it is something starting with @def... (e.g. @deffnx), it doesn't. 83@c So we must assure during macro expansion that a @def... is seen. 84@c 85@c The following macros have to be used: 86@c 87@c One item: 88@c 89@c @Def... 90@c 91@c Two items: 92@c 93@c @Def...List 94@c @Def...ListEnd 95@c 96@c More than two: 97@c 98@c @Def...List 99@c @Def...Item 100@c @Def...Item 101@c ... 102@c @Def...ListEnd 103@c 104@c The definition block must end with 105@c 106@c @endDef... 107@c 108@c The above is valid for texinfo 4.0f and above. 109 110 111@c a dummy macro to assure the `@def...' 112 113@macro defdummy 114@c 115@end macro 116 117 118@c definition of requests 119 120@macro Defreq{name, arg} 121@deffn Request @t{.\name\} \arg\ 122@rqindex \name\ 123@c 124@end macro 125 126@macro DefreqList{name, arg} 127@deffn Request @t{.\name\} \arg\ 128@defdummy 129@rqindex \name\ 130@c 131@end macro 132 133@macro DefreqItem{name, arg} 134@deffnx Request @t{.\name\} \arg\ 135@defdummy 136@rqindex \name\ 137@c 138@end macro 139 140@macro DefreqListEnd{name, arg} 141@deffnx Request @t{.\name\} \arg\ 142@rqindex \name\ 143@c 144@end macro 145 146@macro endDefreq 147@end deffn 148@end macro 149 150 151@c definition of escapes 152 153@macro Defesc{name, delimI, arg, delimII} 154@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 155@esindex \name\ 156@c 157@end macro 158 159@macro DefescList{name, delimI, arg, delimII} 160@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 161@defdummy 162@esindex \name\ 163@c 164@end macro 165 166@macro DefescItem{name, delimI, arg, delimII} 167@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 168@defdummy 169@esindex \name\ 170@c 171@end macro 172 173@macro DefescListEnd{name, delimI, arg, delimII} 174@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 175@esindex \name\ 176@c 177@end macro 178 179@macro endDefesc 180@end deffn 181@end macro 182 183 184@c definition of registers 185 186@macro Defreg{name} 187@deffn Register @t{\\n[\name\]} 188@vindex \name\ 189@c 190@end macro 191 192@macro DefregList{name} 193@deffn Register @t{\\n[\name\]} 194@defdummy 195@vindex \name\ 196@c 197@end macro 198 199@macro DefregItem{name} 200@deffnx Register @t{\\n[\name\]} 201@defdummy 202@vindex \name\ 203@c 204@end macro 205 206@macro DefregListEnd{name} 207@deffnx Register @t{\\n[\name\]} 208@vindex \name\ 209@c 210@end macro 211 212@macro endDefreg 213@end deffn 214@end macro 215 216 217@c definition of registers specific to macro packages, preprocessors, etc. 218 219@macro Defmpreg{name, package} 220@deffn Register @t{\\n[\name\]} 221@vindex \name\ @r{[}\package\@r{]} 222@c 223@end macro 224 225@macro DefmpregList{name, package} 226@deffn Register @t{\\n[\name\]} 227@defdummy 228@vindex \name\ @r{[}\package\@r{]} 229@c 230@end macro 231 232@macro DefmpregItem{name, package} 233@deffnx Register @t{\\n[\name\]} 234@defdummy 235@vindex \name\ @r{[}\package\@r{]} 236@c 237@end macro 238 239@macro DefmpregListEnd{name, package} 240@deffnx Register @t{\\n[\name\]} 241@vindex \name\ @r{[}\package\@r{]} 242@c 243@end macro 244 245@macro endDefmpreg 246@end deffn 247@end macro 248 249 250@c definition of macros 251 252@macro Defmac{name, arg, package} 253@defmac @t{.\name\} \arg\ 254@maindex \name\ @r{[}\package\@r{]} 255@c 256@end macro 257 258@macro DefmacList{name, arg, package} 259@defmac @t{.\name\} \arg\ 260@defdummy 261@maindex \name\ @r{[}\package\@r{]} 262@c 263@end macro 264 265@macro DefmacItem{name, arg, package} 266@defmacx @t{.\name\} \arg\ 267@defdummy 268@maindex \name\ @r{[}\package\@r{]} 269@c 270@end macro 271 272@macro DefmacListEnd{name, arg, package} 273@defmacx @t{.\name\} \arg\ 274@maindex \name\ @r{[}\package\@r{]} 275@c 276@end macro 277 278@macro endDefmac 279@end defmac 280@end macro 281 282 283@c definition of strings 284 285@macro Defstr{name, package} 286@deffn String @t{\\*[\name\]} 287@stindex \name\ @r{[}\package\@r{]} 288@c 289@end macro 290 291@macro DefstrList{name, package} 292@deffn String @t{\\*[\name\]} 293@defdummy 294@stindex \name\ @r{[}\package\@r{]} 295@c 296@end macro 297 298@macro DefstrItem{name, package} 299@deffnx String @t{\\*[\name\]} 300@defdummy 301@stindex \name\ @r{[}\package\@r{]} 302@c 303@end macro 304 305@macro DefstrListEnd{name, package} 306@deffnx String @t{\\*[\name\]} 307@stindex \name\ @r{[}\package\@r{]} 308@c 309@end macro 310 311@macro endDefstr 312@end deffn 313@end macro 314 315 316@c our example macro 317 318@macro Example 319@example 320@group 321@end macro 322 323@macro endExample 324@end group 325@end example 326@end macro 327 328 329@c <text> 330 331@tex 332\gdef\Langlemacro{\angleleft} 333\gdef\Ranglemacro{\angleright} 334@end tex 335 336@iftex 337@set Langlemacro @Langlemacro 338@set Ranglemacro @Ranglemacro 339@end iftex 340 341@ifnottex 342@set Langlemacro < 343@set Ranglemacro > 344@end ifnottex 345 346@macro angles{text} 347@value{Langlemacro}@r{\text\}@value{Ranglemacro} 348@end macro 349 350 351@c a <= sign 352@c 353@c A value defined with @set is embedded into three group levels if 354@c called with @value, so we need seven \aftergroup to put \le outside 355@c of the groups -- this is necessary to get proper mathematical spacing. 356 357@tex 358\gdef\LEmacro{\aftergroup\aftergroup\aftergroup\aftergroup 359 \aftergroup\aftergroup\aftergroup\le} 360@end tex 361 362@iftex 363@set LEmacro @LEmacro 364@end iftex 365 366@ifnottex 367@set LEmacro <= 368@end ifnottex 369 370@macro LE 371@value{LEmacro} 372@end macro 373 374 375@c We need special parentheses, brackets, and braces: 376@c 377@c . Real parentheses in @deffn produce an error while compiling with 378@c TeX. 379@c . Real brackets use the wrong font in @deffn, overriding @t{}. 380@c 381@c . @{ and @} fail with info if used in a macro. 382@c 383@c Since macros aren't expanded in @deffn during -E, the following 384@c definitions are for non-TeX only. 385@c 386@c This is true for texinfo 4.0 and above. 387 388@iftex 389@set Lparenmacro @lparen 390@set Rparenmacro @rparen 391@set Lbrackmacro @lbrack 392@set Rbrackmacro @rbrack 393@set Lbracemacro @{ 394@set Rbracemacro @} 395@end iftex 396 397@ifnottex 398@set Lparenmacro ( 399@set Rparenmacro ) 400@set Lbrackmacro [ 401@set Rbrackmacro ] 402@set Lbracemacro @{ 403@set Rbracemacro @} 404@end ifnottex 405 406@macro Lparen{} 407@value{Lparenmacro} 408@end macro 409@macro Rparen{} 410@value{Rparenmacro} 411@end macro 412@macro Lbrack{} 413@value{Lbrackmacro} 414@end macro 415@macro Rbrack{} 416@value{Rbrackmacro} 417@end macro 418@macro Lbrace{} 419@value{Lbracemacro} 420@end macro 421@macro Rbrace{} 422@value{Rbracemacro} 423@end macro 424 425 426@c This suppresses the word `Appendix' in the appendix headers. 427 428@tex 429\gdef\gobblefirst#1#2{#2} 430\gdef\putwordAppendix{\gobblefirst} 431@end tex 432 433 434@c We map some latin-1 characters to corresponding texinfo macros. 435 436@tex 437\global\catcode`^^e4\active % � 438\gdef^^e4{\"a} 439\global\catcode`^^c4\active % � 440\gdef^^c4{\"A} 441\global\catcode`^^e9\active % � 442\gdef^^e9{\'e} 443\global\catcode`^^c9\active % � 444\gdef^^c9{\'E} 445\global\catcode`^^f6\active % � 446\gdef^^f6{\"o} 447\global\catcode`^^d6\active % � 448\gdef^^d6{\"O} 449\global\catcode`^^fc\active % � 450\gdef^^fc{\"u} 451\global\catcode`^^dc\active % � 452\gdef^^dc{\"U} 453\global\catcode`^^e6\active % � 454\gdef^^e6{\ae} 455\global\catcode`^^c6\active % � 456\gdef^^c6{\AE} 457\global\catcode`^^df\active % � 458\gdef^^df{\ss} 459@end tex 460 461 462@c Note: We say `Roman numerals' but `roman font'. 463 464 465@dircategory Typesetting 466@direntry 467* Groff: (groff). The GNU troff document formatting system. 468@end direntry 469 470 471@titlepage 472@title groff 473@subtitle The GNU implementation of @code{troff} 474@subtitle Edition 1.19.2 475@subtitle Summer 2005 476@author by Trent A.@tie{}Fisher 477@author and Werner Lemberg (@email{bug-groff@@gnu.org}) 478 479@page 480@vskip 0pt plus 1filll 481@insertcopying 482@end titlepage 483 484 485@contents 486 487@ifinfo 488@node Top, Introduction, (dir), (dir) 489@top GNU troff 490 491@insertcopying 492@end ifinfo 493 494@ifhtml 495@menu 496* Introduction:: 497* Invoking groff:: 498* Tutorial for Macro Users:: 499* Macro Packages:: 500* gtroff Reference:: 501* Preprocessors:: 502* Output Devices:: 503* File formats:: 504* Installation:: 505* Copying This Manual:: 506* Request Index:: 507* Escape Index:: 508* Operator Index:: 509* Register Index:: 510* Macro Index:: 511* String Index:: 512* Glyph Name Index:: 513* Font File Keyword Index:: 514* Program and File Index:: 515* Concept Index:: 516@end menu 517 518@node Top, Introduction, (dir), (dir) 519@top GNU troff 520 521@insertcopying 522@end ifhtml 523 524@menu 525* Introduction:: 526* Invoking groff:: 527* Tutorial for Macro Users:: 528* Macro Packages:: 529* gtroff Reference:: 530* Preprocessors:: 531* Output Devices:: 532* File formats:: 533* Installation:: 534* Copying This Manual:: 535* Request Index:: 536* Escape Index:: 537* Operator Index:: 538* Register Index:: 539* Macro Index:: 540* String Index:: 541* Glyph Name Index:: 542* Font File Keyword Index:: 543* Program and File Index:: 544* Concept Index:: 545@end menu 546 547 548 549@c ===================================================================== 550@c ===================================================================== 551 552@node Introduction, Invoking groff, Top, Top 553@chapter Introduction 554@cindex introduction 555 556GNU @code{troff} (or @code{groff}) is a system for typesetting 557documents. @code{troff} is very flexible and has been in existence (and 558use) for about 3@tie{}decades. It is quite widespread and firmly 559entrenched in the @acronym{UNIX} community. 560 561@menu 562* What Is groff?:: 563* History:: 564* groff Capabilities:: 565* Macro Package Intro:: 566* Preprocessor Intro:: 567* Output device intro:: 568* Credits:: 569@end menu 570 571 572@c ===================================================================== 573 574@node What Is groff?, History, Introduction, Introduction 575@section What Is @code{groff}? 576@cindex what is @code{groff}? 577@cindex @code{groff} -- what is it? 578 579@code{groff} belongs to an older generation of document preparation 580systems, which operate more like compilers than the more recent 581interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 582systems. @code{groff} and its contemporary counterpart, @TeX{}, both 583work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 584normal text files with embedded formatting commands. These files can 585then be processed by @code{groff} to produce a typeset document on a 586variety of devices. 587 588Likewise, @code{groff} should not be confused with a @dfn{word 589processor}, since that term connotes an integrated system that includes 590an editor and a text formatter. Also, many word processors follow the 591@acronym{WYSIWYG} paradigm discussed earlier. 592 593Although @acronym{WYSIWYG} systems may be easier to use, they have a 594number of disadvantages compared to @code{troff}: 595 596@itemize @bullet 597@item 598They must be used on a graphics display to work on a document. 599 600@item 601Most of the @acronym{WYSIWYG} systems are either non-free or are not 602very portable. 603 604@item 605@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 606 607@item 608It is difficult to have a wide range of capabilities available within 609the confines of a GUI/window system. 610 611@item 612It is more difficult to make global changes to a document. 613@end itemize 614 615@quotation 616``GUIs normally make it simple to accomplish simple actions and 617impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 618@code{comp.unix.wizards}) 619@end quotation 620 621 622@c ===================================================================== 623 624@node History, groff Capabilities, What Is groff?, Introduction 625@section History 626@cindex history 627 628@cindex @code{runoff}, the program 629@cindex @code{rf}, the program 630@code{troff} can trace its origins back to a formatting program called 631@code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS 632operating system in the mid-sixties. This name came from the common 633phrase of the time ``I'll run off a document.'' Bob Morris ported it to 634the 635 architecture and called the program @code{roff} (an abbreviation 635of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 636(before having @acronym{UNIX}), and at the same time (1969), Doug 637McIllroy rewrote an extended and simplified version of @code{roff} in 638the @acronym{BCPL} programming language. 639 640@cindex @code{roff}, the program 641The first version of @acronym{UNIX} was developed on a @w{PDP-7} which 642was sitting around Bell Labs. In 1971 the developers wanted to get a 643@w{PDP-11} for further work on the operating system. In order to 644justify the cost for this system, they proposed that they would 645implement a document formatting system for the @acronym{AT&T} patents 646division. This first formatting program was a reimplementation of 647McIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna. 648 649@cindex @code{nroff}, the program 650When they needed a more flexible language, a new version of @code{roff} 651called @code{nroff} (``Newer @code{roff}'') was written. It had a much 652more complicated syntax, but provided the basis for all future versions. 653When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 654version of @code{nroff} that would drive it. It was dubbed 655@code{troff}, for ``typesetter @code{roff}'', although many people have 656speculated that it actually means ``Times @code{roff}'' because of the 657use of the Times font family in @code{troff} by default. As such, the 658name @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 659 660With @code{troff} came @code{nroff} (they were actually the same program 661except for some @samp{#ifdef}s), which was for producing output for line 662printers and character terminals. It understood everything @code{troff} 663did, and ignored the commands which were not applicable (e.g.@: font 664changes). 665 666Since there are several things which cannot be done easily in 667@code{troff}, work on several preprocessors began. These programs would 668transform certain parts of a document into @code{troff}, which made a 669very natural use of pipes in @acronym{UNIX}. 670 671The @code{eqn} preprocessor allowed mathematical formul� to be 672specified in a much simpler and more intuitive manner. @code{tbl} is a 673preprocessor for formatting tables. The @code{refer} preprocessor (and 674the similar program, @code{bib}) processes citations in a document 675according to a bibliographic database. 676 677Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 678language and produced output specifically for the CAT phototypesetter. 679He rewrote it in C, although it was now 7000@tie{}lines of uncommented 680code and still dependent on the CAT. As the CAT became less common, and 681was no longer supported by the manufacturer, the need to make it support 682other devices became a priority. However, before this could be done, 683Ossanna was killed in a car accident. 684 685@pindex ditroff 686@cindex @code{ditroff}, the program 687So, Brian Kernighan took on the task of rewriting @code{troff}. The 688newly rewritten version produced device independent code which was 689very easy for postprocessors to read and translate to the appropriate 690printer codes. Also, this new version of @code{troff} (called 691@code{ditroff} for ``device independent @code{troff}'') had several 692extensions, which included drawing functions. 693 694Due to the additional abilities of the new version of @code{troff}, 695several new preprocessors appeared. The @code{pic} preprocessor 696provides a wide range of drawing functions. Likewise the @code{ideal} 697preprocessor did the same, although via a much different paradigm. The 698@code{grap} preprocessor took specifications for graphs, but, unlike 699other preprocessors, produced @code{pic} code. 700 701James Clark began work on a GNU implementation of @code{ditroff} in 702early@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released 703June@tie{}1990. @code{groff} included: 704 705@itemize @bullet 706@item 707A replacement for @code{ditroff} with many extensions. 708 709@item 710The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 711 712@item 713Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 714X@tie{}Windows. GNU @code{troff} also eliminated the need for a 715separate @code{nroff} program with a postprocessor which would produce 716@acronym{ASCII} output. 717 718@item 719A version of the @file{me} macros and an implementation of the 720@file{man} macros. 721@end itemize 722 723Also, a front-end was included which could construct the, sometimes 724painfully long, pipelines required for all the post- and preprocessors. 725 726Development of GNU @code{troff} progressed rapidly, and saw the 727additions of a replacement for @code{refer}, an implementation of the 728@file{ms} and @file{mm} macros, and a program to deduce how to format a 729document (@code{grog}). 730 731It was declared a stable (i.e.@: non-beta) package with the release of 732version@tie{}1.04 around November@tie{}1991. 733 734Beginning in@tie{}1999, @code{groff} has new maintainers (the package was 735an orphan for a few years). As a result, new features and programs like 736@code{grn}, a preprocessor for gremlin images, and an output device to 737produce @acronym{HTML} output have been added. 738 739 740@c ===================================================================== 741 742@node groff Capabilities, Macro Package Intro, History, Introduction 743@section @code{groff} Capabilities 744@cindex @code{groff} capabilities 745@cindex capabilities of @code{groff} 746 747So what exactly is @code{groff} capable of doing? @code{groff} provides 748a wide range of low-level text formatting operations. Using these, it 749is possible to perform a wide range of formatting tasks, such as 750footnotes, table of contents, multiple columns, etc. Here's a list of 751the most important operations supported by @code{groff}: 752 753@itemize @bullet 754@item 755text filling, adjusting, and centering 756 757@item 758hyphenation 759 760@item 761page control 762 763@item 764font and glyph size control 765 766@item 767vertical spacing (e.g.@: double-spacing) 768 769@item 770line length and indenting 771 772@item 773macros, strings, diversions, and traps 774 775@item 776number registers 777 778@item 779tabs, leaders, and fields 780 781@item 782input and output conventions and character translation 783 784@item 785overstrike, bracket, line drawing, and zero-width functions 786 787@item 788local horizontal and vertical motions and the width function 789 790@item 791three-part titles 792 793@item 794output line numbering 795 796@item 797conditional acceptance of input 798 799@item 800environment switching 801 802@item 803insertions from the standard input 804 805@item 806input/output file switching 807 808@item 809output and error messages 810@end itemize 811 812 813@c ===================================================================== 814 815@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 816@section Macro Packages 817@cindex macro packages 818 819Since @code{groff} provides such low-level facilities, it can be quite 820difficult to use by itself. However, @code{groff} provides a 821@dfn{macro} facility to specify how certain routine operations 822(e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@: 823should be done. These macros can be collected together into a @dfn{macro 824package}. There are a number of macro packages available; the most 825common (and the ones described in this manual) are @file{man}, 826@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 827 828 829@c ===================================================================== 830 831@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 832@section Preprocessors 833@cindex preprocessors 834 835Although @code{groff} provides most functions needed to format a 836document, some operations would be unwieldy (e.g.@: to draw pictures). 837Therefore, programs called @dfn{preprocessors} were written which 838understand their own language and produce the necessary @code{groff} 839operations. These preprocessors are able to differentiate their own 840input from the rest of the document via markers. 841 842To use a preprocessor, @acronym{UNIX} pipes are used to feed the output 843from the preprocessor into @code{groff}. Any number of preprocessors 844may be used on a given document; in this case, the preprocessors are 845linked together into one pipeline. However, with @code{groff}, the user 846does not need to construct the pipe, but only tell @code{groff} what 847preprocessors to use. 848 849@code{groff} currently has preprocessors for producing tables 850(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 851(@code{pic} and @code{grn}), and for processing bibliographies 852(@code{refer}). An associated program which is useful when dealing with 853preprocessors is @code{soelim}. 854 855A free implementation of @code{grap}, a preprocessor for drawing graphs, 856can be obtained as an extra package; @code{groff} can use @code{grap} 857also. 858 859There are other preprocessors in existence, but, unfortunately, no free 860implementations are available. Among them are preprocessors for drawing 861mathematical pictures (@code{ideal}) and chemical structures 862(@code{chem}). 863 864 865@c ===================================================================== 866 867@node Output device intro, Credits, Preprocessor Intro, Introduction 868@section Output Devices 869@cindex postprocessors 870@cindex output devices 871@cindex devices for output 872 873@code{groff} actually produces device independent code which may be 874fed into a postprocessor to produce output for a particular device. 875Currently, @code{groff} has postprocessors for @sc{PostScript} 876devices, character terminals, X@tie{}Windows (for previewing), @TeX{} 877DVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use 878@acronym{CAPSL}), and @acronym{HTML}. 879 880 881@c ===================================================================== 882 883@node Credits, , Output device intro, Introduction 884@section Credits 885@cindex credits 886 887Large portions of this manual were taken from existing documents, most 888notably, the manual pages for the @code{groff} package by James Clark, 889and Eric Allman's papers on the @file{me} macro package. 890 891The section on the @file{man} macro package is partly based on 892Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the 893Debian GNU/Linux system. 894 895Larry Kollar contributed the section in the @file{ms} macro package. 896 897 898 899@c ===================================================================== 900@c ===================================================================== 901 902@node Invoking groff, Tutorial for Macro Users, Introduction, Top 903@chapter Invoking @code{groff} 904@cindex invoking @code{groff} 905@cindex @code{groff} invocation 906 907This section focuses on how to invoke the @code{groff} front end. This 908front end takes care of the details of constructing the pipeline among 909the preprocessors, @code{gtroff} and the postprocessor. 910 911It has become a tradition that GNU programs get the prefix @samp{g} to 912distinguish it from its original counterparts provided by the host (see 913@ref{Environment}, for more details). Thus, for example, @code{geqn} is 914GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which 915don't contain proprietary versions of @code{troff}, and on 916MS-DOS/MS-Windows, where @code{troff} and associated programs are not 917available at all, this prefix is omitted since GNU @code{troff} is the 918only used incarnation of @code{troff}. Exception: @samp{groff} is never 919replaced by @samp{roff}. 920 921In this document, we consequently say @samp{gtroff} when talking about 922the GNU @code{troff} program. All other implementations of @code{troff} 923are called @acronym{AT&T} @code{troff} which is the common origin of 924all @code{troff} derivates (with more or less compatible changes). 925Similarly, we say @samp{gpic}, @samp{geqn}, etc. 926 927@menu 928* Groff Options:: 929* Environment:: 930* Macro Directories:: 931* Font Directories:: 932* Paper Size:: 933* Invocation Examples:: 934@end menu 935 936 937@c ===================================================================== 938 939@node Groff Options, Environment, Invoking groff, Invoking groff 940@section Options 941@cindex options 942 943@pindex groff 944@pindex gtroff 945@pindex gpic 946@pindex geqn 947@pindex ggrn 948@pindex grap 949@pindex gtbl 950@pindex grefer 951@pindex gsoelim 952@code{groff} normally runs the @code{gtroff} program and a postprocessor 953appropriate for the selected device. The default device is @samp{ps} 954(but it can be changed when @code{groff} is configured and built). It 955can optionally preprocess with any of @code{gpic}, @code{geqn}, 956@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 957 958This section only documents options to the @code{groff} front end. Many 959of the arguments to @code{groff} are passed on to @code{gtroff}, 960therefore those are also included. Arguments to pre- or postprocessors 961can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 962gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 963gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 964grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 965grolbp}, and @ref{Invoking gxditview}. 966 967The command line format for @code{groff} is: 968 969@Example 970groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 971 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 972 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 973 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 974 [ @var{files}@dots{} ] 975@endExample 976 977The command line format for @code{gtroff} is as follows. 978 979@Example 980gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 981 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 982 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 983 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 984@endExample 985 986@noindent 987Obviously, many of the options to @code{groff} are actually passed on to 988@code{gtroff}. 989 990Options without an argument can be grouped behind a single@tie{}@option{-}. 991A filename of@tie{}@file{-} denotes the standard input. It is possible to 992have whitespace between an option and its parameter. 993 994The @code{grog} command can be used to guess the correct @code{groff} 995command to format a file. 996 997Here's the description of the command-line options: 998 999@cindex command-line options 1000@table @samp 1001@item -h 1002Print a help message. 1003 1004@item -e 1005Preprocess with @code{geqn}. 1006 1007@item -t 1008Preprocess with @code{gtbl}. 1009 1010@item -g 1011Preprocess with @code{ggrn}. 1012 1013@item -G 1014Preprocess with @code{grap}. 1015 1016@item -p 1017Preprocess with @code{gpic}. 1018 1019@item -s 1020Preprocess with @code{gsoelim}. 1021 1022@item -c 1023Suppress color output. 1024 1025@item -R 1026Preprocess with @code{grefer}. No mechanism is provided for passing 1027arguments to @code{grefer} because most @code{grefer} options have 1028equivalent commands which can be included in the file. @xref{grefer}, 1029for more details. 1030 1031@pindex troffrc 1032@pindex troffrc-end 1033Note that @code{gtroff} also accepts a @option{-R} option, which is not 1034accessible via @code{groff}. This option prevents the loading of the 1035@file{troffrc} and @file{troffrc-end} files. 1036 1037@item -v 1038Make programs run by @code{groff} print out their version number. 1039 1040@item -V 1041Print the pipeline on @code{stdout} instead of executing it. If specified 1042more than once, print the pipeline on @code{stderr} and execute it. 1043 1044@item -z 1045Suppress output from @code{gtroff}. Only error messages are printed. 1046 1047@item -Z 1048Do not postprocess the output of @code{gtroff}. Normally @code{groff} 1049automatically runs the appropriate postprocessor. 1050 1051@item -P@var{arg} 1052Pass @var{arg} to the postprocessor. Each argument should be passed 1053with a separate @option{-P} option. Note that @code{groff} does not 1054prepend @samp{-} to @var{arg} before passing it to the postprocessor. 1055 1056@item -l 1057Send the output to a spooler for printing. The command used for this is 1058specified by the @code{print} command in the device description file 1059(see @ref{Font Files}, for more info). If not present, @option{-l} is 1060ignored. 1061 1062@item -L@var{arg} 1063Pass @var{arg} to the spooler. Each argument should be passed with a 1064separate @option{-L} option. Note that @code{groff} does not prepend 1065a @samp{-} to @var{arg} before passing it to the postprocessor. 1066If the @code{print} keyword in the device description file is missing, 1067@option{-L} is ignored. 1068 1069@item -T@var{dev} 1070Prepare output for device @var{dev}. The default device is @samp{ps}, 1071unless changed when @code{groff} was configured and built. The 1072following are the output devices currently available: 1073 1074@table @code 1075@item ps 1076For @sc{PostScript} printers and previewers. 1077 1078@item dvi 1079For @TeX{} DVI format. 1080 1081@item X75 1082For a 75@dmn{dpi} X11 previewer. 1083 1084@item X75-12 1085For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 1086document. 1087 1088@item X100 1089For a 100@dmn{dpi} X11 previewer. 1090 1091@item X100-12 1092For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 1093document. 1094 1095@item ascii 1096@cindex encoding, output, @acronym{ASCII} 1097@cindex @acronym{ASCII}, output encoding 1098@cindex output encoding, @acronym{ASCII} 1099For typewriter-like devices using the (7-bit) @acronym{ASCII} 1100character set. 1101 1102@item latin1 1103@cindex encoding, output, @w{latin-1} (ISO @w{8859-1}) 1104@cindex @w{latin-1} (ISO @w{8859-1}), output encoding 1105@cindex ISO @w{8859-1} (@w{latin-1}), output encoding 1106@cindex output encoding, @w{latin-1} (ISO @w{8859-1}) 1107For typewriter-like devices that support the @w{Latin-1} 1108(ISO@tie{}@w{8859-1}) character set. 1109 1110@item utf8 1111@cindex encoding, output, @w{utf-8} 1112@cindex @w{utf-8}, output encoding 1113@cindex output encoding, @w{utf-8} 1114For typewriter-like devices which use the Unicode (ISO@tie{}10646) 1115character set with @w{UTF-8} encoding. 1116 1117@item cp1047 1118@cindex encoding, output, @acronym{EBCDIC} 1119@cindex @acronym{EBCDIC}, output encoding 1120@cindex output encoding, @acronym{EBCDIC} 1121@cindex encoding, output, cp1047 1122@cindex cp1047, output encoding 1123@cindex output encoding, cp1047 1124@cindex IBM cp1047 output encoding 1125For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 1126cp1047. 1127 1128@item lj4 1129For HP LaserJet4-compatible (or other PCL5-compatible) printers. 1130 1131@item lbp 1132For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 1133printers). 1134 1135@pindex pre-grohtml 1136@pindex post-grohtml 1137@cindex @code{grohtml}, the program 1138@item html 1139To produce @acronym{HTML} output. Note that the @acronym{HTML} driver 1140consists of two parts, a preprocessor (@code{pre-grohtml}) and a 1141postprocessor (@code{post-grohtml}). 1142@end table 1143 1144@cindex output device name string register (@code{.T}) 1145@cindex output device usage number register (@code{.T}) 1146The predefined @code{gtroff} string register @code{.T} contains the 1147current output device; the read-only number register @code{.T} is set 1148to@tie{}1 if this option is used (which is always true if @code{groff} is 1149used to call @code{gtroff}). @xref{Built-in Registers}. 1150 1151The postprocessor to be used for a device is specified by the 1152@code{postpro} command in the device description file. (@xref{Font 1153Files}, for more info.) This can be overridden with the @option{-X} 1154option. 1155 1156@item -X 1157Preview with @code{gxditview} instead of using the usual postprocessor. 1158This is unlikely to produce good results except with @option{-Tps}. 1159 1160Note that this is not the same as using @option{-TX75} or 1161@option{-TX100} to view a document with @code{gxditview}: The former 1162uses the metrics of the specified device, whereas the latter uses 1163X-specific fonts and metrics. 1164 1165@item -N 1166Don't allow newlines with @code{eqn} delimiters. This is the same as 1167the @option{-N} option in @code{geqn}. 1168 1169@item -S 1170@cindex @code{open} request, and safer mode 1171@cindex @code{opena} request, and safer mode 1172@cindex @code{pso} request, and safer mode 1173@cindex @code{sy} request, and safer mode 1174@cindex @code{pi} request, and safer mode 1175@cindex safer mode 1176@cindex mode, safer 1177Safer mode. Pass the @option{-S} option to @code{gpic} and disable the 1178@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 1179requests. For security reasons, this is enabled by default. 1180 1181@item -U 1182@cindex mode, unsafe 1183@cindex unsafe mode 1184Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso}, 1185@code{sy}, and @code{pi} requests. 1186 1187@item -a 1188@cindex @acronym{ASCII} approximation output register (@code{.A}) 1189Generate an @acronym{ASCII} approximation of the typeset output. The 1190read-only register @code{.A} is then set to@tie{}1. @xref{Built-in 1191Registers}. A typical example is 1192 1193@Example 1194groff -a -man -Tdvi troff.man | less 1195@endExample 1196 1197@noindent 1198which shows how lines are broken for the DVI device. Note that this 1199option is rather useless today since graphic output devices are 1200available virtually everywhere. 1201 1202@item -b 1203Print a backtrace with each warning or error message. This backtrace 1204should help track down the cause of the error. The line numbers given 1205in the backtrace may not always be correct: @code{gtroff} can get 1206confused by @code{as} or @code{am} requests while counting line numbers. 1207 1208@item -i 1209Read the standard input after all the named input files have been 1210processed. 1211 1212@item -w@var{name} 1213Enable warning @var{name}. Available warnings are described in 1214@ref{Debugging}. Multiple @option{-w} options are allowed. 1215 1216@item -W@var{name} 1217Inhibit warning @var{name}. Multiple @option{-W} options are allowed. 1218 1219@item -E 1220Inhibit all error messages. 1221 1222@item -C 1223Enable compatibility mode. @xref{Implementation Differences}, for the 1224list of incompatibilities between @code{groff} and @acronym{AT&T} 1225@code{troff}. 1226 1227@item -d@var{c}@var{s} 1228@itemx -d@var{name}=@var{s} 1229Define @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must 1230be a one-letter name; @var{name} can be of arbitrary length. All string 1231assignments happen before loading any macro file (including the start-up 1232file). 1233 1234@item -f@var{fam} 1235Use @var{fam} as the default font family. @xref{Font Families}. 1236 1237@item -m@var{name} 1238Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches 1239for this in its macro directories. If it isn't found, it tries 1240@file{tmac.@var{name}} (searching in the same directories). 1241 1242@item -n@var{num} 1243Number the first page @var{num}. 1244 1245@item -o@var{list} 1246@cindex print current page register (@code{.P}) 1247Output only pages in @var{list}, which is a comma-separated list of page 1248ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}} 1249means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}} 1250means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every 1251page beginning with@tie{}@var{n}. @code{gtroff} exits after printing the 1252last page in the list. All the ranges are inclusive on both ends. 1253 1254Within @code{gtroff}, this information can be extracted with the 1255@samp{.P} register. @xref{Built-in Registers}. 1256 1257If your document restarts page numbering at the beginning of each 1258chapter, then @code{gtroff} prints the specified page range for each 1259chapter. 1260 1261@item -r@var{c}@var{n} 1262@itemx -r@var{name}=@var{n} 1263Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}. 1264@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary 1265length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All 1266register assignments happen before loading any macro file (including 1267the start-up file). 1268 1269@item -F@var{dir} 1270Search @file{@var{dir}} for subdirectories @file{dev@var{name}} 1271(@var{name} is the name of the device), for the @file{DESC} file, and 1272for font files before looking in the standard directories (@pxref{Font 1273Directories}). This option is passed to all pre- and postprocessors 1274using the @env{GROFF_FONT_PATH} environment variable. 1275 1276@item -M@var{dir} 1277Search directory @file{@var{dir}} for macro files before the standard 1278directories (@pxref{Macro Directories}). 1279 1280@item -I@var{dir} 1281This option may be used to specify a directory to search for files. 1282It is passed to the following programs: 1283 1284@itemize 1285@item 1286@code{gsoelim} (see @ref{gsoelim} for more details); 1287it also implies @code{groff}'s @option{-s} option. 1288 1289@item 1290@code{gtroff}; it is used to search files named in the @code{psbb} and 1291@code{so} requests. 1292 1293@item 1294@code{grops}; it is used to search files named in the 1295@w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes. 1296@end itemize 1297 1298The current directory is always searched first. This option may be specified 1299more than once; the directories will be searched in the order specified. No 1300directory search is performed for files specified using an absolute path. 1301@end table 1302 1303 1304@c ===================================================================== 1305 1306@node Environment, Macro Directories, Groff Options, Invoking groff 1307@section Environment 1308@cindex environment variables 1309@cindex variables in environment 1310 1311There are also several environment variables (of the operating system, 1312not within @code{gtroff}) which can modify the behavior of @code{groff}. 1313 1314@table @code 1315@item GROFF_COMMAND_PREFIX 1316@tindex GROFF_COMMAND_PREFIX@r{, environment variable} 1317@cindex command prefix 1318@cindex prefix, for commands 1319If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff} 1320instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 1321@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 1322apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 1323@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 1324 1325The default command prefix is determined during the installation process. 1326If a non-GNU troff system is found, prefix @samp{g} is used, none 1327otherwise. 1328 1329@item GROFF_TMAC_PATH 1330@tindex GROFF_TMAC_PATH@r{, environment variable} 1331A colon-separated list of directories in which to search for macro files 1332(before the default directories are tried). @xref{Macro Directories}. 1333 1334@item GROFF_TYPESETTER 1335@tindex GROFF_TYPESETTER@r{, environment variable} 1336The default output device. 1337 1338@item GROFF_FONT_PATH 1339@tindex GROFF_FONT_PATH@r{, environment variable} 1340A colon-separated list of directories in which to search for the 1341@code{dev}@var{name} directory (before the default directories are 1342tried). @xref{Font Directories}. 1343 1344@item GROFF_BIN_PATH 1345@tindex GROFF_BIN_PATH@r{, environment variable} 1346This search path, followed by @code{PATH}, is used for commands executed 1347by @code{groff}. 1348 1349@item GROFF_TMPDIR 1350@tindex GROFF_TMPDIR@r{, environment variable} 1351@tindex TMPDIR@r{, environment variable} 1352The directory in which @code{groff} creates temporary files. If this is 1353not set and @env{TMPDIR} is set, temporary files are created in that 1354directory. Otherwise temporary files are created in a system-dependent 1355default directory (on Unix and GNU/Linux systems, this is usually 1356@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 1357@code{post-grohtml} can create temporary files in this directory. 1358@end table 1359 1360Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 1361rather than colons, to separate the directories in the lists described 1362above. 1363 1364 1365@c ===================================================================== 1366 1367@node Macro Directories, Font Directories, Environment, Invoking groff 1368@section Macro Directories 1369@cindex macro directories 1370@cindex directories for macros 1371@cindex searching macros 1372@cindex macros, searching 1373 1374All macro file names must be named @code{@var{name}.tmac} or 1375@code{tmac.@var{name}} to make the @option{-m@var{name}} command line 1376option work. The @code{mso} request doesn't have this restriction; any 1377file name can be used, and @code{gtroff} won't try to append or prepend 1378the @samp{tmac} string. 1379 1380@cindex tmac, directory 1381@cindex directory, for tmac files 1382@cindex tmac, path 1383@cindex path, for tmac files 1384@cindex searching macro files 1385@cindex macro files, searching 1386@cindex files, macro, searching 1387Macro files are kept in the @dfn{tmac directories}, all of which 1388constitute the @dfn{tmac path}. The elements of the search path for 1389macro files are (in that order): 1390 1391@itemize @bullet 1392@item 1393The directories specified with @code{gtroff}'s or @code{groff}'s 1394@option{-M} command line option. 1395 1396@item 1397@tindex GROFF_TMAC_PATH@r{, environment variable} 1398The directories given in the @env{GROFF_TMAC_PATH} environment 1399variable. 1400 1401@item 1402@cindex safer mode 1403@cindex mode, safer 1404@cindex unsafe mode 1405@cindex mode, unsafe 1406@cindex current directory 1407@cindex directory, current 1408The current directory (only if in unsafe mode using the @option{-U} 1409command line switch). 1410 1411@item 1412@cindex home directory 1413@cindex directory, home 1414The home directory. 1415 1416@item 1417@cindex site-specific directory 1418@cindex directory, site-specific 1419@cindex platform-specific directory 1420@cindex directory, platform-specific 1421A platform-dependent directory, a site-specific (platform-independent) 1422directory, and the main tmac directory; the default locations are 1423 1424@Example 1425/usr/local/lib/groff/site-tmac 1426/usr/local/share/groff/site-tmac 1427/usr/local/share/groff/1.18.2/tmac 1428@endExample 1429 1430@noindent 1431assuming that the version of @code{groff} is 1.18.2, and the installation 1432prefix was @file{/usr/local}. It is possible to fine-tune those 1433directories during the installation process. 1434@end itemize 1435 1436 1437@c ===================================================================== 1438 1439@node Font Directories, Paper Size, Macro Directories, Invoking groff 1440@section Font Directories 1441@cindex font directories 1442@cindex directories for fonts 1443@cindex searching fonts 1444@cindex fonts, searching 1445 1446Basically, there is no restriction how font files for @code{groff} are 1447named and how long font names are; however, to make the font family 1448mechanism work (@pxref{Font Families}), fonts within a family should 1449start with the family name, followed by the shape. For example, the 1450Times family uses @samp{T} for the family name and @samp{R}, @samp{B}, 1451@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold', 1452`italic', and `bold italic', respectively. Thus the final font names 1453are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}. 1454 1455@cindex font path 1456@cindex path, for font files 1457All font files are kept in the @dfn{font directories} which constitute 1458the @dfn{font path}. The file search functions will always append the 1459directory @code{dev}@var{name}, where @var{name} is the name of the 1460output device. Assuming, say, DVI output, and @file{/foo/bar} as a 1461font directory, the font files for @code{grodvi} must be in 1462@file{/foo/bar/devdvi}. 1463 1464The elements of the search path for font files are (in that order): 1465 1466@itemize @bullet 1467@item 1468The directories specified with @code{gtroff}'s or @code{groff}'s 1469@option{-F} command line option. All device drivers and some 1470preprocessors also have this option. 1471 1472@item 1473@tindex GROFF_FONT_PATH@r{, environment variable} 1474The directories given in the @env{GROFF_FONT_PATH} environment 1475variable. 1476 1477@item 1478@cindex site-specific directory 1479@cindex directory, site-specific 1480A site-specific directory and the main font directory; the default 1481locations are 1482 1483@Example 1484/usr/local/share/groff/site-font 1485/usr/local/share/groff/1.18.2/font 1486@endExample 1487 1488@noindent 1489assuming that the version of @code{groff} is 1.18.2, and the installation 1490prefix was @file{/usr/local}. It is possible to fine-tune those 1491directories during the installation process. 1492@end itemize 1493 1494 1495@c ===================================================================== 1496 1497@node Paper Size, Invocation Examples, Font Directories, Invoking groff 1498@section Paper Size 1499@cindex paper size 1500@cindex size, paper 1501@cindex landscape page orientation 1502@cindex orientation, landscape 1503@cindex page orientation, landscape 1504 1505In groff, the page size for @code{gtroff} and for output devices are 1506handled separately. @xref{Page Layout}, for vertical manipulation of 1507the page size. @xref{Line Layout}, for horizontal changes. 1508 1509A default paper size can be set in the device's @file{DESC} file. Most 1510output devices also have a command line option @option{-p} to override 1511the default paper size and option @option{-l} to use landscape 1512orientation. @xref{DESC File Format}, for a description of the 1513@code{papersize} keyword which takes the same argument as @option{-p}. 1514 1515@pindex papersize.tmac 1516@pindex troffrc 1517A convenient shorthand to set a particular paper size for @code{gtroff} 1518is command line option @option{-dpaper=@var{size}}. This defines string 1519@code{paper} which is processed in file @file{papersize.tmac} (loaded in 1520the start-up file @file{troffrc} by default). Possible values for 1521@var{size} are the same as the predefined values for the 1522@code{papersize} keyword (but only in lowercase) except 1523@code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes 1524landscape orientation. 1525 1526For example, use the following for PS output on A4 paper in landscape 1527orientation: 1528 1529@Example 1530groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps 1531@endExample 1532 1533Note that it is up to the particular macro package to respect default 1534page dimensions set in this way (most do). 1535 1536 1537@c ===================================================================== 1538 1539@node Invocation Examples, , Paper Size, Invoking groff 1540@section Invocation Examples 1541@cindex invocation examples 1542@cindex examples of invocation 1543 1544This section lists several common uses of @code{groff} and the 1545corresponding command lines. 1546 1547@Example 1548groff file 1549@endExample 1550 1551@noindent 1552This command processes @file{file} without a macro package or a 1553preprocessor. The output device is the default, @samp{ps}, and the 1554output is sent to @code{stdout}. 1555 1556@Example 1557groff -t -mandoc -Tascii file | less 1558@endExample 1559 1560@noindent 1561This is basically what a call to the @code{man} program does. 1562@code{gtroff} processes the manual page @file{file} with the 1563@file{mandoc} macro file (which in turn either calls the @file{man} or 1564the @file{mdoc} macro package), using the @code{tbl} preprocessor and 1565the @acronym{ASCII} output device. Finally, the @code{less} pager 1566displays the result. 1567 1568@Example 1569groff -X -m me file 1570@endExample 1571 1572@noindent 1573Preview @file{file} with @code{gxditview}, using the @file{me} macro 1574package. Since no @option{-T} option is specified, use the default 1575device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 1576@w{@samp{-me}}; the latter is an anachronism from the early days of 1577@acronym{UNIX}.@footnote{The same is true for the other main macro 1578packages that come with @code{groff}: @file{man}, @file{mdoc}, 1579@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 1580for example, to load @file{trace.tmac}, either @samp{-mtrace} or 1581@w{@samp{-m trace}} must be used.} 1582 1583@Example 1584groff -man -rD1 -z file 1585@endExample 1586 1587@noindent 1588Check @file{file} with the @file{man} macro package, forcing 1589double-sided printing -- don't produce any output. 1590 1591@menu 1592* grog:: 1593@end menu 1594 1595@c --------------------------------------------------------------------- 1596 1597@node grog, , Invocation Examples, Invocation Examples 1598@subsection @code{grog} 1599 1600@pindex grog 1601@code{grog} reads files, guesses which of the @code{groff} preprocessors 1602and/or macro packages are required for formatting them, and prints the 1603@code{groff} command including those options on the standard output. It 1604generates one or more of the options @option{-e}, @option{-man}, 1605@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc}, 1606@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 1607@option{-s}, and @option{-t}. 1608 1609A special file name@tie{}@file{-} refers to the standard input. Specifying 1610no files also means to read the standard input. Any specified options 1611are included in the printed command. No space is allowed between 1612options and their arguments. The only options recognized are 1613@option{-C} (which is also passed on) to enable compatibility mode, and 1614@option{-v} to print the version number and exit. 1615 1616For example, 1617 1618@Example 1619grog -Tdvi paper.ms 1620@endExample 1621 1622@noindent 1623guesses the appropriate command to print @file{paper.ms} and then prints 1624it to the command line after adding the @option{-Tdvi} option. For 1625direct execution, enclose the call to @code{grog} in backquotes at the 1626@acronym{UNIX} shell prompt: 1627 1628@Example 1629`grog -Tdvi paper.ms` > paper.dvi 1630@endExample 1631 1632@noindent 1633As seen in the example, it is still necessary to redirect the output to 1634something meaningful (i.e.@: either a file or a pager program like 1635@code{less}). 1636 1637 1638 1639@c ===================================================================== 1640@c ===================================================================== 1641 1642@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 1643@chapter Tutorial for Macro Users 1644@cindex tutorial for macro users 1645@cindex macros, tutorial for users 1646@cindex user's tutorial for macros 1647@cindex user's macro tutorial 1648 1649Most users tend to use a macro package to format their papers. This 1650means that the whole breadth of @code{groff} is not necessary for most 1651people. This chapter covers the material needed to efficiently use a 1652macro package. 1653 1654@menu 1655* Basics:: 1656* Common Features:: 1657@end menu 1658 1659 1660@c ===================================================================== 1661 1662@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 1663@section Basics 1664@cindex basics of macros 1665@cindex macro basics 1666 1667This section covers some of the basic concepts necessary to understand 1668how to use a macro package.@footnote{This section is derived from 1669@cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.} 1670References are made throughout to more detailed information, if desired. 1671 1672@code{gtroff} reads an input file prepared by the user and outputs a 1673formatted document suitable for publication or framing. The input 1674consists of text, or words to be printed, and embedded commands 1675(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 1676format the output. For more detail on this, see @ref{Embedded 1677Commands}. 1678 1679The word @dfn{argument} is used in this chapter to mean a word or number 1680which appears on the same line as a request, and which modifies the 1681meaning of that request. For example, the request 1682 1683@Example 1684.sp 1685@endExample 1686 1687@noindent 1688spaces one line, but 1689 1690@Example 1691.sp 4 1692@endExample 1693 1694@noindent 1695spaces four lines. The number@tie{}4 is an argument to the @code{sp} 1696request which says to space four lines instead of one. Arguments are 1697separated from the request and from each other by spaces (@emph{no} 1698tabs). More details on this can be found in @ref{Request and Macro 1699Arguments}. 1700 1701The primary function of @code{gtroff} is to collect words from input 1702lines, fill output lines with those words, justify the right-hand margin 1703by inserting extra spaces in the line, and output the result. For 1704example, the input: 1705 1706@Example 1707Now is the time 1708for all good men 1709to come to the aid 1710of their party. 1711Four score and seven 1712years ago, etc. 1713@endExample 1714 1715@noindent 1716is read, packed onto output lines, and justified to produce: 1717 1718@quotation 1719Now is the time for all good men to come to the aid of their party. 1720Four score and seven years ago, etc. 1721@end quotation 1722 1723@cindex break 1724@cindex line break 1725Sometimes a new output line should be started even though the current 1726line is not yet full; for example, at the end of a paragraph. To do 1727this it is possible to cause a @dfn{break}, which starts a new output 1728line. Some requests cause a break automatically, as normally do blank 1729input lines and input lines beginning with a space. 1730 1731Not all input lines are text to be formatted. Some input lines are 1732requests which describe how to format the text. Requests always have a 1733period (@samp{.}) or an apostrophe (@samp{'}) as the first character of 1734the input line. 1735 1736The text formatter also does more complex things, such as automatically 1737numbering pages, skipping over page boundaries, putting footnotes in the 1738correct place, and so forth. 1739 1740Here are a few hints for preparing text for input to @code{gtroff}. 1741 1742@itemize @bullet 1743@item 1744First, keep the input lines short. Short input lines are easier to 1745edit, and @code{gtroff} packs words onto longer lines anyhow. 1746 1747@item 1748In keeping with this, it is helpful to begin a new line after every 1749comma or phrase, since common corrections are to add or delete sentences 1750or phrases. 1751 1752@item 1753End each sentence with two spaces -- or better, start each sentence on a 1754new line. @code{gtroff} recognizes characters that usually end a 1755sentence, and inserts sentence space accordingly. 1756 1757@item 1758Do not hyphenate words at the end of lines -- @code{gtroff} is smart 1759enough to hyphenate words as needed, but is not smart enough to take 1760hyphens out and join a word back together. Also, words such as 1761``mother-in-law'' should not be broken over a line, since then a space 1762can occur where not wanted, such as ``@w{mother- in}-law''. 1763@end itemize 1764 1765@cindex double-spacing (@code{ls}) 1766@cindex spacing 1767@code{gtroff} double-spaces output text automatically if you use the 1768request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing 1769@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the 1770vertical space, use the @code{pvs} request (@pxref{Changing Type 1771Sizes}).} 1772 1773A number of requests allow to change the way the output looks, 1774sometimes called the @dfn{layout} of the output page. Most of these 1775requests adjust the placing of @dfn{whitespace} (blank lines or 1776spaces). 1777 1778@cindex new page (@code{bp}) 1779The @code{bp} request starts a new page, causing a line break. 1780 1781@cindex blank line (@code{sp}) 1782@cindex empty line (@code{sp}) 1783@cindex line, empty (@code{sp}) 1784The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank 1785space. @var{N}@tie{}can be omitted (meaning skip a single line) or can 1786be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for 1787@var{N}@tie{}centimeters). For example, the input: 1788 1789@Example 1790.sp 1.5i 1791My thoughts on the subject 1792.sp 1793@endExample 1794 1795@noindent 1796leaves one and a half inches of space, followed by the line ``My 1797thoughts on the subject'', followed by a single blank line (more 1798measurement units are available, see @ref{Measurements}). 1799 1800@cindex centering lines (@code{ce}) 1801@cindex lines, centering (@code{ce}) 1802Text lines can be centered by using the @code{ce} request. The line 1803after @code{ce} is centered (horizontally) on the page. To center more 1804than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number 1805of lines to center), followed by the @var{N}@tie{}lines. To center many 1806lines without counting them, type: 1807 1808@Example 1809.ce 1000 1810lines to center 1811.ce 0 1812@endExample 1813 1814@noindent 1815The @w{@samp{.ce 0}} request tells @code{groff} to center zero more 1816lines, in other words, stop centering. 1817 1818@cindex line break (@code{br}) 1819@cindex break (@code{br}) 1820All of these requests cause a break; that is, they always start a new 1821line. To start a new line without performing any other action, use 1822@code{br}. 1823 1824 1825@c ===================================================================== 1826 1827@node Common Features, , Basics, Tutorial for Macro Users 1828@section Common Features 1829@cindex common features 1830@cindex features, common 1831 1832@code{gtroff} provides very low-level operations for formatting a 1833document. There are many common routine operations which are done in 1834all documents. These common operations are written into @dfn{macros} 1835and collected into a @dfn{macro package}. 1836 1837All macro packages provide certain common capabilities which fall into 1838the following categories. 1839 1840@menu 1841* Paragraphs:: 1842* Sections and Chapters:: 1843* Headers and Footers:: 1844* Page Layout Adjustment:: 1845* Displays:: 1846* Footnotes and Annotations:: 1847* Table of Contents:: 1848* Indices:: 1849* Paper Formats:: 1850* Multiple Columns:: 1851* Font and Size Changes:: 1852* Predefined Strings:: 1853* Preprocessor Support:: 1854* Configuration and Customization:: 1855@end menu 1856 1857@c --------------------------------------------------------------------- 1858 1859@node Paragraphs, Sections and Chapters, Common Features, Common Features 1860@subsection Paragraphs 1861@cindex paragraphs 1862 1863One of the most common and most used capability is starting a 1864paragraph. There are a number of different types of paragraphs, any 1865of which can be initiated with macros supplied by the macro package. 1866Normally, paragraphs start with a blank line and the first line 1867indented, like the text in this manual. There are also block style 1868paragraphs, which omit the indentation: 1869 1870@Example 1871Some men look at constitutions with sanctimonious 1872reverence, and deem them like the ark of the covenant, too 1873sacred to be touched. 1874@endExample 1875 1876@noindent 1877And there are also indented paragraphs which begin with a tag or label 1878at the margin and the remaining text indented. 1879 1880@Example 1881one This is the first paragraph. Notice how the first 1882 line of the resulting paragraph lines up with the 1883 other lines in the paragraph. 1884@endExample 1885@Example 1886longlabel 1887 This paragraph had a long label. The first 1888 character of text on the first line does not line up 1889 with the text on second and subsequent lines, 1890 although they line up with each other. 1891@endExample 1892 1893A variation of this is a bulleted list. 1894 1895@Example 1896. Bulleted lists start with a bullet. It is possible 1897 to use other glyphs instead of the bullet. In nroff 1898 mode using the ASCII character set for output, a dot 1899 is used instead of a real bullet. 1900@endExample 1901 1902@c --------------------------------------------------------------------- 1903 1904@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features 1905@subsection Sections and Chapters 1906 1907Most macro packages supply some form of section headers. The simplest 1908kind is simply the heading on a line by itself in bold type. Others 1909supply automatically numbered section heading or different heading 1910styles at different levels. Some, more sophisticated, macro packages 1911supply macros for starting chapters and appendices. 1912 1913@c --------------------------------------------------------------------- 1914 1915@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features 1916@subsection Headers and Footers 1917 1918Every macro package gives some way to manipulate the @dfn{headers} and 1919@dfn{footers} (also called @dfn{titles}) on each page. This is text 1920put at the top and bottom of each page, respectively, which contain 1921data like the current page number, the current chapter title, and so 1922on. Its appearance is not affected by the running text. Some packages 1923allow for different ones on the even and odd pages (for material printed 1924in a book form). 1925 1926The titles are called @dfn{three-part titles}, that is, there is a 1927left-justified part, a centered part, and a right-justified part. An 1928automatically generated page number may be put in any of these fields 1929with the @samp{%} character (see @ref{Page Layout}, for more details). 1930 1931@c --------------------------------------------------------------------- 1932 1933@node Page Layout Adjustment, Displays, Headers and Footers, Common Features 1934@subsection Page Layout 1935 1936Most macro packages let the user specify top and bottom margins and 1937other details about the appearance of the printed pages. 1938 1939@c --------------------------------------------------------------------- 1940 1941@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features 1942@subsection Displays 1943@cindex displays 1944 1945@dfn{Displays} are sections of text to be set off from the body of 1946the paper. Major quotes, tables, and figures are types of displays, as 1947are all the examples used in this document. 1948 1949@cindex quotes, major 1950@cindex major quotes 1951@dfn{Major quotes} are quotes which are several lines long, and hence 1952are set in from the rest of the text without quote marks around them. 1953 1954@cindex list 1955A @dfn{list} is an indented, single-spaced, unfilled display. Lists 1956should be used when the material to be printed should not be filled and 1957justified like normal text, such as columns of figures or the examples 1958used in this paper. 1959 1960@cindex keep 1961A @dfn{keep} is a display of lines which are kept on a single page if 1962possible. An example for a keep might be a diagram. Keeps differ from 1963lists in that lists may be broken over a page boundary whereas keeps are 1964not. 1965 1966@cindex keep, floating 1967@cindex floating keep 1968@dfn{Floating keeps} move relative to the text. Hence, they are good for 1969things which are referred to by name, such as ``See figure@tie{}3''. A 1970floating keep appears at the bottom of the current page if it fits; 1971otherwise, it appears at the top of the next page. Meanwhile, the 1972surrounding text `flows' around the keep, thus leaving no blank areas. 1973 1974@c --------------------------------------------------------------------- 1975 1976@node Footnotes and Annotations, Table of Contents, Displays, Common Features 1977@subsection Footnotes and Annotations 1978@cindex footnotes 1979@cindex annotations 1980 1981There are a number of requests to save text for later printing. 1982 1983@dfn{Footnotes} are printed at the bottom of the current page. 1984 1985@cindex delayed text 1986@dfn{Delayed text} is very similar to a footnote except that it is 1987printed when called for explicitly. This allows a list of references to 1988appear (for example) at the end of each chapter, as is the convention in 1989some disciplines. 1990 1991Most macro packages which supply this functionality also supply a means 1992of automatically numbering either type of annotation. 1993 1994@c --------------------------------------------------------------------- 1995 1996@node Table of Contents, Indices, Footnotes and Annotations, Common Features 1997@subsection Table of Contents 1998@cindex table of contents 1999@cindex contents, table of 2000 2001@dfn{Tables of contents} are a type of delayed text having a tag 2002(usually the page number) attached to each entry after a row of dots. 2003The table accumulates throughout the paper until printed, usually after 2004the paper has ended. Many macro packages provide the ability to have 2005several tables of contents (e.g.@: a standard table of contents, a list 2006of tables, etc). 2007 2008@c --------------------------------------------------------------------- 2009 2010@node Indices, Paper Formats, Table of Contents, Common Features 2011@subsection Indices 2012@cindex index, in macro package 2013 2014While some macro packages use the term @dfn{index}, none actually 2015provide that functionality. The facilities they call indices are 2016actually more appropriate for tables of contents. 2017 2018@pindex makeindex 2019To produce a real index in a document, external tools like the 2020@code{makeindex} program are necessary. 2021 2022@c --------------------------------------------------------------------- 2023 2024@node Paper Formats, Multiple Columns, Indices, Common Features 2025@subsection Paper Formats 2026@cindex paper formats 2027 2028Some macro packages provide stock formats for various kinds of 2029documents. Many of them provide a common format for the title and 2030opening pages of a technical paper. The @file{mm} macros in particular 2031provide formats for letters and memoranda. 2032 2033@c --------------------------------------------------------------------- 2034 2035@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features 2036@subsection Multiple Columns 2037 2038Some macro packages (but not @file{man}) provide the ability to have two 2039or more columns on a page. 2040 2041@c --------------------------------------------------------------------- 2042 2043@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features 2044@subsection Font and Size Changes 2045 2046The built-in font and size functions are not always intuitive, so all 2047macro packages provide macros to make these operations simpler. 2048 2049@c --------------------------------------------------------------------- 2050 2051@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features 2052@subsection Predefined Strings 2053 2054Most macro packages provide various predefined strings for a variety of 2055uses; examples are sub- and superscripts, printable dates, quotes and 2056various special characters. 2057 2058@c --------------------------------------------------------------------- 2059 2060@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features 2061@subsection Preprocessor Support 2062 2063All macro packages provide support for various preprocessors and may 2064extend their functionality. 2065 2066For example, all macro packages mark tables (which are processed with 2067@code{gtbl}) by placing them between @code{TS} and @code{TE} macros. 2068The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints 2069a caption at the top of a new page (when the table is too long to fit on 2070a single page). 2071 2072@c --------------------------------------------------------------------- 2073 2074@node Configuration and Customization, , Preprocessor Support, Common Features 2075@subsection Configuration and Customization 2076 2077Some macro packages provide means of customizing many of the details of 2078how the package behaves. This ranges from setting the default type size 2079to changing the appearance of section headers. 2080 2081 2082 2083@c ===================================================================== 2084@c ===================================================================== 2085 2086@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top 2087@chapter Macro Packages 2088@cindex macro packages 2089@cindex packages, macros 2090 2091This chapter documents the main macro packages that come with 2092@code{groff}. 2093 2094Different main macro packages can't be used at the same time; for example 2095 2096@Example 2097groff -m man foo.man -m ms bar.doc 2098@endExample 2099 2100@noindent 2101doesn't work. Note that option arguments are processed before non-option 2102arguments; the above (failing) sample is thus reordered to 2103 2104@Example 2105groff -m man -m ms foo.man bar.doc 2106@endExample 2107 2108@menu 2109* man:: 2110* mdoc:: 2111* ms:: 2112* me:: 2113* mm:: 2114@end menu 2115 2116 2117@c ===================================================================== 2118 2119@node man, mdoc, Macro Packages, Macro Packages 2120@section @file{man} 2121@cindex manual pages 2122@cindex man pages 2123@pindex an.tmac 2124@pindex man.tmac 2125@pindex man-old.tmac 2126 2127This is the most popular and probably the most important macro package 2128of @code{groff}. It is easy to use, and a vast majority of manual pages 2129are based on it. 2130 2131@menu 2132* Man options:: 2133* Man usage:: 2134* Man font macros:: 2135* Miscellaneous man macros:: 2136* Predefined man strings:: 2137* Preprocessors in man pages:: 2138* Optional man extensions:: 2139@end menu 2140 2141@c --------------------------------------------------------------------- 2142 2143@node Man options, Man usage, man, man 2144@subsection Options 2145 2146The command line format for using the @file{man} macros with 2147@code{groff} is: 2148 2149@Example 2150groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ] 2151 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ] 2152 [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ] 2153 [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ] 2154@endExample 2155 2156@noindent 2157It is possible to use @samp{-man} instead of @w{@samp{-m man}}. 2158 2159@table @code 2160@item -rcR=1 2161This option (the default if a TTY output device is used) creates a 2162single, very long page instead of multiple pages. Use @code{-rcR=0} 2163to disable it. 2164 2165@item -rC1 2166If more than one manual page is given on the command line, number the 2167pages continuously, rather than starting each at@tie{}1. 2168 2169@item -rD1 2170Double-sided printing. Footers for even and odd pages are formatted 2171differently. 2172 2173@item -rFT=@var{dist} 2174Set the position of the footer text to @var{dist}. If positive, the 2175distance is measured relative to the top of the page, otherwise it is 2176relative to the bottom. The default is @minus{}0.5@dmn{i}. 2177 2178@item -rHY=@var{flags} 2179Set hyphenation flags. Possible values are 1@tie{}to hyphenate without 2180restrictions, 2@tie{} to not hyphenate the last word on a page, 21814@tie{}to not hyphenate the last two characters of a word, and 21828@tie{}to not hyphenate the first two characters of a word. These 2183values are additive; the default is@tie{}14. 2184 2185@item -rIN=@var{length} 2186Set the body text indentation to @var{length}. 2187If not specified, the indentation defaults to 7@dmn{n} 2188(7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise. 2189For nroff, this value should always be an integer multiple of unit @samp{n} 2190to get consistent indentation. 2191 2192@item -rLL=@var{length} 2193Set line length to @var{length}. If not specified, the line length 2194is set to respect any value set by a prior @samp{ll} request (which 2195@emph{must} be in effect when the @samp{TH} macro is invoked), if 2196this differs from the built-in default for the formatter; otherwise it 2197defaults to 78@dmn{n} in nroff mode (this is 78 characters per 2198line) and 6.5@dmn{i} in troff mode.@footnote{Note that the use of 2199a @samp{.ll @var{length}} request to initialize the line length, prior 2200to use of the @samp{TH} macro, is supported for backward compatibility 2201with some versions of the @code{man} program. @emph{Always} use the 2202@option{-rLL=@var{length}} option, or an equivalent @samp{.nr LL @var{length}} 2203request, in preference to such a @samp{.ll @var{length}} request. 2204In particular, note that in nroff mode, the request @samp{.ll 65n}, 2205(with any @var{length} expression which evaluates equal to 65@dmn{n}, 2206i.e., the formatter's default line length in nroff mode), will @emph{not} 2207set the line length to 65@dmn{n} (it will be adjusted to the @code{man} 2208macro package's default setting of 78@dmn{n}), whereas the use of the 2209@option{-rLL=65n} option, or the @samp{.nr LL 65n} 2210request @emph{will} establish a line length of 65@dmn{n}.} 2211 2212@item -rLT=@var{length} 2213Set title length to @var{length}. If not specified, the title length 2214defaults to the line length. 2215 2216@item -rP@var{nnn} 2217Page numbering starts with @var{nnn} rather than with@tie{}1. 2218 2219@item -rS@var{xx} 2220Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base 2221document font size instead of the default value of@tie{}10@dmn{pt}. 2222 2223@item -rSN=@var{length} 2224Set the indentation for sub-subheadings to @var{length}. 2225If not specified, the indentation defaults to 3@dmn{n}. 2226 2227@item -rX@var{nnn} 2228After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, 2229@var{nnn}c, etc. For example, the option @option{-rX2} produces the 2230following page numbers: 1, 2, 2a, 2b, 2c, etc. 2231@end table 2232 2233@c --------------------------------------------------------------------- 2234 2235@node Man usage, Man font macros, Man options, man 2236@subsection Usage 2237@cindex @code{man} macros 2238@cindex macros for manual pages [@code{man}] 2239 2240@pindex man.local 2241This section describes the available macros for manual pages. For 2242further customization, put additional macros and requests into the file 2243@file{man.local} which is loaded immediately after the @file{man} 2244package. 2245 2246@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man} 2247Set the title of the man page to @var{title} and the section to 2248@var{section}, which must have a value between 1 and@tie{}8. The value 2249of @var{section} may also have a string appended, e.g.@: @samp{.pm}, 2250to indicate a specific subsection of the man pages. 2251 2252Both @var{title} and @var{section} are positioned at the left and right 2253in the header line (with @var{section} in parentheses immediately 2254appended to @var{title}. @var{extra1} is positioned in the middle of 2255the footer line. @var{extra2} is positioned at the left in the footer 2256line (or at the left on even pages and at the right on odd pages if 2257double-sided printing is active). @var{extra3} is centered in the 2258header line. 2259 2260For @acronym{HTML} output, headers and footers are completely suppressed. 2261 2262Additionally, this macro starts a new page; the new line number is@tie{}1 2263again (except if the @option{-rC1} option is given on the command line) 2264-- this feature is intended only for formatting multiple man pages; a 2265single man page should contain exactly one @code{TH} macro at the 2266beginning of the file. 2267@endDefmac 2268 2269@Defmac {SH, [@Var{heading}], man} 2270Set up an unnumbered section heading sticking out to the left. Prints 2271out all the text following @code{SH} up to the end of the line (or the 2272text in the next line if there is no argument to @code{SH}) in bold 2273face (or the font specified by the string @code{HF}), one size larger than 2274the base document size. Additionally, the left margin and the indentation 2275for the following text is reset to its default value. 2276@endDefmac 2277 2278@Defmac {SS, [@Var{heading}], man} 2279Set up an unnumbered (sub)section heading. Prints out all the text 2280following @code{SS} up to the end of the line (or the text in the next 2281line if there is no argument to @code{SS}) in bold face (or the font 2282specified by the string @code{HF}), at the same size as the base document 2283size. Additionally, the left margin and the indentation for the 2284following text is reset to its default value. 2285@endDefmac 2286 2287@Defmac {TP, [@Var{nnn}], man} 2288Set up an indented paragraph with label. The indentation is set to 2289@var{nnn} if that argument is supplied (the default unit is @samp{n} 2290if omitted), otherwise it is set to the previous indentation value 2291specified with @code{TP}, @code{IP}, or @code{HP} (or to the default 2292value if none of them have been used yet). 2293 2294The first line of text following this macro is interpreted as a string 2295to be printed flush-left, as it is appropriate for a label. It is not 2296interpreted as part of a paragraph, so there is no attempt to fill the 2297first line with text from the following input lines. Nevertheless, if 2298the label is not as wide as the indentation the paragraph starts 2299at the same line (but indented), continuing on the following lines. 2300If the label is wider than the indentation the descriptive part 2301of the paragraph begins on the line following the label, entirely 2302indented. Note that neither font shape nor font size of the label is 2303set to a default value; on the other hand, the rest of the text has 2304default font settings. 2305@endDefmac 2306 2307@DefmacList {LP, , man} 2308@DefmacItem {PP, , man} 2309@DefmacListEnd {P, , man} 2310These macros are mutual aliases. Any of them causes a line break at 2311the current position, followed by a vertical space downwards by the 2312amount specified by the @code{PD} macro. The font size and shape are 2313reset to the default value (10@dmn{pt} roman if no @option{-rS} option 2314is given on the command line). Finally, the current left margin and the 2315indentation is restored. 2316@endDefmac 2317 2318@Defmac {IP, [@Var{designator} [@Var{nnn}]], man} 2319Set up an indented paragraph, using @var{designator} as a tag to mark 2320its beginning. The indentation is set to @var{nnn} if that argument 2321is supplied (default unit is @samp{n}), otherwise it is set to the 2322previous indentation value specified with @code{TP}, @code{IP}, or 2323@code{HP} (or the default value if none of them have been used yet). 2324Font size and face of the paragraph (but not the designator) are reset 2325to their default values. 2326 2327To start an indented paragraph with a particular indentation but without 2328a designator, use @samp{""} (two double quotes) as the first argument of 2329@code{IP}. 2330 2331For example, to start a paragraph with bullets as the designator and 23324@tie{}en indentation, write 2333 2334@Example 2335.IP \(bu 4 2336@endExample 2337@endDefmac 2338 2339@Defmac {HP, [@Var{nnn}], man} 2340@cindex hanging indentation [@code{man}] 2341@cindex @code{man} macros, hanging indentation 2342Set up a paragraph with hanging left indentation. The indentation is 2343set to @var{nnn} if that argument is supplied (default unit is 2344@samp{n}), otherwise it is set to the previous indentation value 2345specified with @code{TP}, @code{IP}, or @code{HP} (or the default 2346value if non of them have been used yet). Font size and face are reset 2347to their default values. 2348@endDefmac 2349 2350@Defmac {RS, [@Var{nnn}], man} 2351@cindex left margin, how to move [@code{man}] 2352@cindex @code{man} macros, moving left margin 2353Move the left margin to the right by the value @var{nnn} if specified 2354(default unit is @samp{n}); otherwise it is set to the previous 2355indentation value specified with @code{TP}, @code{IP}, or @code{HP} 2356(or to the default value if none of them have been used yet). The 2357indentation value is then set to the default. 2358 2359Calls to the @code{RS} macro can be nested. 2360@endDefmac 2361 2362@Defmac {RE, [@Var{nnn}], man} 2363Move the left margin back to level @var{nnn}, restoring the previous left 2364margin. If no argument is given, it moves one level back. The first 2365level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call 2366to @code{RS} increases the level by@tie{}1. 2367@endDefmac 2368 2369@cindex line breaks, with vertical space [@code{man}] 2370@cindex @code{man} macros, line breaks with vertical space 2371To summarize, the following macros cause a line break with the insertion 2372of vertical space (which amount can be changed with the @code{PD} 2373macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, 2374@code{P}), @code{IP}, and @code{HP}. 2375 2376@cindex line breaks, without vertical space [@code{man}] 2377@cindex @code{man} macros, line breaks without vertical space 2378The macros @code{RS} and @code{RE} also cause a break but do not insert 2379vertical space. 2380 2381@cindex default indentation, resetting [@code{man}] 2382@cindex indentaion, resetting to default [@code{man}] 2383@cindex @code{man} macros, resetting default indentation 2384Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}), 2385and @code{RS} reset the indentation to its default value. 2386 2387@c --------------------------------------------------------------------- 2388 2389@node Man font macros, Miscellaneous man macros, Man usage, man 2390@subsection Macros to set fonts 2391@cindex font selection [@code{man}] 2392@cindex @code{man} macros, how to set fonts 2393 2394The standard font is roman; the default text size is 10@tie{}point. 2395If command line option @option{-rS=@var{n}} is given, use 2396@var{n}@dmn{pt} as the default text size. 2397 2398@Defmac {SM, [@Var{text}], man} 2399Set the text on the same line or the text on the next line in a font 2400that is one point size smaller than the default font. 2401@endDefmac 2402 2403@Defmac {SB, [@Var{text}], man} 2404@cindex bold face [@code{man}] 2405@cindex @code{man} macros, bold face 2406Set the text on the same line or the text on the next line in bold face 2407font, one point size smaller than the default font. 2408@endDefmac 2409 2410@Defmac {BI, text, man} 2411Set its arguments alternately in bold face and italic, without a space 2412between the arguments. Thus, 2413 2414@Example 2415.BI this "word and" that 2416@endExample 2417 2418@noindent 2419produces ``thisword andthat'' with ``this'' and ``that'' in bold face, 2420and ``word and'' in italics. 2421@endDefmac 2422 2423@Defmac {IB, text, man} 2424Set its arguments alternately in italic and bold face, without a space 2425between the arguments. 2426@endDefmac 2427 2428@Defmac {RI, text, man} 2429Set its arguments alternately in roman and italic, without a space between 2430the arguments. 2431@endDefmac 2432 2433@Defmac {IR, text, man} 2434Set its arguments alternately in italic and roman, without a space between 2435the arguments. 2436@endDefmac 2437 2438@Defmac {BR, text, man} 2439Set its arguments alternately in bold face and roman, without a space 2440between the arguments. 2441@endDefmac 2442 2443@Defmac {RB, text, man} 2444Set its arguments alternately in roman and bold face, without a space 2445between the arguments. 2446@endDefmac 2447 2448@Defmac {B, [@Var{text}], man} 2449Set @var{text} in bold face. If no text is present on the line where 2450the macro is called, then the text of the next line appears in bold 2451face. 2452@endDefmac 2453 2454@Defmac {I, [@Var{text}], man} 2455@cindex italic fonts [@code{man}] 2456@cindex @code{man} macros, italic fonts 2457Set @var{text} in italic. If no text is present on the line where the 2458macro is called, then the text of the next line appears in italic. 2459@endDefmac 2460 2461@c --------------------------------------------------------------------- 2462 2463@node Miscellaneous man macros, Predefined man strings, Man font macros, man 2464@subsection Miscellaneous macros 2465 2466@pindex grohtml 2467@cindex @code{man} macros, default indentation 2468@cindex default indentation [@code{man}] 2469The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in 2470nroff mode except for @code{grohtml} which ignores indentation. 2471 2472@Defmac {DT, , man} 2473@cindex tab stops [@code{man}] 2474@cindex @code{man} macros, tab stops 2475Set tabs every 0.5@tie{}inches. Since this macro is always executed 2476during a call to the @code{TH} macro, it makes sense to call it only if 2477the tab positions have been changed. 2478@endDefmac 2479 2480@Defmac {PD, [@Var{nnn}], man} 2481@cindex empty space before a paragraph [@code{man}] 2482@cindex @code{man} macros, empty space before a paragraph 2483Adjust the empty space before a new paragraph (or section). The 2484optional argument gives the amount of space (default unit is 2485@samp{v}); without parameter, the value is reset to its default value 2486(1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise). 2487 2488This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as 2489well as @code{PP} and @code{P}), @code{IP}, and @code{HP}. 2490@endDefmac 2491 2492The following two macros are included for 2493BSD compatibility. 2494 2495@Defmac {AT, [@Var{system} [@Var{release}]], man} 2496@cindex @code{man}macros, BSD compatibility 2497Alter the footer for use with @acronym{AT&T} manpages. 2498This command exists only for compatibility; don't use it. 2499The first argument @var{system} can be: 2500 2501@table @code 2502@item 3 25037th Edition (the default) 2504 2505@item 4 2506System III 2507 2508@item 5 2509System V 2510@end table 2511 2512An optional second argument @var{release} to @code{AT} specifies the 2513release number (such as ``System V Release 3''). 2514@endDefmac 2515 2516@Defmac {UC, [@Var{version}], man} 2517@cindex @code{man}macros, BSD compatibility 2518Alters the footer for use with @acronym{BSD} manpages. 2519This command exists only for compatibility; don't use it. 2520The argument can be: 2521 2522@table @code 2523@item 3 25243rd Berkeley Distribution (the default) 2525 2526@item 4 25274th Berkeley Distribution 2528 2529@item 5 25304.2 Berkeley Distribution 2531 2532@item 6 25334.3 Berkeley Distribution 2534 2535@item 7 25364.4 Berkeley Distribution 2537@end table 2538@endDefmac 2539 2540@c --------------------------------------------------------------------- 2541 2542@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man 2543@subsection Predefined strings 2544 2545The following strings are defined: 2546 2547@Defstr {S, man} 2548Switch back to the default font size. 2549@endDefstr 2550 2551@Defstr {HF, man} 2552The typeface used for headings. 2553The default is @samp{B}. 2554@endDefstr 2555 2556@Defstr {R, man} 2557The `registered' sign. 2558@endDefstr 2559 2560@Defstr {Tm, man} 2561The `trademark' sign. 2562@endDefstr 2563 2564@DefstrList {lq, man} 2565@DefstrListEnd {rq, man} 2566@cindex @code{lq} glyph, and @code{lq} string [@code{man}] 2567@cindex @code{rq} glyph, and @code{rq} string [@code{man}] 2568Left and right quote. This is equal to @code{\(lq} and @code{\(rq}, 2569respectively. 2570@endDefstr 2571 2572@c --------------------------------------------------------------------- 2573 2574@node Preprocessors in man pages, Optional man extensions, Predefined man strings, man 2575@subsection Preprocessors in @file{man} pages 2576 2577@cindex preprocessor, calling convention 2578@cindex calling convention of preprocessors 2579If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has 2580become common usage to make the first line of the man page look like 2581this: 2582 2583@Example 2584'\" @var{word} 2585@endExample 2586 2587@pindex geqn@r{, invocation in manual pages} 2588@pindex grefer@r{, invocation in manual pages} 2589@pindex gtbl@r{, invocation in manual pages} 2590@pindex man@r{, invocation of preprocessors} 2591@noindent 2592Note the single space character after the double quote. @var{word} 2593consists of letters for the needed preprocessors: @samp{e} for 2594@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. 2595Modern implementations of the @code{man} program read this first line 2596and automatically call the right preprocessor(s). 2597 2598@c --------------------------------------------------------------------- 2599 2600@node Optional man extensions, , Preprocessors in man pages, man 2601@subsection Optional @file{man} extensions 2602 2603@pindex man.local 2604Use the file @file{man.local} for local extensions 2605to the @code{man} macros or for style changes. 2606 2607@unnumberedsubsubsec Custom headers and footers 2608@cindex @code{man} macros, custom headers and footers 2609 2610In groff versions 1.18.2 and later, you can specify custom 2611headers and footers by redefining the following macros in 2612@file{man.local}. 2613 2614@Defmac {PT, , man} 2615Control the content of the headers. 2616Normally, the header prints the command name 2617and section number on either side, and the 2618optional fifth argument to @code{TH} in the center. 2619@endDefmac 2620 2621@Defmac {BT, , man} 2622Control the content of the footers. 2623Normally, the footer prints the page number 2624and the third and fourth arguments to @code{TH}. 2625 2626Use the @code{FT} number register to specify the 2627footer position. 2628The default is @minus{}0.5@dmn{i}. 2629@endDefmac 2630 2631@unnumberedsubsubsec Ultrix-specific man macros 2632@cindex Ultrix-specific @code{man} macros 2633@cindex @code{man} macros, Ultrix-specific 2634 2635@pindex man.ultrix 2636The @code{groff} source distribution includes 2637a file named @file{man.ultrix}, containing 2638macros compatible with the Ultrix variant of 2639@code{man}. 2640Copy this file into @file{man.local} (or use the @code{mso} request to 2641load it) to enable the following macros. 2642 2643@Defmac {CT, @Var{key}, man} 2644Print @samp{<CTRL/@var{key}>}. 2645@endDefmac 2646 2647@Defmac {CW, , man} 2648Print subsequent text using the constant width (Courier) typeface. 2649@endDefmac 2650 2651@Defmac {Ds, , man} 2652Begin a non-filled display. 2653@endDefmac 2654 2655@Defmac {De, , man} 2656End a non-filled display started with @code{Ds}. 2657@endDefmac 2658 2659@Defmac {EX, [@Var{indent}], man} 2660Begins a non-filled display 2661using the constant width (Courier) typeface. 2662Use the optional @var{indent} argument to 2663indent the display. 2664@endDefmac 2665 2666@Defmac {EE, , man} 2667End a non-filled display started with @code{EX}. 2668@endDefmac 2669 2670@Defmac {G, [@Var{text}], man} 2671Sets @var{text} in Helvetica. 2672If no text is present on the line where 2673the macro is called, then the text of the 2674next line appears in Helvetica. 2675@endDefmac 2676 2677@Defmac {GL, [@Var{text}], man} 2678Sets @var{text} in Helvetica Oblique. 2679If no text is present on the line where 2680the macro is called, then the text of the 2681next line appears in Helvetica Oblique. 2682@endDefmac 2683 2684@Defmac {HB, [@Var{text}], man} 2685Sets @var{text} in Helvetica Bold. 2686If no text is present on the line where 2687the macro is called, then all text up to 2688the next @code{HB} appears in Helvetica Bold. 2689@endDefmac 2690 2691@Defmac {TB, [@Var{text}], man} 2692Identical to @code{HB}. 2693@endDefmac 2694 2695@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man} 2696Set a manpage reference in Ultrix format. 2697The @var{title} is in Courier instead of italic. 2698Optional punctuation follows the section number without 2699an intervening space. 2700@endDefmac 2701 2702@Defmac {NT, [@code{C}] [@Var{title}], man} 2703Begin a note. 2704Print the optional @Var{title}, or the word ``Note'', 2705centered on the page. 2706Text following the macro makes up the body of the note, 2707and is indented on both sides. 2708If the first argument is @code{C}, the body of the 2709note is printed centered (the second argument replaces 2710the word ``Note'' if specified). 2711@endDefmac 2712 2713@Defmac {NE, , man} 2714End a note begun with @code{NT}. 2715@endDefmac 2716 2717@Defmac {PN, @Var{path} [@Var{punct}], man} 2718Set the path name in constant width (Courier), 2719followed by optional punctuation. 2720@endDefmac 2721 2722@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man} 2723When called with two arguments, identical to @code{PN}. 2724When called with three arguments, 2725set the second argument in constant width (Courier), 2726bracketed by the first and third arguments in the current font. 2727@endDefmac 2728 2729@Defmac {R, , man} 2730Switch to roman font and turn off any underlining in effect. 2731@endDefmac 2732 2733@Defmac {RN, , man} 2734Print the string @samp{<RETURN>}. 2735@endDefmac 2736 2737@Defmac {VS, [@code{4}], man} 2738Start printing a change bar in the margin if 2739the number @code{4} is specified. 2740Otherwise, this macro does nothing. 2741@endDefmac 2742 2743@Defmac {VE, , man} 2744End printing the change bar begun by @code{VS}. 2745@endDefmac 2746 2747@unnumberedsubsubsec Simple example 2748 2749The following example @file{man.local} file 2750alters the @code{SH} macro to add some extra 2751vertical space before printing the heading. 2752Headings are printed in Helvetica Bold. 2753 2754@Example 2755.\" Make the heading fonts Helvetica 2756.ds HF HB 2757. 2758.\" Put more whitespace in front of headings. 2759.rn SH SH-orig 2760.de SH 2761. if t .sp (u;\\n[PD]*2) 2762. SH-orig \\$* 2763.. 2764@endExample 2765 2766@c ===================================================================== 2767 2768@node mdoc, ms, man, Macro Packages 2769@section @file{mdoc} 2770@cindex @code{mdoc} macros 2771 2772@c XXX documentation 2773@c XXX this is a placeholder until we get stuff knocked into shape 2774See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc} 2775at the command line). 2776 2777 2778@c ===================================================================== 2779 2780@node ms, me, mdoc, Macro Packages 2781@section @file{ms} 2782@cindex @code{ms} macros 2783 2784The @file{-ms} macros are suitable for reports, letters, books, user 2785manuals, and so forth. The package provides macros for cover pages, 2786section headings, paragraphs, lists, footnotes, pagination, and a 2787table of contents. 2788 2789@menu 2790* ms Intro:: 2791* General ms Structure:: 2792* ms Document Control Registers:: 2793* ms Cover Page Macros:: 2794* ms Body Text:: 2795* ms Page Layout:: 2796* Differences from AT&T ms:: 2797* Naming Conventions:: 2798@end menu 2799 2800@c --------------------------------------------------------------------- 2801 2802@node ms Intro, General ms Structure, ms, ms 2803@subsection Introduction to @file{ms} 2804 2805The original @file{-ms} macros were included with @acronym{AT&T} 2806@code{troff} as well as the @file{man} macros. While the @file{man} 2807package is intended for brief documents that can be read on-line as 2808well as printed, the @file{ms} macros are suitable for longer 2809documents that are meant to be printed rather than read on-line. 2810 2811The @file{ms} macro package included with @code{groff} is a complete, 2812bottom-up re-implementation. Several macros (specific to 2813@acronym{AT&T} or Berkeley) are not included, while several new 2814commands are. @xref{Differences from AT&T ms}, for more information. 2815 2816@c --------------------------------------------------------------------- 2817 2818@node General ms Structure, ms Document Control Registers, ms Intro, ms 2819@subsection General structure of an @file{ms} document 2820@cindex @code{ms} macros, general structure 2821 2822The @file{ms} macro package expects a certain amount of structure, but 2823not as much as packages such as @file{man} or @file{mdoc}. 2824 2825The simplest documents can begin with a paragraph macro (such as 2826@code{LP} or @code{PP}), and consist of text separated by paragraph 2827macros or even blank lines. Longer documents have a structure as 2828follows: 2829 2830@table @strong 2831@item Document type 2832If you invoke the @code{RP} (report) macro on the first line of the 2833document, @code{groff} prints the cover page information on its own 2834page; otherwise it prints the information on the first page with your 2835document text immediately following. Other document formats found in 2836@acronym{AT&T} @code{troff} are specific to @acronym{AT&T} or 2837Berkeley, and are not supported in @code{groff}. 2838 2839@item Format and layout 2840By setting number registers, you can change your document's type (font 2841and size), margins, spacing, headers and footers, and footnotes. 2842@xref{ms Document Control Registers}, for more details. 2843 2844@item Cover page 2845A cover page consists of a title, the author's name and institution, 2846an abstract, and the date.@footnote{Actually, only the title is 2847required.} @xref{ms Cover Page Macros}, for more details. 2848 2849@item Body 2850Following the cover page is your document. You can use the @file{ms} 2851macros to write reports, letters, books, and so forth. The package is 2852designed for structured documents, consisting of paragraphs 2853interspersed with headings and augmented by lists, footnotes, tables, 2854and other common constructs. @xref{ms Body Text}, for more details. 2855 2856@item Table of contents 2857Longer documents usually include a table of contents, which you can 2858invoke by placing the @code{TC} macro at the end of your document. 2859The @file{ms} macros have minimal indexing facilities, consisting of 2860the @code{IX} macro, which prints an entry on standard error. 2861Printing the table of contents at the end is necessary since 2862@code{groff} is a single-pass text formatter, thus it cannot determine 2863the page number of each section until that section has actually been 2864set and printed. Since @file{ms} output is intended for hardcopy, you 2865can manually relocate the pages containing the table of contents 2866between the cover page and the body text after printing. 2867@end table 2868 2869@c --------------------------------------------------------------------- 2870 2871@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms 2872@subsection Document control registers 2873@cindex @code{ms} macros, document control registers 2874 2875The following is a list of document control number registers. For the 2876sake of consistency, set registers related to margins at the beginning 2877of your document, or just after the @code{RP} macro. You can set 2878other registers later in your document, but you should keep them 2879together at the beginning to make them easy to find and edit as 2880necessary. 2881 2882@unnumberedsubsubsec Margin Settings 2883 2884@Defmpreg {PO, ms} 2885Defines the page offset (i.e., the left margin). There is no explicit 2886right margin setting; the combination of the @code{PO} and @code{LL} 2887registers implicitly define the right margin width. 2888 2889Effective: next page. 2890 2891Default value: 1@dmn{i}. 2892@endDefmpreg 2893 2894@Defmpreg {LL, ms} 2895Defines the line length (i.e., the width of the body text). 2896 2897Effective: next paragraph. 2898 2899Default: 6@dmn{i}. 2900@endDefmpreg 2901 2902@Defmpreg {LT, ms} 2903Defines the title length (i.e., the header and footer width). This 2904is usually the same as @code{LL}, but not necessarily. 2905 2906Effective: next paragraph. 2907 2908Default: 6@dmn{i}. 2909@endDefmpreg 2910 2911@Defmpreg {HM, ms} 2912Defines the header margin height at the top of the page. 2913 2914Effective: next page. 2915 2916Default: 1@dmn{i}. 2917@endDefmpreg 2918 2919@Defmpreg {FM, ms} 2920Defines the footer margin height at the bottom of the page. 2921 2922Effective: next page. 2923 2924Default: 1@dmn{i}. 2925@endDefmpreg 2926 2927@unnumberedsubsubsec Text Settings 2928 2929@Defmpreg {PS, ms} 2930Defines the point size of the body text. If the value is larger than 2931or equal to 1000, divide it by 1000 to get a fractional point size. 2932For example, @samp{.nr PS 10250} sets the document's point size to 293310.25@dmn{p}. 2934 2935Effective: next paragraph. 2936 2937Default: 10@dmn{p}. 2938@endDefmpreg 2939 2940@Defmpreg {VS, ms} 2941Defines the space between lines (line height plus leading). If the 2942value is larger than or equal to 1000, divide it by 1000 to get a 2943fractional point size. Due to backwards compatibility, @code{VS} must 2944be smaller than 40000 (this is 40.0@dmn{p}). 2945 2946Effective: next paragraph. 2947 2948Default: 12@dmn{p}. 2949@endDefmpreg 2950 2951@Defmpreg {PSINCR, ms} 2952Defines an increment in point size, which will be applied to section 2953headings at nesting levels below the value specified in @code{GROWPS}. 2954The value of @code{PSINCR} should be specified in points, with the 2955@dmn{p} scaling factor, and may include a fractional component; for 2956example, @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of 29571.5@dmn{p}. 2958 2959Effective: next section heading. 2960 2961Default: 1@dmn{p}. 2962@endDefmpreg 2963 2964@Defmpreg {GROWPS, ms} 2965Defines the heading level below which the point size increment set by 2966@code{PSINCR} becomes effective. Section headings at and above the 2967level specified by @code{GROWPS} will be printed at the point size set 2968by @code{PS}; for each level below the value of @code{GROWPS}, the 2969point size will be increased in steps equal to the value of 2970@code{PSINCR}. Setting @code{GROWPS} to any value less than@tie{}2 2971disables the incremental heading size feature. 2972 2973Effective: next section heading. 2974 2975Default: 0. 2976@endDefmpreg 2977 2978@Defmpreg {HY, ms} 2979Defines the hyphenation level. @code{HY} sets safely the value of the 2980low-level @code{hy} register. Setting the value of @code{HY} 2981to@tie{}0 is equivalent to using the @code{nh} request. 2982 2983Effective: next paragraph. 2984 2985Default: 14. 2986@endDefmpreg 2987 2988@Defmpreg {FAM, ms} 2989Defines the font family used to typeset the document. 2990 2991Effective: next paragraph. 2992 2993Default: as defined in the output device. 2994@endDefmpreg 2995 2996@unnumberedsubsubsec Paragraph Settings 2997 2998@Defmpreg {PI, ms} 2999Defines the initial indentation of a (@code{PP} macro) paragraph. 3000 3001Effective: next paragraph. 3002 3003Default: 5@dmn{n}. 3004@endDefmpreg 3005 3006@Defmpreg {PD, ms} 3007Defines the space between paragraphs. 3008 3009Effective: next paragraph. 3010 3011Default: 0.3@dmn{v}. 3012@endDefmpreg 3013 3014@Defmpreg {QI, ms} 3015Defines the indentation on both sides of a quoted (@code{QP} macro) 3016paragraph. 3017 3018Effective: next paragraph. 3019 3020Default: 5@dmn{n}. 3021@endDefmpreg 3022 3023@Defmpreg {PORPHANS, ms} 3024Defines the minimum number of initial lines of any paragraph which 3025should be kept together, to avoid orphan lines at the bottom of a 3026page. If a new paragraph is started close to the bottom of a page, 3027and there is insufficient space to accommodate @code{PORPHANS} lines 3028before an automatic page break, then the page break will be forced, 3029before the start of the paragraph. 3030 3031Effective: next paragraph. 3032 3033Default: 1. 3034@endDefmpreg 3035 3036@Defmpreg {HORPHANS, ms} 3037Defines the minimum number of lines of the following paragraph which 3038should be kept together with any section heading introduced by the 3039@code{NH} or @code{SH} macros. If a section heading is placed close 3040to the bottom of a page, and there is insufficient space to 3041accommodate both the heading and at least @code{HORPHANS} lines of the 3042following paragraph, before an automatic page break, then the page 3043break will be forced before the heading. 3044 3045Effective: next paragraph. 3046 3047Default: 1. 3048@endDefmpreg 3049 3050@unnumberedsubsubsec Footnote Settings 3051 3052@Defmpreg {FL, ms} 3053Defines the length of a footnote. 3054 3055Effective: next footnote. 3056 3057Default: @math{@code{@\n[LL]} * 5 / 6}. 3058@endDefmpreg 3059 3060@Defmpreg {FI, ms} 3061Defines the footnote indentation. 3062 3063Effective: next footnote. 3064 3065Default: 2@dmn{n}. 3066@endDefmpreg 3067 3068@Defmpreg {FF, ms} 3069The footnote format: 3070@table @code 3071@item 0 3072Print the footnote number as a superscript; indent the footnote 3073(default). 3074 3075@item 1 3076Print the number followed by a period (like 1.@:) and indent the 3077footnote. 3078 3079@item 2 3080Like 1, without an indentation. 3081 3082@item 3 3083Like 1, but print the footnote number as a hanging paragraph. 3084@end table 3085 3086Effective: next footnote. 3087 3088Default: 0. 3089@endDefmpreg 3090 3091@Defmpreg {FPS, ms} 3092Defines the footnote point size. If the value is larger than or equal 3093to 1000, divide it by 1000 to get a fractional point size. 3094 3095Effective: next footnote. 3096 3097Default: @math{@code{@\n[PS]} - 2}. 3098@endDefmpreg 3099 3100@Defmpreg {FVS, ms} 3101Defines the footnote vertical spacing. If the value is larger than or 3102equal to 1000, divide it by 1000 to get a fractional point size. 3103 3104Effective: next footnote. 3105 3106Default: @math{@code{@\n[FPS]} + 2}. 3107@endDefmpreg 3108 3109@Defmpreg {FPD, ms} 3110Defines the footnote paragraph spacing. 3111 3112Effective: next footnote. 3113 3114Default: @math{@code{@\n[PD]} / 2}. 3115@endDefmpreg 3116 3117@unnumberedsubsubsec Miscellaneous Number Registers 3118 3119@Defmpreg {MINGW, ms} 3120Defines the minimum width between columns in a multi-column document. 3121 3122Effective: next page. 3123 3124Default: 2@dmn{n}. 3125@endDefmpreg 3126 3127@c --------------------------------------------------------------------- 3128 3129@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms 3130@subsection Cover page macros 3131@cindex @code{ms} macros, cover page 3132@cindex cover page macros, [@code{ms}] 3133 3134Use the following macros to create a cover page for your document in 3135the order shown. 3136 3137@Defmac {RP, [@code{no}], ms} 3138Specifies the report format for your document. The report format 3139creates a separate cover page. The default action (no @code{RP} 3140macro) is to print a subset of the cover page on page@tie{}1 of your 3141document. 3142 3143If you use the word @code{no} as an optional argument, @code{groff} 3144prints a title page but does not repeat any of the title page 3145information (title, author, abstract, etc.@:) on page@tie{}1 of the 3146document. 3147@endDefmac 3148 3149@Defmac {P1, , ms} 3150(P-one) Prints the header on page@tie{}1. The default is to suppress 3151the header. 3152@endDefmac 3153 3154@Defmac {DA, [@dots{}], ms} 3155(optional) Prints the current date, or the arguments to the macro if 3156any, on the title page (if specified) and in the footers. This is the 3157default for @code{nroff}. 3158@endDefmac 3159 3160@Defmac {ND, [@dots{}], ms} 3161(optional) Prints the current date, or the arguments to the macro if 3162any, on the title page (if specified) but not in the footers. This is 3163the default for @code{troff}. 3164@endDefmac 3165 3166@Defmac {TL, , ms} 3167Specifies the document title. @code{groff} collects text following 3168the @code{TL} macro into the title, until reaching the author name or 3169abstract. 3170@endDefmac 3171 3172@Defmac {AU, , ms} 3173Specifies the author's name, which appears on the line (or lines) 3174immediately following. You can specify multiple authors as follows: 3175 3176@Example 3177.AU 3178John Doe 3179.AI 3180University of West Bumblefuzz 3181.AU 3182Martha Buck 3183.AI 3184Monolithic Corporation 3185 3186... 3187@endExample 3188@endDefmac 3189 3190@Defmac {AI, , ms} 3191Specifies the author's institution. You can specify multiple 3192institutions in the same way that you specify multiple authors. 3193@endDefmac 3194 3195@Defmac {AB, [@code{no}], ms} 3196Begins the abstract. The default is to print the word 3197@acronym{ABSTRACT}, centered and in italics, above the text of the 3198abstract. The word @code{no} as an optional argument suppresses this 3199heading. 3200@endDefmac 3201 3202@Defmac {AE, , ms} 3203Ends the abstract. 3204@endDefmac 3205 3206The following is example mark-up for a title page. 3207@cindex title page, example markup 3208@cindex example markup, title page 3209 3210@Example 3211@cartouche 3212.RP 3213.TL 3214The Inevitability of Code Bloat 3215in Commercial and Free Software 3216.AU 3217J. Random Luser 3218.AI 3219University of West Bumblefuzz 3220.AB 3221This report examines the long-term growth 3222of the code bases in two large, popular software 3223packages; the free Emacs and the commercial 3224Microsoft Word. 3225While differences appear in the type or order 3226of features added, due to the different 3227methodologies used, the results are the same 3228in the end. 3229.PP 3230The free software approach is shown to be 3231superior in that while free software can 3232become as bloated as commercial offerings, 3233free software tends to have fewer serious 3234bugs and the added features are in line with 3235user demand. 3236.AE 3237 3238... the rest of the paper follows ... 3239@end cartouche 3240@endExample 3241 3242@c --------------------------------------------------------------------- 3243 3244@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms 3245@subsection Body text 3246@cindex @code{ms} macros, body text 3247 3248This section describes macros used to mark up the body of your 3249document. Examples include paragraphs, sections, and other groups. 3250 3251@menu 3252* Paragraphs in ms:: 3253* Headings in ms:: 3254* Highlighting in ms:: 3255* Lists in ms:: 3256* Indentation values in ms:: 3257* Tabstops in ms:: 3258* ms Displays and Keeps:: 3259* ms Insertions:: 3260* Example multi-page table:: 3261* ms Footnotes:: 3262@end menu 3263 3264@c --------------------------------------------------------------------- 3265 3266@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text 3267@subsubsection Paragraphs 3268@cindex @code{ms} macros, paragraph handling 3269 3270The following paragraph types are available. 3271 3272@DefmacList {PP, , ms} 3273@DefmacListEnd {LP, , ms} 3274Sets a paragraph with an initial indentation. 3275@endDefmac 3276 3277@Defmac {QP, , ms} 3278Sets a paragraph that is indented at both left and right margins. The 3279effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element. 3280The next paragraph or heading returns margins to normal. 3281@endDefmac 3282 3283@Defmac {XP, , ms} 3284Sets a paragraph whose lines are indented, except for the first line. 3285This is a Berkeley extension. 3286@endDefmac 3287 3288The following markup uses all four paragraph macros. 3289 3290@Example 3291@cartouche 3292.NH 2 3293Cases used in the study 3294.LP 3295The following software and versions were 3296considered for this report. 3297.PP 3298For commercial software, we chose 3299.B "Microsoft Word for Windows" , 3300starting with version 1.0 through the 3301current version (Word 2000). 3302.PP 3303For free software, we chose 3304.B Emacs , 3305from its first appearance as a standalone 3306editor through the current version (v20). 3307See [Bloggs 2002] for details. 3308.QP 3309Franklin's Law applied to software: 3310software expands to outgrow both 3311RAM and disk space over time. 3312.LP 3313Bibliography: 3314.XP 3315Bloggs, Joseph R., 3316.I "Everyone's a Critic" , 3317Underground Press, March 2002. 3318A definitive work that answers all questions 3319and criticisms about the quality and usability of 3320free software. 3321@end cartouche 3322@endExample 3323 3324The @code{PORPHANS} register (@pxref{ms Document Control Registers}) 3325operates in conjunction with each of these macros, to inhibit the 3326printing of orphan lines at the bottom of any page. 3327 3328@c --------------------------------------------------------------------- 3329 3330@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text 3331@subsubsection Headings 3332@cindex @code{ms} macros, headings 3333 3334Use headings to create a hierarchical structure for your document. 3335The @file{ms} macros print headings in @strong{bold}, using the same 3336font family and point size as the body text. 3337 3338The following describes the heading macros: 3339 3340@DefmacList {NH, @Var{curr-level}, ms} 3341@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms} 3342Numbered heading. The argument is either a numeric argument to 3343indicate the level of the heading, or the letter@tie{}@code{S} 3344followed by numeric arguments to set the heading level explicitly. 3345 3346If you specify heading levels out of sequence, such as invoking 3347@samp{.NH 3} after @samp{.NH 1}, @code{groff} prints a warning on 3348standard error. 3349@endDefmac 3350 3351@DefstrList {SN, ms} 3352@DefstrItem {SN-DOT, ms} 3353@DefstrListEnd {SN-NO-DOT, ms} 3354After invocation of @code{NH}, the assigned section number is made 3355available in the strings @code{SN-DOT} (exactly as it appears in the 3356printed section heading) and @code{SN-NO-DOT} (with the final period 3357omitted). The string @code{SN} is also defined, as an alias for 3358@code{SN-DOT}; if preferred, you may redefine it as an alias for 3359@code{SN-NO-DOT}, by including the initialization 3360 3361@Example 3362.ds SN-NO-DOT 3363.als SN SN-NO-DOT 3364@endExample 3365 3366@noindent 3367@strong{before} your first use of @code{NH}, or simply 3368 3369@Example 3370.als SN SN-NO-DOT 3371@endExample 3372 3373@noindent 3374@strong{after} your first use of @code{NH}. 3375@endDefstr 3376 3377@Defmac {SH, [@Var{match-level}], ms} 3378Unnumbered subheading. 3379 3380The optional @var{match-level} argument is a GNU extension. It is a 3381number indicating the level of the heading, in a manner analogous to 3382the @var{curr-level} argument to @code{.NH}. Its purpose is to match 3383the point size, at which the heading is printed, to the size of a 3384numbered heading at the same level, when the @code{GROWPS} and 3385@code{PSINCR} heading size adjustment mechanism is in effect. 3386@xref{ms Document Control Registers}. 3387@endDefmac 3388 3389The @code{HORPHANS} register (@pxref{ms Document Control Registers}) 3390operates in conjunction with the @code{NH} and @code{SH} macros, to 3391inhibit the printing of orphaned section headings at the bottom of any 3392page. 3393 3394@c --------------------------------------------------------------------- 3395 3396@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text 3397@subsubsection Highlighting 3398@cindex @code{ms} macros, highlighting 3399 3400The @file{ms} macros provide a variety of methods to highlight or 3401emphasize text: 3402 3403@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3404Sets its first argument in @strong{bold type}. If you specify a 3405second argument, @code{groff} prints it in the previous font after the 3406bold text, with no intervening space (this allows you to set 3407punctuation after the highlighted text without highlighting the 3408punctuation). Similarly, it prints the third argument (if any) in the 3409previous font @strong{before} the first argument. For example, 3410 3411@Example 3412.B foo ) ( 3413@endExample 3414 3415prints (@strong{foo}). 3416 3417If you give this macro no arguments, @code{groff} prints all text 3418following in bold until the next highlighting, paragraph, or heading 3419macro. 3420@endDefmac 3421 3422@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3423Sets its first argument in roman (or regular) type. It operates 3424similarly to the @code{B}@tie{}macro otherwise. 3425@endDefmac 3426 3427@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3428Sets its first argument in @emph{italic type}. It operates similarly 3429to the @code{B}@tie{}macro otherwise. 3430@endDefmac 3431 3432@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3433Sets its first argument in a @code{constant width face}. It operates 3434similarly to the @code{B}@tie{}macro otherwise. 3435@endDefmac 3436 3437@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3438Sets its first argument in bold italic type. It operates similarly to 3439the @code{B}@tie{}macro otherwise. 3440@endDefmac 3441 3442@Defmac {BX, [@Var{txt}], ms} 3443Prints its argument and draws a box around it. If you want to box a 3444string that contains spaces, use a digit-width space (@code{\0}). 3445@endDefmac 3446 3447@Defmac {UL, [@Var{txt} [@Var{post}]], ms} 3448Prints its first argument with an underline. If you specify a second 3449argument, @code{groff} prints it in the previous font after the 3450underlined text, with no intervening space. 3451@endDefmac 3452 3453@Defmac {LG, , ms} 3454Prints all text following in larger type (two points larger than the 3455current point size) until the next font size, highlighting, paragraph, 3456or heading macro. You can specify this macro multiple times to 3457enlarge the point size as needed. 3458@endDefmac 3459 3460@Defmac {SM, , ms} 3461Prints all text following in smaller type (two points smaller than the 3462current point size) until the next type size, highlighting, paragraph, 3463or heading macro. You can specify this macro multiple times to reduce 3464the point size as needed. 3465@endDefmac 3466 3467@Defmac {NL, , ms} 3468Prints all text following in the normal point size (that is, the value 3469of the @code{PS} register). 3470@endDefmac 3471 3472@DefstrList {@Lbrace{}, ms} 3473@DefstrListEnd {@Rbrace{}, ms} 3474Text enclosed with @code{\*@{} and @code{\*@}} is printed as a 3475superscript. 3476@endDefstr 3477 3478@c --------------------------------------------------------------------- 3479 3480@node Lists in ms, Indentation values in ms, Highlighting in ms, ms Body Text 3481@subsubsection Lists 3482@cindex @code{ms} macros, lists 3483 3484The @code{IP} macro handles duties for all lists. 3485 3486@Defmac {IP, [@Var{marker} [@Var{width}]], ms} 3487The @var{marker} is usually a bullet glyph (@code{\[bu]}) for 3488unordered lists, a number (or auto-incrementing number register) for 3489numbered lists, or a word or phrase for indented (glossary-style) 3490lists. 3491 3492The @var{width} specifies the indentation for the body of each list 3493item; its default unit is @samp{n}. Once specified, the indentation 3494remains the same for all list items in the document until specified 3495again. 3496 3497The @code{PORPHANS} register (@pxref{ms Document Control Registers}) 3498operates in conjunction with the @code{IP} macro, to inhibit the 3499printing of orphaned list markers at the bottom of any page. 3500@endDefmac 3501 3502The following is an example of a bulleted list. 3503@cindex example markup, bulleted list [@code{ms}] 3504@cindex bulleted list, example markup [@code{ms}] 3505 3506@Example 3507A bulleted list: 3508.IP \[bu] 2 3509lawyers 3510.IP \[bu] 3511guns 3512.IP \[bu] 3513money 3514@endExample 3515 3516Produces: 3517 3518@Example 3519A bulleted list: 3520 3521o lawyers 3522 3523o guns 3524 3525o money 3526@endExample 3527 3528The following is an example of a numbered list. 3529@cindex example markup, numbered list [@code{ms}] 3530@cindex numbered list, example markup [@code{ms}] 3531 3532@Example 3533.nr step 1 1 3534A numbered list: 3535.IP \n[step] 3 3536lawyers 3537.IP \n+[step] 3538guns 3539.IP \n+[step] 3540money 3541@endExample 3542 3543Produces: 3544 3545@Example 3546A numbered list: 3547 35481. lawyers 3549 35502. guns 3551 35523. money 3553@endExample 3554 3555Note the use of the auto-incrementing number register in this example. 3556 3557The following is an example of a glossary-style list. 3558@cindex example markup, glossary-style list [@code{ms}] 3559@cindex glossary-style list, example markup [@code{ms}] 3560 3561@Example 3562A glossary-style list: 3563.IP lawyers 0.4i 3564Two or more attorneys. 3565.IP guns 3566Firearms, preferably 3567large-caliber. 3568.IP money 3569Gotta pay for those 3570lawyers and guns! 3571@endExample 3572 3573Produces: 3574 3575@Example 3576A glossary-style list: 3577 3578lawyers 3579 Two or more attorneys. 3580 3581guns Firearms, preferably large-caliber. 3582 3583money 3584 Gotta pay for those lawyers and guns! 3585@endExample 3586 3587In the last example, the @code{IP} macro places the definition on the 3588same line as the term if it has enough space; otherwise, it breaks to 3589the next line and starts the definition below the term. This may or 3590may not be the effect you want, especially if some of the definitions 3591break and some do not. The following examples show two possible ways 3592to force a break. 3593 3594The first workaround uses the @code{br} request to force a break after 3595printing the term or label. 3596 3597@Example 3598@cartouche 3599A glossary-style list: 3600.IP lawyers 0.4i 3601Two or more attorneys. 3602.IP guns 3603.br 3604Firearms, preferably large-caliber. 3605.IP money 3606Gotta pay for those lawyers and guns! 3607@end cartouche 3608@endExample 3609 3610The second workaround uses the @code{\p} escape to force the break. 3611Note the space following the escape; this is important. If you omit 3612the space, @code{groff} prints the first word on the same line as the 3613term or label (if it fits) @strong{then} breaks the line. 3614 3615@Example 3616@cartouche 3617A glossary-style list: 3618.IP lawyers 0.4i 3619Two or more attorneys. 3620.IP guns 3621\p Firearms, preferably large-caliber. 3622.IP money 3623Gotta pay for those lawyers and guns! 3624@end cartouche 3625@endExample 3626 3627To set nested lists, use the @code{RS} and @code{RE} macros. 3628@xref{Indentation values in ms}, for more information. 3629@cindex @code{ms} macros, nested lists 3630@cindex nested lists [@code{ms}] 3631 3632For example: 3633 3634@Example 3635@cartouche 3636.IP \[bu] 2 3637Lawyers: 3638.RS 3639.IP \[bu] 3640Dewey, 3641.IP \[bu] 3642Cheatham, 3643.IP \[bu] 3644and Howe. 3645.RE 3646.IP \[bu] 3647Guns 3648@end cartouche 3649@endExample 3650 3651Produces: 3652 3653@Example 3654o Lawyers: 3655 3656 o Dewey, 3657 3658 o Cheatham, 3659 3660 o and Howe. 3661 3662o Guns 3663@endExample 3664 3665@c --------------------------------------------------------------------- 3666 3667@node Indentation values in ms, Tabstops in ms, Lists in ms, ms Body Text 3668@subsubsection Indentation values 3669 3670In many situations, you may need to indentation a section of text 3671while still wrapping and filling. @xref{Lists in ms}, for an example 3672of nested lists. 3673 3674@DefmacList {RS, , ms} 3675@DefmacListEnd {RE, , ms} 3676These macros begin and end an indented section. The @code{PI} 3677register controls the amount of indentation, allowing the indented 3678text to line up under hanging and indented paragraphs. 3679@endDefmac 3680 3681@xref{ms Displays and Keeps}, for macros to indentation and turn off 3682filling. 3683 3684@c --------------------------------------------------------------------- 3685 3686@node Tabstops in ms, ms Displays and Keeps, Indentation values in ms, ms Body Text 3687@subsubsection Tab Stops 3688 3689Use the @code{ta} request to define tab stops as needed. @xref{Tabs 3690and Fields}. 3691 3692@Defmac{TA, , ms} 3693Use this macro to reset the tab stops to the default for @file{ms} 3694(every 5n). You can redefine the @code{TA} macro to create a 3695different set of default tab stops. 3696@endDefmac 3697 3698@c --------------------------------------------------------------------- 3699 3700@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text 3701@subsubsection Displays and keeps 3702@cindex @code{ms} macros, displays 3703@cindex @code{ms} macros, keeps 3704@cindex keeps [@code{ms}] 3705@cindex displays [@code{ms}] 3706 3707Use displays to show text-based examples or figures (such as code 3708listings). 3709 3710Displays turn off filling, so lines of code are displayed as-is 3711without inserting @code{br} requests in between each line. Displays 3712can be @dfn{kept} on a single page, or allowed to break across pages. 3713 3714@DefmacList {DS, @t{L}, ms} 3715@DefmacItem {LD, , ms} 3716@DefmacListEnd {DE, , ms} 3717Left-justified display. The @samp{.DS L} call generates a page break, 3718if necessary, to keep the entire display on one page. The @code{LD} 3719macro allows the display to break across pages. The @code{DE} macro 3720ends the display. 3721@endDefmac 3722 3723@DefmacList {DS, @t{I}, ms} 3724@DefmacItem {ID, , ms} 3725@DefmacListEnd {DE, , ms} 3726Indents the display as defined by the @code{DI} register. The 3727@samp{.DS I} call generates a page break, if necessary, to keep the 3728entire display on one page. The @code{ID} macro allows the display to 3729break across pages. The @code{DE} macro ends the display. 3730@endDefmac 3731 3732@DefmacList {DS, @t{B}, ms} 3733@DefmacItem {BD, , ms} 3734@DefmacListEnd {DE, , ms} 3735Sets a block-centered display: the entire display is left-justified, 3736but indented so that the longest line in the display is centered on 3737the page. The @samp{.DS B} call generates a page break, if necessary, 3738to keep the entire display on one page. The @code{BD} macro allows 3739the display to break across pages. The @code{DE} macro ends the 3740display. 3741@endDefmac 3742 3743@DefmacList {DS, @t{C}, ms} 3744@DefmacItem {CD, , ms} 3745@DefmacListEnd {DE, , ms} 3746Sets a centered display: each line in the display is centered. The 3747@samp{.DS C} call generates a page break, if necessary, to keep the 3748entire display on one page. The @code{CD} macro allows the display to 3749break across pages. The @code{DE} macro ends the display. 3750@endDefmac 3751 3752@DefmacList {DS, @t{R}, ms} 3753@DefmacItem {RD, , ms} 3754@DefmacListEnd {DE, , ms} 3755Right-justifies each line in the display. The @samp{.DS R} call 3756generates a page break, if necessary, to keep the entire display on 3757one page. The @code{RD} macro allows the display to break across 3758pages. The @code{DE} macro ends the display. 3759@endDefmac 3760 3761@DefmacList {Ds, , ms} 3762@DefmacListEnd {De, , ms} 3763These two macros were formerly provided as aliases for @code{DS} and 3764@code{DE}, respectively. They have been removed, and should no longer 3765be used. The original implementations of @code{DS} and @code{DE} are 3766retained, and should be used instead. X11 documents which actually 3767use @code{Ds} and @code{De} always load a specific macro file from the 3768X11 distribution (@file{macros.t}) which provides proper definitions 3769for the two macros. 3770@endDefmac 3771 3772On occasion, you may want to @dfn{keep} other text together on a page. 3773For example, you may want to keep two paragraphs together, or a 3774paragraph that refers to a table (or list, or other item) immediately 3775following. The @file{ms} macros provide the @code{KS} and @code{KE} 3776macros for this purpose. 3777 3778@DefmacList {KS, , ms} 3779@DefmacListEnd {KE, , ms} 3780The @code{KS} macro begins a block of text to be kept on a single 3781page, and the @code{KE} macro ends the block. 3782@endDefmac 3783 3784@DefmacList {KF, , ms} 3785@DefmacListEnd {KE, , ms} 3786Specifies a @dfn{floating keep}; if the keep cannot fit on the current 3787page, @code{groff} holds the contents of the keep and allows text 3788following the keep (in the source file) to fill in the remainder of 3789the current page. When the page breaks, whether by an explicit 3790@code{bp} request or by reaching the end of the page, @code{groff} 3791prints the floating keep at the top of the new page. This is useful 3792for printing large graphics or tables that do not need to appear 3793exactly where specified. 3794@endDefmac 3795 3796You can also use the @code{ne} request to force a page break if there 3797is not enough vertical space remaining on the page. 3798 3799Use the following macros to draw a box around a section of text (such 3800as a display). 3801 3802@DefmacList {B1, , ms} 3803@DefmacListEnd {B2, , ms} 3804Marks the beginning and ending of text that is to have a box drawn 3805around it. The @code{B1} macro begins the box; the @code{B2} macro 3806ends it. Text in the box is automatically placed in a diversion 3807(keep). 3808@endDefmac 3809 3810@c --------------------------------------------------------------------- 3811 3812@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text 3813@subsubsection Tables, figures, equations, and references 3814@cindex @code{ms} macros, tables 3815@cindex @code{ms} macros, figures 3816@cindex @code{ms} macros, equations 3817@cindex @code{ms} macros, references 3818@cindex tables [@code{ms}] 3819@cindex figures [@code{ms}] 3820@cindex equations [@code{ms}] 3821@cindex references [@code{ms}] 3822 3823The @file{ms} macros support the standard @code{groff} preprocessors: 3824@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}. 3825@pindex tbl 3826@pindex pic 3827@pindex eqn 3828@pindex refer 3829You mark text meant for preprocessors by enclosing it 3830in pairs of tags as follows. 3831 3832@DefmacList {TS, [@code{H}], ms} 3833@DefmacListEnd {TE, , ms} 3834Denotes a table, to be processed by the @code{tbl} preprocessor. The 3835optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} to 3836create a running header with the information up to the @code{TH} 3837macro. @code{groff} prints the header at the beginning of the table; 3838if the table runs onto another page, @code{groff} prints the header on 3839the next page as well. 3840@endDefmac 3841 3842@DefmacList {PS, , ms} 3843@DefmacListEnd {PE, , ms} 3844Denotes a graphic, to be processed by the @code{pic} preprocessor. 3845You can create a @code{pic} file by hand, using the @acronym{AT&T} 3846@code{pic} manual available on the Web as a reference, or by using a 3847graphics program such as @code{xfig}. 3848@endDefmac 3849 3850@DefmacList {EQ, [@Var{align}], ms} 3851@DefmacListEnd {EN, , ms} 3852Denotes an equation, to be processed by the @code{eqn} preprocessor. 3853The optional @var{align} argument can be @code{C}, @code{L}, 3854or@tie{}@code{I} to center (the default), left-justify, or indent the 3855equation. 3856@endDefmac 3857 3858@DefmacList {[, , ms} 3859@DefmacListEnd {], , ms} 3860Denotes a reference, to be processed by the @code{refer} preprocessor. 3861The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive 3862reference to the preprocessor and the format of the bibliographic 3863database. 3864@endDefmac 3865 3866@menu 3867* Example multi-page table:: 3868@end menu 3869 3870@c --------------------------------------------------------------------- 3871 3872@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text 3873@subsubsection An example multi-page table 3874@cindex example markup, multi-page table [@code{ms}] 3875@cindex multi-page table, example markup [@code{ms}] 3876 3877The following is an example of how to set up a table that may print 3878across two or more pages. 3879 3880@Example 3881@cartouche 3882.TS H 3883allbox expand; 3884cb | cb . 3885Text ...of heading... 3886_ 3887.TH 3888.T& 3889l | l . 3890... the rest of the table follows... 3891.CW 3892.TE 3893@end cartouche 3894@endExample 3895 3896@c --------------------------------------------------------------------- 3897 3898@node ms Footnotes, , Example multi-page table, ms Body Text 3899@subsubsection Footnotes 3900@cindex @code{ms} macros, footnotes 3901@cindex footnotes [@code{ms}] 3902 3903The @file{ms} macro package has a flexible footnote system. You can 3904specify either numbered footnotes or symbolic footnotes (that is, 3905using a marker such as a dagger symbol). 3906 3907@Defstr {*, ms} 3908Specifies the location of a numbered footnote marker in the text. 3909@endDefesc 3910 3911@DefmacList {FS, , ms} 3912@DefmacListEnd {FE, , ms} 3913Specifies the text of the footnote. The default action is to create a 3914numbered footnote; you can create a symbolic footnote by specifying a 3915@dfn{mark} glyph (such as @code{\[dg]} for the dagger glyph) in the 3916body text and as an argument to the @code{FS} macro, followed by the 3917text of the footnote and the @code{FE} macro. 3918@endDefmac 3919 3920You can control how @code{groff} prints footnote numbers by changing 3921the value of the @code{FF} register. @xref{ms Document Control 3922Registers}. 3923 3924@cindex footnotes, and keeps [@code{ms}] 3925@cindex keeps, and footnotes [@code{ms}] 3926@cindex footnotes, and displays [@code{ms}] 3927@cindex displays, and footnotes [@code{ms}] 3928Footnotes can be safely used within keeps and displays, but you should 3929avoid using numbered footnotes within floating keeps. You can set a 3930second @code{\**} marker between a @code{\**} and its corresponding 3931@code{.FS} entry; as long as each @code{FS} macro occurs @emph{after} 3932the corresponding @code{\**} and the occurrences of @code{.FS} are in 3933the same order as the corresponding occurrences of @code{\**}. 3934 3935@c --------------------------------------------------------------------- 3936 3937@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms 3938@subsection Page layout 3939@cindex @code{ms} macros, page layout 3940@cindex page layout [@code{ms}] 3941 3942The default output from the @file{ms} macros provides a minimalist 3943page layout: it prints a single column, with the page number centered 3944at the top of each page. It prints no footers. 3945 3946You can change the layout by setting the proper number registers and 3947strings. 3948 3949@menu 3950* ms Headers and Footers:: 3951* ms Margins:: 3952* ms Multiple Columns:: 3953* ms TOC:: 3954* ms Strings and Special Characters:: 3955@end menu 3956 3957@c --------------------------------------------------------------------- 3958 3959@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout 3960@subsubsection Headers and footers 3961@cindex @code{ms} macros, headers 3962@cindex @code{ms} macros, footers 3963@cindex headers [@code{ms}] 3964@cindex footers [@code{ms}] 3965 3966For documents that do not distinguish between odd and even pages, set 3967the following strings: 3968 3969@DefstrList {LH, ms} 3970@DefstrItem {CH, ms} 3971@DefstrListEnd {RH, ms} 3972Sets the left, center, and right headers. 3973@endDefstr 3974 3975@DefstrList {LF, ms} 3976@DefstrItem {CF, ms} 3977@DefstrListEnd {RF, ms} 3978Sets the left, center, and right footers. 3979@endDefstr 3980 3981For documents that need different information printed in the even and 3982odd pages, use the following macros: 3983 3984@DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3985@DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3986@DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3987@DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3988The @code{OH} and @code{EH} macros define headers for the odd and even 3989pages; the @code{OF} and @code{EF} macros define footers for the odd 3990and even pages. This is more flexible than defining the individual 3991strings. 3992 3993You can replace the quote (@code{'}) marks with any character not 3994appearing in the header or footer text. 3995@endDefmac 3996 3997@c --------------------------------------------------------------------- 3998 3999@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout 4000@subsubsection Margins 4001@cindex @code{ms} macros, margins 4002 4003You control margins using a set of number registers. @xref{ms 4004Document Control Registers}, for details. 4005 4006@c --------------------------------------------------------------------- 4007 4008@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout 4009@subsubsection Multiple columns 4010@cindex @code{ms} macros, multiple columns 4011@cindex multiple columns [@code{ms}] 4012 4013The @file{ms} macros can set text in as many columns as will 4014reasonably fit on the page. The following macros are available; all 4015of them force a page break if a multi-column mode is already set. 4016However, if the current mode is single-column, starting a multi-column 4017mode does @emph{not} force a page break. 4018 4019@Defmac {1C, , ms} 4020Single-column mode. 4021@endDefmac 4022 4023@Defmac {2C, , ms} 4024Two-column mode. 4025@endDefmac 4026 4027@Defmac {MC, [@Var{width} [@Var{gutter}]], ms} 4028Multi-column mode. If you specify no arguments, it is equivalent to 4029the @code{2C} macro. Otherwise, @var{width} is the width of each 4030column and @var{gutter} is the space between columns. The 4031@code{MINGW} number register controls the default gutter width. 4032@endDefmac 4033 4034@c --------------------------------------------------------------------- 4035 4036@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout 4037@subsubsection Creating a table of contents 4038@cindex @code{ms} macros, creating table of contents 4039@cindex table of contents, creating [@code{ms}] 4040 4041The facilities in the @file{ms} macro package for creating a table of 4042contents are semi-automated at best. Assuming that you want the table 4043of contents to consist of the document's headings, you need to repeat 4044those headings wrapped in @code{XS} and @code{XE} macros. 4045 4046@DefmacList {XS, [@Var{page}], ms} 4047@DefmacItem {XA, [@Var{page}], ms} 4048@DefmacListEnd {XE, , ms} 4049These macros define a table of contents or an individual entry in the 4050table of contents, depending on their use. The macros are very 4051simple; they cannot indent a heading based on its level. The easiest 4052way to work around this is to add tabs to the table of contents 4053string. The following is an example: 4054 4055@Example 4056@cartouche 4057.NH 1 4058Introduction 4059.XS 4060Introduction 4061.XE 4062.LP 4063... 4064.CW 4065.NH 2 4066Methodology 4067.XS 4068Methodology 4069.XE 4070.LP 4071... 4072@end cartouche 4073@endExample 4074 4075You can manually create a table of contents by beginning with the 4076@code{XS} macro for the first entry, specifying the page number for 4077that entry as the argument to @code{XS}. Add subsequent entries using 4078the @code{XA} macro, specifying the page number for that entry as the 4079argument to @code{XA}. The following is an example: 4080 4081@Example 4082@cartouche 4083.XS 1 4084Introduction 4085.XA 2 4086A Brief History of the Universe 4087.XA 729 4088Details of Galactic Formation 4089... 4090.XE 4091@end cartouche 4092@endExample 4093@endDefmac 4094 4095@Defmac {TC, [@code{no}], ms} 4096Prints the table of contents on a new page, setting the page number 4097to@tie{}@strong{i} (Roman lowercase numeral one). You should usually 4098place this macro at the end of the file, since @code{groff} is a 4099single-pass formatter and can only print what has been collected up to 4100the point that the @code{TC} macro appears. 4101 4102The optional argument @code{no} suppresses printing the title 4103specified by the string register @code{TOC}. 4104@endDefmac 4105 4106@Defmac{PX, [@code{no}], ms} 4107Prints the table of contents on a new page, using the current page 4108numbering sequence. Use this macro to print a manually-generated 4109table of contents at the beginning of your document. 4110 4111The optional argument @code{no} suppresses printing the title 4112specified by the string register @code{TOC}. 4113@endDefmac 4114 4115The @cite{Groff and Friends HOWTO} includes a @code{sed} script that 4116automatically inserts @code{XS} and @code{XE} macro entries after each 4117heading in a document. 4118 4119Altering the @code{NH} macro to automatically build the table of 4120contents is perhaps initially more difficult, but would save a great 4121deal of time in the long run if you use @file{ms} regularly. 4122 4123@c --------------------------------------------------------------------- 4124 4125@node ms Strings and Special Characters, , ms TOC, ms Page Layout 4126@subsubsection Strings and Special Characters 4127@cindex @code{ms} macros, strings 4128@cindex @code{ms} macros, special characters 4129@cindex @code{ms} macros, accent marks 4130@cindex accent marks [@code{ms}] 4131@cindex special characters [@code{ms}] 4132@cindex strings [@code{ms}] 4133 4134The @file{ms} macros provide the following predefined strings. You 4135can change the string definitions to help in creating documents in 4136languages other than English. 4137 4138@Defstr {REFERENCES, ms} 4139Contains the string printed at the beginning of the references 4140(bibliography) page. The default is @samp{References}. 4141@endDefstr 4142 4143@Defstr {ABSTRACT, ms} 4144Contains the string printed at the beginning of the abstract. The 4145default is @samp{ABSTRACT}. 4146@endDefstr 4147 4148@Defstr {TOC, ms} 4149Contains the string printed at the beginning of the table of contents. 4150@endDefstr 4151 4152@DefstrList {MONTH1, ms} 4153@DefstrItem {MONTH2, ms} 4154@DefstrItem {MONTH3, ms} 4155@DefstrItem {MONTH4, ms} 4156@DefstrItem {MONTH5, ms} 4157@DefstrItem {MONTH6, ms} 4158@DefstrItem {MONTH7, ms} 4159@DefstrItem {MONTH8, ms} 4160@DefstrItem {MONTH9, ms} 4161@DefstrItem {MONTH10, ms} 4162@DefstrItem {MONTH11, ms} 4163@DefstrListEnd {MONTH12, ms} 4164Prints the full name of the month in dates. The default is 4165@samp{January}, @samp{February}, etc. 4166@endDefstr 4167 4168The following special characters are available@footnote{For an 4169explanation what special characters are see @ref{Special 4170Characters}.}: 4171 4172@Defstr {-, ms} 4173Prints an em dash. 4174@endDefstr 4175 4176@DefstrList {Q, ms} 4177@DefstrListEnd {U, ms} 4178Prints typographer's quotes in troff, and plain quotes in nroff. 4179@code{\*Q} is the left quote and @code{\*U} is the right quote. 4180@endDefstr 4181 4182Improved accent marks are available in the @file{ms} macros. 4183 4184@Defmac {AM, , ms} 4185Specify this macro at the beginning of your document to enable 4186extended accent marks and special characters. This is a Berkeley 4187extension. 4188 4189To use the accent marks, place them @strong{after} the character being 4190accented. 4191 4192Note that groff's native support for accents is superior to the 4193following definitions. 4194@endDefmac 4195 4196The following accent marks are available after invoking the @code{AM} 4197macro: 4198 4199@Defstr {\', ms} 4200Acute accent. 4201@endDefstr 4202 4203@Defstr {\`, ms} 4204Grave accent. 4205@endDefstr 4206 4207@Defstr {^, ms} 4208Circumflex. 4209@endDefstr 4210 4211@Defstr {\,, ms} 4212Cedilla. 4213@endDefstr 4214 4215@Defstr {~, ms} 4216Tilde. 4217@endDefstr 4218 4219@deffn String @t{\*[:]} 4220@ifnotinfo 4221@stindex : @r{[}ms@r{]} 4222@end ifnotinfo 4223@ifinfo 4224@stindex \*[@r{<colon>}] @r{[}ms@r{]} 4225@end ifinfo 4226Umlaut. 4227@end deffn 4228 4229@Defstr {v, ms} 4230Hacek. 4231@endDefstr 4232 4233@Defstr {_, ms} 4234Macron (overbar). 4235@endDefstr 4236 4237@Defstr {., ms} 4238Underdot. 4239@endDefstr 4240 4241@Defstr {o, ms} 4242Ring above. 4243@endDefstr 4244 4245The following are standalone characters available after invoking the 4246@code{AM} macro: 4247 4248@Defstr {?, ms} 4249Upside-down question mark. 4250@endDefstr 4251 4252@Defstr {!, ms} 4253Upside-down exclamation point. 4254@endDefstr 4255 4256@Defstr {8, ms} 4257German � ligature. 4258@endDefstr 4259 4260@Defstr {3, ms} 4261Yogh. 4262@endDefstr 4263 4264@Defstr {Th, ms} 4265Uppercase thorn. 4266@endDefstr 4267 4268@Defstr {th, ms} 4269Lowercase thorn. 4270@endDefstr 4271 4272@Defstr {D-, ms} 4273Uppercase eth. 4274@endDefstr 4275 4276@Defstr {d-, ms} 4277Lowercase eth. 4278@endDefstr 4279 4280@Defstr {q, ms} 4281Hooked o. 4282@endDefstr 4283 4284@Defstr {ae, ms} 4285Lowercase � ligature. 4286@endDefstr 4287 4288@Defstr {Ae, ms} 4289Uppercase � ligature. 4290@endDefstr 4291 4292@c --------------------------------------------------------------------- 4293 4294@node Differences from AT&T ms, Naming Conventions, ms Page Layout, ms 4295@subsection Differences from @acronym{AT&T} @file{ms} 4296@cindex @code{ms} macros, differences from @acronym{AT&T} 4297@cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences 4298 4299This section lists the (minor) differences between the @code{groff 4300-ms} macros and @acronym{AT&T} @code{troff -ms} macros. 4301 4302@itemize @bullet 4303@item 4304The internals of @code{groff -ms} differ from the internals of 4305@acronym{AT&T} @code{troff -ms}. Documents that depend upon 4306implementation details of @acronym{AT&T} @code{troff -ms} may not 4307format properly with @code{groff -ms}. 4308 4309@item 4310The general error-handling policy of @code{groff -ms} is to detect and 4311report errors, rather than silently to ignore them. 4312 4313@item 4314@code{groff -ms} does not work in compatibility mode (this is, with 4315the @option{-C} option). 4316 4317@item 4318There is no special support for typewriter-like devices. 4319 4320@item 4321@code{groff -ms} does not provide cut marks. 4322 4323@item 4324Multiple line spacing is not supported. Use a larger vertical spacing 4325instead. 4326 4327@item 4328Some @acronym{UNIX} @code{ms} documentation says that the @code{CW} 4329and @code{GW} number registers can be used to control the column width 4330and gutter width, respectively. These number registers are not used in 4331@code{groff -ms}. 4332 4333@item 4334Macros that cause a reset (paragraphs, headings, etc.@:) may change 4335the indentation. Macros that change the indentation do not increment 4336or decrement the indentation, but rather set it absolutely. This can 4337cause problems for documents that define additional macros of their 4338own. The solution is to use not the @code{in} request but instead the 4339@code{RS} and @code{RE} macros. 4340 4341@item 4342To make @code{groff -ms} use the default page offset (which also 4343specifies the left margin), the @code{PO} register must stay undefined 4344until the first @file{-ms} macro is evaluated. This implies that 4345@code{PO} should not be used early in the document, unless it is 4346changed also: Remember that accessing an undefined register 4347automatically defines it. 4348@end itemize 4349 4350@Defmpreg {GS, ms} 4351This number register is set to@tie{}1 by the @code{groff -ms} macros, 4352but it is not used by the @code{AT&T} @code{troff -ms} macros. 4353Documents that need to determine whether they are being formatted with 4354@code{AT&T} @code{troff -ms} or @code{groff -ms} should use this 4355number register. 4356@endDefmpreg 4357 4358@menu 4359* Missing ms Macros:: 4360* Additional ms Macros:: 4361@end menu 4362 4363@c --------------------------------------------------------------------- 4364 4365@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms 4366@subsubsection @code{troff} macros not appearing in @code{groff} 4367 4368Macros missing from @code{groff -ms} are cover page macros specific to 4369Bell Labs and Berkeley. The macros known to be missing are: 4370 4371@table @code 4372@item .TM 4373Technical memorandum; a cover sheet style 4374 4375@item .IM 4376Internal memorandum; a cover sheet style 4377 4378@item .MR 4379Memo for record; a cover sheet style 4380 4381@item .MF 4382Memo for file; a cover sheet style 4383 4384@item .EG 4385Engineer's notes; a cover sheet style 4386 4387@item .TR 4388Computing Science Tech Report; a cover sheet style 4389 4390@item .OK 4391Other keywords 4392 4393@item .CS 4394Cover sheet information 4395 4396@item .MH 4397A cover sheet macro 4398@end table 4399 4400@c --------------------------------------------------------------------- 4401 4402@node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms 4403@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff} 4404 4405The @code{groff -ms} macros have a few minor extensions 4406compared to the @acronym{AT&T} @code{troff -ms} macros. 4407 4408@Defmac {AM, , ms} 4409Improved accent marks. 4410@xref{ms Strings and Special Characters}, for details. 4411@endDefmac 4412 4413@Defmac {DS, @t{I}, ms} 4414Indented display. 4415The default behavior of @acronym{AT&T} @code{troff -ms} 4416was to indent; the @code{groff} default prints displays 4417flush left with the body text. 4418@endDefmac 4419 4420@Defmac {CW, , ms} 4421Print text in @code{constant width} (Courier) font. 4422@endDefmac 4423 4424@Defmac {IX, , ms} 4425Indexing term (printed on standard error). 4426You can write a script to capture and process an index 4427generated in this manner. 4428@endDefmac 4429 4430The following additional number registers 4431appear in @code{groff -ms}: 4432 4433@Defmpreg {MINGW, ms} 4434Specifies a minimum space 4435between columns (for multi-column output); this takes the 4436place of the @code{GW} register that was documented but apparently 4437not implemented in @acronym{AT&T} @code{troff}. 4438@endDefmpreg 4439 4440Several new string registers are available as well. 4441You can change these to handle (for example) the local language. 4442@xref{ms Strings and Special Characters}, for details. 4443 4444@c --------------------------------------------------------------------- 4445 4446@node Naming Conventions, , Differences from AT&T ms, ms 4447@subsection Naming Conventions 4448@cindex @code{ms} macros, naming conventions 4449@cindex naming conventions, @code{ms} macros 4450 4451The following conventions are used for names of macros, strings and 4452number registers. External names available to documents that use the 4453@code{groff -ms} macros contain only uppercase letters and digits. 4454 4455Internally the macros are divided into modules; naming conventions are 4456as follows: 4457 4458@itemize @bullet 4459@item 4460Names used only within one module are of the form 4461@var{module}@code{*}@var{name}. 4462 4463@item 4464Names used outside the module in which they are defined are of the 4465form @var{module}@code{@@}@var{name}. 4466 4467@item 4468Names associated with a particular environment are of the form 4469@var{environment}@code{:}@var{name}; these are used only within the 4470@code{par} module. 4471 4472@item 4473@var{name} does not have a module prefix. 4474 4475@item 4476Constructed names used to implement arrays are of the form 4477@var{array}@code{!}@var{index}. 4478@end itemize 4479 4480Thus the groff ms macros reserve the following names: 4481 4482@itemize @bullet 4483@item 4484Names containing the characters @code{*}, @code{@@}, 4485and@tie{}@code{:}. 4486 4487@item 4488Names containing only uppercase letters and digits. 4489@end itemize 4490 4491 4492@c ===================================================================== 4493 4494@node me, mm, ms, Macro Packages 4495@section @file{me} 4496@cindex @code{me} macro package 4497 4498@c XXX documentation 4499@c XXX this is a placeholder until we get stuff knocked into shape 4500See the @file{meintro.me} and @file{meref.me} documents in 4501groff's @file{doc} directory. 4502 4503 4504@c ===================================================================== 4505 4506@node mm, , me, Macro Packages 4507@section @file{mm} 4508@cindex @code{mm} macro package 4509 4510@c XXX documentation 4511@c XXX this is a placeholder until we get stuff knocked into shape 4512See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at 4513the command line). 4514 4515 4516@c ===================================================================== 4517@c ===================================================================== 4518 4519@node gtroff Reference, Preprocessors, Macro Packages, Top 4520@chapter @code{gtroff} Reference 4521@cindex reference, @code{gtroff} 4522@cindex @code{gtroff}, reference 4523 4524This chapter covers @strong{all} of the facilities of @code{gtroff}. 4525Users of macro packages may skip it if not interested in details. 4526 4527 4528@menu 4529* Text:: 4530* Measurements:: 4531* Expressions:: 4532* Identifiers:: 4533* Embedded Commands:: 4534* Registers:: 4535* Manipulating Filling and Adjusting:: 4536* Manipulating Hyphenation:: 4537* Manipulating Spacing:: 4538* Tabs and Fields:: 4539* Character Translations:: 4540* Troff and Nroff Mode:: 4541* Line Layout:: 4542* Line Control:: 4543* Page Layout:: 4544* Page Control:: 4545* Fonts and Symbols:: 4546* Sizes:: 4547* Strings:: 4548* Conditionals and Loops:: 4549* Writing Macros:: 4550* Page Motions:: 4551* Drawing Requests:: 4552* Traps:: 4553* Diversions:: 4554* Environments:: 4555* Suppressing output:: 4556* Colors:: 4557* I/O:: 4558* Postprocessor Access:: 4559* Miscellaneous:: 4560* Gtroff Internals:: 4561* Debugging:: 4562* Implementation Differences:: 4563@end menu 4564 4565 4566@c ===================================================================== 4567 4568@node Text, Measurements, gtroff Reference, gtroff Reference 4569@section Text 4570@cindex text, @code{gtroff} processing 4571 4572@code{gtroff} input files contain text with control commands 4573interspersed throughout. But, even without control codes, @code{gtroff} 4574still does several things with the input text: 4575 4576@itemize @bullet 4577@item 4578filling and adjusting 4579 4580@item 4581adding additional space after sentences 4582 4583@item 4584hyphenating 4585 4586@item 4587inserting implicit line breaks 4588@end itemize 4589 4590@menu 4591* Filling and Adjusting:: 4592* Hyphenation:: 4593* Sentences:: 4594* Tab Stops:: 4595* Implicit Line Breaks:: 4596* Input Conventions:: 4597* Input Encodings:: 4598@end menu 4599 4600@c --------------------------------------------------------------------- 4601 4602@node Filling and Adjusting, Hyphenation, Text, Text 4603@subsection Filling and Adjusting 4604@cindex filling 4605@cindex adjusting 4606 4607When @code{gtroff} reads text, it collects words from the input and fits 4608as many of them together on one output line as it can. This is known as 4609@dfn{filling}. 4610 4611@cindex leading spaces 4612@cindex spaces, leading and trailing 4613@cindex extra spaces 4614@cindex trailing spaces 4615Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} 4616it. This means it widens the spacing between words until the text 4617reaches the right margin (in the default adjustment mode). Extra spaces 4618between words are preserved, but spaces at the end of lines are ignored. 4619Spaces at the front of a line cause a @dfn{break} (breaks are 4620explained in @ref{Implicit Line Breaks}). 4621 4622@xref{Manipulating Filling and Adjusting}. 4623 4624@c --------------------------------------------------------------------- 4625 4626@node Hyphenation, Sentences, Filling and Adjusting, Text 4627@subsection Hyphenation 4628@cindex hyphenation 4629 4630Since the odds are not great for finding a set of words, for every 4631output line, which fit nicely on a line without inserting excessive 4632amounts of space between words, @code{gtroff} hyphenates words so 4633that it can justify lines without inserting too much space between 4634words. It uses an internal hyphenation algorithm (a simplified version 4635of the algorithm used within @TeX{}) to indicate which words can be 4636hyphenated and how to do so. When a word is hyphenated, the first part 4637of the word is added to the current filled line being output (with 4638an attached hyphen), and the other portion is added to the next 4639line to be filled. 4640 4641@xref{Manipulating Hyphenation}. 4642 4643@c --------------------------------------------------------------------- 4644 4645@node Sentences, Tab Stops, Hyphenation, Text 4646@subsection Sentences 4647@cindex sentences 4648 4649Although it is often debated, some typesetting rules say there should be 4650different amounts of space after various punctuation marks. For 4651example, the @cite{Chicago typsetting manual} says that a period at the 4652end of a sentence should have twice as much space following it as would 4653a comma or a period as part of an abbreviation. 4654 4655@c XXX exact citation of Chicago manual 4656 4657@cindex sentence space 4658@cindex space between sentences 4659@cindex french-spacing 4660@code{gtroff} does this by flagging certain characters (normally 4661@samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters. 4662When @code{gtroff} encounters one of these characters at the end of a 4663line, it appends a normal space followed by a @dfn{sentence space} in 4664the formatted output. (This justifies one of the conventions mentioned 4665in @ref{Input Conventions}.) 4666 4667@cindex transparent characters 4668@cindex character, transparent 4669@cindex @code{dg} glyph, at end of sentence 4670@cindex @code{rq} glyph, at end of sentence 4671@cindex @code{"}, at end of sentence 4672@cindex @code{'}, at end of sentence 4673@cindex @code{)}, at end of sentence 4674@cindex @code{]}, at end of sentence 4675@cindex @code{*}, at end of sentence 4676In addition, the following characters and symbols are treated 4677transparently while handling end-of-sentence characters: @samp{"}, 4678@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}. 4679 4680See the @code{cflags} request in @ref{Using Symbols}, for more details. 4681 4682@cindex @code{\&}, at end of sentence 4683To prevent the insertion of extra space after an end-of-sentence 4684character (at the end of a line), append @code{\&}. 4685 4686@c --------------------------------------------------------------------- 4687 4688@node Tab Stops, Implicit Line Breaks, Sentences, Text 4689@subsection Tab Stops 4690@cindex tab stops 4691@cindex stops, tabulator 4692@cindex tab character 4693@cindex character, tabulator 4694 4695@cindex @acronym{EBCDIC} encoding 4696@cindex encoding, @acronym{EBCDIC} 4697@code{gtroff} translates @dfn{tabulator characters}, also called 4698@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or 4699@acronym{EBCDIC} @code{0x05}), in the input into movements to the next 4700tabulator stop. These tab stops are initially located every half inch 4701across the page. Using this, simple tables can be made easily. 4702However, it can often be deceptive as the appearance (and width) of the 4703text on a terminal and the results from @code{gtroff} can vary greatly. 4704 4705Also, a possible sticking point is that lines beginning with tab 4706characters are still filled, again producing unexpected results. 4707For example, the following input 4708 4709@multitable {12345678} {12345678} {12345678} {12345678} 4710@item 4711@tab 1 @tab 2 @tab 3 4712@item 4713@tab @tab 4 @tab 5 4714@end multitable 4715 4716@noindent 4717produces 4718 4719@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} 4720@item 4721@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5 4722@end multitable 4723 4724@xref{Tabs and Fields}. 4725 4726@c --------------------------------------------------------------------- 4727 4728@node Implicit Line Breaks, Input Conventions, Tab Stops, Text 4729@subsection Implicit Line Breaks 4730@cindex implicit line breaks 4731@cindex implicit breaks of lines 4732@cindex line, implicit breaks 4733@cindex break, implicit 4734@cindex line break 4735 4736An important concept in @code{gtroff} is the @dfn{break}. When a break 4737occurs, @code{gtroff} outputs the partially filled line 4738(unjustified), and resumes collecting and filling text on the next output 4739line. 4740 4741@cindex blank line 4742@cindex empty line 4743@cindex line, blank 4744@cindex blank line macro (@code{blm}) 4745There are several ways to cause a break in @code{gtroff}. A blank 4746line not only causes a break, but it also outputs a one-line vertical 4747space (effectively a blank line). Note that this behaviour can be 4748modified with the blank line macro request @code{blm}. 4749@xref{Blank Line Traps}. 4750 4751@cindex fill mode 4752@cindex mode, fill 4753A line that begins with a space causes a break and the space is 4754output at the beginning of the next line. Note that this space isn't 4755adjusted, even in fill mode. 4756 4757The end of file also causes a break -- otherwise the last line of 4758the document may vanish! 4759 4760Certain requests also cause breaks, implicitly or explicitly. This is 4761discussed in @ref{Manipulating Filling and Adjusting}. 4762 4763@c --------------------------------------------------------------------- 4764 4765@node Input Conventions, Input Encodings, Implicit Line Breaks, Text 4766@subsection Input Conventions 4767@cindex input conventions 4768@cindex conventions for input 4769 4770Since @code{gtroff} does filling automatically, it is traditional in 4771@code{groff} not to try and type things in as nicely formatted 4772paragraphs. These are some conventions commonly used when typing 4773@code{gtroff} text: 4774 4775@itemize @bullet 4776@item 4777Break lines after punctuation, particularly at the end of a sentence 4778and in other logical places. Keep separate phrases on lines by 4779themselves, as entire phrases are often added or deleted when editing. 4780 4781@item 4782Try to keep lines less than 40-60@tie{}characters, to allow space for 4783inserting more text. 4784 4785@item 4786Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., 4787don't try using spaces to get proper indentation). 4788@end itemize 4789 4790@c --------------------------------------------------------------------- 4791 4792@node Input Encodings, , Input Conventions, Text 4793@subsection Input Encodings 4794 4795Currently, the following input encodings are available. 4796 4797@table @asis 4798@item cp1047 4799@cindex encoding, input, @acronym{EBCDIC} 4800@cindex @acronym{EBCDIC}, input encoding 4801@cindex input encoding, @acronym{EBCDIC} 4802@cindex encoding, input, cp1047 4803@cindex cp1047, input encoding 4804@cindex input encoding, cp1047 4805@cindex IBM cp1047 input encoding 4806@pindex cp1047.tmac 4807This input encoding works only on @acronym{EBCDIC} platforms (and vice 4808versa, the other input encodings don't work with @acronym{EBCDIC}); the 4809file @file{cp1047.tmac} is by default loaded at start-up. 4810 4811@item latin-1 4812@cindex encoding, input, @w{latin-1} (ISO @w{8859-1}) 4813@cindex @w{latin-1} (ISO @w{8859-1}), input encoding 4814@cindex ISO @w{8859-1} (@w{latin-1}), input encoding 4815@cindex input encoding, @w{latin-1} (ISO @w{8859-1}) 4816@pindex latin1.tmac 4817This is the default input encoding on non-@acronym{EBCDIC} platforms; 4818the file @file{latin1.tmac} is loaded at start-up. 4819 4820@item latin-2 4821@cindex encoding, input, @w{latin-2} (ISO @w{8859-2}) 4822@cindex @w{latin-2} (ISO @w{8859-2}), input encoding 4823@cindex ISO @w{8859-2} (@w{latin-2}), input encoding 4824@cindex input encoding, @w{latin-2} (ISO @w{8859-2}) 4825@pindex latin2.tmac 4826To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very 4827beginning of your document or use @samp{-mlatin2} as a command line 4828argument for @code{groff}. 4829 4830@item latin-9 (latin-0) 4831@cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15}) 4832@cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding 4833@cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding 4834@cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15}) 4835@pindex latin9.tmac 4836This encoding is intended (at least in Europe) to replace @w{latin-1} 4837encoding. The main difference to @w{latin-1} is that @w{latin-9} 4838contains the Euro character. To use this encoding, either say 4839@w{@samp{.mso latin9.tmac}} at the very beginning of your document or 4840use @samp{-mlatin9} as a command line argument for @code{groff}. 4841@end table 4842 4843Note that it can happen that some input encoding characters are not 4844available for a particular output device. For example, saying 4845 4846@Example 4847groff -Tlatin1 -mlatin9 ... 4848@endExample 4849 4850@noindent 4851will fail if you use the Euro character in the input. Usually, this 4852limitation is present only for devices which have a limited set of 4853output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other 4854devices it is usually sufficient to install proper fonts which contain 4855the necessary glyphs. 4856 4857@pindex freeeuro.pfa 4858@pindex ec.tmac 4859Due to the importance of the Euro glyph in Europe, the groff package now 4860comes with a @sc{PostScript} font called @file{freeeuro.pfa} which 4861provides various glyph shapes for the Euro. With other words, 4862@w{latin-9} encoding is supported for the @option{-Tps} device out of 4863the box (@w{latin-2} isn't). 4864 4865By its very nature, @option{-Tutf8} supports all input encodings; 4866@option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the 4867command line @option{-mec} is used also to load the file @file{ec.tmac} 4868(which flips to the EC fonts). 4869 4870 4871@c ===================================================================== 4872 4873@node Measurements, Expressions, Text, gtroff Reference 4874@section Measurements 4875@cindex measurements 4876 4877@cindex units of measurement 4878@cindex basic unit (@code{u}) 4879@cindex machine unit (@code{u}) 4880@cindex measurement unit 4881@cindex @code{u} unit 4882@cindex unit, @code{u} 4883@code{gtroff} (like many other programs) requires numeric parameters to 4884specify various measurements. Most numeric parameters@footnote{those 4885that specify vertical or horizontal motion or a type size} may have a 4886@dfn{measurement unit} attached. These units are specified as a single 4887character which immediately follows the number or expression. Each of 4888these units are understood, by @code{gtroff}, to be a multiple of its 4889@dfn{basic unit}. So, whenever a different measurement unit is 4890specified @code{gtroff} converts this into its @dfn{basic units}. This 4891basic unit, represented by a @samp{u}, is a device dependent measurement 4892which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an 4893inch. The values may be given as fractional numbers; however, 4894fractional basic units are always rounded to integers. 4895 4896Some of the measurement units are completely independent of any of the 4897current settings (e.g.@: type size) of @code{gtroff}. 4898 4899@table @code 4900@item i 4901@cindex inch unit (@code{i}) 4902@cindex @code{i} unit 4903@cindex unit, @code{i} 4904Inches. An antiquated measurement unit still in use in certain 4905backwards countries with incredibly low-cost computer equipment. One 4906inch is equal to@tie{}2.54@dmn{cm}. 4907 4908@item c 4909@cindex centimeter unit (@code{c}) 4910@cindex @code{c} unit 4911@cindex unit, @code{c} 4912Centimeters. One centimeter is equal to@tie{}0.3937@dmn{in}. 4913 4914@item p 4915@cindex point unit (@code{p}) 4916@cindex @code{p} unit 4917@cindex unit, @code{p} 4918Points. This is a typesetter's measurement used for measure type size. 4919It is 72@tie{}points to an inch. 4920 4921@item P 4922@cindex pica unit (@code{P}) 4923@cindex @code{P} unit 4924@cindex unit, @code{P} 4925Pica. Another typesetting measurement. 6@tie{}Picas to an inch (and 492612@tie{}points to a pica). 4927 4928@item s 4929@itemx z 4930@cindex @code{s} unit 4931@cindex unit, @code{s} 4932@cindex @code{z} unit 4933@cindex unit, @code{z} 4934@xref{Fractional Type Sizes}, for a discussion of these units. 4935 4936@item f 4937@cindex @code{f} unit 4938@cindex unit, @code{f} 4939Fractions. Value is 65536. 4940@xref{Colors}, for usage. 4941@end table 4942 4943The other measurements understood by @code{gtroff} depend on 4944settings currently in effect in @code{gtroff}. These are very useful 4945for specifying measurements which should look proper with any size of 4946text. 4947 4948@table @code 4949@item m 4950@cindex em unit (@code{m}) 4951@cindex @code{m} unit 4952@cindex unit, @code{m} 4953Ems. This unit is equal to the current font size in points. So called 4954because it is @emph{approximately} the width of the letter@tie{}@samp{m} 4955in the current font. 4956 4957@item n 4958@cindex en unit (@code{n}) 4959@cindex @code{n} unit 4960@cindex unit, @code{n} 4961Ens. In @code{groff}, this is half of an em. 4962 4963@item v 4964@cindex vertical space unit (@code{v}) 4965@cindex space, vertical, unit (@code{v}) 4966@cindex @code{v} unit 4967@cindex unit, @code{v} 4968Vertical space. This is equivalent to the current line spacing. 4969@xref{Sizes}, for more information about this. 4970 4971@item M 4972@cindex @code{M} unit 4973@cindex unit, @code{M} 4974100ths of an em. 4975@end table 4976 4977@menu 4978* Default Units:: 4979@end menu 4980 4981@c --------------------------------------------------------------------- 4982 4983@node Default Units, , Measurements, Measurements 4984@subsection Default Units 4985@cindex default units 4986@cindex units, default 4987 4988Many requests take a default unit. While this can be helpful at times, 4989it can cause strange errors in some expressions. For example, the line 4990length request expects em units. Here are several attempts to get a 4991line length of 3.5@tie{}inches and their results: 4992 4993@Example 49943.5i @result{} 3.5i 49957/2 @result{} 0i 49967/2i @result{} 0i 4997(7 / 2)u @result{} 0i 49987i/2 @result{} 0.1i 49997i/2u @result{} 3.5i 5000@endExample 5001 5002@noindent 5003Everything is converted to basic units first. In the above example it 5004is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m} 5005equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value 50067@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to 50071680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 50080.1@dmn{i}. As can be seen, a scaling indicator after a closing 5009parenthesis is simply ignored. 5010 5011@cindex measurements, specifying safely 5012Thus, the safest way to specify measurements is to always 5013attach a scaling indicator. If you want to multiply or divide by a 5014certain scalar value, use @samp{u} as the unit for that value. 5015 5016 5017@c ===================================================================== 5018 5019@node Expressions, Identifiers, Measurements, gtroff Reference 5020@section Expressions 5021@cindex expressions 5022 5023@code{gtroff} has most arithmetic operators common to other languages: 5024 5025@itemize @bullet 5026@item 5027@cindex arithmetic operators 5028@cindex operators, arithmetic 5029@opindex + 5030@opindex - 5031@opindex / 5032@opindex * 5033@opindex % 5034Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} 5035(division), @samp{*} (multiplication), @samp{%} (modulo). 5036 5037@code{gtroff} only provides integer arithmetic. The internal type used 5038for computing results is @samp{int}, which is usually a 32@dmn{bit} 5039signed integer. 5040 5041@item 5042@cindex comparison operators 5043@cindex operators, comparison 5044@opindex < 5045@opindex > 5046@opindex >= 5047@opindex <= 5048@opindex = 5049@opindex == 5050Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} 5051(less than or equal), @samp{>=} (greater than or equal), @samp{=} 5052(equal), @samp{==} (the same as @samp{=}). 5053 5054@item 5055@cindex logical operators 5056@cindex operators, logical 5057@opindex & 5058@ifnotinfo 5059@opindex : 5060@end ifnotinfo 5061@ifinfo 5062@opindex @r{<colon>} 5063@end ifinfo 5064Logical: @samp{&} (logical and), @samp{:} (logical or). 5065 5066@item 5067@cindex unary operators 5068@cindex operators, unary 5069@opindex - 5070@opindex + 5071@opindex ! 5072@cindex @code{if} request, and the @samp{!} operator 5073@cindex @code{while} request, and the @samp{!} operator 5074Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} 5075(just for completeness; does nothing in expressions), @samp{!} (logical 5076not; this works only within @code{if} and @code{while} requests). See 5077below for the use of unary operators in motion requests. 5078 5079@item 5080@cindex extremum operators (@code{>?}, @code{<?}) 5081@cindex operators, extremum (@code{>?}, @code{<?}) 5082@opindex >? 5083@opindex <? 5084Extrema: @samp{>?} (maximum), @samp{<?} (minimum). 5085 5086Example: 5087 5088@Example 5089.nr x 5 5090.nr y 3 5091.nr z (\n[x] >? \n[y]) 5092@endExample 5093 5094@noindent 5095The register@tie{}@code{z} now contains@tie{}5. 5096 5097@item 5098@cindex scaling operator 5099@cindex operator, scaling 5100Scaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c} 5101as the default scaling indicator. If @var{c} is missing, ignore scaling 5102indicators in the evaluation of@tie{}@var{e}. 5103@end itemize 5104 5105@cindex parentheses 5106@cindex order of evaluation in expressions 5107@cindex expression, order of evaluation 5108@opindex ( 5109@opindex ) 5110Parentheses may be used as in any other language. However, in 5111@code{gtroff} they are necessary to ensure order of evaluation. 5112@code{gtroff} has no operator precedence; expressions are evaluated left 5113to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were 5114parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be 5115expected. 5116 5117@cindex @code{+}, and page motion 5118@cindex @code{-}, and page motion 5119@cindex motion operators 5120@cindex operators, motion 5121For many requests which cause a motion on the page, the unary operators 5122@samp{+} and @samp{-} work differently if leading an expression. They 5123then indicate a motion relative to the current position (down or up, 5124respectively). 5125 5126@cindex @code{|}, and page motion 5127@cindex absolute position operator (@code{|}) 5128@cindex position, absolute, operator (@code{|}) 5129Similarly, a leading @samp{|} operator indicates an absolute position. 5130For vertical movements, it specifies the distance from the top of the 5131page; for horizontal movements, it gives the distance from the beginning 5132of the @emph{input} line. 5133 5134@cindex @code{bp} request, using @code{+} and@tie{}@code{-} 5135@cindex @code{in} request, using @code{+} and@tie{}@code{-} 5136@cindex @code{ll} request, using @code{+} and@tie{}@code{-} 5137@cindex @code{lt} request, using @code{+} and@tie{}@code{-} 5138@cindex @code{nm} request, using @code{+} and@tie{}@code{-} 5139@cindex @code{nr} request, using @code{+} and@tie{}@code{-} 5140@cindex @code{pl} request, using @code{+} and@tie{}@code{-} 5141@cindex @code{pn} request, using @code{+} and@tie{}@code{-} 5142@cindex @code{po} request, using @code{+} and@tie{}@code{-} 5143@cindex @code{ps} request, using @code{+} and@tie{}@code{-} 5144@cindex @code{pvs} request, using @code{+} and@tie{}@code{-} 5145@cindex @code{rt} request, using @code{+} and@tie{}@code{-} 5146@cindex @code{ti} request, using @code{+} and@tie{}@code{-} 5147@cindex @code{\H}, using @code{+} and@tie{}@code{-} 5148@cindex @code{\R}, using @code{+} and@tie{}@code{-} 5149@cindex @code{\s}, using @code{+} and@tie{}@code{-} 5150@samp{+} and @samp{-} are also treated differently by the following 5151requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, 5152@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, 5153@code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}. 5154Here, leading plus and minus signs indicate increments and decrements. 5155 5156@xref{Setting Registers}, for some examples. 5157 5158@Defesc {\\B, ', anything, '} 5159@cindex numeric expression, valid 5160@cindex valid numeric expression 5161Return@tie{}1 if @var{anything} is a valid numeric expression; 5162or@tie{}0 if @var{anything} is empty or not a valid numeric expression. 5163@endDefesc 5164 5165@cindex space characters, in expressions 5166@cindex expressions, and space characters 5167Due to the way arguments are parsed, spaces are not allowed in 5168expressions, unless the entire expression is surrounded by parentheses. 5169 5170@xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}. 5171 5172 5173@c ===================================================================== 5174 5175@node Identifiers, Embedded Commands, Expressions, gtroff Reference 5176@section Identifiers 5177@cindex identifiers 5178 5179Like any other language, @code{gtroff} has rules for properly formed 5180@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of 5181almost any printable character, with the exception of the following 5182characters: 5183 5184@itemize @bullet 5185@item 5186@cindex whitespace characters 5187@cindex newline character 5188@cindex character, whitespace 5189Whitespace characters (spaces, tabs, and newlines). 5190 5191@item 5192@cindex character, backspace 5193@cindex backspace character 5194@cindex @acronym{EBCDIC} encoding of backspace 5195Backspace (@acronym{ASCII}@tie{}@code{0x08} or 5196@acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}. 5197 5198@item 5199@cindex invalid input characters 5200@cindex input characters, invalid 5201@cindex characters, invalid input 5202@cindex Unicode 5203The following input characters are invalid and are ignored if 5204@code{groff} runs on a machine based on @acronym{ASCII}, causing a 5205warning message of type @samp{input} (see @ref{Debugging}, for more 5206details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F}, 5207@code{0x80}-@code{0x9F}. 5208 5209And here are the invalid input characters if @code{groff} runs on an 5210@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09}, 5211@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F}, 5212@code{0x30}-@code{0x3F}. 5213 5214Currently, some of these reserved codepoints are used internally, thus 5215making it non-trivial to extend @code{gtroff} to cover Unicode or other 5216character sets and encodings which use characters of these ranges. 5217 5218Note that invalid characters are removed before parsing; an 5219identifier @code{foo}, followed by an invalid character, followed by 5220@code{bar} is treated as @code{foobar}. 5221@end itemize 5222 5223For example, any of the following is valid. 5224 5225@Example 5226br 5227PP 5228(l 5229end-list 5230@@_ 5231@endExample 5232 5233@cindex @code{]}, as part of an identifier 5234@noindent 5235Note that identifiers longer than two characters with a closing bracket 5236(@samp{]}) in its name can't be accessed with escape sequences which 5237expect an identifier as a parameter. For example, @samp{\[foo]]} 5238accesses the glyph @samp{foo}, followed by @samp{]}, whereas 5239@samp{\C'foo]'} really asks for glyph @samp{foo]}. 5240 5241@cindex @code{refer}, and macro names starting with @code{[} or @code{]} 5242@cindex @code{[}, macro names starting with, and @code{refer} 5243@cindex @code{]}, macro names starting with, and @code{refer} 5244@cindex macro names, starting with @code{[} or @code{]}, and @code{refer} 5245To avoid problems with the @code{refer} preprocessor, macro names 5246should not start with @samp{[} or @samp{]}. Due to backwards 5247compatibility, everything after @samp{.[} and @samp{.]} is handled as 5248a special argument to @code{refer}. For example, @samp{.[foo} makes 5249@code{refer} to start a reference, using @samp{foo} as a parameter. 5250 5251@Defesc {\\A, ', ident, '} 5252Test whether an identifier @var{ident} is valid in @code{gtroff}. It 5253expands to the character@tie{}1 or@tie{}0 according to whether its 5254argument (usually delimited by quotes) is or is not acceptable as the 5255name of a string, macro, diversion, number register, environment, or 5256font. It returns@tie{}0 if no argument is given. This is useful for 5257looking up user input in some sort of associative table. 5258 5259@Example 5260\A'end-list' 5261 @result{} 1 5262@endExample 5263@endDefesc 5264 5265@xref{Escapes}, for details on parameter delimiting characters. 5266 5267Identifiers in @code{gtroff} can be any length, but, in some contexts, 5268@code{gtroff} needs to be told where identifiers end and text begins 5269(and in different ways depending on their length): 5270 5271@itemize @bullet 5272@item 5273Single character. 5274 5275@cindex @code{(}, starting a two-character identifier 5276@item 5277Two characters. Must be prefixed with @samp{(} in some situations. 5278 5279@cindex @code{[}, starting an identifier 5280@cindex @code{]}, ending an identifier 5281@item 5282Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} 5283and@tie{}@samp{]} in some situations. Any length identifier can be put 5284in brackets. 5285@end itemize 5286 5287@cindex undefined identifiers 5288@cindex identifiers, undefined 5289Unlike many other programming languages, undefined identifiers are 5290silently ignored or expanded to nothing. 5291When @code{gtroff} finds an undefined identifier, it emits a 5292warning, doing the following: 5293 5294@itemize @bullet 5295@item 5296If the identifier is a string, macro, or diversion, 5297@code{gtroff} defines it as empty. 5298 5299@item 5300If the identifier is a number register, @code{gtroff} 5301defines it with a value of@tie{}0. 5302@end itemize 5303 5304@xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}. 5305 5306Note that macros, strings, and diversions share the same name space. 5307 5308@Example 5309.de xxx 5310. nop foo 5311.. 5312. 5313.di xxx 5314bar 5315.br 5316.di 5317. 5318.xxx 5319 @result{} bar 5320@endExample 5321 5322@noindent 5323As can be seen in the previous example, @code{gtroff} reuses the 5324identifier @samp{xxx}, changing it from a macro to a diversion. 5325No warning is emitted! The contents of the first macro definition is 5326lost. 5327 5328@xref{Interpolating Registers}, and @ref{Strings}. 5329 5330 5331@c ===================================================================== 5332 5333@node Embedded Commands, Registers, Identifiers, gtroff Reference 5334@section Embedded Commands 5335@cindex embedded commands 5336@cindex commands, embedded 5337 5338Most documents need more functionality beyond filling, adjusting and 5339implicit line breaking. In order to gain further functionality, 5340@code{gtroff} allows commands to be embedded into the text, in two ways. 5341 5342The first is a @dfn{request} which takes up an entire line, and does 5343some large-scale operation (e.g.@: break lines, start new pages). 5344 5345The other is an @dfn{escape} which can be usually embedded anywhere 5346in the text; most requests can accept it even as an argument. 5347Escapes generally do more minor operations like sub- and superscripts, 5348print a symbol, etc. 5349 5350@menu 5351* Requests:: 5352* Macros:: 5353* Escapes:: 5354@end menu 5355 5356@c --------------------------------------------------------------------- 5357 5358@node Requests, Macros, Embedded Commands, Embedded Commands 5359@subsection Requests 5360@cindex requests 5361 5362@cindex control character (@code{.}) 5363@cindex character, control (@code{.}) 5364@cindex no-break control character (@code{'}) 5365@cindex character, no-break control (@code{'}) 5366@cindex control character, no-break (@code{'}) 5367A request line begins with a control character, which is either a single 5368quote (@samp{'}, the @dfn{no-break control character}) or a period 5369(@samp{.}, the normal @dfn{control character}). These can be changed; 5370see @ref{Character Translations}, for details. After this there may be 5371optional tabs or spaces followed by an identifier which is the name of 5372the request. This may be followed by any number of space-separated 5373arguments (@emph{no} tabs here). 5374 5375@cindex structuring source code of documents or macro packages 5376@cindex documents, structuring the source code 5377@cindex macro packages, structuring the source code 5378Since a control character followed by whitespace only is ignored, it 5379is common practice to use this feature for structuring the source code 5380of documents or macro packages. 5381 5382@Example 5383.de foo 5384. tm This is foo. 5385.. 5386. 5387. 5388.de bar 5389. tm This is bar. 5390.. 5391@endExample 5392 5393@cindex blank line 5394@cindex blank line macro (@code{blm}) 5395Another possibility is to use the blank line macro request @code{blm} 5396by assigning an empty macro to it. 5397 5398@Example 5399.de do-nothing 5400.. 5401.blm do-nothing \" activate blank line macro 5402 5403.de foo 5404. tm This is foo. 5405.. 5406 5407 5408.de bar 5409. tm This is bar. 5410.. 5411 5412.blm \" deactivate blank line macro 5413@endExample 5414 5415@xref{Blank Line Traps}. 5416 5417@cindex zero width space character (@code{\&}) 5418@cindex character, zero width space (@code{\&}) 5419@cindex space character, zero width (@code{\&}) 5420@cindex @code{\&}, escaping control characters 5421To begin a line with a control character without it being interpreted, 5422precede it with @code{\&}. This represents a zero width space, which 5423means it does not affect the output. 5424 5425In most cases the period is used as a control character. Several 5426requests cause a break implicitly; using the single quote control 5427character prevents this. 5428 5429@menu 5430* Request and Macro Arguments:: 5431@end menu 5432 5433@node Request and Macro Arguments, , Requests, Requests 5434@subsubsection Request and Macro Arguments 5435@cindex request arguments 5436@cindex macro arguments 5437@cindex arguments to requests and macros 5438 5439Arguments to requests and macros are processed much like the shell: 5440The line is split into arguments according to 5441spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows 5442tabs for argument separation -- @code{gtroff} intentionally doesn't 5443support this.} 5444 5445@cindex spaces, in a macro argument 5446An argument to a macro which is intended to contain spaces can either be 5447enclosed in double quotes, or have the spaces @dfn{escaped} with 5448backslashes. This is @emph{not} true for requests. 5449 5450Here are a few examples for a hypothetical macro @code{uh}: 5451 5452@Example 5453.uh The Mouse Problem 5454.uh "The Mouse Problem" 5455.uh The\ Mouse\ Problem 5456@endExample 5457 5458@cindex @code{\~}, difference to @code{\@key{SP}} 5459@cindex @code{\@key{SP}}, difference to @code{\~} 5460@noindent 5461The first line is the @code{uh} macro being called with 3 arguments, 5462@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the 5463same effect of calling the @code{uh} macro with one argument, @samp{The 5464Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces, 5465is ``classical'' in the sense that it can be found in most @code{troff} 5466documents. Nevertheless, it is not optimal in all situations, since 5467@w{@samp{\ }} inserts a fixed-width, non-breaking space character which 5468can't stretch. @code{gtroff} provides a different command @code{\~} to 5469insert a stretchable, non-breaking space.} 5470 5471@cindex @code{"}, in a macro argument 5472@cindex double quote, in a macro argument 5473A double quote which isn't preceded by a space doesn't start a macro 5474argument. If not closing a string, it is printed literally. 5475 5476For example, 5477 5478@Example 5479.xxx a" "b c" "de"fg" 5480@endExample 5481 5482@noindent 5483has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}. 5484Don't rely on this obscure behaviour! 5485 5486There are two possibilities to get a double quote reliably. 5487 5488@itemize @bullet 5489@item 5490Enclose the whole argument with double quotes and use two consecutive double 5491quotes to represent a single one. This traditional solution has the 5492disadvantage that double quotes don't survive argument expansion again if 5493called in compatibility mode (using the @option{-C} option of @code{groff}): 5494 5495@Example 5496.de xx 5497. tm xx: `\\$1' `\\$2' `\\$3' 5498. 5499. yy "\\$1" "\\$2" "\\$3" 5500.. 5501.de yy 5502. tm yy: `\\$1' `\\$2' `\\$3' 5503.. 5504.xx A "test with ""quotes""" . 5505 @result{} xx: `A' `test with "quotes"' `.' 5506 @result{} yy: `A' `test with ' `quotes""' 5507@endExample 5508 5509@noindent 5510If not in compatibility mode, you get the expected result 5511 5512@Example 5513xx: `A' `test with "quotes"' `.' 5514yy: `A' `test with "quotes"' `.' 5515@endExample 5516 5517@noindent 5518since @code{gtroff} preserves the input level. 5519 5520@item 5521Use the double quote glyph @code{\(dq}. This works with and without 5522compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq} 5523back to a double quote input character. 5524 5525Not that this method won't work with @acronym{UNIX} @code{troff} in general 5526since the glyph `dq' isn't defined normally. 5527@end itemize 5528 5529@cindex @code{ds} request, and double quotes 5530Double quotes in the @code{ds} request are handled differently. 5531@xref{Strings}, for more details. 5532 5533@c --------------------------------------------------------------------- 5534 5535@node Macros, Escapes, Requests, Embedded Commands 5536@subsection Macros 5537@cindex macros 5538 5539@code{gtroff} has a @dfn{macro} facility for defining a series of lines 5540which can be invoked by name. They are called in the same manner as 5541requests -- arguments also may be passed basically in the same manner. 5542 5543@xref{Writing Macros}, and @ref{Request and Macro Arguments}. 5544 5545@c --------------------------------------------------------------------- 5546 5547@node Escapes, , Macros, Embedded Commands 5548@subsection Escapes 5549@cindex escapes 5550 5551Escapes may occur anywhere in the input to @code{gtroff}. They usually 5552begin with a backslash and are followed by a single character which 5553indicates the function to be performed. The escape character can be 5554changed; see @ref{Character Translations}. 5555 5556Escape sequences which require an identifier as a parameter accept three 5557possible syntax forms. 5558 5559@itemize @bullet 5560@item 5561The next single character is the identifier. 5562 5563@cindex @code{(}, starting a two-character identifier 5564@item 5565If this single character is an opening parenthesis, take the following 5566two characters as the identifier. Note that there is no closing 5567parenthesis after the identifier. 5568 5569@cindex @code{[}, starting an identifier 5570@cindex @code{]}, ending an identifier 5571@item 5572If this single character is an opening bracket, take all characters 5573until a closing bracket as the identifier. 5574@end itemize 5575 5576@noindent 5577Examples: 5578 5579@Example 5580\fB 5581\n(XX 5582\*[TeX] 5583@endExample 5584 5585@cindex @code{'}, delimiting arguments 5586@cindex argument delimiting characters 5587@cindex characters, argument delimiting 5588@cindex delimiting characters for arguments 5589Other escapes may require several arguments and/or some special format. 5590In such cases the argument is traditionally enclosed in single quotes 5591(and quotes are always used in this manual for the definitions of escape 5592sequences). The enclosed text is then processed according to what that 5593escape expects. Example: 5594 5595@Example 5596\l'1.5i\(bu' 5597@endExample 5598 5599@cindex @code{\o}, possible quote characters 5600@cindex @code{\b}, possible quote characters 5601@cindex @code{\X}, possible quote characters 5602Note that the quote character can be replaced with any other character 5603which does not occur in the argument (even a newline or a space 5604character) in the following escapes: @code{\o}, @code{\b}, and 5605@code{\X}. This makes e.g. 5606 5607@Example 5608A caf 5609\o 5610e\' 5611 5612 5613in Paris 5614 @result{} A caf� in Paris 5615@endExample 5616 5617@noindent 5618possible, but it is better not to use this feature to avoid confusion. 5619 5620@cindex @code{\%}, used as delimiter 5621@cindex @code{\@key{SP}}, used as delimiter 5622@cindex @code{\|}, used as delimiter 5623@cindex @code{\^}, used as delimiter 5624@cindex @code{\@{}, used as delimiter 5625@cindex @code{\@}}, used as delimiter 5626@cindex @code{\'}, used as delimiter 5627@cindex @code{\`}, used as delimiter 5628@cindex @code{\-}, used as delimiter 5629@cindex @code{\_}, used as delimiter 5630@cindex @code{\!}, used as delimiter 5631@cindex @code{\?}, used as delimiter 5632@cindex @code{\@@}, used as delimiter 5633@cindex @code{\)}, used as delimiter 5634@cindex @code{\/}, used as delimiter 5635@cindex @code{\,}, used as delimiter 5636@cindex @code{\&}, used as delimiter 5637@ifnotinfo 5638@cindex @code{\:}, used as delimiter 5639@end ifnotinfo 5640@ifinfo 5641@cindex @code{\@r{<colon>}}, used as delimiter 5642@end ifinfo 5643@cindex @code{\~}, used as delimiter 5644@cindex @code{\0}, used as delimiter 5645@cindex @code{\a}, used as delimiter 5646@cindex @code{\c}, used as delimiter 5647@cindex @code{\d}, used as delimiter 5648@cindex @code{\e}, used as delimiter 5649@cindex @code{\E}, used as delimiter 5650@cindex @code{\p}, used as delimiter 5651@cindex @code{\r}, used as delimiter 5652@cindex @code{\t}, used as delimiter 5653@cindex @code{\u}, used as delimiter 5654The following escapes sequences (which are handled similarly to 5655characters since they don't take a parameter) are also allowed as 5656delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, 5657@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 5658@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, 5659@code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, 5660@code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. 5661Again, don't use these if possible. 5662 5663@cindex @code{\A}, allowed delimiters 5664@cindex @code{\B}, allowed delimiters 5665@cindex @code{\Z}, allowed delimiters 5666@cindex @code{\C}, allowed delimiters 5667@cindex @code{\w}, allowed delimiters 5668No newline characters as delimiters are allowed in the following 5669escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}. 5670 5671@cindex @code{\D}, allowed delimiters 5672@cindex @code{\h}, allowed delimiters 5673@cindex @code{\H}, allowed delimiters 5674@cindex @code{\l}, allowed delimiters 5675@cindex @code{\L}, allowed delimiters 5676@cindex @code{\N}, allowed delimiters 5677@cindex @code{\R}, allowed delimiters 5678@cindex @code{\s}, allowed delimiters 5679@cindex @code{\S}, allowed delimiters 5680@cindex @code{\v}, allowed delimiters 5681@cindex @code{\x}, allowed delimiters 5682Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l}, 5683@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, 5684and @code{\x} can't use the following characters as delimiters: 5685 5686@itemize @bullet 5687@item 5688@cindex numbers, and delimiters 5689@cindex digits, and delimiters 5690The digits @code{0}-@code{9}. 5691 5692@item 5693@cindex operators, as delimiters 5694@cindex @code{+}, as delimiter 5695@cindex @code{-}, as delimiter 5696@cindex @code{/}, as delimiter 5697@cindex @code{*}, as delimiter 5698@cindex @code{%}, as delimiter 5699@cindex @code{<}, as delimiter 5700@cindex @code{>}, as delimiter 5701@cindex @code{=}, as delimiter 5702@cindex @code{&}, as delimiter 5703@ifnotinfo 5704@cindex @code{:}, as delimiter 5705@end ifnotinfo 5706@ifinfo 5707@cindex <colon>, as delimiter 5708@end ifinfo 5709@cindex @code{(}, as delimiter 5710@cindex @code{)}, as delimiter 5711@cindex @code{.}, as delimiter 5712The (single-character) operators @samp{+-/*%<>=&:().}. 5713 5714@item 5715@cindex space character 5716@cindex character, space 5717@cindex tab character 5718@cindex character, tab 5719@cindex newline character 5720@cindex character, newline 5721The space, tab, and newline characters. 5722 5723@item 5724@cindex @code{\%}, used as delimiter 5725@ifnotinfo 5726@cindex @code{\:}, used as delimiter 5727@end ifnotinfo 5728@ifinfo 5729@cindex @code{\@r{<colon>}}, used as delimiter 5730@end ifinfo 5731@cindex @code{\@{}, used as delimiter 5732@cindex @code{\@}}, used as delimiter 5733@cindex @code{\'}, used as delimiter 5734@cindex @code{\`}, used as delimiter 5735@cindex @code{\-}, used as delimiter 5736@cindex @code{\_}, used as delimiter 5737@cindex @code{\!}, used as delimiter 5738@cindex @code{\@@}, used as delimiter 5739@cindex @code{\/}, used as delimiter 5740@cindex @code{\c}, used as delimiter 5741@cindex @code{\e}, used as delimiter 5742@cindex @code{\p}, used as delimiter 5743All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}}, 5744@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@}, 5745@code{\/}, @code{\c}, @code{\e}, and @code{\p}. 5746@end itemize 5747 5748@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 5749@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 5750To have a backslash (actually, the current escape character) appear in the 5751output several escapes are defined: @code{\\}, @code{\e} or @code{\E}. 5752These are very similar, and only differ with respect to being used in 5753macros or diversions. @xref{Character Translations}, for an exact 5754description of those escapes. 5755 5756@xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions}, 5757@ref{Identifiers}, for more information. 5758 5759@menu 5760* Comments:: 5761@end menu 5762 5763@node Comments, , Escapes, Escapes 5764@subsubsection Comments 5765@cindex comments 5766 5767Probably one of the most@footnote{Unfortunately, this is a lie. But 5768hopefully future @code{gtroff} hackers will believe it @code{:-)}} 5769common forms of escapes is the comment. 5770 5771@Defesc {\\", , , } 5772Start a comment. Everything to the end of the input line is ignored. 5773 5774This may sound simple, but it can be tricky to keep the comments from 5775interfering with the appearance of the final output. 5776 5777@cindex @code{ds}, @code{ds1} requests, and comments 5778@cindex @code{as}, @code{as1} requests, and comments 5779If the escape is to the right of some text or a request, that portion 5780of the line is ignored, but the space leading up to it is noticed by 5781@code{gtroff}. This only affects the @code{ds} and @code{as} 5782request and its variants. 5783 5784@cindex tabs, before comments 5785@cindex comments, lining up with tabs 5786One possibly irritating idiosyncracy is that tabs must not be used to 5787line up comments. Tabs are not treated as whitespace between the 5788request and macro arguments. 5789 5790@cindex undefined request 5791@cindex request, undefined 5792A comment on a line by itself is treated as a blank line, because 5793after eliminating the comment, that is all that remains: 5794 5795@Example 5796Test 5797\" comment 5798Test 5799@endExample 5800 5801@noindent 5802produces 5803 5804@Example 5805Test 5806 5807Test 5808@endExample 5809 5810To avoid this, it is common to start the line with @code{.\"} which 5811causes the line to be treated as an undefined request and thus ignored 5812completely. 5813 5814@cindex @code{'}, as a comment 5815Another commenting scheme seen sometimes is three consecutive single 5816quotes (@code{'''}) at the beginning of a line. This works, but 5817@code{gtroff} gives a warning about an undefined macro (namely 5818@code{''}), which is harmless, but irritating. 5819@endDefesc 5820 5821@Defesc {\\#, , , } 5822To avoid all this, @code{gtroff} has a new comment mechanism using the 5823@code{\#} escape. This escape works the same as @code{\"} except that 5824the newline is also ignored: 5825 5826@Example 5827Test 5828\# comment 5829Test 5830@endExample 5831 5832@noindent 5833produces 5834 5835@Example 5836Test Test 5837@endExample 5838 5839@noindent 5840as expected. 5841@endDefesc 5842 5843@Defreq {ig, [@Var{end}]} 5844Ignore all input until @code{gtroff} encounters the macro named 5845@code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not 5846specified). This is useful for commenting out large blocks of text: 5847 5848@Example 5849text text text... 5850.ig 5851This is part of a large block 5852of text that has been 5853temporarily(?) commented out. 5854 5855We can restore it simply by removing 5856the .ig request and the ".." at the 5857end of the block. 5858.. 5859More text text text... 5860@endExample 5861 5862@noindent 5863produces 5864 5865@Example 5866text text text@dots{} More text text text@dots{} 5867@endExample 5868 5869@noindent 5870Note that the commented-out block of text does not 5871cause a break. 5872 5873The input is read in copy-mode; auto-incremented registers @emph{are} 5874affected (@pxref{Auto-increment}). 5875@endDefreq 5876 5877 5878@c ===================================================================== 5879 5880@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference 5881@section Registers 5882@cindex registers 5883 5884Numeric variables in @code{gtroff} are called @dfn{registers}. There 5885are a number of built-in registers, supplying anything from the date to 5886details of formatting parameters. 5887 5888@xref{Identifiers}, for details on register identifiers. 5889 5890@menu 5891* Setting Registers:: 5892* Interpolating Registers:: 5893* Auto-increment:: 5894* Assigning Formats:: 5895* Built-in Registers:: 5896@end menu 5897 5898@c --------------------------------------------------------------------- 5899 5900@node Setting Registers, Interpolating Registers, Registers, Registers 5901@subsection Setting Registers 5902@cindex setting registers (@code{nr}, @code{\R}) 5903@cindex registers, setting (@code{nr}, @code{\R}) 5904 5905Define or set registers using the @code{nr} request or the 5906@code{\R} escape. 5907 5908@DefreqList {nr, ident value} 5909@DefescListEnd {\\R, ', ident value, '} 5910Set number register @var{ident} to @var{value}. If @var{ident} 5911doesn't exist, @code{gtroff} creates it. 5912 5913The argument to @code{\R} usually has to be enclosed in quotes. 5914@xref{Escapes}, for details on parameter delimiting characters. 5915 5916The @code{\R} escape doesn't produce an input token in @code{gtroff}; 5917with other words, it vanishes completely after @code{gtroff} has 5918processed it. 5919@endDefreq 5920 5921For example, the following two lines are equivalent: 5922 5923@Example 5924.nr a (((17 + (3 * 4))) % 4) 5925\R'a (((17 + (3 * 4))) % 4)' 5926 @result{} 1 5927@endExample 5928 5929Both @code{nr} and @code{\R} have two additional special forms to 5930increment or decrement a register. 5931 5932@DefreqList {nr, ident @t{+}@Var{value}} 5933@DefreqItem {nr, ident @t{-}@Var{value}} 5934@DefescItem {\\R, ', ident @t{+}value, '} 5935@DefescListEnd {\\R, ', ident @t{-}value, '} 5936Increment (decrement) register @var{ident} by @var{value}. 5937 5938@Example 5939.nr a 1 5940.nr a +1 5941\na 5942 @result{} 2 5943@endExample 5944 5945@cindex negating register values 5946To assign the negated value of a register to another register, some care 5947must be taken to get the desired result: 5948 5949@Example 5950.nr a 7 5951.nr b 3 5952.nr a -\nb 5953\na 5954 @result{} 4 5955.nr a (-\nb) 5956\na 5957 @result{} -3 5958@endExample 5959 5960@noindent 5961The surrounding parentheses prevent the interpretation of the minus sign 5962as a decrementing operator. An alternative is to start the assignment 5963with a @samp{0}: 5964 5965@Example 5966.nr a 7 5967.nr b -3 5968.nr a \nb 5969\na 5970 @result{} 4 5971.nr a 0\nb 5972\na 5973 @result{} -3 5974@endExample 5975@endDefreq 5976 5977@Defreq {rr, ident} 5978@cindex removing number register (@code{rr}) 5979@cindex number register, removing (@code{rr}) 5980@cindex register, removing (@code{rr}) 5981Remove number register @var{ident}. If @var{ident} doesn't exist, the 5982request is ignored. 5983@endDefreq 5984 5985@Defreq {rnn, ident1 ident2} 5986@cindex renaming number register (@code{rnn}) 5987@cindex number register, renaming (@code{rnn}) 5988@cindex register, renaming (@code{rnn}) 5989Rename number register @var{ident1} to @var{ident2}. If either 5990@var{ident1} or @var{ident2} doesn't exist, the request is ignored. 5991@endDefreq 5992 5993@Defreq {aln, ident1 ident2} 5994@cindex alias, number register, creating (@code{aln}) 5995@cindex creating alias, for number register (@code{aln}) 5996@cindex number register, creating alias (@code{aln}) 5997@cindex register, creating alias (@code{aln}) 5998Create an alias @var{ident1} for a number register @var{ident2}. The 5999new name and the old name are exactly equivalent. If @var{ident1} is 6000undefined, a warning of type @samp{reg} is generated, and the request 6001is ignored. @xref{Debugging}, for information about warnings. 6002@endDefreq 6003 6004@c --------------------------------------------------------------------- 6005 6006@node Interpolating Registers, Auto-increment, Setting Registers, Registers 6007@subsection Interpolating Registers 6008@cindex interpolating registers (@code{\n}) 6009@cindex registers, interpolating (@code{\n}) 6010 6011Numeric registers can be accessed via the @code{\n} escape. 6012 6013@DefescList {\\n, , i, } 6014@DefescItem {\\n, @Lparen{}, id, } 6015@DefescListEnd {\\n, @Lbrack{}, ident, @Rbrack{}} 6016@cindex nested assignments 6017@cindex assignments, nested 6018@cindex indirect assignments 6019@cindex assignments, indirect 6020Interpolate number register with name @var{ident} (one-character 6021name@tie{}@var{i}, two-character name @var{id}). This means that the value 6022of the register is expanded in-place while @code{gtroff} is parsing the 6023input line. Nested assignments (also called indirect assignments) are 6024possible. 6025 6026@Example 6027.nr a 5 6028.nr as \na+\na 6029\n(as 6030 @result{} 10 6031@endExample 6032 6033@Example 6034.nr a1 5 6035.nr ab 6 6036.ds str b 6037.ds num 1 6038\n[a\n[num]] 6039 @result{} 5 6040\n[a\*[str]] 6041 @result{} 6 6042@endExample 6043@endDefesc 6044 6045@c --------------------------------------------------------------------- 6046 6047@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 6048@subsection Auto-increment 6049@cindex auto-increment 6050@cindex increment, automatic 6051 6052Number registers can also be auto-incremented and auto-decremented. 6053The increment or decrement value can be specified with a third 6054argument to the @code{nr} request or @code{\R} escape. 6055 6056@Defreq {nr, ident value incr} 6057@cindex @code{\R}, difference to @code{nr} 6058Set number register @var{ident} to @var{value}; the increment for 6059auto-incrementing is set to @var{incr}. Note that the @code{\R} 6060escape doesn't support this notation. 6061@endDefreq 6062 6063To activate auto-incrementing, the escape @code{\n} has a special 6064syntax form. 6065 6066@DefescList {\\n, +, i, } 6067@DefescItem {\\n, -, i, } 6068@DefescItem {\\n, @Lparen{}+, id, } 6069@DefescItem {\\n, @Lparen{}-, id, } 6070@DefescItem {\\n, +@Lparen{}, id, } 6071@DefescItem {\\n, -@Lparen{}, id, } 6072@DefescItem {\\n, @Lbrack{}+, ident, @Rbrack{}} 6073@DefescItem {\\n, @Lbrack{}-, ident, @Rbrack{}} 6074@DefescItem {\\n, +@Lbrack{}, ident, @Rbrack{}} 6075@DefescListEnd {\\n, -@Lbrack{}, ident, @Rbrack{}} 6076Before interpolating, increment or decrement @var{ident} 6077(one-character name@tie{}@var{i}, two-character name @var{id}) by the 6078auto-increment value as specified with the @code{nr} request (or the 6079@code{\R} escape). If no auto-increment value has been specified, 6080these syntax forms are identical to @code{\n}. 6081@endDefesc 6082 6083For example, 6084 6085@Example 6086.nr a 0 1 6087.nr xx 0 5 6088.nr foo 0 -2 6089\n+a, \n+a, \n+a, \n+a, \n+a 6090.br 6091\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 6092.br 6093\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 6094@endExample 6095 6096@noindent 6097produces 6098 6099@Example 61001, 2, 3, 4, 5 6101-5, -10, -15, -20, -25 6102-2, -4, -6, -8, -10 6103@endExample 6104 6105@cindex increment value without changing the register 6106@cindex value, incrementing without changing the register 6107To change the increment value without changing the value of a register 6108(@var{a} in the example), the following can be used: 6109 6110@Example 6111.nr a \na 10 6112@endExample 6113 6114@c --------------------------------------------------------------------- 6115 6116@node Assigning Formats, Built-in Registers, Auto-increment, Registers 6117@subsection Assigning Formats 6118@cindex assigning formats (@code{af}) 6119@cindex formats, assigning (@code{af}) 6120 6121When a register is used in the text of an input file (as opposed to 6122part of an expression), it is textually replaced (or interpolated) 6123with a representation of that number. This output format can be 6124changed to a variety of formats (numbers, Roman numerals, etc.). This 6125is done using the @code{af} request. 6126 6127@Defreq {af, ident format} 6128Change the output format of a number register. The first argument 6129@var{ident} is the name of the number register to be changed, and the 6130second argument @var{format} is the output format. The following 6131output formats are available: 6132 6133@table @code 6134@item 1 6135Decimal arabic numbers. This is the default format: 0, 1, 2, 61363,@tie{}@enddots{} 6137 6138@item 0@dots{}0 6139Decimal numbers with as many digits as specified. So, @samp{00} would 6140result in printing numbers as 01, 02, 03,@tie{}@enddots{} 6141 6142In fact, any digit instead of zero will do; @code{gtroff} only counts 6143how many digits are specified. As a consequence, @code{af}'s default 6144format @samp{1} could be specified as @samp{0} also (and exactly this is 6145returned by the @code{\g} escape, see below). 6146 6147@item I 6148@cindex Roman numerals 6149@cindex numerals, Roman 6150Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{} 6151 6152@item i 6153Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{} 6154 6155@item A 6156Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{} 6157 6158@item a 6159Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{} 6160@end table 6161 6162Omitting the number register format causes a warning of type 6163@samp{missing}. @xref{Debugging}, for more details. Specifying a 6164nonexistent format causes an error. 6165 6166The following example produces @samp{10, X, j, 010}: 6167 6168@Example 6169.nr a 10 6170.af a 1 \" the default format 6171\na, 6172.af a I 6173\na, 6174.af a a 6175\na, 6176.af a 001 6177\na 6178@endExample 6179 6180@cindex Roman numerals, maximum and minimum 6181@cindex maximum values of Roman numerals 6182@cindex minimum values of Roman numerals 6183The largest number representable for the @samp{i} and @samp{I} formats 6184is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z} 6185and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does 6186@code{gtroff}. Currently, the correct glyphs of Roman numeral five 6187thousand and Roman numeral ten thousand (Unicode code points 6188@code{U+2182} and @code{U+2181}, respectively) are not available. 6189 6190If @var{ident} doesn't exist, it is created. 6191 6192@cindex read-only register, changing format 6193@cindex changing format, and read-only registers 6194Changing the output format of a read-only register causes an error. It 6195is necessary to first copy the register's value to a writeable register, 6196then apply the @code{af} request to this other register. 6197@endDefreq 6198 6199@DefescList {\\g, , i, } 6200@DefescItem {\\g, @Lparen{}, id, } 6201@DefescListEnd {\\g, @Lbrack{}, ident, @Rbrack{}} 6202@cindex format of register (@code{\g}) 6203@cindex register, format (@code{\g}) 6204Return the current format of the specified register @var{ident} 6205(one-character name@tie{}@var{i}, two-character name @var{id}). For 6206example, @samp{\ga} after the previous example would produce the 6207string @samp{000}. If the register hasn't been defined yet, nothing 6208is returned. 6209@endDefesc 6210 6211@c --------------------------------------------------------------------- 6212 6213@node Built-in Registers, , Assigning Formats, Registers 6214@subsection Built-in Registers 6215@cindex built-in registers 6216@cindex registers, built-in 6217 6218The following lists some built-in registers which are not described 6219elsewhere in this manual. Any register which begins with a @samp{.} is 6220read-only. A complete listing of all built-in registers can be found in 6221@ref{Register Index}. 6222 6223@table @code 6224@item \n[.F] 6225@cindex current input file name register (@code{.F}) 6226@cindex input file name, current, register (@code{.F}) 6227@vindex .F 6228This string-valued register returns the current input file name. 6229 6230@item \n[.H] 6231@cindex horizontal resolution register (@code{.H}) 6232@cindex resolution, horizontal, register (@code{.H}) 6233@vindex .H 6234Horizontal resolution in basic units. 6235 6236@item \n[.U] 6237@cindex safer mode 6238@cindex mode, safer 6239@cindex unsafe mode 6240@cindex mode, unsafe 6241If @code{gtroff} is called with the @option{-U} command line option, the 6242number register @code{.U} is set to@tie{}1, and zero otherwise. 6243@xref{Groff Options}. 6244 6245@item \n[.V] 6246@cindex vertical resolution register (@code{.V}) 6247@cindex resolution, vertical, register (@code{.V}) 6248@vindex .V 6249Vertical resolution in basic units. 6250 6251@item \n[seconds] 6252@cindex seconds, current time (@code{seconds}) 6253@cindex time, current, seconds (@code{seconds}) 6254@cindex current time, seconds (@code{seconds}) 6255@vindex seconds 6256The number of seconds after the minute, normally in the range@tie{}0 6257to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized 6258at start-up of @code{gtroff}. 6259 6260@item \n[minutes] 6261@cindex minutes, current time (@code{minutes}) 6262@cindex time, current, minutes (@code{minutes}) 6263@cindex current time, minutes (@code{minutes}) 6264@vindex minutes 6265The number of minutes after the hour, in the range@tie{}0 to@tie{}59. 6266Initialized at start-up of @code{gtroff}. 6267 6268@item \n[hours] 6269@cindex hours, current time (@code{hours}) 6270@cindex time, current, hours (@code{hours}) 6271@cindex current time, hours (@code{hours}) 6272@vindex hours 6273The number of hours past midnight, in the range@tie{}0 to@tie{}23. 6274Initialized at start-up of @code{gtroff}. 6275 6276@item \n[dw] 6277@cindex day of the week register (@code{dw}) 6278@cindex date, day of the week register (@code{dw}) 6279@vindex dw 6280Day of the week (1-7). 6281 6282@item \n[dy] 6283@cindex day of the month register (@code{dy}) 6284@cindex date, day of the month register (@code{dy}) 6285@vindex dy 6286Day of the month (1-31). 6287 6288@item \n[mo] 6289@cindex month of the year register (@code{mo}) 6290@cindex date, month of the year register (@code{mo}) 6291@vindex mo 6292Current month (1-12). 6293 6294@item \n[year] 6295@cindex date, year register (@code{year}, @code{yr}) 6296@cindex year, current, register (@code{year}, @code{yr}) 6297@vindex year 6298The current year. 6299 6300@item \n[yr] 6301@vindex yr 6302The current year minus@tie{}1900. Unfortunately, the documentation of 6303@acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It 6304incorrectly claimed that @code{yr} contains the last two digits of the 6305year. That claim has never been true of either @acronym{AT&T} 6306@code{troff} or GNU @code{troff}. Old @code{troff} input that looks 6307like this: 6308 6309@Example 6310'\" The following line stopped working after 1999 6311This document was formatted in 19\n(yr. 6312@endExample 6313 6314@noindent 6315can be corrected as follows: 6316 6317@Example 6318This document was formatted in \n[year]. 6319@endExample 6320 6321@noindent 6322or, to be portable to older @code{troff} versions, as follows: 6323 6324@Example 6325.nr y4 1900+\n(yr 6326This document was formatted in \n(y4. 6327@endExample 6328 6329@item \n[.c] 6330@vindex .c 6331@itemx \n[c.] 6332@vindex c. 6333@cindex input line number register (@code{.c}, @code{c.}) 6334@cindex line number, input, register (@code{.c}, @code{c.}) 6335The current @emph{input} line number. Register @samp{.c} is read-only, 6336whereas @samp{c.} (a @code{gtroff} extension) is writable also, 6337affecting both @samp{.c} and @samp{c.}. 6338 6339@item \n[ln] 6340@vindex ln 6341@cindex output line number register (@code{ln}) 6342@cindex line number, output, register (@code{ln}) 6343The current @emph{output} line number after a call to the @code{nm} 6344request to activate line numbering. 6345 6346@xref{Miscellaneous}, for more information about line numbering. 6347 6348@item \n[.x] 6349@vindex .x 6350@cindex major version number register (@code{.x}) 6351@cindex version number, major, register (@code{.x}) 6352The major version number. For example, if the version number 6353is 1.03 then @code{.x} contains@tie{}@samp{1}. 6354 6355@item \n[.y] 6356@vindex .y 6357@cindex minor version number register (@code{.y}) 6358@cindex version number, minor, register (@code{.y}) 6359The minor version number. For example, if the version number 6360is 1.03 then @code{.y} contains@tie{}@samp{03}. 6361 6362@item \n[.Y] 6363@vindex .Y 6364@cindex revision number register (@code{.Y}) 6365The revision number of @code{groff}. 6366 6367@item \n[$$] 6368@vindex $$ 6369@cindex process ID of @code{gtroff} register (@code{$$}) 6370@cindex @code{gtroff}, process ID register (@code{$$}) 6371The process ID of @code{gtroff}. 6372 6373@item \n[.g] 6374@vindex .g 6375@cindex @code{gtroff}, identification register (@code{.g}) 6376@cindex GNU-specific register (@code{.g}) 6377Always@tie{}1. Macros should use this to determine whether they are 6378running under GNU @code{troff}. 6379 6380@item \n[.A] 6381@vindex .A 6382@cindex @acronym{ASCII} approximation output register (@code{.A}) 6383If the command line option @option{-a} is used to produce an 6384@acronym{ASCII} approximation of the output, this is set to@tie{}1, zero 6385otherwise. @xref{Groff Options}. 6386 6387@item \n[.P] 6388@vindex .P 6389This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current 6390page is actually being printed, i.e., if the @option{-o} option is being 6391used to only print selected pages. @xref{Groff Options}, for more 6392information. 6393 6394@item \n[.T] 6395@vindex .T 6396If @code{gtroff} is called with the @option{-T} command line option, the 6397number register @code{.T} is set to@tie{}1, and zero otherwise. 6398@xref{Groff Options}. 6399 6400@item \*[.T] 6401@stindex .T 6402@cindex output device name string register (@code{.T}) 6403A single read-write string register which contains the current output 6404device (for example, @samp{latin1} or @samp{ps}). This is the only 6405string register defined by @code{gtroff}. 6406@end table 6407 6408 6409@c ===================================================================== 6410 6411@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference 6412@section Manipulating Filling and Adjusting 6413@cindex manipulating filling and adjusting 6414@cindex filling and adjusting, manipulating 6415@cindex adjusting and filling, manipulating 6416@cindex justifying text 6417@cindex text, justifying 6418 6419@cindex break 6420@cindex line break 6421@cindex @code{bp} request, causing implicit linebreak 6422@cindex @code{ce} request, causing implicit linebreak 6423@cindex @code{cf} request, causing implicit linebreak 6424@cindex @code{fi} request, causing implicit linebreak 6425@cindex @code{fl} request, causing implicit linebreak 6426@cindex @code{in} request, causing implicit linebreak 6427@cindex @code{nf} request, causing implicit linebreak 6428@cindex @code{rj} request, causing implicit linebreak 6429@cindex @code{sp} request, causing implicit linebreak 6430@cindex @code{ti} request, causing implicit linebreak 6431@cindex @code{trf} request, causing implicit linebreak 6432Various ways of causing @dfn{breaks} were given in @ref{Implicit Line 6433Breaks}. The @code{br} request likewise causes a break. Several 6434other requests also cause breaks, but implicitly. These are 6435@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, 6436@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. 6437 6438@Defreq {br, } 6439Break the current line, i.e., the input collected so far is emitted 6440without adjustment. 6441 6442If the no-break control character is used, @code{gtroff} suppresses 6443the break: 6444 6445@Example 6446a 6447'br 6448b 6449 @result{} a b 6450@endExample 6451@endDefreq 6452 6453Initially, @code{gtroff} fills and adjusts text to both margins. 6454Filling can be disabled via the @code{nf} request and re-enabled with 6455the @code{fi} request. 6456 6457@DefreqList {fi, } 6458@DefregListEnd {.u} 6459@cindex fill mode (@code{fi}) 6460@cindex mode, fill (@code{fi}) 6461Activate fill mode (which is the default). This request implicitly 6462enables adjusting; it also inserts a break in the text currently being 6463filled. The read-only number register @code{.u} is set to@tie{}1. 6464 6465The fill mode status is associated with the current environment 6466(@pxref{Environments}). 6467 6468See @ref{Line Control}, for interaction with the @code{\c} escape. 6469@endDefreq 6470 6471@Defreq {nf, } 6472@cindex no-fill mode (@code{nf}) 6473@cindex mode, no-fill (@code{nf}) 6474Activate no-fill mode. Input lines are output as-is, retaining line 6475breaks and ignoring the current line length. This command implicitly 6476disables adjusting; it also causes a break. The number register 6477@code{.u} is set to@tie{}0. 6478 6479The fill mode status is associated with the current environment 6480(@pxref{Environments}). 6481 6482See @ref{Line Control}, for interaction with the @code{\c} escape. 6483@endDefreq 6484 6485@DefreqList {ad, [@Var{mode}]} 6486@DefregListEnd {.j} 6487Set adjusting mode. 6488 6489Activation and deactivation of adjusting is done implicitly with 6490calls to the @code{fi} or @code{nf} requests. 6491 6492@var{mode} can have one of the following values: 6493 6494@table @code 6495@item l 6496@cindex ragged-right 6497Adjust text to the left margin. This produces what is traditionally 6498called ragged-right text. 6499 6500@item r 6501@cindex ragged-left 6502Adjust text to the right margin, producing ragged-left text. 6503 6504@item c 6505@cindex centered text 6506@cindex @code{ce} request, difference to @samp{.ad@tie{}c} 6507Center filled text. This is different to the @code{ce} request which 6508only centers text without filling. 6509 6510@item b 6511@itemx n 6512Justify to both margins. This is the default used by @code{gtroff}. 6513@end table 6514 6515Finally, @var{mode} can be the numeric argument returned by the @code{.j} 6516register. 6517 6518With no argument, @code{gtroff} adjusts lines in the same way it did 6519before adjusting was deactivated (with a call to @code{na}, for 6520example). 6521 6522@Example 6523text 6524.ad r 6525.nr ad \n[.j] 6526text 6527.ad c 6528text 6529.na 6530text 6531.ad \" back to centering 6532text 6533.ad \n[ad] \" back to right justifying 6534@endExample 6535 6536@cindex adjustment mode register (@code{.j}) 6537The current adjustment mode is available in the read-only number 6538register @code{.j}; it can be stored and subsequently used to set 6539adjustment. 6540 6541The adjustment mode status is associated with the current environment 6542(@pxref{Environments}). 6543@endDefreq 6544 6545@Defreq {na, } 6546Disable adjusting. This request won't change the current adjustment 6547mode: A subsequent call to @code{ad} uses the previous adjustment 6548setting. 6549 6550The adjustment mode status is associated with the current environment 6551(@pxref{Environments}). 6552@endDefreq 6553 6554@DefreqList {brp, } 6555@DefescListEnd {\\p, , , } 6556Adjust the current line and cause a break. 6557 6558In most cases this produces very ugly results since @code{gtroff} 6559doesn't have a sophisticated paragraph building algorithm (as @TeX{} 6560have, for example); instead, @code{gtroff} fills and adjusts a paragraph 6561line by line: 6562 6563@Example 6564 This is an uninteresting sentence. 6565 This is an uninteresting sentence.\p 6566 This is an uninteresting sentence. 6567@endExample 6568 6569@noindent 6570is formatted as 6571 6572@Example 6573 This is an uninteresting sentence. This is an 6574 uninteresting sentence. 6575 This is an uninteresting sentence. 6576@endExample 6577@endDefreq 6578 6579@DefreqList {ss, word_space_size [@Var{sentence_space_size}]} 6580@DefregItem {.ss} 6581@DefregListEnd {.sss} 6582@cindex word space size register (@code{.ss}) 6583@cindex size of word space register (@code{.ss}) 6584@cindex space between words register (@code{.ss}) 6585@cindex sentence space size register (@code{.sss}) 6586@cindex size of sentence space register (@code{.sss}) 6587@cindex space between sentences register (@code{.sss}) 6588Change the size of a space between words. It takes its units as one 6589twelfth of the space width parameter for the current font. 6590Initially both the @var{word_space_size} and @var{sentence_space_size} 6591are@tie{}12. In fill mode, the values specify the minimum distance. 6592 6593@cindex fill mode 6594@cindex mode, fill 6595If two arguments are given to the @code{ss} request, the second 6596argument sets the sentence space size. If the second argument is not 6597given, sentence space size is set to @var{word_space_size}. The 6598sentence space size is used in two circumstances: If the end of a 6599sentence occurs at the end of a line in fill mode, then both an 6600inter-word space and a sentence space are added; if two spaces follow 6601the end of a sentence in the middle of a line, then the second space 6602is a sentence space. If a second argument is never given to the 6603@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the 6604same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as 6605in @acronym{UNIX} @code{troff}, a sentence should always be followed 6606by either a newline or two spaces. 6607 6608The read-only number registers @code{.ss} and @code{.sss} hold the 6609values of the parameters set by the first and second arguments of the 6610@code{ss} request. 6611 6612The word space and sentence space values are associated with the current 6613environment (@pxref{Environments}). 6614 6615Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not} 6616ignored if a TTY output device is used; the given values are then 6617rounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}). 6618 6619The request is ignored if there is no parameter. 6620 6621@cindex discardable horizontal space 6622@cindex space, discardable, horizontal 6623@cindex horizontal discardable space 6624Another useful application of the @code{ss} request is to insert 6625discardable horizontal space, i.e., space which is discarded at a line 6626break. For example, paragraph-style footnotes could be separated this 6627way: 6628 6629@Example 6630.ll 4.5i 66311.\ This is the first footnote.\c 6632.ss 48 6633.nop 6634.ss 12 66352.\ This is the second footnote. 6636@endExample 6637 6638@noindent 6639The result: 6640 6641@Example 66421. This is the first footnote. 2. This 6643is the second footnote. 6644@endExample 6645 6646@noindent 6647Note that the @code{\h} escape produces unbreakable space. 6648@endDefreq 6649 6650@DefreqList {ce, [@Var{nnn}]} 6651@DefregListEnd {.ce} 6652@cindex centering lines (@code{ce}) 6653@cindex lines, centering (@code{ce}) 6654Center text. While the @w{@samp{.ad c}} request also centers text, 6655it fills the text as well. @code{ce} does not fill the 6656text it affects. This request causes a break. The number of lines 6657still to be centered is associated with the current environment 6658(@pxref{Environments}). 6659 6660The following example demonstrates the differences. 6661Here the input: 6662 6663@Example 6664.ll 4i 6665.ce 1000 6666This is a small text fragment which shows the differences 6667between the `.ce' and the `.ad c' request. 6668.ce 0 6669 6670.ad c 6671This is a small text fragment which shows the differences 6672between the `.ce' and the `.ad c' request. 6673@endExample 6674 6675@noindent 6676And here the result: 6677 6678@Example 6679 This is a small text fragment which 6680 shows the differences 6681between the `.ce' and the `.ad c' request. 6682 6683 This is a small text fragment which 6684shows the differences between the `.ce' 6685 and the `.ad c' request. 6686@endExample 6687 6688With no arguments, @code{ce} centers the next line of text. @var{nnn} 6689specifies the number of lines to be centered. If the argument is zero 6690or negative, centering is disabled. 6691 6692The basic length for centering text is the line length (as set with the 6693@code{ll} request) minus the indentation (as set with the @code{in} 6694request). Temporary indentation is ignored. 6695 6696As can be seen in the previous example, it is a common idiom to turn 6697on centering for a large number of lines, and to turn off centering 6698after text to be centered. This is useful for any request which takes 6699a number of lines as an argument. 6700 6701The @code{.ce} read-only number register contains the number of lines 6702remaining to be centered, as set by the @code{ce} request. 6703@endDefreq 6704 6705@DefreqList {rj, [@Var{nnn}]} 6706@DefregListEnd {.rj} 6707@cindex justifying text (@code{rj}) 6708@cindex text, justifying (@code{rj}) 6709@cindex right-justifying (@code{rj}) 6710Justify unfilled text to the right margin. Arguments are identical to 6711the @code{ce} request. The @code{.rj} read-only number register is 6712the number of lines to be right-justified as set by the @code{rj} 6713request. This request causes a break. The number of lines still to be 6714right-justified is associated with the current environment 6715(@pxref{Environments}). 6716@endDefreq 6717 6718 6719@c ===================================================================== 6720 6721@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference 6722@section Manipulating Hyphenation 6723@cindex manipulating hyphenation 6724@cindex hyphenation, manipulating 6725 6726 6727Here a description of requests which influence hyphenation. 6728 6729@DefreqList {hy, [@Var{mode}]} 6730@DefregListEnd {.hy} 6731Enable hyphenation. The request has an optional numeric argument, 6732@var{mode}, to restrict hyphenation if necessary: 6733 6734@table @code 6735@item 1 6736The default argument if @var{mode} is omitted. Hyphenate without 6737restrictions. This is also the start-up value of @code{gtroff}. 6738 6739@item 2 6740Do not hyphenate the last word on a page or column. 6741 6742@item 4 6743Do not hyphenate the last two characters of a word. 6744 6745@item 8 6746Do not hyphenate the first two characters of a word. 6747@end table 6748 6749Values in the previous table are additive. For example, the 6750value@tie{}12 causes @code{gtroff} to neither hyphenate the last 6751two nor the first two characters of a word. 6752 6753@cindex hyphenation restrictions register (@code{.hy}) 6754The current hyphenation restrictions can be found in the read-only 6755number register @samp{.hy}. 6756 6757The hyphenation mode is associated with the current environment 6758(@pxref{Environments}). 6759@endDefreq 6760 6761@Defreq {nh, } 6762Disable hyphenation (i.e., set the hyphenation mode to zero). Note 6763that the hyphenation mode of the last call to @code{hy} is not 6764remembered. 6765 6766The hyphenation mode is associated with the current environment 6767(@pxref{Environments}). 6768@endDefreq 6769 6770@DefreqList {hlm, [@Var{nnn}]} 6771@DefregItem {.hlm} 6772@DefregListEnd {.hlc} 6773@cindex explicit hyphen (@code{\%}) 6774@cindex hyphen, explicit (@code{\%}) 6775@cindex consecutive hyphenated lines (@code{hlm}) 6776@cindex lines, consecutive hyphenated (@code{hlm}) 6777@cindex hyphenated lines, consecutive (@code{hlm}) 6778Set the maximum number of consecutive hyphenated lines to @var{nnn}. 6779If this number is negative, there is no maximum. The default value 6780is@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated 6781with the current environment (@pxref{Environments}). Only lines 6782output from a given environment count towards the maximum associated 6783with that environment. Hyphens resulting from @code{\%} are counted; 6784explicit hyphens are not. 6785 6786The current setting of @code{hlm} is available in the @code{.hlm} 6787read-only number register. Also the number of immediately preceding 6788consecutive hyphenated lines are available in the read-only number 6789register @samp{.hlc}. 6790@endDefreq 6791 6792@Defreq {hw, word1 word2 @dots{}} 6793Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The 6794words must be given with hyphens at the hyphenation points. For 6795example: 6796 6797@Example 6798.hw in-sa-lub-rious 6799@endExample 6800 6801@noindent 6802Besides the space character, any character whose hyphenation code value 6803is zero can be used to separate the arguments of @code{hw} (see the 6804documentation for the @code{hcode} request below for more information). 6805In addition, this request can be used more than once. 6806 6807Hyphenation exceptions specified with the @code{hw} request are 6808associated with the current hyphenation language; it causes an error 6809if there is no current hyphenation language. 6810 6811This request is ignored if there is no parameter. 6812 6813In old versions of @code{troff} there was a limited amount of space to 6814store such information; fortunately, with @code{gtroff}, this is no 6815longer a restriction. 6816@endDefreq 6817 6818@DefescList {\\%, , , } 6819@deffnx Escape @t{\:} 6820@ifnotinfo 6821@esindex \: 6822@end ifnotinfo 6823@ifinfo 6824@esindex \@r{<colon>} 6825@end ifinfo 6826@cindex hyphenation character (@code{\%}) 6827@cindex character, hyphenation (@code{\%}) 6828@cindex disabling hyphenation (@code{\%}) 6829@cindex hyphenation, disabling (@code{\%}) 6830To tell @code{gtroff} how to hyphenate words on the fly, use the 6831@code{\%} escape, also known as the @dfn{hyphenation character}. 6832Preceding a word with this character prevents it from being 6833hyphenated; putting it inside a word indicates to @code{gtroff} that 6834the word may be hyphenated at that point. Note that this mechanism 6835only affects that one occurrence of the word; to change the 6836hyphenation of a word for the entire document, use the @code{hw} 6837request. 6838 6839The @code{\:} escape inserts a zero-width break point 6840(that is, the word breaks but without adding a hyphen). 6841 6842@Example 6843... check the /var/log/\:httpd/\:access_log file ... 6844@endExample 6845 6846@cindex @code{\X}, followed by @code{\%} 6847@cindex @code{\Y}, followed by @code{\%} 6848@cindex @code{\%}, following @code{\X} or @code{\Y} 6849Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%} 6850escape in (say) @w{@samp{\X'...'\%foobar}} and 6851@w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts 6852a hyphenation point at the beginning of @samp{foobar}; most likely 6853this isn't what you want to do. 6854@endDefesc 6855 6856@Defreq {hc, [@Var{char}]} 6857Change the hyphenation character to @var{char}. This character then 6858works the same as the @code{\%} escape, and thus, no longer appears in 6859the output. Without an argument, @code{hc} resets the hyphenation 6860character to be @code{\%} (the default) only. 6861 6862The hyphenation character is associated with the current environment 6863(@pxref{Environments}). 6864@endDefreq 6865 6866@DefreqList {hpf, pattern_file} 6867@DefreqItem {hpfa, pattern_file} 6868@DefreqListEnd {hpfcode, a b [c d @dots{}]} 6869@cindex hyphenation patterns (@code{hpf}) 6870@cindex patterns for hyphenation (@code{hpf}) 6871Read in a file of hyphenation patterns. This file is searched for in 6872the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is 6873searched for if the @option{-m@var{name}} option is specified. 6874 6875It should have the same format as (simple) @TeX{} patterns files. 6876More specifically, the following scanning rules are implemented. 6877 6878@itemize @bullet 6879@item 6880A percent sign starts a comment (up to the end of the line) 6881even if preceded by a backslash. 6882 6883@item 6884No support for `digraphs' like @code{\$}. 6885 6886@item 6887@code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character 6888code of @var{x} in the range 0-127) are recognized; other use of @code{^} 6889causes an error. 6890 6891@item 6892No macro expansion. 6893 6894@item 6895@code{hpf} checks for the expression @code{\patterns@{@dots{}@}} 6896(possibly with whitespace before and after the braces). 6897Everything between the braces is taken as hyphenation patterns. 6898Consequently, @code{@{} and @code{@}} are not allowed in patterns. 6899 6900@item 6901Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation 6902exceptions. 6903 6904@item 6905@code{\endinput} is recognized also. 6906 6907@item 6908For backwards compatibility, if @code{\patterns} is missing, 6909the whole file is treated as a list of hyphenation patterns 6910(only recognizing the @code{%} character as the start of a comment). 6911@end itemize 6912 6913If no @code{hpf} request is specified (either in the document or in a 6914macro package), @code{gtroff} won't hyphenate at all. 6915 6916The @code{hpfa} request appends a file of patterns to the current list. 6917 6918The @code{hpfcode} request defines mapping values for character codes in 6919hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping 6920(after reading the patterns) before replacing or appending them to 6921the current list of patterns. Its arguments are pairs of character codes 6922-- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a} 6923to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You 6924can use character codes which would be invalid otherwise. 6925 6926@pindex troffrc 6927@pindex troffrc-end 6928@pindex hyphen.us 6929@pindex hyphenex.us 6930The set of hyphenation patterns is associated with the current language 6931set by the @code{hla} request. The @code{hpf} request is usually 6932invoked by the @file{troffrc} or @file{troffrc-end} file; by default, 6933@file{troffrc} loads hyphenation patterns and exceptions for American 6934English (in files @file{hyphen.us} and @file{hyphenex.us}). 6935 6936A second call to @code{hpf} (for the same language) will replace the 6937hyphenation patterns with the new ones. 6938 6939Invoking @code{hpf} causes an error if there is no current hyphenation 6940language. 6941@endDefreq 6942 6943@Defreq {hcode, c1 code1 [c2 code2 @dots{}]} 6944@cindex hyphenation code (@code{hcode}) 6945@cindex code, hyphenation (@code{hcode}) 6946Set the hyphenation code of character @var{c1} to @var{code1}, that of 6947@var{c2} to @var{code2}, etc. A hyphenation code must be a single 6948input character (not a special character) other than a digit or a 6949space. 6950 6951To make hyphenation work, hyphenation codes must be set up. At 6952start-up, groff only assigns hyphenation codes to the letters 6953@samp{a}-@samp{z} (mapped to themselves) and to the letters 6954@samp{A}-@samp{Z} (mapped to @samp{a}-@samp{z}); all other hyphenation 6955codes are set to zero. Normally, hyphenation patterns contain only 6956lowercase letters which should be applied regardless of case. With 6957other words, the words `FOO' and `Foo' should be hyphenated exactly the 6958same way as the word `foo' is hyphenated, and this is what @code{hcode} 6959is good for. Words which contain other letters won't be hyphenated 6960properly if the corresponding hyphenation patterns actually do contain 6961them. For example, the following @code{hcode} requests are necessary to 6962assign hyphenation codes to the letters @samp{�������} (this is needed 6963for German): 6964 6965@Example 6966.hcode � � � � 6967.hcode � � � � 6968.hcode � � � � 6969.hcode � � 6970@endExample 6971 6972Without those assignments, groff treats German words like 6973@w{`Kinderg�rten'} (the plural form of `kindergarten') as two 6974substrings @w{`kinderg'} and @w{`rten'} because the hyphenation code 6975of the umlaut@tie{}a is zero by default. There is a German 6976hyphenation pattern which covers @w{`kinder'}, so groff finds the 6977hyphenation `kin-der'. The other two hyphenation points 6978(`kin-der-g�r-ten') are missed. 6979 6980This request is ignored if it has no parameter. 6981@endDefreq 6982 6983@DefreqList {hym, [@Var{length}]} 6984@DefregListEnd {.hym} 6985@cindex hyphenation margin (@code{hym}) 6986@cindex margin for hyphenation (@code{hym}) 6987@cindex @code{ad} request, and hyphenation margin 6988Set the (right) hyphenation margin to @var{length}. If the current 6989adjustment mode is not @samp{b} or @samp{n}, the line is not 6990hyphenated if it is shorter than @var{length}. Without an argument, 6991the hyphenation margin is reset to its default value, which is@tie{}0. 6992The default scaling indicator for this request is @samp{m}. The 6993hyphenation margin is associated with the current environment 6994(@pxref{Environments}). 6995 6996A negative argument resets the hyphenation margin to zero, emitting 6997a warning of type @samp{range}. 6998 6999@cindex hyphenation margin register (@code{.hym}) 7000The current hyphenation margin is available in the @code{.hym} read-only 7001number register. 7002@endDefreq 7003 7004@DefreqList {hys, [@Var{hyphenation_space}]} 7005@DefregListEnd {.hys} 7006@cindex hyphenation space (@code{hys}) 7007@cindex @code{ad} request, and hyphenation space 7008Set the hyphenation space to @var{hyphenation_space}. If the current 7009adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line 7010if it can be justified by adding no more than @var{hyphenation_space} 7011extra space to each word space. Without argument, the hyphenation 7012space is set to its default value, which is@tie{}0. The default 7013scaling indicator for this request is @samp{m}. The hyphenation 7014space is associated with the current environment 7015(@pxref{Environments}). 7016 7017A negative argument resets the hyphenation space to zero, emitting a 7018warning of type @samp{range}. 7019 7020@cindex hyphenation space register (@code{.hys}) 7021The current hyphenation space is available in the @code{.hys} read-only 7022number register. 7023@endDefreq 7024 7025@Defreq {shc, [@Var{glyph}]} 7026@cindex soft hyphen character, setting (@code{shc}) 7027@cindex character, soft hyphen, setting (@code{shc}) 7028@cindex glyph, soft hyphen (@code{hy}) 7029@cindex soft hyphen glyph (@code{hy}) 7030@cindex @code{char} request, and soft hyphen character 7031@cindex @code{tr} request, and soft hyphen character 7032Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft 7033hyphen character} is a misnomer since it is an output glyph.} If the 7034argument is omitted, the soft hyphen character is set to the default 7035glyph @code{\(hy} (this is the start-up value of @code{gtroff} also). 7036The soft hyphen character is the glyph that is inserted when a word is 7037hyphenated at a line break. If the soft hyphen character does not 7038exist in the font of the character immediately preceding a potential 7039break point, then the line is not broken at that point. Neither 7040definitions (specified with the @code{char} request) nor translations 7041(specified with the @code{tr} request) are considered when finding the 7042soft hyphen character. 7043@endDefreq 7044 7045@DefreqList {hla, language} 7046@DefregListEnd {.hla} 7047@cindex @code{hpf} request, and hyphenation language 7048@cindex @code{hw} request, and hyphenation language 7049@pindex troffrc 7050@pindex troffrc-end 7051Set the current hyphenation language to the string @var{language}. 7052Hyphenation exceptions specified with the @code{hw} request and 7053hyphenation patterns specified with the @code{hpf} and @code{hpfa} 7054requests are both associated with the current hyphenation language. 7055The @code{hla} request is usually invoked by the @file{troffrc} or the 7056@file{troffrc-end} files; @file{troffrc} sets the default language to 7057@samp{us}. 7058 7059@cindex hyphenation language register (@code{.hla}) 7060The current hyphenation language is available as a string in the 7061read-only number register @samp{.hla}. 7062 7063@Example 7064.ds curr_language \n[.hla] 7065\*[curr_language] 7066 @result{} us 7067@endExample 7068@endDefreq 7069 7070 7071@c ===================================================================== 7072 7073@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference 7074@section Manipulating Spacing 7075@cindex manipulating spacing 7076@cindex spacing, manipulating 7077 7078@Defreq {sp, [@Var{distance}]} 7079Space downwards @var{distance}. With no argument it advances 70801@tie{}line. A negative argument causes @code{gtroff} to move up the page 7081the specified distance. If the argument is preceded by a @samp{|} 7082then @code{gtroff} moves that distance from the top of the page. This 7083request causes a line break. The default scaling indicator is @samp{v}. 7084 7085If a vertical trap is sprung during execution of @code{sp}, the amount of 7086vertical space after the trap is discarded. For example, this 7087 7088@Example 7089.de xxx 7090.. 7091. 7092.wh 0 xxx 7093. 7094.pl 5v 7095foo 7096.sp 2 7097bar 7098.sp 50 7099baz 7100@endExample 7101 7102@noindent 7103results in 7104 7105@Example 7106foo 7107 7108 7109bar 7110 7111baz 7112@endExample 7113 7114@cindex @code{sp} request, and traps 7115@cindex discarded space in traps 7116@cindex space, discarded, in traps 7117@cindex traps, and discarded space 7118The amount of discarded space is available in the number register 7119@code{.trunc}. 7120 7121To protect @code{sp} against vertical traps, use the @code{vpt} request: 7122 7123@Example 7124.vpt 0 7125.sp -3 7126.vpt 1 7127@endExample 7128@endDefreq 7129 7130@DefreqList {ls, [@Var{nnn}]} 7131@DefregListEnd {.L} 7132@cindex double-spacing (@code{ls}) 7133Output @w{@var{nnn}@minus{}1} blank lines after each line of text. 7134With no argument, @code{gtroff} uses the previous value before the 7135last @code{ls} call. 7136 7137@Example 7138.ls 2 \" This causes double-spaced output 7139.ls 3 \" This causes triple-spaced output 7140.ls \" Again double-spaced 7141@endExample 7142 7143The line spacing is associated with the current environment 7144(@pxref{Environments}). 7145 7146@cindex line spacing register (@code{.L}) 7147The read-only number register @code{.L} contains the current line 7148spacing setting. 7149@endDefreq 7150 7151@xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs} 7152as alternatives to @code{ls}. 7153 7154@DefescList {\\x, ', spacing, '} 7155@DefregListEnd {.a} 7156Sometimes, extra vertical spacing is only needed occasionally, e.g.@: 7157to allow space for a tall construct (like an equation). The @code{\x} 7158escape does this. The escape is given a numerical argument, usually 7159enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator 7160is @samp{v}. If this number is positive extra vertical space is 7161inserted below the current line. A negative number adds space above. 7162If this escape is used multiple times on the same line, the maximum of 7163the values is used. 7164 7165@xref{Escapes}, for details on parameter delimiting characters. 7166 7167@cindex extra post-vertical line space register (@code{.a}) 7168The @code{.a} read-only number register contains the most recent 7169(nonnegative) extra vertical line space. 7170 7171Using @code{\x} can be necessary in combination with the @code{\b} 7172escape, as the following example shows. 7173 7174@Example 7175This is a test with the \[rs]b escape. 7176.br 7177This is a test with the \[rs]b escape. 7178.br 7179This is a test with \b'xyz'\x'-1m'\x'1m'. 7180.br 7181This is a test with the \[rs]b escape. 7182.br 7183This is a test with the \[rs]b escape. 7184@endExample 7185 7186@noindent 7187produces 7188 7189@Example 7190This is a test with the \b escape. 7191This is a test with the \b escape. 7192 x 7193This is a test with y. 7194 z 7195This is a test with the \b escape. 7196This is a test with the \b escape. 7197@endExample 7198@endDefesc 7199 7200@DefreqList {ns, } 7201@DefreqItem {rs, } 7202@DefregListEnd {.ns} 7203@cindex @code{sp} request, and no-space mode 7204@cindex no-space mode (@code{ns}) 7205@cindex mode, no-space (@code{ns}) 7206@cindex blank lines, disabling 7207@cindex lines, blank, disabling 7208Enable @dfn{no-space mode}. In this mode, spacing (either via 7209@code{sp} or via blank lines) is disabled. The @code{bp} request to 7210advance to the next page is also disabled, except if it is accompanied 7211by a page number (see @ref{Page Control}, for more information). This 7212mode ends when actual text is output or the @code{rs} request is 7213encountered which ends no-space mode. The read-only number register 7214@code{.ns} is set to@tie{}1 as long as no-space mode is active. 7215 7216This request is useful for macros that conditionally 7217insert vertical space before the text starts 7218(for example, a paragraph macro could insert some space 7219except when it is the first paragraph after a section header). 7220@endDefreq 7221 7222 7223@c ===================================================================== 7224 7225@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 7226@section Tabs and Fields 7227@cindex tabs, and fields 7228@cindex fields, and tabs 7229 7230@cindex @acronym{EBCDIC} encoding of a tab 7231A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC} 7232char@tie{}5) causes a horizontal movement to the next tab stop (much 7233like it did on a typewriter). 7234 7235@Defesc {\\t, , , } 7236@cindex tab character, non-interpreted (@code{\t}) 7237@cindex character, tab, non-interpreted (@code{\t}) 7238This escape is a non-interpreted tab character. In copy mode 7239(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 7240@endDefesc 7241 7242@DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 7243@DefregListEnd {.tabs} 7244Change tab stop positions. This request takes a series of tab 7245specifiers as arguments (optionally divided into two groups with the 7246letter @samp{T}) which indicate where each tab stop is to be 7247(overriding any previous settings). 7248 7249Tab stops can be specified absolutely, i.e., as the distance from the 7250left margin. For example, the following sets 6@tie{}tab stops every 7251one inch. 7252 7253@Example 7254.ta 1i 2i 3i 4i 5i 6i 7255@endExample 7256 7257Tab stops can also be specified using a leading @samp{+} 7258which means that the specified tab stop is set relative to 7259the previous tab stop. For example, the following is equivalent to the 7260previous example. 7261 7262@Example 7263.ta 1i +1i +1i +1i +1i +1i 7264@endExample 7265 7266@code{gtroff} supports an extended syntax to specify repeat values after 7267the @samp{T} mark (these values are always taken as relative) -- this is 7268the usual way to specify tabs set at equal intervals. The following is, 7269yet again, the same as the previous examples. It does even more since 7270it defines an infinite number of tab stops separated by one inch. 7271 7272@Example 7273.ta T 1i 7274@endExample 7275 7276Now we are ready to interpret the full syntax given at the beginning: 7277Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 7278tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 7279and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 7280@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 7281 7282Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 728320c 23c 28c 30c @dots{}}. 7284 7285The material in each tab column (i.e., the column between two tab stops) 7286may be justified to the right or left or centered in the column. This 7287is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 7288specifier. The default justification is @samp{L}. Example: 7289 7290@Example 7291.ta 1i 2iC 3iR 7292@endExample 7293 7294Some notes: 7295 7296@itemize @bullet 7297@item 7298The default unit of the @code{ta} request is @samp{m}. 7299 7300@item 7301A tab stop is converted into a non-breakable horizontal movement which 7302can be neither stretched nor squeezed. For example, 7303 7304@Example 7305.ds foo a\tb\tc 7306.ta T 5i 7307\*[foo] 7308@endExample 7309 7310@noindent 7311creates a single line which is a bit longer than 10@tie{}inches (a string 7312is used to show exactly where the tab characters are). Now consider the 7313following: 7314 7315@Example 7316.ds bar a\tb b\tc 7317.ta T 5i 7318\*[bar] 7319@endExample 7320 7321@noindent 7322@code{gtroff} first converts the tab stops of the line into unbreakable 7323horizontal movements, then splits the line after the second @samp{b} 7324(assuming a sufficiently short line length). Usually, this isn't what 7325the user wants. 7326 7327@item 7328Superfluous tabs (i.e., tab characters which do not correspond to a tab 7329stop) are ignored except the first one which delimits the characters 7330belonging to the last tab stop for right-justifying or centering. 7331Consider the following example 7332 7333@Example 7334.ds Z foo\tbar\tfoo 7335.ds ZZ foo\tbar\tfoobar 7336.ds ZZZ foo\tbar\tfoo\tbar 7337.ta 2i 4iR 7338\*[Z] 7339.br 7340\*[ZZ] 7341.br 7342\*[ZZZ] 7343.br 7344@endExample 7345 7346@noindent 7347which produces the following output: 7348 7349@Example 7350foo bar foo 7351foo bar foobar 7352foo bar foobar 7353@endExample 7354 7355@noindent 7356The first line right-justifies the second `foo' relative to the tab 7357stop. The second line right-justifies `foobar'. The third line finally 7358right-justifies only `foo' because of the additional tab character which 7359marks the end of the string belonging to the last defined tab stop. 7360 7361@item 7362Tab stops are associated with the current environment 7363(@pxref{Environments}). 7364 7365@item 7366Calling @code{ta} without an argument removes all tab stops. 7367 7368@item 7369@cindex tab stops, for TTY output devices 7370The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}. 7371@end itemize 7372 7373@cindex tab settings register (@code{.tabs}) 7374The read-only number register @code{.tabs} contains a string 7375representation of the current tab settings suitable for use as an 7376argument to the @code{ta} request. 7377 7378@Example 7379.ds tab-string \n[.tabs] 7380\*[tab-string] 7381 @result{} T120u 7382@endExample 7383 7384@cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs} 7385@cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S}) 7386The @code{troff} version of the Plan@tie{}9 operating system uses 7387register @code{.S} for the same purpose. 7388@endDefreq 7389 7390@Defreq {tc, [@Var{fill-glyph}]} 7391@cindex tab repetition character (@code{tc}) 7392@cindex character, tab repetition (@code{tc}) 7393@cindex glyph, tab repetition (@code{tc}) 7394Normally @code{gtroff} fills the space to the next tab stop with 7395whitespace. This can be changed with the @code{tc} request. With no 7396argument @code{gtroff} reverts to using whitespace, which is the 7397default. The value of this @dfn{tab repetition character} is 7398associated with the current environment 7399(@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a 7400misnomer since it is an output glyph.} 7401@endDefreq 7402 7403@DefreqList {linetabs, n} 7404@DefregListEnd {.linetabs} 7405@cindex tab, line-tabs mode 7406@cindex line-tabs mode 7407@cindex mode, line-tabs 7408If @var{n} is missing or not zero, enable @dfn{line-tabs} mode, 7409or disable it otherwise (the default). 7410In line-tabs mode, @code{gtroff} computes tab distances 7411relative to the (current) output line instead of the input line. 7412 7413For example, the following code: 7414 7415@Example 7416.ds x a\t\c 7417.ds y b\t\c 7418.ds z c 7419.ta 1i 3i 7420\*x 7421\*y 7422\*z 7423@endExample 7424 7425@noindent 7426in normal mode, results in the output 7427 7428@Example 7429a b c 7430@endExample 7431 7432@noindent 7433in line-tabs mode, the same code outputs 7434 7435@Example 7436a b c 7437@endExample 7438 7439Line-tabs mode is associated with the current environment. 7440The read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs 7441mode, and 0 in normal mode. 7442@endDefreq 7443 7444@menu 7445* Leaders:: 7446* Fields:: 7447@end menu 7448 7449@c --------------------------------------------------------------------- 7450 7451@node Leaders, Fields, Tabs and Fields, Tabs and Fields 7452@subsection Leaders 7453@cindex leaders 7454 7455Sometimes it may may be desirable to use the @code{tc} request to fill a 7456particular tab stop with a given glyph (for example dots in a table 7457of contents), but also normal tab stops on the rest of the line. For 7458this @code{gtroff} provides an alternate tab mechanism, called 7459@dfn{leaders} which does just that. 7460 7461@cindex leader character 7462A leader character (character code@tie{}1) behaves similarly to a tab 7463character: It moves to the next tab stop. The only difference is that 7464for this movement, the fill glyph defaults to a period character and 7465not to space. 7466 7467@Defesc {\\a, , , } 7468@cindex leader character, non-interpreted (@code{\a}) 7469@cindex character, leader, non-interpreted (@code{\a}) 7470This escape is a non-interpreted leader character. In copy mode 7471(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 7472character. 7473@endDefesc 7474 7475@Defreq {lc, [@Var{fill-glyph}]} 7476@cindex leader repetition character (@code{lc}) 7477@cindex character, leader repetition (@code{lc}) 7478@cindex glyph, leader repetition (@code{lc}) 7479Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader 7480repetition character} is a misnomer since it is an output glyph.} 7481Without an argument, leaders act the same as tabs (i.e., using 7482whitespace for filling). @code{gtroff}'s start-up value is a dot 7483(@samp{.}). The value of the leader repetition character is 7484associated with the current environment (@pxref{Environments}). 7485@endDefreq 7486 7487@cindex table of contents 7488@cindex contents, table of 7489For a table of contents, to name an example, tab stops may be defined so 7490that the section number is one tab stop, the title is the second with 7491the remaining space being filled with a line of dots, and then the page 7492number slightly separated from the dots. 7493 7494@Example 7495.ds entry 1.1\tFoo\a\t12 7496.lc . 7497.ta 1i 5i +.25i 7498\*[entry] 7499@endExample 7500 7501@noindent 7502This produces 7503 7504@Example 75051.1 Foo.......................................... 12 7506@endExample 7507 7508@c --------------------------------------------------------------------- 7509 7510@node Fields, , Leaders, Tabs and Fields 7511@subsection Fields 7512@cindex fields 7513 7514@cindex field delimiting character (@code{fc}) 7515@cindex delimiting character, for fields (@code{fc}) 7516@cindex character, field delimiting (@code{fc}) 7517@cindex field padding character (@code{fc}) 7518@cindex padding character, for fields (@code{fc}) 7519@cindex character, field padding (@code{fc}) 7520@dfn{Fields} are a more general way of laying out tabular data. A field 7521is defined as the data between a pair of @dfn{delimiting characters}. 7522It contains substrings which are separated by @dfn{padding characters}. 7523The width of a field is the distance on the @emph{input} line from the 7524position where the field starts to the next tab stop. A padding 7525character inserts stretchable space similar to @TeX{}'s @code{\hss} 7526command (thus it can even be negative) to make the sum of all substring 7527lengths plus the stretchable space equal to the field width. If more 7528than one padding character is inserted, the available space is evenly 7529distributed among them. 7530 7531@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 7532Define a delimiting and a padding character for fields. If the latter 7533is missing, the padding character defaults to a space character. If 7534there is no argument at all, the field mechanism is disabled (which is 7535the default). Note that contrary to e.g.@: the tab repetition 7536character, delimiting and padding characters are @emph{not} associated 7537to the current environment (@pxref{Environments}). 7538 7539Example: 7540 7541@Example 7542.fc # ^ 7543.ta T 3i 7544#foo^bar^smurf# 7545.br 7546#foo^^bar^smurf# 7547@endExample 7548 7549@noindent 7550and here the result: 7551 7552@Example 7553foo bar smurf 7554foo bar smurf 7555@endExample 7556@endDefreq 7557 7558 7559@c ===================================================================== 7560 7561@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 7562@section Character Translations 7563@cindex character translations 7564@cindex translations of characters 7565 7566@cindex control character, changing (@code{cc}) 7567@cindex character, control, changing (@code{cc}) 7568@cindex no-break control character, changing (@code{c2}) 7569@cindex character, no-break control, changing (@code{c2}) 7570@cindex control character, no-break, changing (@code{c2}) 7571The control character (@samp{.}) and the no-break control character 7572(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 7573respectively. 7574 7575@Defreq {cc, [@Var{c}]} 7576Set the control character to@tie{}@var{c}. With no argument the default 7577control character @samp{.} is restored. The value of the control 7578character is associated with the current environment 7579(@pxref{Environments}). 7580@endDefreq 7581 7582@Defreq {c2, [@Var{c}]} 7583Set the no-break control character to@tie{}@var{c}. With no argument the 7584default control character @samp{'} is restored. The value of the 7585no-break control character is associated with the current environment 7586(@pxref{Environments}). 7587@endDefreq 7588 7589@Defreq {eo, } 7590@cindex disabling @code{\} (@code{eo}) 7591@cindex @code{\}, disabling (@code{eo}) 7592Disable the escape mechanism completely. After executing this 7593request, the backslash character @samp{\} no longer starts an escape 7594sequence. 7595 7596This request can be very helpful in writing macros since it is not 7597necessary then to double the escape character. Here an example: 7598 7599@Example 7600.\" This is a simplified version of the 7601.\" .BR request from the man macro package 7602.eo 7603.de BR 7604. ds result \& 7605. while (\n[.$] >= 2) \@{\ 7606. as result \fB\$1\fR\$2 7607. shift 2 7608. \@} 7609. if \n[.$] .as result \fB\$1 7610\*[result] 7611. ft R 7612.. 7613.ec 7614@endExample 7615@endDefreq 7616 7617@Defreq {ec, [@Var{c}]} 7618@cindex escape character, changing (@code{ec}) 7619@cindex character, escape, changing (@code{ec}) 7620Set the escape character to@tie{}@var{c}. With no argument the default 7621escape character @samp{\} is restored. It can be also used to 7622re-enable the escape mechanism after an @code{eo} request. 7623 7624Note that changing the escape character globally will likely break 7625macro packages since @code{gtroff} has no mechanism to `intern' macros, 7626i.e., to convert a macro definition into an internal form which is 7627independent of its representation (@TeX{} has this mechanism). 7628If a macro is called, it is executed literally. 7629@endDefreq 7630 7631@DefreqList {ecs, } 7632@DefreqListEnd {ecr, } 7633The @code{ecs} request saves the current escape character 7634in an internal register. 7635Use this request in combination with the @code{ec} request to 7636temporarily change the escape character. 7637 7638The @code{ecr} request restores the escape character 7639saved with @code{ecs}. 7640Without a previous call to @code{ecs}, this request 7641sets the escape character to @code{\}. 7642@endDefreq 7643 7644@DefescList {\\\\, , , } 7645@DefescItem {\\e, , , } 7646@DefescListEnd {\\E, , , } 7647Print the current escape character (which is the backslash character 7648@samp{\} by default). 7649 7650@code{\\} is a `delayed' backslash; more precisely, it is the default 7651escape character followed by a backslash, which no longer has special 7652meaning due to the leading escape character. It is @emph{not} an escape 7653sequence in the usual sense! In any unknown escape sequence 7654@code{\@var{X}} the escape character is ignored and @var{X} is printed. 7655But if @var{X} is equal to the current escape character, no warning is 7656emitted. 7657 7658As a consequence, only at top-level or in a diversion a backslash glyph is 7659printed; in copy-in mode, it expands to a single backslash which then 7660combines with the following character to an escape sequence. 7661 7662The @code{\E} escape differs from @code{\e} by printing an escape 7663character that is not interpreted in copy mode. 7664Use this to define strings with escapes that work 7665when used in copy mode (for example, as a macro argument). 7666The following example defines strings to begin and end 7667a superscript: 7668 7669@Example 7670.ds @{ \v'-.3m'\s'\En[.s]*60/100' 7671.ds @} \s0\v'.3m' 7672@endExample 7673 7674Another example to demonstrate the differences between the various escape 7675sequences, using a strange escape character, @samp{-}. 7676 7677@Example 7678.ec - 7679.de xxx 7680--A'123' 7681.. 7682.xxx 7683 @result{} -A'foo' 7684@endExample 7685 7686@noindent 7687The result is surprising for most users, expecting @samp{1} since 7688@samp{foo} is a valid identifier. What has happened? As mentioned 7689above, the leading escape character makes the following character 7690ordinary. Written with the default escape character the sequence 7691@samp{--} becomes @samp{\-} -- this is the minus sign. 7692 7693If the escape character followed by itself is a valid escape sequence, 7694only @code{\E} yields the expected result: 7695 7696@Example 7697.ec - 7698.de xxx 7699-EA'123' 7700.. 7701.xxx 7702 @result{} 1 7703@endExample 7704@endDefesc 7705 7706@Defesc {\\., , , } 7707Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence. 7708As before, a warning message is suppressed if the escape character is 7709followed by a dot, and the dot itself is printed. 7710 7711@Example 7712.de foo 7713. nop foo 7714. 7715. de bar 7716. nop bar 7717\\.. 7718. 7719.. 7720.foo 7721.bar 7722 @result{} foo bar 7723@endExample 7724 7725@noindent 7726The first backslash is consumed while the macro is read, and the second 7727is swallowed while exexuting macro @code{foo}. 7728@endDefesc 7729 7730A @dfn{translation} is a mapping of an input character to an output 7731glyph. The mapping occurs at output time, i.e., the input character 7732gets assigned the metric information of the mapped output character 7733right before input tokens are converted to nodes (@pxref{Gtroff 7734Internals}, for more on this process). 7735 7736@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7737@DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7738Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to 7739glyph@tie{}@var{d}, etc. If there is an odd number of arguments, the 7740last one is translated to an unstretchable space (@w{@samp{\ }}). 7741 7742The @code{trin} request is identical to @code{tr}, 7743but when you unformat a diversion with @code{asciify} 7744it ignores the translation. 7745@xref{Diversions}, for details about the @code{asciify} request. 7746 7747Some notes: 7748 7749@itemize @bullet 7750@item 7751@cindex @code{\(}, and translations 7752@cindex @code{\[}, and translations 7753@cindex @code{\'}, and translations 7754@cindex @code{\`}, and translations 7755@cindex @code{\-}, and translations 7756@cindex @code{\_}, and translations 7757@cindex @code{\C}, and translations 7758@cindex @code{\N}, and translations 7759@cindex @code{char} request, and translations 7760@cindex special characters 7761@cindex character, special 7762@cindex numbered glyph (@code{\N}) 7763@cindex glyph, numbered (@code{\N}) 7764Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 7765@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 7766glyphs defined with the @code{char} request, and numbered glyphs 7767(@code{\N'@var{xxx}'}) can be translated also. 7768 7769@item 7770@cindex @code{\e}, and translations 7771The @code{\e} escape can be translated also. 7772 7773@item 7774@cindex @code{\%}, and translations 7775@cindex @code{\~}, and translations 7776Characters can be mapped onto the @code{\%} and @code{\~} escapes (but 7777@code{\%} and @code{\~} can't be mapped onto another glyph). 7778 7779@item 7780@cindex backspace character, and translations 7781@cindex character, backspace, and translations 7782@cindex leader character, and translations 7783@cindex character, leader, and translations 7784@cindex newline character, and translations 7785@cindex character, newline, and translations 7786@cindex tab character, and translations 7787@cindex character, tab, and translations 7788@cindex @code{\a}, and translations 7789@cindex @code{\t}, and translations 7790The following characters can't be translated: space (with one exception, 7791see below), backspace, newline, leader (and @code{\a}), tab (and 7792@code{\t}). 7793 7794@item 7795@cindex @code{shc} request, and translations 7796Translations are not considered for finding the soft hyphen character 7797set with the @code{shc} request. 7798 7799@item 7800@cindex @code{\&}, and translations 7801The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c} 7802followed by the zero width space character) maps this character to nothing. 7803 7804@Example 7805.tr a\& 7806foo bar 7807 @result{} foo br 7808@endExample 7809 7810@noindent 7811It is even possible to map the space character to nothing: 7812 7813@Example 7814.tr aa \& 7815foo bar 7816 @result{} foobar 7817@endExample 7818 7819@noindent 7820As shown in the example, the space character can't be the first 7821character/glyph pair as an argument of @code{tr}. Additionally, it is 7822not possible to map the space character to any other glyph; requests 7823like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 7824 7825If justification is active, lines are justified in spite of the 7826`empty' space character (but there is no minimal distance, i.e.@: the 7827space character, between words). 7828 7829@item 7830After an output glyph has been constructed (this happens at the 7831moment immediately before the glyph is appended to an output 7832glyph list, either by direct output, in a macro, diversion, or 7833string), it is no longer affected by @code{tr}. 7834 7835@item 7836Translating character to glyphs where one of them or both are 7837undefined is possible also; @code{tr} does not check whether the 7838entities in its argument do exist. 7839 7840@xref{Gtroff Internals}. 7841 7842@item 7843@code{troff} no longer has a hard-coded dependency on @w{Latin-1}; 7844all @code{char@var{XXX}} entities have been removed from the font 7845description files. This has a notable consequence which shows up in 7846warnings like @code{can't find character with input code @var{XXX}} 7847if the @code{tr} request isn't handled properly. 7848 7849Consider the following translation: 7850 7851@Example 7852.tr �� 7853@endExample 7854 7855@noindent 7856This maps input character @code{�} onto glyph @code{�}, which is 7857identical to glyph @code{char201}. But this glyph intentionally 7858doesn't exist! Instead, @code{\[char201]} is treated as an input 7859character entity and is by default mapped onto @code{\['E]}, and 7860@code{gtroff} doesn't handle translations of translations. 7861 7862The right way to write the above translation is 7863 7864@Example 7865.tr �\['E] 7866@endExample 7867 7868@noindent 7869With other words, the first argument of @code{tr} should be an input 7870character or entity, and the second one a glyph entity. 7871 7872@item 7873Without an argument, the @code{tr} request is ignored. 7874@end itemize 7875@endDefreq 7876 7877@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7878@cindex @code{\!}, and @code{trnt} 7879@code{trnt} is the same as the @code{tr} request except that the 7880translations do not apply to text that is transparently throughput 7881into a diversion with @code{\!}. @xref{Diversions}, for more 7882information. 7883 7884For example, 7885 7886@Example 7887.tr ab 7888.di x 7889\!.tm a 7890.di 7891.x 7892@endExample 7893 7894@noindent 7895prints @samp{b} to the standard error stream; if @code{trnt} is used 7896instead of @code{tr} it prints @samp{a}. 7897@endDefreq 7898 7899 7900@c ===================================================================== 7901 7902@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 7903@section Troff and Nroff Mode 7904@cindex troff mode 7905@cindex mode, troff 7906@cindex nroff mode 7907@cindex mode, nroff 7908 7909Originally, @code{nroff} and @code{troff} were two separate programs, 7910the former for TTY output, the latter for everything else. With GNU 7911@code{troff}, both programs are merged into one executable, sending 7912its output to a device driver (@code{grotty} for TTY devices, 7913@code{grops} for @sc{PostScript}, etc.) which interprets the 7914intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 7915it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 7916since the differences are hardcoded. For GNU @code{troff}, this 7917distinction is not appropriate because @code{gtroff} simply takes the 7918information given in the font files for a particular device without 7919handling requests specially if a TTY output device is used. 7920 7921Usually, a macro package can be used with all output devices. 7922Nevertheless, it is sometimes necessary to make a distinction between 7923TTY and non-TTY devices: @code{gtroff} provides two built-in 7924conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 7925@code{while} requests to decide whether @code{gtroff} shall behave 7926like @code{nroff} or like @code{troff}. 7927 7928@Defreq {troff, } 7929@pindex troffrc 7930@pindex troffrc-end 7931Make the @samp{t} built-in condition true (and the @samp{n} built-in 7932condition false) for @code{if}, @code{ie}, and @code{while} 7933conditional requests. This is the default if @code{gtroff} 7934(@emph{not} @code{groff}) is started with the @option{-R} switch to 7935avoid loading of the start-up files @file{troffrc} and 7936@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 7937mode if the output device is not a TTY (e.g.@: `ps'). 7938@endDefreq 7939 7940@Defreq {nroff, } 7941@pindex tty.tmac 7942Make the @samp{n} built-in condition true (and the @samp{t} built-in 7943condition false) for @code{if}, @code{ie}, and @code{while} 7944conditional requests. This is the default if @code{gtroff} uses a TTY 7945output device; the code for switching to nroff mode is in the file 7946@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 7947@endDefreq 7948 7949@xref{Conditionals and Loops}, for more details on built-in 7950conditions. 7951 7952 7953@c ===================================================================== 7954 7955@node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference 7956@section Line Layout 7957@cindex line layout 7958@cindex layout, line 7959 7960@cindex dimensions, line 7961@cindex line dimensions 7962The following drawing shows the dimensions which @code{gtroff} uses for 7963placing a line of output onto the page. They are labeled with the 7964request which manipulates each dimension. 7965 7966@Example 7967 -->| in |<-- 7968 |<-----------ll------------>| 7969 +----+----+----------------------+----+ 7970 | : : : | 7971 +----+----+----------------------+----+ 7972 -->| po |<-- 7973 |<--------paper width---------------->| 7974@endExample 7975 7976@noindent 7977These dimensions are: 7978 7979@ftable @code 7980@item po 7981@cindex left margin (@code{po}) 7982@cindex margin, left (@code{po}) 7983@cindex page offset (@code{po}) 7984@cindex offset, page (@code{po}) 7985@dfn{Page offset} -- this is the leftmost position of text on the final 7986output, defining the @dfn{left margin}. 7987 7988@item in 7989@cindex indentation (@code{in}) 7990@cindex line indentation (@code{in}) 7991@dfn{Indentation} -- this is the distance from the left margin where 7992text is printed. 7993 7994@item ll 7995@cindex line length (@code{ll}) 7996@cindex length of line (@code{ll}) 7997@dfn{Line length} -- this is the distance from the left margin to right 7998margin. 7999@end ftable 8000 8001A simple demonstration: 8002 8003@Example 8004.ll 3i 8005This is text without indentation. 8006The line length has been set to 3\~inch. 8007.in +.5i 8008.ll -.5i 8009Now the left and right margins are both increased. 8010.in 8011.ll 8012Calling .in and .ll without parameters restore 8013the previous values. 8014@endExample 8015 8016Result: 8017 8018@Example 8019This is text without indenta- 8020tion. The line length has 8021been set to 3 inch. 8022 Now the left and 8023 right margins are 8024 both increased. 8025Calling .in and .ll without 8026parameters restore the previ- 8027ous values. 8028@endExample 8029 8030@DefreqList {po, [@Var{offset}]} 8031@DefreqItem {po, @t{+}@Var{offset}} 8032@DefreqItem {po, @t{-}@Var{offset}} 8033@DefregListEnd {.o} 8034@pindex troffrc 8035Set horizontal page offset to @var{offset} (or increment or decrement 8036the current value by @var{offset}). Note that this request does not 8037cause a break, so changing the page offset in the middle of text being 8038filled may not yield the expected result. The initial value is 80391@dmn{i}. For TTY output devices, it is set to 0 in the startup file 8040@file{troffrc}; the default scaling indicator is @samp{m} (and 8041not @samp{v} as incorrectly documented in the original 8042@acronym{UNIX} troff manual). 8043 8044The current page offset can be found in the read-only number register 8045@samp{.o}. 8046 8047If @code{po} is called without an argument, the page offset is reset to 8048the previous value before the last call to @code{po}. 8049 8050@Example 8051.po 3i 8052\n[.o] 8053 @result{} 720 8054.po -1i 8055\n[.o] 8056 @result{} 480 8057.po 8058\n[.o] 8059 @result{} 720 8060@endExample 8061@endDefreq 8062 8063@DefreqList {in, [@Var{indent}]} 8064@DefreqItem {in, @t{+}@Var{indent}} 8065@DefreqItem {in, @t{-}@Var{indent}} 8066@DefregListEnd {.i} 8067Set indentation to @var{indent} (or increment or decrement the 8068current value by @var{indent}). This request causes a break. 8069Initially, there is no indentation. 8070 8071If @code{in} is called without an argument, the indentation is reset to 8072the previous value before the last call to @code{in}. The default 8073scaling indicator is @samp{m}. 8074 8075The indentation is associated with the current environment 8076(@pxref{Environments}). 8077 8078If a negative indentation value is specified (which is not allowed), 8079@code{gtroff} emits a warning of type @samp{range} and sets the 8080indentation to zero. 8081 8082The effect of @code{in} is delayed until a partially collected line 8083(if it exists) is output. A temporary indentation value is reset to 8084zero also. 8085 8086The current indentation (as set by @code{in}) can be found in the 8087read-only number register @samp{.i}. 8088@endDefreq 8089 8090@DefreqList {ti, offset} 8091@DefreqItem {ti, @t{+}@Var{offset}} 8092@DefreqItem {ti, @t{-}@Var{offset}} 8093@DefregListEnd {.in} 8094Temporarily indent the next output line by @var{offset}. If an 8095increment or decrement value is specified, adjust the temporary 8096indentation relative to the value set by the @code{in} request. 8097 8098This request causes a break; its value is associated with the current 8099environment (@pxref{Environments}). The default scaling indicator 8100is @samp{m}. A call of @code{ti} without an argument is ignored. 8101 8102If the total indentation value is negative (which is not allowed), 8103@code{gtroff} emits a warning of type @samp{range} and sets the 8104temporary indentation to zero. `Total indentation' is either 8105@var{offset} if specified as an absolute value, or the temporary plus 8106normal indentation, if @var{offset} is given as a relative value. 8107 8108The effect of @code{ti} is delayed until a partially collected line (if 8109it exists) is output. 8110 8111The read-only number register @code{.in} is the indentation that applies 8112to the current output line. 8113 8114The difference between @code{.i} and @code{.in} is that the latter takes 8115into account whether a partially collected line still uses the old 8116indentation value or a temporary indentation value is active. 8117@endDefreq 8118 8119@DefreqList {ll, [@Var{length}]} 8120@DefreqItem {ll, @t{+}@Var{length}} 8121@DefreqItem {ll, @t{-}@Var{length}} 8122@DefregItem {.l} 8123@DefregListEnd {.ll} 8124Set the line length to @var{length} (or increment or decrement the 8125current value by @var{length}). Initially, the line length is set to 81266.5@dmn{i}. The effect of @code{ll} is delayed until a partially 8127collected line (if it exists) is output. The default scaling 8128indicator is @samp{m}. 8129 8130If @code{ll} is called without an argument, the line length is reset to 8131the previous value before the last call to @code{ll}. If a negative 8132line length is specified (which is not allowed), @code{gtroff} emits a 8133warning of type @samp{range} and sets the line length to zero. 8134 8135The line length is associated with the current environment 8136(@pxref{Environments}). 8137 8138@cindex line length register (@code{.l}) 8139The current line length (as set by @code{ll}) can be found in the 8140read-only number register @samp{.l}. The read-only number register 8141@code{.ll} is the line length that applies to the current output line. 8142 8143Similar to @code{.i} and @code{.in}, the difference between @code{.l} 8144and @code{.ll} is that the latter takes into account whether a partially 8145collected line still uses the old line length value. 8146@endDefreq 8147 8148 8149@c ===================================================================== 8150 8151@node Line Control, Page Layout, Line Layout, gtroff Reference 8152@section Line Control 8153@cindex line control 8154@cindex control, line 8155 8156It is important to understand how @code{gtroff} handles input and output 8157lines. 8158 8159Many escapes use positioning relative to the input line. For example, 8160this 8161 8162@Example 8163This is a \h'|1.2i'test. 8164 8165This is a 8166\h'|1.2i'test. 8167@endExample 8168 8169@noindent 8170produces 8171 8172@Example 8173This is a test. 8174 8175This is a test. 8176@endExample 8177 8178The main usage of this feature is to define macros which act exactly 8179at the place where called. 8180 8181@Example 8182.\" A simple macro to underline a word 8183.de underline 8184. nop \\$1\l'|0\[ul]' 8185.. 8186@endExample 8187 8188@noindent 8189In the above example, @samp{|0} specifies a negative distance from the 8190current position (at the end of the just emitted argument @code{\$1}) back 8191to the beginning of the input line. Thus, the @samp{\l} escape draws a 8192line from right to left. 8193 8194@cindex input line continuation (@code{\}) 8195@cindex line, input, continuation (@code{\}) 8196@cindex continuation, input line (@code{\}) 8197@cindex output line, continuation (@code{\c}) 8198@cindex line, output, continuation (@code{\c}) 8199@cindex continuation, output line (@code{\c}) 8200@cindex interrupted line 8201@cindex line, interrupted 8202@code{gtroff} makes a difference between input and output line 8203continuation; the latter is also called @dfn{interrupting} a line. 8204 8205@DefescList {\\@key{RET}, , ,} 8206@DefescItem {\\c, , ,} 8207@DefregListEnd{.int} 8208Continue a line. @code{\@key{RET}} (this is a backslash at the end 8209of a line immediately followed by a newline) works on the input level, 8210suppressing the effects of the following newline in the input. 8211 8212@Example 8213This is a \ 8214.test 8215 @result{} This is a .test 8216@endExample 8217 8218The @samp{|} operator is also affected. 8219 8220@cindex @code{\R}, after @code{\c} 8221@code{\c} works on the output level. Anything after this escape on the 8222same line is ignored, except @code{\R} which works as usual. Anything 8223before @code{\c} on the same line will be appended to the current partial 8224output line. The next non-command line after an interrupted line counts 8225as a new input line. 8226 8227The visual results depend on whether no-fill mode is active. 8228 8229@itemize @bullet 8230@item 8231@cindex @code{\c}, and no-fill mode 8232@cindex no-fill mode, and @code{\c} 8233@cindex mode, no-fill, and @code{\c} 8234If no-fill mode is active (using the @code{nf} request), the next input 8235text line after @code{\c} will be handled as a continuation of the same 8236input text line. 8237 8238@Example 8239.nf 8240This is a \c 8241test. 8242 @result{} This is a test. 8243@endExample 8244 8245@item 8246@cindex @code{\c}, and fill mode 8247@cindex fill mode, and @code{\c} 8248@cindex mode, fill, and @code{\c} 8249If fill mode is active (using the @code{fi} request), a word interrupted 8250with @code{\c} will be continued with the text on the next input text line, 8251without an intervening space. 8252 8253@Example 8254This is a te\c 8255st. 8256 @result{} This is a test. 8257@endExample 8258@end itemize 8259 8260Note that an intervening control line which causes a break is stronger 8261than @code{\c}, flushing out the current partial line in the usual way. 8262 8263@cindex interrupted line register (@code{.int}) 8264The @code{.int} register contains a positive value 8265if the last output line was interrupted with @code{\c}; this is 8266associated with the current environment (@pxref{Environments}). 8267@endDefesc 8268 8269@c ===================================================================== 8270 8271@node Page Layout, Page Control, Line Control, gtroff Reference 8272@section Page Layout 8273@cindex page layout 8274@cindex layout, page 8275 8276@code{gtroff} provides some very primitive operations for controlling 8277page layout. 8278 8279@DefreqList {pl, [@Var{length}]} 8280@DefreqItem {pl, @t{+}@Var{length}} 8281@DefreqItem {pl, @t{-}@Var{length}} 8282@DefregListEnd {.p} 8283@cindex page length (@code{pl}) 8284@cindex length of page (@code{pl}) 8285Set the @dfn{page length} to @var{length} (or increment or decrement 8286the current value by @var{length}). This is the length of the 8287physical output page. The default scaling indicator is @samp{v}. 8288 8289@cindex page length register (@code{.p}) 8290The current setting can be found in the read-only number register 8291@samp{.p}. 8292 8293@cindex top margin 8294@cindex margin, top 8295@cindex bottom margin 8296@cindex margin, bottom 8297Note that this only specifies the size of the page, not the top and 8298bottom margins. Those are not set by @code{gtroff} directly. 8299@xref{Traps}, for further information on how to do this. 8300 8301Negative @code{pl} values are possible also, but not very useful: No 8302trap is sprung, and each line is output on a single page (thus 8303suppressing all vertical spacing). 8304 8305If no argument or an invalid argument is given, @code{pl} sets the page 8306length to 11@dmn{i}. 8307@endDefreq 8308 8309@cindex headers 8310@cindex footers 8311@cindex titles 8312@code{gtroff} provides several operations which help in setting up top 8313and bottom titles (or headers and footers). 8314 8315@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 8316@cindex title line (@code{tl}) 8317@cindex three-part title (@code{tl}) 8318@cindex page number character (@code{%}) 8319Print a @dfn{title line}. It consists of three parts: a left 8320justified portion, a centered portion, and a right justified portion. 8321The argument separator @samp{'} can be replaced with any character not 8322occurring in the title line. The @samp{%} character is replaced with 8323the current page number. This character can be changed with the 8324@code{pc} request (see below). 8325 8326Without argument, @code{tl} is ignored. 8327 8328Some notes: 8329 8330@itemize @bullet 8331@item 8332A title line is not restricted to the top or bottom of a page. 8333 8334@item 8335@code{tl} prints the title line immediately, ignoring a partially filled 8336line (which stays untouched). 8337 8338@item 8339It is not an error to omit closing delimiters. For example, 8340@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 8341title line with the left justified word @samp{foo}; the centered and 8342right justfied parts are empty. 8343 8344@item 8345@code{tl} accepts the same parameter delimiting characters as the 8346@code{\A} escape; see @ref{Escapes}. 8347@end itemize 8348@endDefreq 8349 8350@DefreqList {lt, [@Var{length}]} 8351@DefreqItem {lt, @t{+}@Var{length}} 8352@DefreqItem {lt, @t{-}@Var{length}} 8353@DefregListEnd {.lt} 8354@cindex length of title line (@code{lt}) 8355@cindex title line, length (@code{lt}) 8356@cindex title line length register (@code{.lt}) 8357The title line is printed using its own line length, which is 8358specified (or incremented or decremented) with the @code{lt} request. 8359Initially, the title line length is set to 6.5@dmn{i}. If a negative 8360line length is specified (which is not allowed), @code{gtroff} emits a 8361warning of type @samp{range} and sets the title line length to zero. 8362The default scaling indicator is @samp{m}. If @code{lt} is called 8363without an argument, the title length is reset to the previous value 8364before the last call to @code{lt}. 8365 8366The current setting of this is available in the @code{.lt} read-only 8367number register; it is associated with the current environment 8368(@pxref{Environments}). 8369@endDefreq 8370 8371@DefreqList {pn, page} 8372@DefreqItem {pn, @t{+}@Var{page}} 8373@DefreqItem {pn, @t{-}@Var{page}} 8374@DefregListEnd {.pn} 8375@cindex page number (@code{pn}) 8376@cindex number, page (@code{pn}) 8377Change (increase or decrease) the page number of the @emph{next} page. 8378The only argument is the page number; the request is ignored without a 8379parameter. 8380 8381The read-only number register @code{.pn} contains the number of the next 8382page: either the value set by a @code{pn} request, or the number of the 8383current page plus@tie{}1. 8384@endDefreq 8385 8386@Defreq {pc, [@Var{char}]} 8387@cindex changing the page number character (@code{pc}) 8388@cindex page number character, changing (@code{pc}) 8389@vindex % 8390Change the page number character (used by the @code{tl} request) to a 8391different character. With no argument, this mechanism is disabled. 8392Note that this doesn't affect the number register@tie{}@code{%}. 8393@endDefreq 8394 8395@xref{Traps}. 8396 8397 8398@c ===================================================================== 8399 8400@node Page Control, Fonts and Symbols, Page Layout, gtroff Reference 8401@section Page Control 8402@cindex page control 8403@cindex control, page 8404 8405@DefreqList {bp, [@Var{page}]} 8406@DefreqItem {bp, @t{+}@Var{page}} 8407@DefreqItem {bp, @t{-}@Var{page}} 8408@DefregListEnd {%} 8409@cindex new page (@code{bp}) 8410@cindex page, new (@code{bp}) 8411Stop processing the current page and move to the next page. This 8412request causes a break. It can also take an argument to set 8413(increase, decrease) the page number of the next page (which actually 8414becomes the current page after @code{bp} has finished). The 8415difference between @code{bp} and @code{pn} is that @code{pn} does not 8416cause a break or actually eject a page. @xref{Page Layout}. 8417 8418@Example 8419.de newpage \" define macro 8420'bp \" begin page 8421'sp .5i \" vertical space 8422.tl 'left top'center top'right top' \" title 8423'sp .3i \" vertical space 8424.. \" end macro 8425@endExample 8426 8427@cindex @code{bp} request, and top-level diversion 8428@cindex top-level diversion, and @code{bp} 8429@cindex diversion, top-level, and @code{bp} 8430@code{bp} has no effect if not called within the top-level diversion 8431(@pxref{Diversions}). 8432 8433@cindex page number register (@code{%}) 8434@cindex current page number (@code{%}) 8435The read-write register@tie{}@code{%} holds the current page number. 8436 8437The number register @code{.pe} is set to@tie{}1 while @code{bp} is 8438active. @xref{Page Location Traps}. 8439@endDefreq 8440 8441@Defreq {ne, [@Var{space}]} 8442@cindex orphan lines, preventing with @code{ne} 8443@cindex conditional page break (@code{ne}) 8444@cindex page break, conditional (@code{ne}) 8445It is often necessary to force a certain amount of space before a new 8446page occurs. This is most useful to make sure that there is not a 8447single @dfn{orphan} line left at the bottom of a page. The @code{ne} 8448request ensures that there is a certain distance, specified by the 8449first argument, before the next page is triggered (see @ref{Traps}, 8450for further information). The default scaling indicator for @code{ne} 8451is @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no 8452argument is given. 8453 8454For example, to make sure that no fewer than 2@tie{}lines get orphaned, 8455do the following before each paragraph: 8456 8457@Example 8458.ne 2 8459text text text 8460@endExample 8461 8462@code{ne} will then automatically cause a page break if there is space 8463for one line only. 8464@endDefreq 8465 8466@DefreqList {sv, [@Var{space}]} 8467@DefreqListEnd {os, } 8468@cindex @code{ne} request, comparison with @code{sv} 8469@code{sv} is similar to the @code{ne} request; it reserves the 8470specified amount of vertical space. If the desired amount of space 8471exists before the next trap (or the bottom page boundary if no trap is 8472set), the space is output immediately (ignoring a partially filled line 8473which stays untouched). If there is not enough space, it is stored for 8474later output via the @code{os} request. The default value is@tie{}1@dmn{v} 8475if no argument is given; the default scaling indicator is @samp{v}. 8476 8477@cindex @code{sv} request, and no-space mode 8478@cindex @code{os} request, and no-space mode 8479Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv} 8480request allows negative values for @var{space}, @code{os} will ignore 8481them. 8482@endDefreq 8483 8484@Defreg {nl} 8485@cindex current vertical position (@code{nl}) 8486@cindex vertical position, current (@code{nl}) 8487@cindex position, vertical, current (@code{nl}) 8488This register contains the current vertical position. If the vertical 8489position is zero and the top of page transition hasn't happened yet, 8490@code{nl} is set to negative value. @code{gtroff} itself does this at 8491the very beginning of a document before anything has been printed, but 8492the main usage is to plant a header trap on a page if this page has 8493already started. 8494 8495Consider the following: 8496 8497@Example 8498.de xxx 8499. sp 8500. tl ''Header'' 8501. sp 8502.. 8503. 8504First page. 8505.bp 8506.wh 0 xxx 8507.nr nl (-1) 8508Second page. 8509@endExample 8510 8511@noindent 8512Result: 8513 8514@Example 8515First page. 8516 8517... 8518 8519 Header 8520 8521Second page. 8522 8523... 8524@endExample 8525 8526@noindent 8527Without resetting @code{nl} to a negative value, the just planted trap 8528would be active beginning with the @emph{next} page, not the current 8529one. 8530 8531@xref{Diversions}, for a comparison with the @code{.h} and @code{.d} 8532registers. 8533@endDefreg 8534 8535@c ===================================================================== 8536 8537@node Fonts and Symbols, Sizes, Page Control, gtroff Reference 8538@section Fonts and Symbols 8539@cindex fonts 8540 8541@code{gtroff} can switch fonts at any point in the text. 8542 8543The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 8544These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY 8545devices, there is also at least one symbol font which contains various 8546special symbols (Greek, mathematics). 8547 8548@menu 8549* Changing Fonts:: 8550* Font Families:: 8551* Font Positions:: 8552* Using Symbols:: 8553* Special Fonts:: 8554* Artificial Fonts:: 8555* Ligatures and Kerning:: 8556@end menu 8557 8558@c --------------------------------------------------------------------- 8559 8560@node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols 8561@subsection Changing Fonts 8562@cindex fonts 8563 8564@DefreqList {ft, [@Var{font}]} 8565@DefescItem {\\f, , f, } 8566@DefescItem {\\f, @Lparen{}, fn, } 8567@DefescItem {\\f, @Lbrack{}, font, @Rbrack{}} 8568@DefregListEnd {.sty} 8569@cindex changing fonts (@code{ft}, @code{\f}) 8570@cindex fonts, changing (@code{ft}, @code{\f}) 8571@cindex @code{sty} request, and changing fonts 8572@cindex @code{fam} request, and changing fonts 8573@cindex @code{\F}, and changing fonts 8574@kindex styles 8575@kindex family 8576@pindex DESC 8577The @code{ft} request and the @code{\f} escape change the current font 8578to @var{font} (one-character name@tie{}@var{f}, two-character name 8579@var{fn}). 8580 8581If @var{font} is a style name (as set with the @code{sty} request or 8582with the @code{styles} command in the @file{DESC} file), use it within 8583the current font family (as set with the @code{fam} request, @code{\F} 8584escape, or with the @code{family} command in the @file{DESC} file). 8585 8586@cindex previous font (@code{ft}, @code{\f[]}, @code{\fP}) 8587@cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP}) 8588With no argument or using @samp{P} as an argument, @code{.ft} switches 8589to the previous font. Use @code{\f[]} to do this with the escape. The 8590old syntax forms @code{\fP} or @code{\f[P]} are also supported. 8591 8592Fonts are generally specified as upper-case strings, which are usually 85931@tie{}to 4 characters representing an abbreviation or acronym of the 8594font name. This is no limitation, just a convention. 8595 8596The example below produces two identical lines. 8597 8598@Example 8599eggs, bacon, 8600.ft B 8601spam 8602.ft 8603and sausage. 8604 8605eggs, bacon, \fBspam\fP and sausage. 8606@endExample 8607 8608Note that @code{\f} doesn't produce an input token in @code{gtroff}. 8609As a consequence, it can be used in requests like @code{mc} (which 8610expects a single character as an argument) to change the font on 8611the fly: 8612 8613@Example 8614.mc \f[I]x\f[] 8615@endExample 8616 8617The current style name is available in the read-only number register 8618@samp{.sty} (this is a string-valued register); if the current font 8619isn't a style, the empty string is returned. It is associated with 8620the current environment. 8621 8622@xref{Font Positions}, for an alternative syntax. 8623@endDefreq 8624 8625@Defreq {ftr, f [@Var{g}]} 8626@cindex @code{ft} request, and font translations 8627@cindex @code{ul} request, and font translations 8628@cindex @code{bd} request, and font translations 8629@cindex @code{\f}, and font translations 8630@cindex @code{cs} request, and font translations 8631@cindex @code{tkf} request, and font translations 8632@cindex @code{special} request, and font translations 8633@cindex @code{fspecial} request, and font translations 8634@cindex @code{fp} request, and font translations 8635@cindex @code{sty} request, and font translations 8636@cindex @code{if} request, and font translations 8637@cindex @code{ie} request, and font translations 8638@cindex @code{while} request, and font translations 8639Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font 8640named@tie{}@var{f} is referred to in a @code{\f} escape sequence, 8641in the @code{F} and @code{S} conditional operators, or in the 8642@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 8643@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests, 8644font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f} 8645the translation is undone. 8646@endDefreq 8647 8648@c --------------------------------------------------------------------- 8649 8650@node Font Families, Font Positions, Changing Fonts, Fonts and Symbols 8651@subsection Font Families 8652@cindex font families 8653@cindex families, font 8654@cindex font styles 8655@cindex styles, font 8656 8657Due to the variety of fonts available, @code{gtroff} has added the 8658concept of @dfn{font families} and @dfn{font styles}. The fonts are 8659specified as the concatenation of the font family and style. Specifying 8660a font without the family part causes @code{gtroff} to use that style of 8661the current family. 8662 8663@cindex PostScript fonts 8664@cindex fonts, PostScript 8665Currently, fonts for the devices @option{-Tps}, @option{-Tdvi}, 8666@option{-Tlj4}, @option{-Tlbp}, and the X11 fonts are set up to this 8667mechanism. By default, @code{gtroff} uses the Times family with the four 8668styles @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 8669 8670This way, it is possible to use the basic four fonts and to select a 8671different font family on the command line (@pxref{Groff Options}). 8672 8673@DefreqList {fam, [@Var{family}]} 8674@DefregItem {.fam} 8675@DefescItem {\\F, , f, } 8676@DefescItem {\\F, @Lparen{}, fm, } 8677@DefescItem {\\F, @Lbrack{}, family, @Rbrack{}} 8678@DefregListEnd {.fn} 8679@cindex changing font family (@code{fam}, @code{\F}) 8680@cindex font family, changing (@code{fam}, @code{\F}) 8681Switch font family to @var{family} (one-character name@tie{}@var{f}, 8682two-character name @var{fm}). If no argument is given, switch 8683back to the previous font family. Use @code{\F[]} to do this with the 8684escape. Note that @code{\FP} doesn't work; it selects font family 8685@samp{P} instead. 8686 8687The value at start-up is @samp{T}. 8688The current font family is available in the read-only number register 8689@samp{.fam} (this is a string-valued register); it is associated with 8690the current environment. 8691 8692@Example 8693spam, 8694.fam H \" helvetica family 8695spam, \" used font is family H + style R = HR 8696.ft B \" family H + style B = font HB 8697spam, 8698.fam T \" times family 8699spam, \" used font is family T + style B = TB 8700.ft AR \" font AR (not a style) 8701baked beans, 8702.ft R \" family T + style R = font TR 8703and spam. 8704@endExample 8705 8706Note that @code{\F} doesn't produce an input token in @code{gtroff}. 8707As a consequence, it can be used in requests like @code{mc} (which 8708expects a single character as an argument) to change the font family on 8709the fly: 8710 8711@Example 8712.mc \F[P]x\F[] 8713@endExample 8714 8715The @samp{.fn} register contains the current @dfn{real font name} 8716of the current font. 8717This is a string-valued register. 8718If the current font is a style, the value of @code{\n[.fn]} 8719is the proper concatenation of family and style name. 8720@endDefreq 8721 8722@Defreq {sty, n style} 8723@cindex changing font style (@code{sty}) 8724@cindex font style, changing (@code{sty}) 8725@cindex @code{cs} request, and font styles 8726@cindex @code{bd} request, and font styles 8727@cindex @code{tkf} request, and font styles 8728@cindex @code{uf} request, and font styles 8729@cindex @code{fspecial} request, and font styles 8730Associate @var{style} with font position@tie{}@var{n}. A font position 8731can be associated either with a font or with a style. The current 8732font is the index of a font position and so is also either a font or a 8733style. If it is a style, the font that is actually used is the font 8734which name is the concatenation of the name of the current 8735family and the name of the current style. For example, if the current 8736font is@tie{}1 and font position@tie{}1 is associated with style 8737@samp{R} and the current font family is @samp{T}, then font 8738@samp{TR} will be used. If the current font is not a style, then the 8739current family is ignored. If the requests @code{cs}, @code{bd}, 8740@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, 8741they will instead be applied to the member of the current family 8742corresponding to that style. 8743 8744@var{n}@tie{}must be a non-negative integer value. 8745 8746@pindex DESC 8747@kindex styles 8748The default family can be set with the @option{-f} option 8749(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 8750file controls which font positions (if any) are initially associated 8751with styles rather than fonts. For example, the default setting for 8752@sc{PostScript} fonts 8753 8754@Example 8755styles R I B BI 8756@endExample 8757 8758@noindent 8759is equivalent to 8760 8761@Example 8762.sty 1 R 8763.sty 2 I 8764.sty 3 B 8765.sty 4 BI 8766@endExample 8767 8768@code{fam} and @code{\F} always check whether the current font position 8769is valid; this can give surprising results if the current font position is 8770associated with a style. 8771 8772In the following example, we want to access the @sc{PostScript} font 8773@code{FooBar} from the font family @code{Foo}: 8774 8775@Example 8776.sty \n[.fp] Bar 8777.fam Foo 8778 @result{} warning: can't find font `FooR' 8779@endExample 8780 8781@noindent 8782The default font position at start-up is@tie{}1; for the 8783@sc{PostScript} device, this is associated with style @samp{R}, so 8784@code{gtroff} tries to open @code{FooR}. 8785 8786A solution to this problem is to use a dummy font like the following: 8787 8788@Example 8789.fp 0 dummy TR \" set up dummy font at position 0 8790.sty \n[.fp] Bar \" register style `Bar' 8791.ft 0 \" switch to font at position 0 8792.fam Foo \" activate family `Foo' 8793.ft Bar \" switch to font `FooBar' 8794@endExample 8795 8796@xref{Font Positions}. 8797@endDefreq 8798 8799@c --------------------------------------------------------------------- 8800 8801@node Font Positions, Using Symbols, Font Families, Fonts and Symbols 8802@subsection Font Positions 8803@cindex font positions 8804@cindex positions, font 8805 8806For the sake of old phototypesetters and compatibility with old versions 8807of @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 8808on which various fonts are mounted. 8809 8810@DefreqList {fp, pos font [@Var{external-name}]} 8811@DefregItem {.f} 8812@DefregListEnd {.fp} 8813@cindex mounting font (@code{fp}) 8814@cindex font, mounting (@code{fp}) 8815Mount font @var{font} at position @var{pos} (which must be a 8816non-negative integer). This numeric position can then be referred to 8817with font changing commands. When @code{gtroff} starts it is using 8818font position@tie{}1 (which must exist; position@tie{}0 is unused 8819usually at start-up). 8820 8821@cindex font position register (@code{.f}) 8822The current font in use, as a font position, is available in the 8823read-only number register @samp{.f}. This can be useful to remember the 8824current font for later recall. It is associated with the current 8825environment (@pxref{Environments}). 8826 8827@Example 8828.nr save-font \n[.f] 8829.ft B 8830... text text text ... 8831.ft \n[save-font] 8832@endExample 8833 8834@cindex next free font position register (@code{.fp}) 8835The number of the next free font position is available in the read-only 8836number register @samp{.fp}. This is useful when mounting a new font, 8837like so: 8838 8839@Example 8840.fp \n[.fp] NEATOFONT 8841@endExample 8842 8843@pindex DESC@r{, and font mounting} 8844Fonts not listed in the @file{DESC} file are automatically mounted on 8845the next available font position when they are referenced. If a font 8846is to be mounted explicitly with the @code{fp} request on an unused 8847font position, it should be mounted on the first unused font position, 8848which can be found in the @code{.fp} register. Although @code{gtroff} 8849does not enforce this strictly, it is not allowed to mount a font at a 8850position whose number is much greater (approx.@: 1000 positions) than 8851that of any currently used position. 8852 8853The @code{fp} request has an optional third argument. This argument 8854gives the external name of the font, which is used for finding the font 8855description file. The second argument gives the internal name of the 8856font which is used to refer to the font in @code{gtroff} after it has 8857been mounted. If there is no third argument then the internal name is 8858used as the external name. This feature makes it possible to use 8859fonts with long names in compatibility mode. 8860@endDefreq 8861 8862Both the @code{ft} request and the @code{\f} escape have alternative 8863syntax forms to access font positions. 8864 8865@DefreqList {ft, nnn} 8866@DefescItem {\\f, , n, } 8867@DefescItem {\\f, @Lparen{}, nn, } 8868@DefescListEnd {\\f, @Lbrack{}, nnn, @Rbrack{}} 8869@cindex changing font position (@code{\f}) 8870@cindex font position, changing (@code{\f}) 8871@cindex @code{sty} request, and font positions 8872@cindex @code{fam} request, and font positions 8873@cindex @code{\F}, and font positions 8874@kindex styles 8875@kindex family 8876@pindex DESC 8877Change the current font position to @var{nnn} (one-digit 8878position@tie{}@var{n}, two-digit position @var{nn}), which must be a 8879non-negative integer. 8880 8881If @var{nnn} is associated with a style (as set with the @code{sty} 8882request or with the @code{styles} command in the @file{DESC} file), use 8883it within the current font family (as set with the @code{fam} request, 8884the @code{\F} escape, or with the @code{family} command in the @file{DESC} 8885file). 8886 8887@Example 8888this is font 1 8889.ft 2 8890this is font 2 8891.ft \" switch back to font 1 8892.ft 3 8893this is font 3 8894.ft 8895this is font 1 again 8896@endExample 8897 8898@xref{Changing Fonts}, for the standard syntax form. 8899@endDefreq 8900 8901@c --------------------------------------------------------------------- 8902 8903@node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols 8904@subsection Using Symbols 8905@cindex using symbols 8906@cindex symbols, using 8907 8908@cindex glyph 8909@cindex character 8910@cindex ligature 8911A @dfn{glyph} is a graphical representation of a @dfn{character}. 8912While a character is an abstract entity containing semantic 8913information, a glyph is something which can be actually seen on screen 8914or paper. It is possible that a character has multiple glyph 8915representation forms (for example, the character `A' can be either 8916written in a roman or an italic font, yielding two different glyphs); 8917sometimes more than one character maps to a single glyph (this is a 8918@dfn{ligature} -- the most common is `fi'). 8919 8920@cindex symbol 8921@cindex special fonts 8922@kindex fonts 8923@pindex DESC 8924@cindex @code{special} request, and glyph search order 8925@cindex @code{fspecial} request, and glyph search order 8926A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 8927glyph names of a particular font are defined in its font file. If the 8928user requests a glyph not available in this font, @code{gtroff} looks 8929up an ordered list of @dfn{special fonts}. By default, the 8930@sc{PostScript} output device supports the two special fonts @samp{SS} 8931(slanted symbols) and @samp{S} (symbols) (the former is looked up 8932before the latter). Other output devices use different names for 8933special fonts. Fonts mounted with the @code{fonts} keyword in the 8934@file{DESC} file are globally available. To install additional 8935special fonts locally (i.e.@: for a particular font), use the 8936@code{fspecial} request. 8937 8938Here the exact rules how @code{gtroff} searches a given symbol: 8939 8940@itemize @bullet 8941@item 8942If the symbol has been defined with the @code{char} request, use it. 8943This hides a symbol with the same name in the current font. 8944 8945@item 8946Check the current font. 8947 8948@item 8949If the symbol has been defined with the @code{fchar} request, use it. 8950 8951@item 8952Check whether the current font has a font-specific list of special fonts; 8953test all fonts in the order of appearance in the last @code{fspecial} 8954call if appropriate. 8955 8956@item 8957If the symbol has been defined with the @code{fschar} request for the 8958current font, use it. 8959 8960@item 8961Check all fonts in the order of appearance in the last @code{special} 8962call. 8963 8964@item 8965If the symbol has been defined with the @code{schar} request, use it. 8966 8967@item 8968As a last resort, consult all fonts loaded up to now for special fonts 8969and check them, starting with the lowest font number. Note that this can 8970sometimes lead to surprising results since the @code{fonts} line in the 8971@file{DESC} file often contains empty positions which are filled later 8972on. For example, consider the following: 8973 8974@Example 8975fonts 3 0 0 FOO 8976@endExample 8977 8978@noindent 8979This mounts font @code{foo} at font position@tie{}3. We assume that 8980@code{FOO} is a special font, containing glyph @code{foo}, 8981and that no font has been loaded yet. The line 8982 8983@Example 8984.fspecial BAR BAZ 8985@endExample 8986 8987@noindent 8988makes font @code{BAZ} special only if font @code{BAR} is active. We 8989further assume that @code{BAZ} is really a special font, i.e., the font 8990description file contains the @code{special} keyword, and that it 8991also contains glyph @code{foo} with a special shape fitting to font 8992@code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at 8993font position@tie{}1, and @code{BAZ} at position@tie{}2. 8994 8995We now switch to a new font @code{XXX}, trying to access glyph @code{foo} 8996which is assumed to be missing. There are neither font-specific special 8997fonts for @code{XXX} nor any other fonts made special with the 8998@code{special} request, so @code{gtroff} starts the search for special 8999fonts in the list of already mounted fonts, with increasing font 9000positions. Consequently, it finds @code{BAZ} before @code{FOO} even for 9001@code{XXX} which is not the intended behaviour. 9002@end itemize 9003 9004@xref{Font Files}, and @ref{Special Fonts}, for more details. 9005 9006@cindex list of available glyphs (@cite{groff_char(7)} man page) 9007@cindex available glyphs, list (@cite{groff_char(7)} man page) 9008@cindex glyphs, available, list (@cite{groff_char(7)} man page) 9009The list of available symbols is device dependent; see the 9010@cite{groff_char(7)} man page for a complete list of all glyphs. For 9011example, say 9012 9013@Example 9014man -Tdvi groff_char > groff_char.dvi 9015@endExample 9016 9017@noindent 9018for a list using the default DVI fonts (not all versions of the 9019@code{man} program support the @option{-T} option). If you want to 9020use an additional macro package to change the used fonts, @code{groff} 9021must be called directly: 9022 9023@Example 9024groff -Tdvi -mec -man groff_char.7 > groff_char.dvi 9025@endExample 9026 9027@cindex composite glyph names 9028@cindex glyph names, composite 9029@cindex groff glyph list (GGL) 9030@cindex GGL (groff glyph list) 9031@cindex adobe glyph list (AGL) 9032@cindex AGL (adobe glyph list) 9033Glyph names not listed in groff_char(7) are derived algorithmically, 9034using a simplified version of the Adobe Glyph List (AGL) algorithm 9035which is described in 9036@uref{http://partners.adobe.com@//asn@//tech@//type@//unicodegn.jsp}. 9037The (frozen) set of glyph names which can't be derived algorithmically 9038is called @dfn{groff glyph list (GGL)}. 9039 9040@itemize @bullet 9041@item 9042A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is 9043not a composite character will be named 9044@code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an 9045uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E}, 9046@code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at 9047least four @code{X} digits; if necessary, add leading zeroes (after the 9048@samp{u}). No zero padding is allowed for character codes greater than 90490xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF 9050represented with character codes from the surrogate area U+D800-U+DFFF) 9051are not allowed too. 9052 9053@item 9054A glyph representing more than a single input character will be named 9055 9056@display 9057@samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{} 9058@end display 9059 9060@noindent 9061Example: @code{u0045_0302_0301}. 9062 9063For simplicity, all Unicode characters which are composites must be 9064decomposed maximally (this is normalization form@tie{}D in the Unicode 9065standard); for example, @code{u00CA_0301} is not a valid glyph name 9066since U+00CA (@sc{latin capital letter e with circumflex}) can be 9067further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302 9068(@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the 9069glyph name for U+1EBE, @sc{latin capital letter e with circumflex and 9070acute}. 9071 9072@item 9073groff maintains a table to decompose all algorithmically derived glyph 9074names which are composites itself. For example, @code{u0100} (@sc{latin 9075letter a with macron}) will be automatically decomposed into 9076@code{u0041_0304}. Additionally, a glyph name of the GGL is preferred 9077to an algorithmically derived glyph name; groff also automatically does 9078the mapping. Example: The glyph @code{u0045_0302} will be mapped to 9079@code{^E}. 9080 9081@item 9082glyph names of the GGL can't be used in composite glyph names; for 9083example, @code{^E_u0301} is invalid. 9084@end itemize 9085 9086@DefescList {\\, @Lparen{}, nm, } 9087@DefescItem {\\, @Lbrack{}, name, @Rbrack{}} 9088@DefescListEnd {\\, @Lbrack{}, component1 component2 @dots{}, @Rbrack{}} 9089Insert a symbol @var{name} (two-character name @var{nm}) or a composite 9090glyph with component glyphs @var{component1}, @var{component2}, 9091@enddots{} There is no special syntax for one-character names -- the 9092natural form @samp{\@var{n}} would collide with escapes.@footnote{Note 9093that a one-character symbol is not the same as an input character, i.e., 9094the character @code{a} is not the same as @code{\[a]}. By default, 9095@code{groff} defines only a single one-character symbol, @code{\[-]}; it 9096is usually accessed as @code{\-}. On the other hand, @code{gtroff} has 9097the special feature that @code{\[char@var{XXX}]} is the same as the 9098input character with character code @var{XXX}. For example, 9099@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII} 9100encoding is active.} 9101 9102If @var{name} is undefined, a warning of type @samp{char} is generated, 9103and the escape is ignored. @xref{Debugging}, for information about 9104warnings. 9105 9106groff resolves @code{\[...]} with more than a single component as 9107follows: 9108 9109@itemize @bullet 9110@item 9111Any component which is found in the GGL will be converted to the 9112@code{u@var{XXXX}} form. 9113 9114@item 9115Any component @code{u@var{XXXX}} which is found in the list of 9116decomposable glyphs will be decomposed. 9117 9118@item 9119The resulting elements are then concatenated with @samp{_} inbetween, 9120dropping the leading @samp{u} in all elements but the first. 9121@end itemize 9122 9123No check for the existence of any component (similar to @code{tr} 9124request) will be done. 9125 9126Examples: 9127 9128@table @code 9129@item \[A ho] 9130@samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the 9131final glyph name would be @code{u0041_02DB}. Note this is not the 9132expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for 9133a proper composite a non-spacing ogonek (U+0328) is necessary. Looking 9134into the file @file{composite.tmac} one can find @w{@samp{.composite ho 9135u0328}} which changes the mapping of @samp{ho} while a composite glyph 9136name is constructed, causing the final glyph name to be 9137@code{u0041_0328}. 9138 9139@item \[^E u0301] 9140@itemx \[^E aa] 9141@itemx \[E a^ aa] 9142@itemx \[E ^ '] 9143@samp{^E} maps to @code{u0045_0302}, thus the final glyph name is 9144@code{u0045_0302_0301} in all forms (assuming proper calls of the 9145@code{composite} request). 9146@end table 9147 9148It is not possible to define glyphs with names like @w{@samp{A ho}} 9149within a groff font file. This is not really a limitation; instead, you 9150have to define @code{u0041_0328}. 9151@endDefesc 9152 9153@Defesc {\\C, ', xxx, '} 9154@cindex named character (@code{\C}) 9155@cindex character, named (@code{\C}) 9156Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a 9157misnomer since it accesses an output glyph.} Normally it is more 9158convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage 9159that it is compatible with newer versions of @acronym{AT&T} 9160@code{troff} and is available in compatibility mode. 9161@endDefesc 9162 9163@Defreq {composite, from to} 9164@pindex composite.tmac 9165Map glyph name @var{from} to glyph name @var{to} if it is used in 9166@code{\[...]} with more than one component. See above for examples. 9167 9168This mapping is based on glyph names only; no check for the existence of 9169either glyph is done. 9170 9171A set of default mappings for many accents can be found in the file 9172@file{composite.tmac} which is loaded at start-up. 9173@endDefreq 9174 9175@Defesc {\\N, ', n, '} 9176@cindex numbered glyph (@code{\N}) 9177@cindex glyph, numbered (@code{\N}) 9178@cindex @code{char} request, used with @code{\N} 9179@cindex Unicode 9180Typeset the glyph with code@tie{}@var{n} in the current font 9181(@code{n}@tie{}is @strong{not} the input character code). The 9182number @var{n}@tie{}can be any non-negative decimal integer. Most devices 9183only have glyphs with codes between 0 and@tie{}255; the Unicode 9184output device uses codes in the range 0--65535. If the current 9185font does not contain a glyph with that code, special fonts are 9186@emph{not} searched. The @code{\N} escape sequence can be 9187conveniently used in conjunction with the @code{char} request: 9188 9189@Example 9190.char \[phone] \f[ZD]\N'37' 9191@endExample 9192 9193@noindent 9194@pindex DESC 9195@cindex unnamed glyphs 9196@cindex glyphs, unnamed 9197The code of each glyph is given in the fourth column in the font 9198description file after the @code{charset} command. It is possible to 9199include unnamed glyphs in the font description file by using a 9200name of @samp{---}; the @code{\N} escape sequence is the only way to 9201use these. 9202 9203No kerning is applied to glyphs accessed with @code{\N}. 9204@endDefesc 9205 9206Some escape sequences directly map onto special glyphs. 9207 9208@Defesc {\\', , , } 9209This is a backslash followed by the apostrophe character, @acronym{ASCII} 9210character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same 9211as @code{\[aa]}, the acute accent. 9212@endDefesc 9213 9214@Defesc {\\`, , , } 9215This is a backslash followed by @acronym{ASCII} character @code{0x60} 9216(@acronym{EBCDIC} character @code{0x79} usually). The same as 9217@code{\[ga]}, the grave accent. 9218@endDefesc 9219 9220@Defesc {\\-, , , } 9221This is the same as @code{\[-]}, the minus sign in the current font. 9222@endDefesc 9223 9224@Defreq {cflags, n c1 c2 @dots{}} 9225@cindex glyph properties (@code{cflags}) 9226@cindex character properties (@code{cflags}) 9227@cindex properties of glyphs (@code{cflags}) 9228@cindex properties of characters (@code{cflags}) 9229Input characters and symbols have certain properties associated 9230with it.@footnote{Note that the output glyphs themselves don't have 9231such properties. For @code{gtroff}, a glyph is a numbered box with 9232a given width, depth, and height, nothing else. All manipulations 9233with the @code{cflags} request work on the input level.} These 9234properties can be modified with the @code{cflags} request. The 9235first argument is the sum of the desired flags and the remaining 9236arguments are the characters or symbols to have those properties. 9237It is possible to omit the spaces between the characters or symbols. 9238 9239@table @code 9240@item 1 9241@cindex end-of-sentence characters 9242@cindex characters, end-of-sentence 9243The character ends sentences (initially characters @samp{.?!} have this 9244property). 9245 9246@item 2 9247@cindex hyphenating characters 9248@cindex characters, hyphenation 9249Lines can be broken before the character (initially no characters have 9250this property). 9251 9252@item 4 9253@cindex @code{hy} glyph, and @code{cflags} 9254@cindex @code{em} glyph, and @code{cflags} 9255Lines can be broken after the character (initially the character 9256@samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property). 9257 9258@item 8 9259@cindex overlapping characters 9260@cindex characters, overlapping 9261@cindex @code{ul} glyph, and @code{cflags} 9262@cindex @code{rn} glyph, and @code{cflags} 9263@cindex @code{ru} glyph, and @code{cflags} 9264@cindex @code{radicalex} glyph, and @code{cflags} 9265@cindex @code{sqrtex} glyph, and @code{cflags} 9266The character overlaps horizontally if used as a horizontal line building 9267element. Initially the symbols @samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]}, 9268@samp{\[radicalex]}, and @samp{\[sqrtex]} have this property. 9269 9270@item 16 9271@cindex @code{br} glyph, and @code{cflags} 9272The character overlaps vertically if used as vertical line building element. 9273Initially symbol @samp{\[br]} has this property. 9274 9275@item 32 9276@cindex transparent characters 9277@cindex character, transparent 9278@cindex @code{"}, at end of sentence 9279@cindex @code{'}, at end of sentence 9280@cindex @code{)}, at end of sentence 9281@cindex @code{]}, at end of sentence 9282@cindex @code{*}, at end of sentence 9283@cindex @code{dg} glyph, at end of sentence 9284@cindex @code{rq} glyph, at end of sentence 9285An end-of-sentence character followed by any number of characters with 9286this property is treated as the end of a sentence if followed by a 9287newline or two spaces; in other words the character is 9288@dfn{transparent} for the purposes of end-of-sentence recognition -- 9289this is the same as having a zero space factor in @TeX{} (initially 9290characters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have 9291this property). 9292@end table 9293@endDefreq 9294 9295@DefreqList {char, g [@Var{string}]} 9296@DefreqItem {fchar, g [@Var{string}]} 9297@DefreqItem {fschar, f g [@Var{string}]} 9298@DefreqListEnd {schar, g [@Var{string}]} 9299@cindex defining character (@code{char}) 9300@cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar}) 9301@cindex character, defining (@code{char}) 9302@cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar}) 9303@cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar}) 9304@cindex creating new characters (@code{char}) 9305@cindex defining symbol (@code{char}) 9306@cindex symbol, defining (@code{char}) 9307@cindex defining glyph (@code{char}) 9308@cindex glyph, defining (@code{char}) 9309@cindex escape character, while defining glyph 9310@cindex character, escape, while defining glyph 9311@cindex @code{tr} request, and glyph definitions 9312@cindex @code{cp} request, and glyph definitions 9313@cindex @code{rc} request, and glyph definitions 9314@cindex @code{lc} request, and glyph definitions 9315@cindex @code{\l}, and glyph definitions 9316@cindex @code{\L}, and glyph definitions 9317@cindex @code{\&}, and glyph definitions 9318@cindex @code{\e}, and glyph definitions 9319@cindex @code{hcode} request, and glyph definitions 9320Define a new glyph@tie{}@var{g} to be @var{string} (which can be 9321empty).@footnote{@code{char} is a misnomer since an output glyph is 9322defined.} Every time glyph@tie{}@var{g} needs to be printed, 9323@var{string} is processed in a temporary environment and the result is 9324wrapped up into a single object. Compatibility mode is turned off and 9325the escape character is set to @samp{\} while @var{string} is being 9326processed. Any emboldening, constant spacing or track kerning is 9327applied to this object rather than to individual characters in 9328@var{string}. 9329 9330A glyph defined by these requests can be used just 9331like a normal glyph provided by the output device. In particular, 9332other characters can be translated to it with the @code{tr} or 9333@code{trin} requests; it can be made the leader character by the 9334@code{lc} request; repeated patterns can be drawn with the glyph 9335using the @code{\l} and @code{\L} escape sequences; words containing 9336the glyph can be hyphenated correctly if the @code{hcode} request 9337is used to give the glyph's symbol a hyphenation code. 9338 9339There is a special anti-recursion feature: Use of @code{g} within 9340the glyph's definition is handled like normal characters and symbols 9341not defined with @code{char}. 9342 9343Note that the @code{tr} and @code{trin} requests take precedence if 9344@code{char} accesses the same symbol. 9345 9346@Example 9347.tr XY 9348X 9349 @result{} Y 9350.char X Z 9351X 9352 @result{} Y 9353.tr XX 9354X 9355 @result{} Z 9356@endExample 9357 9358The @code{fchar} request defines a fallback glyph: 9359@code{gtroff} only checks for glyphs defined with @code{fchar} 9360if it cannot find the glyph in the current font. 9361@code{gtroff} carries out this test before checking special fonts. 9362 9363@code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff} 9364checks for glyphs defined with @code{fschar} after the list of fonts 9365declared as font-specific special fonts with the @code{fspecial} request, 9366but before the list of fonts declared as global special fonts with the 9367@code{special} request. 9368 9369Finally, the @code{schar} request defines a global fallback glyph: 9370@code{gtroff} checks for glyphs defined with @code{schar} after the list 9371of fonts declared as global special fonts with the @code{special} request, 9372but before the already mounted special fonts. 9373 9374@xref{Using Symbols}, for a detailed description of the glyph 9375searching mechanism in @code{gtroff}. 9376@endDefreq 9377 9378@DefreqList {rchar, c1 c2 @dots{}} 9379@DefreqListEnd {rfschar, f c1 c2 @dots{}} 9380@cindex removing glyph definition (@code{rchar}, @code{rfschar}) 9381@cindex glyph, removing definition (@code{rchar}, @code{rfschar}) 9382@cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar}) 9383Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{} 9384This undoes the effect of a @code{char}, @code{fchar}, or 9385@code{schar} request. 9386 9387It is possible to omit the whitespace between arguments. 9388 9389The request @code{rfschar} removes glyph definitions defined with 9390@code{fschar} for glyph@tie{}f. 9391@endDefreq 9392 9393@xref{Special Characters}. 9394 9395@c --------------------------------------------------------------------- 9396 9397@node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols 9398@subsection Special Fonts 9399@cindex special fonts 9400@cindex fonts, special 9401 9402Special fonts are those that @code{gtroff} searches 9403when it cannot find the requested glyph in the current font. 9404The Symbol font is usually a special font. 9405 9406@code{gtroff} provides the following two requests to add more special 9407fonts. @xref{Using Symbols}, for a detailed description of the glyph 9408searching mechanism in @code{gtroff}. 9409 9410Usually, only non-TTY devices have special fonts. 9411 9412@DefreqList {special, [@Var{s1} @Var{s2} @dots{}]} 9413@DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]} 9414@kindex fonts 9415@pindex DESC 9416Use the @code{special} request to define special fonts. Initially, this 9417list is empty. 9418 9419Use the @code{fspecial} request to designate special fonts only when 9420font@tie{}@var{f} is active. Initially, this list is empty. 9421 9422Previous calls to @code{special} or @code{fspecial} are overwritten; 9423without arguments, the particular list of special fonts is set to empty. 9424Special fonts are searched in the order they appear as arguments. 9425 9426All fonts which appear in a call to @code{special} or @code{fspecial} are 9427loaded. 9428 9429@xref{Using Symbols}, for the exact search order of glyphs. 9430@endDefreq 9431 9432@c --------------------------------------------------------------------- 9433 9434@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols 9435@subsection Artificial Fonts 9436@cindex artificial fonts 9437@cindex fonts, artificial 9438 9439There are a number of requests and escapes for artificially creating 9440fonts. These are largely vestiges of the days when output devices 9441did not have a wide variety of fonts, and when @code{nroff} and 9442@code{troff} were separate programs. Most of them are no longer 9443necessary in GNU @code{troff}. Nevertheless, they are supported. 9444 9445@DefescList {\\H, ', height, '} 9446@DefescItem {\\H, ', @t{+}height, '} 9447@DefescItem {\\H, ', @t{-}height, '} 9448@DefregListEnd {.height} 9449@cindex changing the font height (@code{\H}) 9450@cindex font height, changing (@code{\H}) 9451@cindex height, font, changing (@code{\H}) 9452Change (increment, decrement) the height of the current font, but not 9453the width. If @var{height} is zero, restore the original height. 9454Default scaling indicator is @samp{z}. 9455 9456The read-only number register @code{.height} contains the font height as 9457set by @code{\H}. 9458 9459Currently, only the @option{-Tps} device supports this feature. 9460 9461Note that @code{\H} doesn't produce an input token in @code{gtroff}. 9462As a consequence, it can be used in requests like @code{mc} (which 9463expects a single character as an argument) to change the font on 9464the fly: 9465 9466@Example 9467.mc \H'+5z'x\H'0' 9468@endExample 9469 9470In compatibility mode, @code{gtroff} behaves differently: If an 9471increment or decrement is used, it is always taken relative to the 9472current point size and not relative to the previously selected font 9473height. Thus, 9474 9475@Example 9476.cp 1 9477\H'+5'test \H'+5'test 9478@endExample 9479 9480@noindent 9481prints the word @samp{test} twice with the same font height (five 9482points larger than the current font size). 9483@endDefesc 9484 9485@DefescList {\\S, ', slant, '} 9486@DefregListEnd {.slant} 9487@cindex changing the font slant (@code{\S}) 9488@cindex font slant, changing (@code{\S}) 9489@cindex slant, font, changing (@code{\S}) 9490Slant the current font by @var{slant} degrees. Positive values slant 9491to the right. Only integer values are possible. 9492 9493The read-only number register @code{.slant} contains the font slant as 9494set by @code{\S}. 9495 9496Currently, only the @option{-Tps} device supports this feature. 9497 9498Note that @code{\S} doesn't produce an input token in @code{gtroff}. 9499As a consequence, it can be used in requests like @code{mc} (which 9500expects a single character as an argument) to change the font on 9501the fly: 9502 9503@Example 9504.mc \S'20'x\S'0' 9505@endExample 9506 9507This request is incorrectly documented in the original @acronym{UNIX} 9508troff manual; the slant is always set to an absolute value. 9509@endDefesc 9510 9511@Defreq {ul, [@Var{lines}]} 9512@cindex underlining (@code{ul}) 9513The @code{ul} request normally underlines subsequent lines if a TTY 9514output device is used. Otherwise, the lines are printed in italics 9515(only the term `underlined' is used in the following). The single 9516argument is the number of input lines to be underlined; with no 9517argument, the next line is underlined. If @var{lines} is zero or 9518negative, stop the effects of @code{ul} (if it was active). Requests 9519and empty lines do not count for computing the number of underlined 9520input lines, even if they produce some output like @code{tl}. Lines 9521inserted by macros (e.g.@: invoked by a trap) do count. 9522 9523At the beginning of @code{ul}, the current font is stored and the 9524underline font is activated. Within the span of a @code{ul} request, 9525it is possible to change fonts, but after the last line affected by 9526@code{ul} the saved font is restored. 9527 9528This number of lines still to be underlined is associated with the 9529current environment (@pxref{Environments}). The underline font can be 9530changed with the @code{uf} request. 9531 9532@c XXX @xref should be changed to grotty 9533 9534@c @xref{Troff and Nroff Mode}, for a discussion how underlining is 9535@c implemented in for TTY output devices, and which problems can arise. 9536 9537The @code{ul} request does not underline spaces. 9538@endDefreq 9539 9540@Defreq {cu, [@Var{lines}]} 9541@cindex continuous underlining (@code{cu}) 9542@cindex underlining, continuous (@code{cu}) 9543The @code{cu} request is similar to @code{ul} but underlines spaces as 9544well (if a TTY output device is used). 9545@endDefreq 9546 9547@Defreq {uf, font} 9548@cindex underline font (@code{uf}) 9549@cindex font for underlining (@code{uf}) 9550Set the underline font (globally) used by @code{ul} and @code{cu}. By 9551default, this is the font at position@tie{}2. @var{font} can be either 9552a non-negative font position or the name of a font. 9553@endDefreq 9554 9555@DefreqList {bd, font [@Var{offset}]} 9556@DefreqItem {bd, font1 font2 [@Var{offset}]} 9557@DefregListEnd {.b} 9558@cindex imitating bold face (@code{bd}) 9559@cindex bold face, imitating (@code{bd}) 9560Artificially create a bold font by printing each glyph twice, 9561slightly offset. 9562 9563Two syntax forms are available. 9564 9565@itemize @bullet 9566@item 9567Imitate a bold font unconditionally. The first argument specifies the 9568font to embolden, and the second is the number of basic units, minus 9569one, by which the two glyphs are offset. If the second argument is 9570missing, emboldening is turned off. 9571 9572@var{font} can be either a non-negative font position or the name of a 9573font. 9574 9575@var{offset} is available in the @code{.b} read-only register if a 9576special font is active; in the @code{bd} request, its default unit is 9577@samp{u}. 9578 9579@cindex @code{fspecial} request, and imitating bold 9580@kindex special 9581@cindex embolding of special fonts 9582@cindex special fonts, emboldening 9583@item 9584Imitate a bold form conditionally. Embolden @var{font1} by 9585@var{offset} only if font @var{font2} is the current font. This 9586command can be issued repeatedly to set up different emboldening 9587values for different current fonts. If the second argument is 9588missing, emboldening is turned off for this particular current font. 9589 9590This affects special fonts only (either set up with the @code{special} 9591command in font files or with the @code{fspecial} request). 9592@end itemize 9593@endDefreq 9594 9595@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 9596@cindex constant glyph space mode (@code{cs}) 9597@cindex mode for constant glyph space (@code{cs}) 9598@cindex glyph, constant space 9599@cindex @code{ps} request, and constant glyph space mode 9600Switch to and from @dfn{constant glyph space mode}. If activated, the 9601width of every glyph is @math{@var{width}/36} ems. The em size is 9602given absolutely by @var{em-size}; if this argument is missing, the em 9603value is taken from the current font size (as set with the @code{ps} 9604request) when the font is effectively in use. Without second and 9605third argument, constant glyph space mode is deactivated. 9606 9607Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is 9608an integer. 9609@endDefreq 9610 9611@c --------------------------------------------------------------------- 9612 9613@node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols 9614@subsection Ligatures and Kerning 9615@cindex ligatures and kerning 9616@cindex kerning and ligatures 9617 9618Ligatures are groups of characters that are run together, i.e, producing 9619a single glyph. For example, the letters `f' and `i' can form a 9620ligature `fi' as in the word `file'. This produces a cleaner look 9621(albeit subtle) to the printed output. Usually, ligatures are not 9622available in fonts for TTY output devices. 9623 9624Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 9625typesetter that was the target of @acronym{AT&T} @code{troff} also 9626supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or 9627`expert' fonts may include ligatures for `ft' and `ct', although GNU 9628@code{troff} does not support these (yet). 9629 9630Only the current font is checked for ligatures and kerns; neither special 9631fonts nor entities defined with the @code{char} request (and its siblings) 9632are taken into account. 9633 9634@DefreqList {lg, [@Var{flag}]} 9635@DefregListEnd {.lg} 9636@cindex activating ligatures (@code{lg}) 9637@cindex ligatures, activating (@code{lg}) 9638@cindex ligatures enabled register (@code{.lg}) 9639Switch the ligature mechanism on or off; if the parameter is non-zero 9640or missing, ligatures are enabled, otherwise disabled. Default is on. 9641The current ligature mode can be found in the read-only number register 9642@code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise). 9643 9644Setting the ligature mode to@tie{}2 enables the two-character ligatures 9645(fi, fl, and ff) and disables the three-character ligatures (ffi and 9646ffl). 9647@endDefreq 9648 9649@dfn{Pairwise kerning} is another subtle typesetting mechanism that 9650modifies the distance between a glyph pair to improve readability. 9651In most cases (but not always) the distance is decreased. 9652@iftex 9653For example, compare the combination of the letters `V' and `A'. With 9654kerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 9655@end iftex 9656Typewriter-like fonts and fonts for terminals where all glyphs 9657have the same width don't use kerning. 9658 9659@DefreqList {kern, [@Var{flag}]} 9660@DefregListEnd {.kern} 9661@cindex activating kerning (@code{kern}) 9662@cindex kerning, activating (@code{kern}) 9663@cindex kerning enabled register (@code{.kern}) 9664Switch kerning on or off. If the parameter is non-zero or missing, 9665enable pairwise kerning, otherwise disable it. The read-only number 9666register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled, 96670@tie{}otherwise. 9668 9669@cindex zero width space character (@code{\&}) 9670@cindex character, zero width space (@code{\&}) 9671@cindex space character, zero width (@code{\&}) 9672If the font description file contains pairwise kerning information, 9673glyphs from that font are kerned. Kerning between two glyphs 9674can be inhibited by placing @code{\&} between them: @samp{V\&A}. 9675 9676@xref{Font File Format}. 9677@endDefreq 9678 9679@cindex track kerning 9680@cindex kerning, track 9681@dfn{Track kerning} expands or reduces the space between glyphs. 9682This can be handy, for example, if you need to squeeze a long word 9683onto a single line or spread some text to fill a narrow column. It 9684must be used with great care since it is usually considered bad 9685typography if the reader notices the effect. 9686 9687@Defreq {tkf, f s1 n1 s2 n2} 9688@cindex activating track kerning (@code{tkf}) 9689@cindex track kerning, activating (@code{tkf}) 9690Enable track kerning for font@tie{}@var{f}. If the current font 9691is@tie{}@var{f} the width of every glyph is increased by an amount 9692between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 9693the current point size is less than or equal to @var{s1} the width is 9694increased by @var{n1}; if it is greater than or equal to @var{s2} the 9695width is increased by @var{n2}; if the point size is greater than or 9696equal to @var{s1} and less than or equal to @var{s2} the increase in 9697width is a linear function of the point size. 9698 9699The default scaling indicator is @samp{z} for @var{s1} and @var{s2}, 9700@samp{p} for @var{n1} and @var{n2}. 9701 9702Note that the track kerning amount is added even to the rightmost glyph 9703in a line; for large values it is thus recommended to increase the line 9704length by the same amount to compensate it. 9705@endDefreq 9706 9707Sometimes, when typesetting letters of different fonts, more or less 9708space at such boundaries are needed. There are two escapes to help 9709with this. 9710 9711@Defesc {\\/, , , } 9712@cindex italic correction (@code{\/}) 9713@cindex correction, italic (@code{\/}) 9714@cindex correction between italic and roman glyph (@code{\/}, @code{\,}) 9715@cindex roman glyph, correction after italic glyph (@code{\/}) 9716@cindex italic glyph, correction before roman glyph (@code{\/}) 9717@cindex glyph, italic correction (@code{\/}) 9718Increase the width of the preceding glyph so that the spacing 9719between that glyph and the following glyph is correct if the 9720following glyph is a roman glyph. For example, if an 9721italic@tie{}@code{f} is immediately followed by a roman right 9722parenthesis, then in many fonts the top right portion of the@tie{}@code{f} 9723overlaps the top left of the right parenthesis. Use this escape 9724sequence whenever an italic glyph is immediately followed by a 9725roman glyph without any intervening space. This small amount of 9726space is also called @dfn{italic correction}. 9727 9728@iftex 9729@c can't use @Example...@endExample here 9730@example 9731@group 9732\f[I]f\f[R]) 9733 @result{} {@it f}@r{)} 9734\f[I]f\/\f[R]) 9735 @result{} @i{f}@r{)} 9736@end group 9737@end example 9738@end iftex 9739@endDefesc 9740 9741@Defesc {\\\,, , , } 9742@cindex left italic correction (@code{\,}) 9743@cindex correction, left italic (@code{\,}) 9744@cindex glyph, left italic correction (@code{\,}) 9745@cindex roman glyph, correction before italic glyph (@code{\,}) 9746@cindex italic glyph, correction after roman glyph (@code{\,}) 9747Modify the spacing of the following glyph so that the spacing 9748between that glyph and the preceding glyph is correct if the 9749preceding glyph is a roman glyph. Use this escape sequence 9750whenever a roman glyph is immediately followed by an italic 9751glyph without any intervening space. In analogy to above, this 9752space could be called @dfn{left italic correction}, but this term 9753isn't used widely. 9754 9755@iftex 9756@c can't use @Example...@endExample here 9757@example 9758@group 9759q\f[I]f 9760 @result{} @r{q}@i{f} 9761q\,\f[I]f 9762 @result{} @r{q}@math{@ptexcomma}@i{f} 9763@end group 9764@end example 9765@end iftex 9766@endDefesc 9767 9768@Defesc {\\&, , , } 9769Insert a zero-width character, which is invisible. Its intended use 9770is to stop interaction of a character with its surrounding. 9771 9772@itemize @bullet 9773@item 9774It prevents the insertion of extra space after an end-of-sentence 9775character. 9776 9777@Example 9778Test. 9779Test. 9780 @result{} Test. Test. 9781Test.\& 9782Test. 9783 @result{} Test. Test. 9784@endExample 9785 9786@item 9787It prevents interpretation of a control character at the beginning of 9788an input line. 9789 9790@Example 9791.Test 9792 @result{} warning: `Test' not defined 9793\&.Test 9794 @result{} .Test 9795@endExample 9796 9797@item 9798It prevents kerning between two glyphs. 9799 9800@iftex 9801@c can't use @Example...@endExample here 9802@example 9803@group 9804VA 9805 @result{} @r{VA} 9806V\&A 9807 @result{} @r{V@w{}A} 9808@end group 9809@end example 9810@end iftex 9811 9812@item 9813It is needed to map an arbitrary character to nothing in the @code{tr} 9814request (@pxref{Character Translations}). 9815@end itemize 9816@endDefesc 9817 9818@Defesc {\\), , , } 9819This escape is similar to @code{\&} except that it behaves like a 9820character declared with the @code{cflags} request to be transparent 9821for the purposes of an end-of-sentence character. 9822 9823Its main usage is in macro definitions to protect against arguments 9824starting with a control character. 9825 9826@Example 9827.de xxx 9828\)\\$1 9829.. 9830.de yyy 9831\&\\$1 9832.. 9833This is a test.\c 9834.xxx ' 9835This is a test. 9836 @result{}This is a test.' This is a test. 9837This is a test.\c 9838.yyy ' 9839This is a test. 9840 @result{}This is a test.' This is a test. 9841@endExample 9842@endDefesc 9843 9844 9845@c ===================================================================== 9846 9847@node Sizes, Strings, Fonts and Symbols, gtroff Reference 9848@section Sizes 9849@cindex sizes 9850 9851@cindex baseline 9852@cindex type size 9853@cindex size of type 9854@cindex vertical spacing 9855@cindex spacing, vertical 9856@code{gtroff} uses two dimensions with each line of text, type size 9857and vertical spacing. The @dfn{type size} is approximately the height 9858of the tallest glyph.@footnote{This is usually the parenthesis. 9859Note that in most cases the real dimensions of the glyphs in a font 9860are @emph{not} related to its type size! For example, the standard 9861@sc{PostScript} font families `Times Roman', `Helvetica', and 9862`Courier' can't be used together at 10@dmn{pt}; to get acceptable 9863output, the size of `Helvetica' has to be reduced by one point, and 9864the size of `Courier' must be increased by one point.} @dfn{Vertical 9865spacing} is the amount of space @code{gtroff} allows for a line of 9866text; normally, this is about 20%@tie{}larger than the current type 9867size. Ratios smaller than this can result in hard-to-read text; 9868larger than this, it spreads the text out more vertically (useful for 9869term papers). By default, @code{gtroff} uses 10@tie{}point type on 987012@tie{}point spacing. 9871 9872@cindex leading 9873The difference between type size and vertical spacing is known, by 9874typesetters, as @dfn{leading} (this is pronounced `ledding'). 9875 9876@menu 9877* Changing Type Sizes:: 9878* Fractional Type Sizes:: 9879@end menu 9880 9881@c --------------------------------------------------------------------- 9882 9883@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 9884@subsection Changing Type Sizes 9885 9886@DefreqList {ps, [@Var{size}]} 9887@DefreqItem {ps, @t{+}@Var{size}} 9888@DefreqItem {ps, @t{-}@Var{size}} 9889@DefescItem {\\s, , size, } 9890@DefregListEnd {.s} 9891@cindex changing type sizes (@code{ps}, @code{\s}) 9892@cindex type sizes, changing (@code{ps}, @code{\s}) 9893@cindex point sizes, changing (@code{ps}, @code{\s}) 9894Use the @code{ps} request or the @code{\s} escape to change (increase, 9895decrease) the type size (in points). Specify @var{size} as either an 9896absolute point size, or as a relative change from the current size. 9897The size@tie{}0, or no argument, goes back to the previous size. 9898 9899Default scaling indicator of @code{size} is @samp{z}. If @code{size} 9900is zero or negative, it is set to 1@dmn{u}. 9901 9902@cindex type size registers (@code{.s}, @code{.ps}) 9903@cindex point size registers (@code{.s}, @code{.ps}) 9904The read-only number register @code{.s} returns the point size in 9905points as a decimal fraction. This is a string. To get the point 9906size in scaled points, use the @code{.ps} register instead. 9907 9908@code{.s} is associated with the current environment 9909(@pxref{Environments}). 9910 9911@Example 9912snap, snap, 9913.ps +2 9914grin, grin, 9915.ps +2 9916wink, wink, \s+2nudge, nudge,\s+8 say no more! 9917.ps 10 9918@endExample 9919 9920The @code{\s} escape may be called in a variety of ways. Much like 9921other escapes there must be a way to determine where the argument ends 9922and the text begins. Any of the following forms are valid: 9923 9924@table @code 9925@item \s@var{n} 9926Set the point size to @var{n}@tie{}points. @var{n}@tie{}must be either 99270 or in the range 4 to@tie{}39. 9928 9929@item \s+@var{n} 9930@itemx \s-@var{n} 9931Increase or decrease the point size by @var{n}@tie{}points. 9932@var{n}@tie{}must be exactly one digit. 9933 9934@item \s(@var{nn} 9935Set the point size to @var{nn}@tie{}points. @var{nn} must be exactly 9936two digits. 9937 9938@item \s+(@var{nn} 9939@itemx \s-(@var{nn} 9940@itemx \s(+@var{nn} 9941@itemx \s(-@var{nn} 9942Increase or decrease the point size by @var{nn}@tie{}points. @var{nn} 9943must be exactly two digits. 9944@end table 9945 9946Note that @code{\s} doesn't produce an input token in @code{gtroff}. 9947As a consequence, it can be used in requests like @code{mc} (which 9948expects a single character as an argument) to change the font on 9949the fly: 9950 9951@Example 9952.mc \s[20]x\s[0] 9953@endExample 9954 9955@xref{Fractional Type Sizes}, for yet another syntactical form of 9956using the @code{\s} escape. 9957@endDefreq 9958 9959@Defreq {sizes, s1 s2 @dots{} sn [0]} 9960Some devices may only have certain permissible sizes, in which case 9961@code{gtroff} rounds to the nearest permissible size. 9962The @file{DESC} file specifies which sizes are permissible for the device. 9963 9964Use the @code{sizes} request to change the permissible sizes 9965for the current output device. 9966Arguments are in scaled points; 9967the @code{sizescale} line in the 9968@file{DESC} file for the output device 9969provides the scaling factor. 9970For example, if the scaling factor is 1000, 9971then the value 12000 is 12@tie{}points. 9972 9973Each argument can be a single point size (such as @samp{12000}), 9974or a range of sizes (such as @samp{4000-72000}). 9975You can optionally end the list with a zero. 9976@endDefreq 9977 9978@DefreqList {vs, [@Var{space}]} 9979@DefreqItem {vs, @t{+}@Var{space}} 9980@DefreqItem {vs, @t{-}@Var{space}} 9981@DefregListEnd {.v} 9982@cindex changing vertical line spacing (@code{vs}) 9983@cindex vertical line spacing, changing (@code{vs}) 9984@cindex vertical line spacing register (@code{.v}) 9985Change (increase, decrease) the vertical spacing by @var{space}. The 9986default scaling indicator is @samp{p}. 9987 9988If @code{vs} is called without an argument, the vertical spacing is 9989reset to the previous value before the last call to @code{vs}. 9990 9991@cindex @code{.V} register, and @code{vs} 9992@code{gtroff} creates a warning of type @samp{range} if @var{space} is 9993negative; the vertical spacing is then set to smallest positive value, 9994the vertical resolution (as given in the @code{.V} register). 9995 9996Note that @w{@samp{.vs 0}} isn't saved in a diversion since it doesn't 9997result in a vertical motion. You explicitly have to repeat this command 9998before inserting the diversion. 9999 10000The read-only number register @code{.v} contains the current vertical 10001spacing; it is associated with the current environment 10002(@pxref{Environments}). 10003@endDefreq 10004 10005@cindex vertical line spacing, effective value 10006The effective vertical line spacing consists of four components. Breaking 10007a line causes the following actions (in the given order). 10008 10009@itemize @bullet 10010@item 10011@cindex extra pre-vertical line space (@code{\x}) 10012@cindex line space, extra pre-vertical (@code{\x}) 10013Move the current point vertically by the @dfn{extra pre-vertical line 10014space}. This is the minimum value of all @code{\x} escapes with a 10015negative argument in the current output line. 10016 10017@item 10018Move the current point vertically by the vertical line spacing as set with 10019the @code{vs} request. 10020 10021@item 10022Output the current line. 10023 10024@item 10025@cindex extra post-vertical line space (@code{\x}) 10026@cindex line space, extra post-vertical (@code{\x}) 10027Move the current point vertically by the @dfn{extra post-vertical line 10028space}. This is the maximum value of all @code{\x} escapes with a 10029positive argument in the line which has just been output. 10030 10031@item 10032@cindex post-vertical line spacing 10033@cindex line spacing, post-vertical (@code{pvs}) 10034Move the current point vertically by the @dfn{post-vertical line spacing} 10035as set with the @code{pvs} request. 10036@end itemize 10037 10038@cindex double-spacing (@code{vs}, @code{pvs}) 10039It is usually better to use @code{vs} or @code{pvs} instead of @code{ls} 10040to produce double-spaced documents: @code{vs} and @code{pvs} have a finer 10041granularity for the inserted vertical space compared to @code{ls}; 10042furthermore, certain preprocessors assume single-spacing. 10043 10044@xref{Manipulating Spacing}, for more details on the @code{\x} escape 10045and the @code{ls} request. 10046 10047@DefreqList {pvs, [@Var{space}]} 10048@DefreqItem {pvs, @t{+}@Var{space}} 10049@DefreqItem {pvs, @t{-}@Var{space}} 10050@DefregListEnd {.pvs} 10051@cindex @code{ls} request, alternative to (@code{pvs}) 10052@cindex post-vertical line spacing, changing (@code{pvs}) 10053@cindex post-vertical line spacing register (@code{.pvs}) 10054Change (increase, decrease) the post-vertical spacing by 10055@var{space}. The default scaling indicator is @samp{p}. 10056 10057If @code{pvs} is called without an argument, the post-vertical spacing is 10058reset to the previous value before the last call to @code{pvs}. 10059 10060@code{gtroff} creates a warning of type @samp{range} if @var{space} is 10061zero or negative; the vertical spacing is then set to zero. 10062 10063The read-only number register @code{.pvs} contains the current 10064post-vertical spacing; it is associated with the current environment 10065(@pxref{Environments}). 10066@endDefreq 10067 10068@c --------------------------------------------------------------------- 10069 10070@node Fractional Type Sizes, , Changing Type Sizes, Sizes 10071@subsection Fractional Type Sizes 10072@cindex fractional type sizes 10073@cindex fractional point sizes 10074@cindex type sizes, fractional 10075@cindex point sizes, fractional 10076@cindex sizes, fractional 10077 10078@cindex @code{s} unit 10079@cindex unit, @code{s} 10080@cindex @code{z} unit 10081@cindex unit, @code{z} 10082@cindex @code{ps} request, with fractional type sizes 10083@cindex @code{cs} request, with fractional type sizes 10084@cindex @code{tkf} request, with fractional type sizes 10085@cindex @code{\H}, with fractional type sizes 10086@cindex @code{\s}, with fractional type sizes 10087A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 10088where @var{sizescale} is specified in the @file{DESC} file (1@tie{}by 10089default). There is a new scale indicator @samp{z} which has the 10090effect of multiplying by @var{sizescale}. Requests and escape 10091sequences in @code{gtroff} interpret arguments that represent a point 10092size as being in units of scaled points, but they evaluate each such 10093argument using a default scale indicator of @samp{z}. Arguments 10094treated in this way are the argument to the @code{ps} request, the 10095third argument to the @code{cs} request, the second and fourth 10096arguments to the @code{tkf} request, the argument to the @code{\H} 10097escape sequence, and those variants of the @code{\s} escape sequence 10098that take a numeric expression as their argument (see below). 10099 10100For example, suppose @var{sizescale} is@tie{}1000; then a scaled point 10101is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 10102equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 1010310250@tie{}scaled points, which is equal to 10.25@tie{}points. 10104 10105@code{gtroff} disallows the use of the @samp{z} scale indicator in 10106instances where it would make no sense, such as a numeric 10107expression whose default scale indicator was neither @samp{u} nor 10108@samp{z}. Similarly it would make 10109no sense to use a scaling indicator other than @samp{z} or @samp{u} in a 10110numeric expression whose default scale indicator was @samp{z}, and so 10111@code{gtroff} disallows this as well. 10112 10113There is also new scale indicator @samp{s} which multiplies by the 10114number of units in a scaled point. So, for example, @samp{\n[.ps]s} is 10115equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 10116scale indicators. 10117 10118@Defreg {.ps} 10119A read-only number register returning the point size in scaled points. 10120 10121@code{.ps} is associated with the current environment 10122(@pxref{Environments}). 10123@endDefreg 10124 10125@DefregList {.psr} 10126@DefregListEnd {.sr} 10127@cindex last-requested point size registers (@code{.psr}, @code{.sr}) 10128@cindex point size registers, last-requested (@code{.psr}, @code{.sr}) 10129@cindex @code{.ps} register, in comparison with @code{.psr} 10130@cindex @code{.s} register, in comparison with @code{.sr} 10131The last-requested point size in scaled points is contained in the 10132@code{.psr} read-only number register. The last requested point size 10133in points as a decimal fraction can be found in @code{.sr}. This is a 10134string-valued read-only number register. 10135 10136Note that the requested point sizes are device-independent, whereas 10137the values returned by the @code{.ps} and @code{.s} registers are not. 10138For example, if a point size of 11@dmn{pt} is requested, and a 10139@code{sizes} request (or a @code{sizescale} line in a @file{DESC} file) 10140specifies 10.95@dmn{pt} instead, this value is actually used. 10141 10142Both registers are associated with the current environment 10143(@pxref{Environments}). 10144@endDefreg 10145 10146The @code{\s} escape has the following syntax for working with 10147fractional type sizes: 10148 10149@table @code 10150@item \s[@var{n}] 10151@itemx \s'@var{n}' 10152Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric 10153expression with a default scale indicator of @samp{z}. 10154 10155@item \s[+@var{n}] 10156@itemx \s[-@var{n}] 10157@itemx \s+[@var{n}] 10158@itemx \s-[@var{n}] 10159@itemx \s'+@var{n}' 10160@itemx \s'-@var{n}' 10161@itemx \s+'@var{n}' 10162@itemx \s-'@var{n}' 10163Increase or or decrease the point size by @var{n}@tie{}scaled points; 10164@var{n}@tie{}is a numeric expression with a default scale indicator of 10165@samp{z}. 10166@end table 10167 10168@xref{Font Files}. 10169 10170 10171@c ===================================================================== 10172 10173@node Strings, Conditionals and Loops, Sizes, gtroff Reference 10174@section Strings 10175@cindex strings 10176 10177@code{gtroff} has string variables, which are entirely for user 10178convenience (i.e.@: there are no built-in strings exept @code{.T}, but 10179even this is a read-write string variable). 10180 10181@DefreqList {ds, name [@Var{string}]} 10182@DefreqItem {ds1, name [@Var{string}]} 10183@DefescItem {\\*, , n, } 10184@DefescItem {\\*, @Lparen{}, nm, } 10185@DefescListEnd {\\*, @Lbrack{}, name arg1 arg2 @dots{}, @Rbrack{}} 10186@cindex string interpolation (@code{\*}) 10187@cindex string expansion (@code{\*}) 10188@cindex interpolation of strings (@code{\*}) 10189@cindex expansion of strings (@code{\*}) 10190@cindex string arguments 10191@cindex arguments, of strings 10192Define and access a string variable @var{name} (one-character 10193name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already 10194exists, @code{ds} overwrites the previous definition. Only the syntax form 10195using brackets can take arguments which are handled identically to 10196macro arguments; the single exception is that a closing bracket as an 10197argument must be enclosed in double quotes. @xref{Request and Macro 10198Arguments}, and @ref{Parameters}. 10199 10200Example: 10201 10202@Example 10203.ds foo a \\$1 test 10204. 10205This is \*[foo nice]. 10206 @result{} This is a nice test. 10207@endExample 10208 10209The @code{\*} escape @dfn{interpolates} (expands in-place) a 10210previously-defined string variable. To be more precise, the stored 10211string is pushed onto the input stack which is then parsed by 10212@code{gtroff}. Similar to number registers, it is possible to nest 10213strings, i.e. string variables can be called within string variables. 10214 10215If the string named by the @code{\*} escape does not exist, it is 10216defined as empty, and a warning of type @samp{mac} is emitted (see 10217@ref{Debugging}, for more details). 10218 10219@cindex comments, with @code{ds} 10220@cindex @code{ds} request, and comments 10221@strong{Caution:} Unlike other requests, the second argument to the 10222@code{ds} request takes up the entire line including trailing spaces. 10223This means that comments on a line with such a request can introduce 10224unwanted space into a string. 10225 10226@Example 10227.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 10228@endExample 10229 10230@noindent 10231Instead the comment should be put on another line or have the comment 10232escape adjacent with the end of the string. 10233 10234@Example 10235.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 10236@endExample 10237 10238@cindex trailing quotes 10239@cindex quotes, trailing 10240@cindex leading spaces with @code{ds} 10241@cindex spaces with @code{ds} 10242@cindex @code{ds} request, and leading spaces 10243To produce leading space the string can be started with a double 10244quote. No trailing quote is needed; in fact, any trailing quote is 10245included in your string. 10246 10247@Example 10248.ds sign " Yours in a white wine sauce, 10249@endExample 10250 10251@cindex multi-line strings 10252@cindex strings, multi-line 10253@cindex newline character, in strings, escaping 10254@cindex escaping newline characters, in strings 10255Strings are not limited to a single line of text. A string can span 10256several lines by escaping the newlines with a backslash. The 10257resulting string is stored @emph{without} the newlines. 10258 10259@Example 10260.ds foo lots and lots \ 10261of text are on these \ 10262next several lines 10263@endExample 10264 10265It is not possible to have real newlines in a string. To put a single 10266double quote character into a string, use two consecutive double quote 10267characters. 10268 10269The @code{ds1} request turns off compatibility mode 10270while interpreting a string. To be more precise, a @dfn{compatibility 10271save} input token is inserted at the beginning of the string, and a 10272@dfn{compatibility restore} input token at the end. 10273 10274@Example 10275.nr xxx 12345 10276.ds aa The value of xxx is \\n[xxx]. 10277.ds1 bb The value of xxx ix \\n[xxx]. 10278. 10279.cp 1 10280. 10281\*(aa 10282 @result{} warning: number register `[' not defined 10283 @result{} The value of xxx is 0xxx]. 10284\*(bb 10285 @result{} The value of xxx ix 12345. 10286@endExample 10287 10288@cindex name space, common, of macros, diversions, and strings 10289@cindex common name space of macros, diversions, and strings 10290@cindex macros, shared name space with strings and diversions 10291@cindex strings, shared name space with macros and diversions 10292@cindex diversions, shared name space with macros and strings 10293Strings, macros, and diversions (and boxes) share the same name space. 10294Internally, even the same mechanism is used to store them. This has 10295some interesting consequences. For example, it is possible to call a 10296macro with string syntax and vice versa. 10297 10298@Example 10299.de xxx 10300a funny test. 10301.. 10302This is \*[xxx] 10303 @result{} This is a funny test. 10304 10305.ds yyy a funny test 10306This is 10307.yyy 10308 @result{} This is a funny test. 10309@endExample 10310 10311Diversions and boxes can be also called with string syntax. 10312 10313Another consequence is that you can copy one-line diversions or boxes 10314to a string. 10315 10316@Example 10317.di xxx 10318a \fItest\fR 10319.br 10320.di 10321.ds yyy This is \*[xxx]\c 10322\*[yyy]. 10323 @result{} @r{This is a }@i{test}. 10324@endExample 10325 10326@noindent 10327As the previous example shows, it is possible to store formatted 10328output in strings. The @code{\c} escape prevents the insertion of an 10329additional blank line in the output. 10330 10331Copying diversions longer than a single output line produces 10332unexpected results. 10333 10334@Example 10335.di xxx 10336a funny 10337.br 10338test 10339.br 10340.di 10341.ds yyy This is \*[xxx]\c 10342\*[yyy]. 10343 @result{} test This is a funny. 10344@endExample 10345 10346Usually, it is not predictable whether a diversion contains one or 10347more output lines, so this mechanism should be avoided. With 10348@acronym{UNIX} @code{troff}, this was the only solution to strip off a 10349final newline from a diversion. Another disadvantage is that the 10350spaces in the copied string are already formatted, making them 10351unstretchable. This can cause ugly results. 10352 10353@cindex stripping final newline in diversions 10354@cindex diversion, stripping final newline 10355@cindex final newline, stripping in diversions 10356@cindex newline, final, stripping in diversions 10357@cindex horizontal space, unformatting 10358@cindex space, horizontal, unformatting 10359@cindex unformatting horizontal space 10360A clean solution to this problem is available in GNU @code{troff}, 10361using the requests @code{chop} to remove the final newline of a 10362diversion, and @code{unformat} to make the horizontal spaces 10363stretchable again. 10364 10365@Example 10366.box xxx 10367a funny 10368.br 10369test 10370.br 10371.box 10372.chop xxx 10373.unformat xxx 10374This is \*[xxx]. 10375 @result{} This is a funny test. 10376@endExample 10377 10378@xref{Gtroff Internals}, for more information. 10379@endDefreq 10380 10381@DefreqList {as, name [@Var{string}]} 10382@DefreqListEnd {as1, name [@Var{string}]} 10383@cindex appending to a string (@code{as}) 10384@cindex string, appending (@code{as}) 10385The @code{as} request is similar to @code{ds} but appends @var{string} 10386to the string stored as @var{name} instead of redefining it. If 10387@var{name} doesn't exist yet, it is created. 10388 10389@Example 10390.as sign " with shallots, onions and garlic, 10391@endExample 10392 10393The @code{as1} request is similar to @code{as}, but compatibility mode 10394is switched off while the appended string is interpreted. To be more 10395precise, a @dfn{compatibility save} input token is inserted at the 10396beginning of the appended string, and a @dfn{compatibility restore} 10397input token at the end. 10398@endDefreq 10399 10400Rudimentary string manipulation routines are given with the next two 10401requests. 10402 10403@Defreq {substring, str n1 [@Var{n2}]} 10404@cindex substring (@code{substring}) 10405Replace the string named @var{str} with the substring 10406defined by the indices @var{n1} and@tie{}@var{n2}. The first character 10407in the string has index@tie{}0. If @var{n2} is omitted, it is taken to 10408be equal to the string's length. If the index value @var{n1} or 10409@var{n2} is negative, it is counted from the end of the 10410string, going backwards: The last character has index@tie{}@minus{}1, the 10411character before the last character has index@tie{}@minus{}2, etc. 10412 10413@Example 10414.ds xxx abcdefgh 10415.substring xxx 1 -4 10416\*[xxx] 10417 @result{} bcde 10418@endExample 10419@endDefreq 10420 10421@Defreq {length, reg str} 10422@cindex length of a string (@code{length}) 10423@cindex string, length of (@code{length}) 10424Compute the number of characters of @var{str} and return it in the 10425number register @var{reg}. If @var{reg} doesn't exist, it is created. 10426@code{str} is read in copy mode. 10427 10428@Example 10429.ds xxx abcd\h'3i'efgh 10430.length yyy \*[xxx] 10431\n[yyy] 10432 @result{} 14 10433@endExample 10434@endDefreq 10435 10436@Defreq {rn, xx yy} 10437@cindex renaming request (@code{rn}) 10438@cindex request, renaming (@code{rn}) 10439@cindex renaming macro (@code{rn}) 10440@cindex macro, renaming (@code{rn}) 10441@cindex renaming string (@code{rn}) 10442@cindex string, renaming (@code{rn}) 10443@cindex renaming diversion (@code{rn}) 10444@cindex diversion, renaming (@code{rn}) 10445Rename the request, macro, diversion, or string @var{xx} to @var{yy}. 10446@endDefreq 10447 10448@Defreq {rm, xx} 10449@cindex removing request (@code{rm}) 10450@cindex request, removing (@code{rm}) 10451@cindex removing macro (@code{rm}) 10452@cindex macro, removing (@code{rm}) 10453@cindex removing string (@code{rm}) 10454@cindex string, removing (@code{rm}) 10455@cindex removing diversion (@code{rm}) 10456@cindex diversion, removing (@code{rm}) 10457Remove the request, macro, diversion, or string @var{xx}. @code{gtroff} 10458treats subsequent invocations as if the object had never been defined. 10459@endDefreq 10460 10461@Defreq {als, new old} 10462@cindex alias, string, creating (@code{als}) 10463@cindex alias, macro, creating (@code{als}) 10464@cindex alias, diversion, creating (@code{als}) 10465@cindex creating alias, for string (@code{als}) 10466@cindex creating alias, for macro (@code{als}) 10467@cindex creating alias, for diversion (@code{als}) 10468@cindex string, creating alias (@code{als}) 10469@cindex macro, creating alias (@code{als}) 10470@cindex diversion, creating alias (@code{als}) 10471Create an alias named @var{new} for the request, string, macro, or 10472diversion object named @var{old}. The new name and the old name are 10473exactly equivalent (it is similar to a hard rather than a soft 10474link). If @var{old} is undefined, @code{gtroff} generates a warning of 10475type @samp{mac} and ignores the request. 10476@endDefreq 10477 10478@Defreq {chop, xx} 10479Remove (chop) the last character from the macro, string, or diversion 10480named @var{xx}. This is useful for removing the newline from the end 10481of diversions that are to be interpolated as strings. This command 10482can be used repeatedly; see @ref{Gtroff Internals}, for details on 10483nodes inserted additionally by @code{gtroff}. 10484@endDefreq 10485 10486@xref{Identifiers}, and @ref{Comments}. 10487 10488 10489@c ===================================================================== 10490 10491@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 10492@section Conditionals and Loops 10493@cindex conditionals and loops 10494@cindex loops and conditionals 10495 10496@menu 10497* Operators in Conditionals:: 10498* if-else:: 10499* while:: 10500@end menu 10501 10502@c --------------------------------------------------------------------- 10503 10504@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 10505@subsection Operators in Conditionals 10506 10507@cindex @code{if} request, operators to use with 10508@cindex @code{while} request, operators to use with 10509In @code{if} and @code{while} requests, there are several more 10510operators available: 10511 10512@table @code 10513@item e 10514@itemx o 10515True if the current page is even or odd numbered (respectively). 10516 10517@item n 10518True if the document is being processed in nroff mode (i.e., the 10519@code{.nroff} command has been issued). 10520 10521@item t 10522True if the document is being processed in troff mode (i.e., the 10523@code{.troff} command has been issued). 10524 10525@item v 10526Always false. This condition is for compatibility with other 10527@code{troff} versions only (identifying a @code{-Tversatec} device). 10528 10529@item '@var{xxx}'@var{yyy}' 10530True if the string @var{xxx} is equal to the string @var{yyy}. Other 10531characters can be used in place of the single quotes; the same set of 10532delimiters as for the @code{\D} escape is used (@pxref{Escapes}). 10533@code{gtroff} formats the strings before being compared: 10534 10535@Example 10536.ie "|"\fR|\fP" \ 10537true 10538.el \ 10539false 10540 @result{} true 10541@endExample 10542 10543@noindent 10544The resulting motions, glyph sizes, and fonts have to 10545match,@footnote{The created output nodes must be identical. 10546@xref{Gtroff Internals}.} and not the individual motion, size, and 10547font requests. In the previous example, @samp{|} and @samp{\fR|\fP} 10548both result in a roman @samp{|} glyph with the same point size and 10549at the same location on the page, so the strings are equal. If 10550@samp{.ft@tie{}I} had been added before the @samp{.ie}, the result 10551would be ``false'' because (the first) @samp{|} produces an italic 10552@samp{|} rather than a roman one. 10553 10554@item r @var{xxx} 10555True if there is a number register named @var{xxx}. 10556 10557@item d @var{xxx} 10558True if there is a string, macro, diversion, or request named @var{xxx}. 10559 10560@item m @var{xxx} 10561True if there is a color named @var{xxx}. 10562 10563@item c @var{g} 10564True if there is a glyph @var{g} available@footnote{The name of this 10565conditional operator is a misnomer since it tests names of output 10566glyphs.}; @var{g} is either an @acronym{ASCII} character or a special 10567character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition 10568is also true if @var{g} has been defined by the @code{char} request. 10569 10570@item F @var{font} 10571True if a font named @var{font} exists. @var{font} is handled as if it was 10572opened with the @code{ft} request (this is, font translation and styles are 10573applied), without actually mounting it. 10574 10575This test doesn't load the complete font but only its header to verify 10576its validity. 10577 10578@item S @var{style} 10579True if style @var{style} has been registered. Font translation is applied. 10580@end table 10581 10582Note that these operators can't be combined with other operators like 10583@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 10584between the exclamation mark and the operator) can be used to negate 10585the result. 10586 10587@Example 10588.nr xxx 1 10589.ie !r xxx \ 10590true 10591.el \ 10592false 10593 @result{} false 10594@endExample 10595 10596A whitespace after @samp{!} always evaluates to zero (this bizarre 10597behaviour is due to compatibility with @acronym{UNIX} @code{troff}). 10598 10599@Example 10600.nr xxx 1 10601.ie ! r xxx \ 10602true 10603.el \ 10604false 10605 @result{} r xxx true 10606@endExample 10607 10608It is possible to omit the whitespace before the argument to the 10609@samp{r}, @samp{d}, and @samp{c} operators. 10610 10611@xref{Expressions}. 10612 10613@c --------------------------------------------------------------------- 10614 10615@node if-else, while, Operators in Conditionals, Conditionals and Loops 10616@subsection if-else 10617@cindex if-else 10618 10619@code{gtroff} has if-then-else constructs like other languages, although 10620the formatting can be painful. 10621 10622@Defreq {if, expr anything} 10623 10624Evaluate the expression @var{expr}, and executes @var{anything} (the 10625remainder of the line) if @var{expr} evaluates to a value greater than 10626zero (true). @var{anything} is interpreted as though it was on a line 10627by itself (except that leading spaces are swallowed). 10628@xref{Expressions}, for more info. 10629 10630@Example 10631.nr xxx 1 10632.nr yyy 2 10633.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 10634 @result{} true 10635@endExample 10636@endDefreq 10637 10638@Defreq{nop, anything} 10639Executes @var{anything}. 10640This is similar to @code{.if@tie{}1}. 10641@endDefreq 10642 10643@DefreqList {ie, expr anything} 10644@DefreqListEnd {el, anything} 10645Use the @code{ie} and @code{el} requests to write an if-then-else. 10646The first request is the `if' part and the latter is the `else' part. 10647 10648@Example 10649.ie n .ls 2 \" double-spacing in nroff 10650.el .ls 1 \" single-spacing in troff 10651@endExample 10652@endDefreq 10653 10654@c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument 10655@c to @deffn 10656@c 10657@c and in 4.2 you still can't use @{ in macros. 10658 10659@c @DefescList {\@{, , , } 10660@c @DefescListEnd {\@}, , , } 10661@deffn Escape @t{\@{} 10662@deffnx Escape @t{\@}} 10663@esindex \@{ 10664@esindex \@} 10665@cindex begin of conditional block (@code{\@{}) 10666@cindex end of conditional block (@code{\@}}) 10667@cindex conditional block, begin (@code{\@{}) 10668@cindex conditional block, end (@code{\@}}) 10669@cindex block, conditional, begin (@code{\@{}) 10670@cindex block, condititional, end (@code{\@}}) 10671In many cases, an if (or if-else) construct needs to execute more than 10672one request. This can be done using the @code{\@{} and @code{\@}} 10673escapes. The following example shows the possible ways to use these 10674escapes (note the position of the opening and closing braces). 10675 10676@Example 10677.ie t \@{\ 10678. ds lq `` 10679. ds rq '' 10680.\@} 10681.el \ 10682.\@{\ 10683. ds lq " 10684. ds rq "\@} 10685@endExample 10686@c @endDefesc 10687@end deffn 10688 10689@xref{Expressions}. 10690 10691@c --------------------------------------------------------------------- 10692 10693@node while, , if-else, Conditionals and Loops 10694@subsection while 10695@cindex while 10696 10697@code{gtroff} provides a looping construct using the @code{while} 10698request, which is used much like the @code{if} (and related) requests. 10699 10700@Defreq {while, expr anything} 10701Evaluate the expression @var{expr}, and repeatedly execute 10702@var{anything} (the remainder of the line) until @var{expr} evaluates 10703to@tie{}0. 10704 10705@Example 10706.nr a 0 1 10707.while (\na < 9) \@{\ 10708\n+a, 10709.\@} 10710\n+a 10711 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 10712@endExample 10713 10714Some remarks. 10715 10716@cindex @code{de} request, and @code{while} 10717@itemize @bullet 10718@item 10719The body of a @code{while} request is treated like the body of a 10720@code{de} request: @code{gtroff} temporarily stores it in a macro 10721which is deleted after the loop has been exited. It can considerably 10722slow down a macro if the body of the @code{while} request (within the 10723macro) is large. Each time the macro is executed, the @code{while} 10724body is parsed and stored again as a temporary macro. 10725 10726@Example 10727.de xxx 10728. nr num 10 10729. while (\\n[num] > 0) \@{\ 10730. \" many lines of code 10731. nr num -1 10732. \@} 10733.. 10734@endExample 10735 10736@cindex recursive macros 10737@cindex macros, recursive 10738@noindent 10739The traditional and ofter better solution (@acronym{UNIX} @code{troff} 10740doesn't have the @code{while} request) is to use a recursive macro 10741instead which is parsed only once during its definition. 10742 10743@Example 10744.de yyy 10745. if (\\n[num] > 0) \@{\ 10746. \" many lines of code 10747. nr num -1 10748. yyy 10749. \@} 10750.. 10751. 10752.de xxx 10753. nr num 10 10754. yyy 10755.. 10756@endExample 10757 10758@noindent 10759Note that the number of available recursion levels is set to@tie{}1000 10760(this is a compile-time constant value of @code{gtroff}). 10761 10762@item 10763The closing brace of a @code{while} body must end a line. 10764 10765@Example 10766.if 1 \@{\ 10767. nr a 0 1 10768. while (\n[a] < 10) \@{\ 10769. nop \n+[a] 10770.\@}\@} 10771 @result{} unbalanced \@{ \@} 10772@endExample 10773@end itemize 10774@endDefreq 10775 10776@Defreq {break, } 10777@cindex @code{while} request, confusing with @code{br} 10778@cindex @code{break} request, in a @code{while} loop 10779@cindex @code{continue} request, in a @code{while} loop 10780Break out of a @code{while} loop. Be sure not to confuse this with 10781the @code{br} request (causing a line break). 10782@endDefreq 10783 10784@Defreq {continue, } 10785Finish the current iteration of a @code{while} loop, immediately 10786restarting the next iteration. 10787@endDefreq 10788 10789@xref{Expressions}. 10790 10791 10792@c ===================================================================== 10793 10794@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 10795@section Writing Macros 10796@cindex writing macros 10797@cindex macros, writing 10798 10799A @dfn{macro} is a collection of text and embedded commands which can 10800be invoked multiple times. Use macros to define common operations. 10801 10802@DefreqList {de, name [@Var{end}]} 10803@DefreqItem {de1, name [@Var{end}]} 10804@DefreqItem {dei, name [@Var{end}]} 10805@DefreqListEnd {dei1, name [@Var{end}]} 10806Define a new macro named @var{name}. @code{gtroff} copies subsequent 10807lines (starting with the next one) into an internal buffer until it 10808encounters the line @samp{..} (two dots). The optional second 10809argument to @code{de} changes this to a macro to @samp{.@var{end}}. 10810 10811There can be whitespace after the first dot in the line containing the 10812ending token (either @samp{.} or macro @samp{@var{end}}). 10813 10814Here a small example macro called @samp{P} which causes a break and 10815inserts some vertical space. It could be used to separate paragraphs. 10816 10817@Example 10818.de P 10819. br 10820. sp .8v 10821.. 10822@endExample 10823 10824The following example defines a macro within another. Remember that 10825expansion must be protected twice; once for reading the macro and 10826once for executing. 10827 10828@Example 10829\# a dummy macro to avoid a warning 10830.de end 10831.. 10832. 10833.de foo 10834. de bar end 10835. nop \f[B]Hallo \\\\$1!\f[] 10836. end 10837.. 10838. 10839.foo 10840.bar Joe 10841 @result{} @b{Hallo Joe!} 10842@endExample 10843 10844@noindent 10845Since @code{\f} has no expansion, it isn't necessary to protect its 10846backslash. Had we defined another macro within @code{bar} which takes 10847a parameter, eight backslashes would be necessary before @samp{$1}. 10848 10849The @code{de1} request turns off compatibility mode 10850while executing the macro. On entry, the current compatibility mode 10851is saved and restored at exit. 10852 10853@Example 10854.nr xxx 12345 10855. 10856.de aa 10857The value of xxx is \\n[xxx]. 10858.. 10859.de1 bb 10860The value of xxx ix \\n[xxx]. 10861.. 10862. 10863.cp 1 10864. 10865.aa 10866 @result{} warning: number register `[' not defined 10867 @result{} The value of xxx is 0xxx]. 10868.bb 10869 @result{} The value of xxx ix 12345. 10870@endExample 10871 10872The @code{dei} request defines a macro indirectly. 10873That is, it expands strings whose names 10874are @var{name} or @var{end} before performing the append. 10875 10876This: 10877 10878@Example 10879.ds xx aa 10880.ds yy bb 10881.dei xx yy 10882@endExample 10883 10884@noindent 10885is equivalent to: 10886 10887@Example 10888.de aa bb 10889@endExample 10890 10891The @code{dei1} request is similar to @code{dei} but with compatibility 10892mode switched off during execution of the defined macro. 10893 10894If compatibility mode is on, @code{de} (and @code{dei}) behave similar to 10895@code{de1} (and @code{dei1}): A `compatibility save' token is inserted at 10896the beginning, and a `compatibility restore' token at the end, with 10897compatibility mode switched on during execution. @xref{Gtroff Internals}, 10898for more information on switching compatibility mode on and off in a 10899single document. 10900 10901@pindex trace.tmac 10902Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}. 10903 10904Note that macro identifiers are shared with identifiers for strings and 10905diversions. 10906@endDefreq 10907 10908@DefreqList {am, name [@Var{end}]} 10909@DefreqItem {am1, name [@Var{end}]} 10910@DefreqItem {ami, name [@Var{end}]} 10911@DefreqListEnd {ami1, name [@Var{end}]} 10912@cindex appending to a macro (@code{am}) 10913@cindex macro, appending (@code{am}) 10914Works similarly to @code{de} except it appends onto the macro named 10915@var{name}. So, to make the previously defined @samp{P} macro actually 10916do indented instead of block paragraphs, add the necessary code to the 10917existing macro like this: 10918 10919@Example 10920.am P 10921.ti +5n 10922.. 10923@endExample 10924 10925The @code{am1} request turns off compatibility mode 10926while executing the appended macro piece. To be more precise, a 10927@dfn{compatibility save} input token is inserted at the beginning of 10928the appended code, and a @dfn{compatibility restore} input token at 10929the end. 10930 10931The @code{ami} request appends indirectly, 10932meaning that @code{gtroff} expands strings whose names 10933are @var{name} or @var{end} before performing the append. 10934 10935The @code{ami1} request is similar to @code{ami} but compatibility mode 10936is switched off during execution of the defined macro. 10937 10938@pindex trace.tmac 10939Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}. 10940@endDefreq 10941 10942@xref{Strings}, for the @code{als} request to rename a macro. 10943 10944The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and 10945@code{as} requests (together with its variants) only create a new object 10946if the name of the macro, diversion or string diversion is currently 10947undefined or if it is defined to be a request; normally they modify the 10948value of an existing object. 10949 10950@Defreq {return, [@Var{anything}]} 10951Exit a macro, immediately returning to the caller. 10952 10953If called with an argument, exit twice, namely the current macro and the 10954macro one level higher. This is used to define a wrapper macro for 10955@code{return} in @file{trace.tmac}. 10956@endDefreq 10957 10958@menu 10959* Copy-in Mode:: 10960* Parameters:: 10961@end menu 10962 10963@c --------------------------------------------------------------------- 10964 10965@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 10966@subsection Copy-in Mode 10967@cindex copy-in mode 10968@cindex mode, copy-in 10969 10970@cindex @code{\n}, when reading text for a macro 10971@cindex @code{\$}, when reading text for a macro 10972@cindex @code{\*}, when reading text for a macro 10973@cindex @code{\\}, when reading text for a macro 10974@cindex \@key{RET}, when reading text for a macro 10975When @code{gtroff} reads in the text for a macro, string, or diversion, 10976it copies the text (including request lines, but excluding escapes) into 10977an internal buffer. Escapes are converted into an internal form, 10978except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 10979@code{\@key{RET}} which are evaluated and inserted into the text where 10980the escape was located. This is known as @dfn{copy-in} mode or 10981@dfn{copy} mode. 10982 10983What this means is that you can specify when these escapes are to be 10984evaluated (either at copy-in time or at the time of use) by insulating 10985the escapes with an extra backslash. Compare this to the @code{\def} 10986and @code{\edef} commands in @TeX{}. 10987 10988The following example prints the numbers 20 and@tie{}10: 10989 10990@Example 10991.nr x 20 10992.de y 10993.nr x 10 10994\&\nx 10995\&\\nx 10996.. 10997.y 10998@endExample 10999 11000@c --------------------------------------------------------------------- 11001 11002@node Parameters, , Copy-in Mode, Writing Macros 11003@subsection Parameters 11004@cindex parameters 11005 11006The arguments to a macro or string can be examined using a variety of 11007escapes. 11008 11009@Defreg {.$} 11010@cindex number of arguments register (@code{.$}) 11011The number of arguments passed to a macro or string. This is a read-only 11012number register. 11013 11014Note that the @code{shift} request can change its value. 11015@endDefreg 11016 11017Any individual argument can be retrieved with one of the following 11018escapes: 11019 11020@DefescList {\\$, , n, } 11021@DefescItem {\\$, @Lparen{}, nn, } 11022@DefescListEnd {\\$, @Lbrack{}, nnn, @Rbrack{}} 11023@cindex copy-in mode, and macro arguments 11024@cindex macro, arguments (@code{\$}) 11025@cindex arguments, macro (@code{\$}) 11026Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th} 11027argument. As usual, the first form only accepts a single number 11028(larger than zero), the second a two-digit number (larger or equal 11029to@tie{}10), and the third any positive integer value (larger 11030than zero). Macros and strings can have an unlimited number of arguments. 11031Note that due to copy-in mode, use two backslashes on these in actual use 11032to prevent interpolation until the macro is actually invoked. 11033@endDefesc 11034 11035@Defreq {shift, [@Var{n}]} 11036Shift the arguments 1@tie{}position, or as 11037many positions as specified by its argument. After executing this 11038request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}}; 11039arguments 1 to@tie{}@var{n} are no longer available. Shifting by 11040negative amounts is currently undefined. 11041 11042The register @code{.$} is adjusted accordingly. 11043@endDefreq 11044 11045@DefescList {\\$*, , , } 11046@DefescListEnd {\\$@@, , , } 11047In some cases it is convenient to use all of the arguments at once (for 11048example, to pass the arguments along to another macro). The @code{\$*} 11049escape concatenates all the arguments separated by spaces. A 11050similar escape is @code{\$@@}, which concatenates all the 11051arguments with each surrounded by double quotes, and separated by 11052spaces. If not in compatibility mode, the input level of double quotes 11053is preserved (see @ref{Request and Macro Arguments}). 11054@endDefesc 11055 11056@Defesc {\\$0, , , } 11057@cindex macro name register (@code{\$0}) 11058@cindex @code{als} request, and @code{\$0} 11059The name used to invoke the current macro. 11060The @code{als} request can make a macro have more than one name. 11061 11062@Example 11063.de generic-macro 11064. ... 11065. if \\n[error] \@{\ 11066. tm \\$0: Houston, we have a problem. 11067. return 11068. \@} 11069.. 11070. 11071.als foo generic-macro 11072.als bar generic-macro 11073@endExample 11074@endDefesc 11075 11076@xref{Request and Macro Arguments}. 11077 11078 11079@c ===================================================================== 11080 11081@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 11082@section Page Motions 11083@cindex page motions 11084@cindex motions, page 11085 11086@xref{Manipulating Spacing}, for a discussion of the main request for 11087vertical motion, @code{sp}. 11088 11089@DefreqList {mk, [@Var{reg}]} 11090@DefreqListEnd {rt, [@Var{dist}]} 11091@cindex marking vertical page location (@code{mk}) 11092@cindex page location, vertical, marking (@code{mk}) 11093@cindex location, vertical, page, marking (@code{mk}) 11094@cindex vertical page location, marking (@code{mk}) 11095@cindex returning to marked vertical page location (@code{rt}) 11096@cindex page location, vertical, returning to marked (@code{rt}) 11097@cindex location, vertical, page, returning to marked (@code{rt}) 11098@cindex vertical page location, returning to marked (@code{rt}) 11099The request @code{mk} can be used to mark a location on a page, for 11100movement to later. This request takes a register name as an argument 11101in which to store the current page location. With no argument it 11102stores the location in an internal register. The results of this can 11103be used later by the @code{rt} or the @code{sp} request (or the 11104@code{\v} escape). 11105 11106The @code{rt} request returns @emph{upwards} to the location marked 11107with the last @code{mk} request. If used with an argument, return to 11108a position which distance from the top of the page is @var{dist} (no 11109previous call to @code{mk} is necessary in this case). Default scaling 11110indicator is @samp{v}. 11111 11112Here a primitive solution for a two-column macro. 11113 11114@Example 11115.nr column-length 1.5i 11116.nr column-gap 4m 11117.nr bottom-margin 1m 11118. 11119@endExample 11120@Example 11121.de 2c 11122. br 11123. mk 11124. ll \\n[column-length]u 11125. wh -\\n[bottom-margin]u 2c-trap 11126. nr right-side 0 11127.. 11128. 11129@endExample 11130@Example 11131.de 2c-trap 11132. ie \\n[right-side] \@{\ 11133. nr right-side 0 11134. po -(\\n[column-length]u + \\n[column-gap]u) 11135. \" remove trap 11136. wh -\\n[bottom-margin]u 11137. \@} 11138. el \@{\ 11139. \" switch to right side 11140. nr right-side 1 11141. po +(\\n[column-length]u + \\n[column-gap]u) 11142. rt 11143. \@} 11144.. 11145. 11146@endExample 11147@Example 11148.pl 1.5i 11149.ll 4i 11150This is a small test which shows how the 11151rt request works in combination with mk. 11152 11153.2c 11154Starting here, text is typeset in two columns. 11155Note that this implementation isn't robust 11156and thus not suited for a real two-column 11157macro. 11158@endExample 11159 11160Result: 11161 11162@Example 11163This is a small test which shows how the 11164rt request works in combination with mk. 11165 11166Starting here, isn't robust 11167text is typeset and thus not 11168in two columns. suited for a 11169Note that this real two-column 11170implementation macro. 11171@endExample 11172@endDefreq 11173 11174The following escapes give fine control of movements about the page. 11175 11176@Defesc {\\v, ', e, '} 11177@cindex vertical motion (@code{\v}) 11178@cindex motion, vertical (@code{\v}) 11179Move vertically, usually from the current location on the page (if no 11180absolute position operator @samp{|} is used). The 11181argument@tie{}@var{e} specifies the distance to move; positive is 11182downwards and negative upwards. The default scaling indicator for this 11183escape is @samp{v}. Beware, however, that @code{gtroff} continues text 11184processing at the point where the motion ends, so you should always 11185balance motions to avoid interference with text processing. 11186 11187@code{\v} doesn't trigger a trap. This can be quite useful; for example, 11188consider a page bottom trap macro which prints a marker in the margin to 11189indicate continuation of a footnote or something similar. 11190@endDefesc 11191 11192There are some special-case escapes for vertical motion. 11193 11194@Defesc {\\r, , , } 11195Move upwards@tie{}1@dmn{v}. 11196@endDefesc 11197 11198@Defesc {\\u, , , } 11199Move upwards@tie{}.5@dmn{v}. 11200@endDefesc 11201 11202@Defesc {\\d, , , } 11203Move down@tie{}.5@dmn{v}. 11204@endDefesc 11205 11206@Defesc {\\h, ', e, '} 11207@cindex inserting horizontal space (@code{\h}) 11208@cindex horizontal space (@code{\h}) 11209@cindex space, horizontal (@code{\h}) 11210@cindex horizontal motion (@code{\h}) 11211@cindex motion, horizontal (@code{\h}) 11212Move horizontally, usually from the current location (if no absolute 11213position operator @samp{|} is used). The expression@tie{}@var{e} 11214indicates how far to move: positive is rightwards and negative 11215leftwards. The default scaling indicator for this escape is @samp{m}. 11216 11217This horizontal space is not discarded at the end of a line. To insert 11218discardable space of a certain length use the @code{ss} request. 11219@endDefesc 11220 11221There are a number of special-case escapes for horizontal motion. 11222 11223@Defesc {\\@key{SP}, , , } 11224@cindex space, unbreakable 11225@cindex unbreakable space 11226An unbreakable and unpaddable (i.e.@: not expanded during filling) 11227space. (Note: This is a backslash followed by a space.) 11228@endDefesc 11229 11230@Defesc {\\~, , , } 11231An unbreakable space that stretches like a normal inter-word space 11232when a line is adjusted. 11233@endDefesc 11234 11235@Defesc {\\|, , , } 11236A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to 11237zero). 11238@endDefesc 11239 11240@Defesc {\\^, , , } 11241A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to 11242zero). 11243@endDefesc 11244 11245@Defesc {\\0, , , } 11246@cindex space, width of a digit (@code{\0}) 11247@cindex digit width space (@code{\0}) 11248A space the size of a digit. 11249@endDefesc 11250 11251The following string sets the @TeX{} logo: 11252 11253@Example 11254.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 11255@endExample 11256 11257@DefescList {\\w, ', text, '} 11258@DefregItem {st} 11259@DefregItem {sb} 11260@DefregItem {rst} 11261@DefregItem {rsb} 11262@DefregItem {ct} 11263@DefregItem {ssc} 11264@DefregListEnd {skw} 11265@cindex width escape (@code{\w}) 11266Return the width of the specified @var{text} in basic units. 11267This allows horizontal movement based on the width of some 11268arbitrary text (e.g.@: given as an argument to a macro). 11269 11270@Example 11271The length of the string `abc' is \w'abc'u. 11272 @result{} The length of the string `abc' is 72u. 11273@endExample 11274 11275Font changes may occur in @var{text} which don't affect current 11276settings. 11277 11278After use, @code{\w} sets several registers: 11279 11280@table @code 11281@item st 11282@itemx sb 11283The highest and lowest point of the baseline, respectively, in @var{text}. 11284 11285@item rst 11286@itemx rsb 11287Like the @code{st} and @code{sb} registers, but takes account of the 11288heights and depths of glyphs. With other words, this gives the 11289highest and lowest point of @var{text}. Values below the baseline are 11290negative. 11291 11292@item ct 11293Defines the kinds of glyphs occurring in @var{text}: 11294 11295@table @asis 11296@item 0 11297only short glyphs, no descenders or tall glyphs. 11298 11299@item 1 11300at least one descender. 11301 11302@item 2 11303at least one tall glyph. 11304 11305@item 3 11306at least one each of a descender and a tall glyph. 11307@end table 11308 11309@item ssc 11310The amount of horizontal space (possibly negative) that should be added 11311to the last glyph before a subscript. 11312 11313@item skw 11314How far to right of the center of the last glyph in the @code{\w} 11315argument, the center of an accent from a roman font should be placed 11316over that glyph. 11317@end table 11318@endDefesc 11319 11320@DefescList {\\k, , p, } 11321@DefescItem {\\k, @Lparen{}, ps, } 11322@DefescListEnd {\\k, @Lbrack{}, position, @Rbrack{}} 11323@cindex saving horizontal input line position (@code{\k}) 11324@cindex horizontal input line position, saving (@code{\k}) 11325@cindex input line position, horizontal, saving (@code{\k}) 11326@cindex position, horizontal input line, saving (@code{\k}) 11327@cindex line, input, horizontal position, saving (@code{\k}) 11328Store the current horizontal position in the @emph{input} line in 11329number register with name @var{position} (one-character name@tie{}@var{p}, 11330two-character name @var{ps}). Use this, for example, to return to the 11331beginning of a string for highlighting or other decoration. 11332@endDefesc 11333 11334@Defreg {hp} 11335@cindex horizontal input line position register (@code{hp}) 11336@cindex input line, horizontal position, register (@code{hp}) 11337@cindex position, horizontal, in input line, register (@code{hp}) 11338@cindex line, input, horizontal position, register (@code{hp}) 11339The current horizontal position at the input line. 11340@endDefreg 11341 11342@Defreg {.k} 11343@cindex horizontal output line position register (@code{.k}) 11344@cindex output line, horizontal position, register (@code{.k}) 11345@cindex position, horizontal, in output line, register (@code{.k}) 11346@cindex line, output, horizontal position, register (@code{.k}) 11347A read-only number register containing the current horizontal output 11348position (relative to the current indentation). 11349@endDefreg 11350 11351@Defesc {\\o, ', abc, '} 11352@cindex overstriking glyphs (@code{\o}) 11353@cindex glyphs, overstriking (@code{\o}) 11354Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs 11355are centered, and the resulting spacing is the largest width of the 11356affected glyphs. 11357@endDefesc 11358 11359@Defesc {\\z, , g, , } 11360@cindex zero-width printing (@code{\z}, @code{\Z}) 11361@cindex printing, zero-width (@code{\z}, @code{\Z}) 11362Print glyph @var{g} with zero width, i.e., without spacing. Use 11363this to overstrike glyphs left-aligned. 11364@endDefesc 11365 11366@Defesc {\\Z, ', anything, '} 11367@cindex zero-width printing (@code{\z}, @code{\Z}) 11368@cindex printing, zero-width (@code{\z}, @code{\Z}) 11369Print @var{anything}, then restore the horizontal and vertical position. 11370The argument may not contain tabs or leaders. 11371 11372The following is an example of a strike-through macro: 11373 11374@Example 11375.de ST 11376.nr ww \w'\\$1' 11377\Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1 11378.. 11379. 11380This is 11381.ST "a test" 11382an actual emergency! 11383@endExample 11384@endDefesc 11385 11386 11387@c ===================================================================== 11388 11389@node Drawing Requests, Traps, Page Motions, gtroff Reference 11390@section Drawing Requests 11391@cindex drawing requests 11392@cindex requests for drawing 11393 11394@code{gtroff} provides a number of ways to draw lines and other figures 11395on the page. Used in combination with the page motion commands (see 11396@ref{Page Motions}, for more info), a wide variety of figures can be 11397drawn. However, for complex drawings these operations can be quite 11398cumbersome, and it may be wise to use graphic preprocessors like 11399@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 11400information. 11401 11402All drawing is done via escapes. 11403 11404@DefescList {\\l, ', l, '} 11405@DefescListEnd {\\l, ', lg, '} 11406@cindex drawing horizontal lines (@code{\l}) 11407@cindex horizontal line, drawing (@code{\l}) 11408@cindex line, horizontal, drawing (@code{\l}) 11409Draw a line horizontally. @var{l} is the length of the line to be 11410drawn. If it is positive, start the line at the current location and 11411draw to the right; its end point is the new current location. Negative 11412values are handled differently: The line starts at the current location 11413and draws to the left, but the current location doesn't move. 11414 11415@var{l} can also be specified absolutely (i.e.@: with a leading 11416@samp{|}) which draws back to the beginning of the input line. 11417Default scaling indicator is @samp{m}. 11418 11419@cindex underscore glyph (@code{\[ru]}) 11420@cindex glyph, underscore (@code{\[ru]}) 11421@cindex line drawing glyph 11422@cindex glyph, for line drawing 11423The optional second parameter@tie{}@var{g} is a glyph to draw the line 11424with. If this second argument is not specified, @code{gtroff} uses 11425the underscore glyph, @code{\[ru]}. 11426 11427@cindex zero width space character (@code{\&}) 11428@cindex character, zero width space (@code{\&}) 11429@cindex space character, zero width (@code{\&}) 11430To separate the two arguments (to prevent @code{gtroff} from 11431interpreting a drawing glyph as a scaling indicator if the glyph is 11432represented by a single character) use @code{\&}. 11433 11434Here a small useful example: 11435 11436@Example 11437.de box 11438\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' 11439.. 11440@endExample 11441 11442@noindent 11443Note that this works by outputting a box rule (a vertical line), then 11444the text given as an argument and then another box rule. Finally, the 11445line drawing escapes both draw from the current location to the 11446beginning of the @emph{input} line -- this works because the line 11447length is negative, not moving the current point. 11448@endDefesc 11449 11450@DefescList {\\L, ', l, '} 11451@DefescListEnd {\\L, ', lg, '} 11452@cindex drawing vertical lines (@code{\L}) 11453@cindex vertical line drawing (@code{\L}) 11454@cindex line, vertical, drawing (@code{\L}) 11455@cindex line drawing glyph 11456@cindex glyph for line drawing 11457@cindex box rule glyph (@code{\[br]}) 11458@cindex glyph, box rule (@code{\[br]}) 11459Draw vertical lines. Its parameters are 11460similar to the @code{\l} escape, except that the default scaling 11461indicator is @samp{v}. The movement is downwards for positive values, 11462and upwards for negative values. The default glyph is the box rule 11463glyph, @code{\[br]}. As with the vertical motion escapes, text 11464processing blindly continues where the line ends. 11465 11466@Example 11467This is a \L'3v'test. 11468@endExample 11469 11470@noindent 11471Here the result, produced with @code{grotty}. 11472 11473@Example 11474This is a 11475 | 11476 | 11477 |test. 11478@endExample 11479@endDefesc 11480 11481@Defesc {\\D, ', command arg @dots{}, '} 11482The @code{\D} escape provides a variety of drawing functions. 11483Note that on character devices, only vertical and horizontal lines are 11484supported within @code{grotty}; other devices may only support a subset 11485of the available drawing functions. 11486 11487The default scaling indicator for all subcommands of @code{\D} is 11488@samp{m} for horizontal distances and @samp{v} for vertical ones. 11489Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}} 11490which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}} 11491which arguments are treated similar to the @code{defcolor} request. 11492 11493@table @code 11494@item \D'l @var{dx} @var{dy}' 11495@cindex line, drawing (@w{@code{\D'l @dots{}'}}) 11496@cindex drawing a line (@w{@code{\D'l @dots{}'}}) 11497Draw a line from the current location to the relative point specified by 11498(@var{dx},@var{dy}), where positive values mean down and right, 11499respectively. The end point of the line is the new current location. 11500 11501The following example is a macro for creating a box around a text string; 11502for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}. 11503 11504@Example 11505.de BOX 11506. nr @@wd \w'\\$1' 11507\h'.2m'\ 11508\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 11509\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ 11510\D'l (\\n[@@wd]u + .4m) 0'\ 11511\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ 11512\D'l -(\\n[@@wd]u + .4m) 0'\ 11513\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 11514\\$1\ 11515\h'.2m' 11516.. 11517@endExample 11518 11519@noindent 11520First, the width of the string is stored in register @code{@@wd}. Then, 11521four lines are drawn to form a box, properly offset by the box margin. 11522The registers @code{rst} and @code{rsb} are set by the @code{\w} escape, 11523containing the largest height and depth of the whole string. 11524 11525@item \D'c @var{d}' 11526@cindex circle, drawing (@w{@code{\D'c @dots{}'}}) 11527@cindex drawing a circle (@w{@code{\D'c @dots{}'}}) 11528Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at the 11529current position. After drawing, the current location is positioned at the 11530rightmost point of the circle. 11531 11532@item \D'C @var{d}' 11533@cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}}) 11534@cindex drawing a solid circle (@w{@code{\D'C @dots{}'}}) 11535@cindex solid circle, drawing (@w{@code{\D'C @dots{}'}}) 11536Draw a solid circle with the same parameters and behaviour as an outlined 11537circle. No outline is drawn. 11538 11539@item \D'e @var{x} @var{y}' 11540@cindex drawing an ellipse (@w{@code{\D'e @dots{}'}}) 11541@cindex ellipse, drawing (@w{@code{\D'e @dots{}'}}) 11542Draw an ellipse with a horizontal diameter of @var{x} and a vertical 11543diameter of @var{y} with the leftmost point at the current position. 11544After drawing, the current location is positioned at the rightmost point of 11545the ellipse. 11546 11547@item \D'E @var{x} @var{y}' 11548@cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}}) 11549@cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}}) 11550@cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}}) 11551Draw a solid ellipse with the same parameters and behaviour as an 11552outlined ellipse. No outline is drawn. 11553 11554@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 11555@cindex arc, drawing (@w{@code{\D'a @dots{}'}}) 11556@cindex drawing an arc (@w{@code{\D'a @dots{}'}}) 11557Draw an arc clockwise from the current location through the two 11558specified relative locations (@var{dx1},@var{dy1}) and 11559(@var{dx2},@var{dy2}). The coordinates of the first point are relative 11560to the current position, and the coordinates of the second point are 11561relative to the first point. After drawing, the current position is moved 11562to the final point of the arc. 11563 11564@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11565@cindex drawing a spline (@w{@code{\D'~ @dots{}'}}) 11566@cindex spline, drawing (@w{@code{\D'~ @dots{}'}}) 11567Draw a spline from the current location to the relative point 11568(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on. 11569The current position is moved to the terminal point of the drawn curve. 11570 11571@item \D'f @var{n}' 11572@cindex gray shading (@w{@code{\D'f @dots{}'}}) 11573@cindex shading filled objects (@w{@code{\D'f @dots{}'}}) 11574Set the shade of gray to be used for filling solid objects to@tie{}@var{n}; 11575@var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0 11576corresponds solid white and 1000 to solid black, and values in between 11577correspond to intermediate shades of gray. This applies only to solid 11578circles, solid ellipses, and solid polygons. By default, a level of 115791000 is used. 11580 11581Despite of being silly, the current point is moved horizontally to the 11582right by@tie{}@var{n}. 11583 11584@cindex @w{@code{\D'f @dots{}'}} and horizontal resolution 11585Don't use this command! It has the serious drawback that it will be 11586always rounded to the next integer multiple of the horizontal resolution 11587(the value of the @code{hor} keyword in the @file{DESC} file). Use 11588@code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead. 11589 11590@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11591@cindex drawing a polygon (@w{@code{\D'p @dots{}'}}) 11592@cindex polygon, drawing (@w{@code{\D'p @dots{}'}}) 11593Draw a polygon from the current location to the relative position 11594(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on. 11595When the specified data points are exhausted, a line is drawn back 11596to the starting point. The current position is changed by adding the 11597sum of all arguments with odd index to the actual horizontal position and 11598the even ones to the vertical position. 11599 11600@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11601@cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}}) 11602@cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}}) 11603@cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}}) 11604Draw a solid polygon with the same parameters and behaviour as an 11605outlined polygon. No outline is drawn. 11606 11607Here a better variant of the box macro to fill the box with some color. 11608Note that the box must be drawn before the text since colors in 11609@code{gtroff} are not transparent; the filled polygon would hide the 11610text completely. 11611 11612@Example 11613.de BOX 11614. nr @@wd \w'\\$1' 11615\h'.2m'\ 11616\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 11617\M[lightcyan]\ 11618\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ 11619 (\\n[@@wd]u + .4m) 0 \ 11620 0 (\\n[rst]u - \\n[rsb]u + .4m) \ 11621 -(\\n[@@wd]u + .4m) 0'\ 11622\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 11623\M[]\ 11624\\$1\ 11625\h'.2m' 11626.. 11627@endExample 11628 11629@item \D't @var{n}' 11630@cindex line thickness (@w{@code{\D't @dots{}'}}) 11631@cindex thickness of lines (@w{@code{\D't @dots{}'}}) 11632Set the current line thickness to @var{n}@tie{}machine units. A value of 11633zero selects the smallest available line thickness. A negative value 11634makes the line thickness proportional to the current point size (this is 11635the default behaviour of @acronym{AT&T} @code{troff}). 11636 11637Despite of being silly, the current point is moved horizontally to the 11638right by@tie{}@var{n}. 11639 11640@item \D'F@var{scheme} @var{color_components}' 11641@cindex unnamed fill colors (@code{\D'F@dots{}'}) 11642@cindex fill colors, unnamed (@code{\D'F@dots{}'}) 11643@cindex colors, fill, unnamed (@code{\D'F@dots{}'}) 11644Change current fill color. @var{scheme} is a single letter denoting the 11645color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g} 11646(gray), or @samp{d} (default color). The color components use exactly 11647the same syntax as in the @code{defcolor} request (@pxref{Colors}); the 11648command @code{\D'Fd'} doesn't take an argument. 11649 11650@emph{No} position changing! 11651 11652Examples: 11653 11654@Example 11655@endExample 11656\D'Fg .3' \" same gray as \D'f 700' 11657\D'Fr #0000ff' \" blue 11658@end table 11659@endDefesc 11660 11661@xref{Graphics Commands}. 11662 11663@Defesc {\\b, ', string, '} 11664@cindex pile, glyph (@code{\b}) 11665@cindex glyph pile (@code{\b}) 11666@cindex stacking glyphs (@code{\b}) 11667@dfn{Pile} a sequence of glyphs vertically, and center it vertically 11668on the current line. Use it to build large brackets and braces. 11669 11670Here an example how to create a large opening brace: 11671 11672@Example 11673\b'\[lt]\[bv]\[lk]\[bv]\[lb]' 11674@endExample 11675 11676@cindex @code{\b}, limitations 11677@cindex limitations of @code{\b} escape 11678The first glyph is on the top, the last glyph in @var{string} is 11679at the bottom. Note that @code{gtroff} separates the glyphs 11680vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m} 11681above the current baseline; the largest glyph width is used as the 11682width for the whole object. This rather unflexible positioning 11683algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary 11684in height for this device. Instead, use the @code{eqn} preprocessor. 11685 11686@xref{Manipulating Spacing}, how to adjust the vertical spacing with 11687the @code{\x} escape. 11688@endDefesc 11689 11690 11691@c ===================================================================== 11692 11693@node Traps, Diversions, Drawing Requests, gtroff Reference 11694@section Traps 11695@cindex traps 11696 11697@dfn{Traps} are locations, which, when reached, call a specified 11698macro. These traps can occur at a given location on the page, at a 11699given location in the current diversion, at a blank line, 11700after a certain number of input lines, or at the end of input. 11701 11702@cindex planting a trap 11703@cindex trap, planting 11704Setting a trap is also called @dfn{planting}. 11705@cindex trap, springing 11706@cindex springing a trap 11707It is also said that a trap is @dfn{sprung} if the associated macro 11708is executed. 11709 11710@menu 11711* Page Location Traps:: 11712* Diversion Traps:: 11713* Input Line Traps:: 11714* Blank Line Traps:: 11715* End-of-input Traps:: 11716@end menu 11717 11718@c --------------------------------------------------------------------- 11719 11720@node Page Location Traps, Diversion Traps, Traps, Traps 11721@subsection Page Location Traps 11722@cindex page location traps 11723@cindex traps, page location 11724 11725@dfn{Page location traps} perform an action when @code{gtroff} 11726reaches or passes a certain vertical location on the page. Page 11727location traps have a variety of purposes, including: 11728 11729@itemize 11730@item 11731setting headers and footers 11732 11733@item 11734setting body text in multiple columns 11735 11736@item 11737setting footnotes 11738@end itemize 11739 11740@DefreqList {vpt, flag} 11741@DefregListEnd {.vpt} 11742@cindex enabling vertical position traps (@code{vpt}) 11743@cindex vertical position traps, enabling (@code{vpt}) 11744@cindex vertical position trap enable register (@code{.vpt}) 11745Enable vertical position traps if @var{flag} is non-zero, or disables 11746them otherwise. Vertical position traps are traps set by the @code{wh} 11747or @code{dt} requests. Traps set by the @code{it} request are not 11748vertical position traps. The parameter that controls whether vertical 11749position traps are enabled is global. Initially vertical position traps 11750are enabled. The current setting of this is available in the 11751@code{.vpt} read-only number register. 11752 11753Note that a page can't be ejected if @code{vpt} is set to zero. 11754@endDefreq 11755 11756@Defreq {wh, dist [@Var{macro}]} 11757Set a page location trap. Non-negative values for @var{dist} set 11758the trap relative to the top of the page; negative values set 11759the trap relative to the bottom of the page. Default scaling 11760indicator is @samp{v}. 11761 11762@var{macro} is the name of the macro to execute when the 11763trap is sprung. If @var{macro} is missing, remove the first trap 11764(if any) at @var{dist}. 11765 11766@cindex page headers 11767@cindex page footers 11768@cindex headers 11769@cindex footers 11770The following is a simple example of how many macro packages 11771set headers and footers. 11772 11773@Example 11774.de hd \" Page header 11775' sp .5i 11776. tl 'Title''date' 11777' sp .3i 11778.. 11779. 11780.de fo \" Page footer 11781' sp 1v 11782. tl ''%'' 11783' bp 11784.. 11785. 11786.wh 0 hd \" trap at top of the page 11787.wh -1i fo \" trap one inch from bottom 11788@endExample 11789 11790A trap at or below the bottom of the page is ignored; it can be made 11791active by either moving it up or increasing the page length so that the 11792trap is on the page. 11793 11794It is possible to have more than one trap at the same location; to do so, 11795the traps must be defined at different locations, then moved together with 11796the @code{ch} request; otherwise the second trap would replace the first 11797one. Earlier defined traps hide later defined traps if moved to the same 11798position (the many empty lines caused by the @code{bp} request are omitted 11799in the following example): 11800 11801@Example 11802.de a 11803. nop a 11804.. 11805.de b 11806. nop b 11807.. 11808.de c 11809. nop c 11810.. 11811. 11812.wh 1i a 11813.wh 2i b 11814.wh 3i c 11815.bp 11816 @result{} a b c 11817@endExample 11818@Example 11819.ch b 1i 11820.ch c 1i 11821.bp 11822 @result{} a 11823@endExample 11824@Example 11825.ch a 0.5i 11826.bp 11827 @result{} a b 11828@endExample 11829@endDefreq 11830 11831@Defreg {.t} 11832@cindex distance to next trap register (@code{.t}) 11833@cindex trap, distance, register (@code{.t}) 11834A read-only number register holding the distance to the next trap. 11835 11836If there are no traps between the current position and the bottom of the 11837page, it contains the distance to the page bottom. In a diversion, the 11838distance to the page bottom is infinite (the returned value is the biggest 11839integer which can be represented in @code{groff}) if there are no diversion 11840traps. 11841@endDefreg 11842 11843@Defreq {ch, macro [@Var{dist}]} 11844@cindex changing trap location (@code{ch}) 11845@cindex trap, changing location (@code{ch}) 11846Change the location of a trap. 11847The first argument is the name of the macro to be invoked at 11848the trap, and the second argument is the new location for the trap 11849(note that the parameters are specified in opposite order as in the 11850@code{wh} request). This is useful for building up footnotes in a 11851diversion to allow more space at the bottom of the page for them. 11852 11853Default scaling indicator for @var{dist} is @samp{v}. If @var{dist} 11854is missing, the trap is removed. 11855 11856@c XXX 11857 11858@ignore 11859@Example 11860... (simplified) footnote example ... 11861@endExample 11862@end ignore 11863@endDefreq 11864 11865@Defreg {.ne} 11866The read-only number register @code{.ne} contains the amount of space 11867that was needed in the last @code{ne} request that caused a trap to be 11868sprung. Useful in conjunction with the @code{.trunc} register. 11869@xref{Page Control}, for more information. 11870 11871Since the @code{.ne} register is only set by traps it doesn't make 11872much sense to use it outside of trap macros. 11873@endDefreg 11874 11875@Defreg {.trunc} 11876@cindex @code{ne} request, and the @code{.trunc} register 11877@cindex truncated vertical space register (@code{.trunc}) 11878A read-only register containing the amount of vertical space truncated 11879by the most recently sprung vertical position trap, or, if the trap was 11880sprung by an @code{ne} request, minus the amount of vertical motion 11881produced by the @code{ne} request. In other words, at the point a trap 11882is sprung, it represents the difference of what the vertical position 11883would have been but for the trap, and what the vertical position 11884actually is. 11885 11886Since the @code{.trunc} register is only set by traps it doesn't make 11887much sense to use it outside of trap macros. 11888@endDefreg 11889 11890@Defreg {.pe} 11891@cindex @code{bp} request, and traps (@code{.pe}) 11892@cindex traps, sprung by @code{bp} request (@code{.pe}) 11893@cindex page ejecting register (@code{.pe}) 11894A read-only register which is set to@tie{}1 while a page is ejected with 11895the @code{bp} request (or by the end of input). 11896 11897Outside of traps this register is always zero. In the following example, 11898only the second call to@tie{}@code{x} is caused by @code{bp}. 11899 11900@Example 11901.de x 11902\&.pe=\\n[.pe] 11903.br 11904.. 11905.wh 1v x 11906.wh 4v x 11907A line. 11908.br 11909Another line. 11910.br 11911 @result{} A line. 11912 .pe=0 11913 Another line. 11914 11915 .pe=1 11916@endExample 11917@endDefreg 11918 11919@cindex diversions, and traps 11920@cindex traps, and diversions 11921An important fact to consider while designing macros is that diversions and 11922traps do not interact normally. For example, if a trap invokes a header 11923macro (while outputting a diversion) which tries to change the font on the 11924current page, the effect will not be visible before the diversion has 11925completely been printed (except for input protected with @code{\!} or 11926@code{\?}) since the data in the diversion is already formatted. In most 11927cases, this is not the expected behaviour. 11928 11929@c --------------------------------------------------------------------- 11930 11931@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 11932@subsection Diversion Traps 11933@cindex diversion traps 11934@cindex traps, diversion 11935 11936@Defreq {dt, [@Var{dist} @Var{macro}]} 11937@cindex @code{.t} register, and diversions 11938@cindex setting diversion trap (@code{dt}) 11939@cindex diversion trap, setting (@code{dt}) 11940@cindex trap, diversion, setting (@code{dt}) 11941Set a trap @emph{within} a diversion. 11942@var{dist} is the location of the trap 11943(identical to the @code{wh} request; default scaling indicator is 11944@samp{v}) and @var{macro} is the name of the macro to be invoked. 11945If called without arguments, the diversion trap is removed. 11946 11947Note that there exists only a single diversion trap. 11948 11949The number register @code{.t} still works within diversions. 11950@xref{Diversions}, for more information. 11951@endDefreq 11952 11953@c --------------------------------------------------------------------- 11954 11955@node Input Line Traps, Blank Line Traps, Diversion Traps, Traps 11956@subsection Input Line Traps 11957@cindex input line traps 11958@cindex traps, input line 11959 11960@DefreqList {it, n macro} 11961@DefreqItem {itc, n macro} 11962@cindex setting input line trap (@code{it}) 11963@cindex input line trap, setting (@code{it}) 11964@cindex trap, input line, setting (@code{it}) 11965Set an input line trap. 11966@var{n}@tie{}is the number of lines of input which may be read before 11967springing the trap, @var{macro} is the macro to be invoked. 11968Request lines are not counted as input lines. 11969 11970For example, one possible use is to have a macro which prints the 11971next @var{n}@tie{}lines in a bold font. 11972 11973@Example 11974.de B 11975. it \\$1 B-end 11976. ft B 11977.. 11978. 11979.de B-end 11980. ft R 11981.. 11982@endExample 11983 11984@cindex input line traps and interrupted lines (@code{itc}) 11985@cindex interrupted lines and input line traps (@code{itc}) 11986@cindex traps, input line, and interrupted lines (@code{itc}) 11987@cindex lines, interrupted, and input line traps (@code{itc}) 11988The @code{itc} request is identical 11989except that an interrupted text line (ending with @code{\c}) 11990is not counted as a separate line. 11991 11992Both requests are associated with the current environment 11993(@pxref{Environments}); switching to another environment disables the 11994current input trap, and going back reactivates it, restoring the number 11995of already processed lines. 11996@endDefreq 11997 11998@c --------------------------------------------------------------------- 11999 12000@node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps 12001@subsection Blank Line Traps 12002@cindex blank line traps 12003@cindex traps, blank line 12004 12005@Defreq {blm, macro} 12006@cindex blank line macro (@code{blm}) 12007Set a blank line trap. 12008@code{gtroff} executes @var{macro} when it encounters a blank line in 12009the input file. 12010@endDefreq 12011 12012@c --------------------------------------------------------------------- 12013 12014@node End-of-input Traps, , Blank Line Traps, Traps 12015@subsection End-of-input Traps 12016@cindex end-of-input traps 12017@cindex traps, end-of-input 12018 12019@Defreq {em, macro} 12020@cindex setting end-of-input trap (@code{em}) 12021@cindex end-of-input trap, setting (@code{em}) 12022@cindex trap, end-of-input, setting (@code{em}) 12023@cindex end-of-input macro (@code{em}) 12024@cindex macro, end-of-input (@code{em}) 12025Set a trap at the end of input. @var{macro} is executed after the 12026last line of the input file has been processed. 12027 12028For example, if the document had to have a section at the bottom of the 12029last page for someone to approve it, the @code{em} request could be 12030used. 12031 12032@Example 12033.de approval 12034. ne 5v 12035. sp |(\\n[.t] - 6v) 12036. in +4i 12037. lc _ 12038. br 12039Approved:\t\a 12040. sp 12041Date:\t\t\a 12042.. 12043. 12044.em approval 12045@endExample 12046@endDefreq 12047 12048 12049@c ===================================================================== 12050 12051@node Diversions, Environments, Traps, gtroff Reference 12052@section Diversions 12053@cindex diversions 12054 12055In @code{gtroff} it is possible to @dfn{divert} text into a named 12056storage area. Due to the similarity to defining macros it is sometimes 12057said to be stored in a macro. This is used for saving text for output 12058at a later time, which is useful for keeping blocks of text on the same 12059page, footnotes, tables of contents, and indices. 12060 12061@cindex top-level diversion 12062@cindex diversion, top-level 12063For orthogonality it is said that @code{gtroff} is in the @dfn{top-level 12064diversion} if no diversion is active (i.e., the data is diverted to the 12065output device). 12066 12067@DefreqList {di, macro} 12068@DefreqListEnd {da, macro} 12069@cindex beginning diversion (@code{di}) 12070@cindex diversion, beginning (@code{di}) 12071@cindex ending diversion (@code{di}) 12072@cindex diversion, ending (@code{di}) 12073@cindex appending to a diversion (@code{da}) 12074@cindex diversion, appending (@code{da}) 12075Begin a diversion. Like the @code{de} 12076request, it takes an argument of a macro name to divert subsequent text 12077into. The @code{da} macro appends to an existing diversion. 12078 12079@code{di} or @code{da} without an argument ends the diversion. 12080@endDefreq 12081 12082@DefreqList {box, macro} 12083@DefreqListEnd {boxa, macro} 12084Begin (or appends to) a diversion like the 12085@code{di} and @code{da} requests. 12086The difference is that @code{box} and @code{boxa} 12087do not include a partially-filled line in the diversion. 12088 12089Compare this: 12090 12091@Example 12092Before the box. 12093.box xxx 12094In the box. 12095.br 12096.box 12097After the box. 12098.br 12099 @result{} Before the box. After the box. 12100.xxx 12101 @result{} In the box. 12102@endExample 12103 12104@noindent 12105with this: 12106 12107@Example 12108Before the diversion. 12109.di yyy 12110In the diversion. 12111.br 12112.di 12113After the diversion. 12114.br 12115 @result{} After the diversion. 12116.yyy 12117 @result{} Before the diversion. In the diversion. 12118@endExample 12119 12120@code{box} or @code{boxa} without an argument ends the diversion. 12121@endDefreq 12122 12123@DefregList {.z} 12124@DefregListEnd {.d} 12125@cindex @code{nl} register, and @code{.d} 12126@cindex nested diversions 12127@cindex diversion, nested 12128@cindex diversion name register (@code{.z}) 12129@cindex vertical position in diversion register (@code{.d}) 12130@cindex position, vertical, in diversion, register (@code{.d}) 12131@cindex diversion, vertical position in, register (@code{.d}) 12132Diversions may be nested. The read-only number register @code{.z} 12133contains the name of the current diversion (this is a string-valued 12134register). The read-only number register @code{.d} contains the current 12135vertical place in the diversion. If not in a diversion it is the same 12136as register @code{nl}. 12137@endDefreg 12138 12139@Defreg {.h} 12140@cindex high-water mark register (@code{.h}) 12141@cindex mark, high-water, register (@code{.h}) 12142@cindex position of lowest text line (@code{.h}) 12143@cindex text line, position of lowest (@code{.h}) 12144The @dfn{high-water mark} on the current page. It corresponds to the 12145text baseline of the lowest line on the page. This is a read-only 12146register. 12147 12148@Example 12149.tm .h==\n[.h], nl==\n[nl] 12150 @result{} .h==0, nl==-1 12151This is a test. 12152.br 12153.sp 2 12154.tm .h==\n[.h], nl==\n[nl] 12155 @result{} .h==40, nl==120 12156@endExample 12157 12158@cindex @code{.h} register, difference to @code{nl} 12159@cindex @code{nl} register, difference to @code{.h} 12160@noindent 12161As can be seen in the previous example, empty lines are not considered 12162in the return value of the @code{.h} register. 12163@endDefreg 12164 12165@DefregList {dn} 12166@DefregListEnd {dl} 12167@cindex @code{dn} register, and @code{da} (@code{boxa}) 12168@cindex @code{dl} register, and @code{da} (@code{boxa}) 12169@cindex @code{da} request, and @code{dn} (@code{dl}) 12170@cindex @code{boxa} request, and @code{dn} (@code{dl}) 12171After completing a diversion, the read-write number registers @code{dn} 12172and @code{dl} contain the vertical and horizontal size of the diversion. 12173Note that only the just processed lines are counted: For the computation 12174of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are 12175handled as if @code{di} and @code{box} had been used -- lines which have 12176been already stored in a macro are not taken into account. 12177 12178@Example 12179.\" Center text both horizontally & vertically 12180. 12181.\" Enclose macro definitions in .eo and .ec 12182.\" to avoid the doubling of the backslash 12183.eo 12184.\" macro .(c starts centering mode 12185.de (c 12186. br 12187. ev (c 12188. evc 0 12189. in 0 12190. nf 12191. di @@c 12192.. 12193@endExample 12194@Example 12195.\" macro .)c terminates centering mode 12196.de )c 12197. br 12198. ev 12199. di 12200. nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v) 12201. sp \n[@@s]u 12202. ce 1000 12203. @@c 12204. ce 0 12205. sp \n[@@s]u 12206. br 12207. fi 12208. rr @@s 12209. rm @@s 12210. rm @@c 12211.. 12212.\" End of macro definitions, restore escape mechanism 12213.ec 12214@endExample 12215@endDefreg 12216 12217@DefescList {\\!, , , } 12218@DefescListEnd {\\?, , anything, \\?} 12219@cindex transparent output (@code{\!}, @code{\?}) 12220@cindex output, transparent (@code{\!}, @code{\?}) 12221Prevent requests, macros, and escapes from being 12222interpreted when read into a diversion. Both escapes take the given text 12223and @dfn{transparently} embed it into the diversion. This is useful for 12224macros which shouldn't be invoked until the diverted text is actually 12225output. 12226 12227The @code{\!} escape transparently embeds text up to 12228and including the end of the line. 12229The @code{\?} escape transparently embeds text until the next 12230occurrence of the @code{\?} escape. Example: 12231 12232@Example 12233\?@var{anything}\? 12234@endExample 12235 12236@noindent 12237@var{anything} may not contain newlines; use @code{\!} to embed 12238newlines in a diversion. The escape sequence @code{\?} is also 12239recognized in copy mode and turned into a single internal code; it is 12240this code that terminates @var{anything}. Thus the following example 12241prints@tie{}4. 12242 12243@Example 12244.nr x 1 12245.nf 12246.di d 12247\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 12248.di 12249.nr x 2 12250.di e 12251.d 12252.di 12253.nr x 3 12254.di f 12255.e 12256.di 12257.nr x 4 12258.f 12259@endExample 12260 12261Both escapes read the data in copy mode. 12262 12263@cindex @code{\!}, in top-level diversion 12264@cindex top-level diversion, and @code{\!} 12265@cindex diversion, top-level, and @code{\!} 12266If @code{\!} is used in the top-level diversion, its argument is 12267directly embedded into the @code{gtroff} intermediate output. This can 12268be used for example to control a postprocessor which processes the data 12269before it is sent to the device driver. 12270 12271@cindex @code{\?}, in top-level diversion 12272@cindex top-level diversion, and @code{\?} 12273@cindex diversion, top-level, and @code{\?} 12274The @code{\?} escape used in the top-level diversion produces no output 12275at all; its argument is simply ignored. 12276@endDefesc 12277 12278@cindex @code{\!}, and @code{output} 12279@cindex @code{output} request, and @code{\!} 12280@Defreq {output, string} 12281Emit @var{string} directly to the @code{gtroff} intermediate output 12282(subject to copy-mode interpretation); this is similar to @code{\!} used 12283at the top level. An initial double quote in @var{string} is stripped off 12284to allow initial blanks. 12285 12286This request can't be used before the first page has started -- if you get 12287an error, simply insert @code{.br} before the @code{output} request. 12288 12289Without argument, @code{output} is ignored. 12290 12291Use with caution! It is normally only needed for mark-up used by a 12292postprocessor which does something with the output before sending it to 12293the output device, filtering out @var{string} again. 12294@endDefreq 12295 12296@Defreq {asciify, div} 12297@cindex unformatting diversions (@code{asciify}) 12298@cindex diversion, unformatting (@code{asciify}) 12299@cindex @code{trin} request, and @code{asciify} 12300@dfn{Unformat} the diversion specified by @var{div} 12301in such a way that @acronym{ASCII} characters, characters translated with 12302the @code{trin} request, space characters, and some escape sequences that 12303were formatted and diverted are treated like ordinary input 12304characters when the diversion is reread. It can be also used for gross 12305hacks; for example, the following sets register@tie{}@code{n} to@tie{}1. 12306 12307@Example 12308.tr @@. 12309.di x 12310@@nr n 1 12311.br 12312.di 12313.tr @@@@ 12314.asciify x 12315.x 12316@endExample 12317 12318@xref{Copy-in Mode}. 12319@endDefreq 12320 12321@Defreq {unformat, div} 12322Like @code{asciify}, unformat the specified diversion. 12323However, @code{unformat} only unformats spaces and tabs 12324between words. 12325Unformatted tabs are treated as input tokens, 12326and spaces are stretchable again. 12327 12328The vertical size of lines is not preserved; glyph information (font, 12329font size, space width, etc.)@: is retained. 12330@endDefreq 12331 12332 12333@c ===================================================================== 12334 12335@node Environments, Suppressing output, Diversions, gtroff Reference 12336@section Environments 12337@cindex environments 12338 12339It happens frequently that some text should be printed in a certain 12340format regardless of what may be in effect at the time, for example, in 12341a trap invoked macro to print headers and footers. To solve this 12342@code{gtroff} processes text in @dfn{environments}. An 12343environment contains most of the parameters that control text 12344processing. It is possible to switch amongst these environments; by 12345default @code{gtroff} processes text in environment@tie{}0. The 12346following is the information kept in an environment. 12347 12348@itemize @bullet 12349@item 12350font parameters (size, family, style, glyph height and slant, space 12351and sentence space size) 12352 12353@item 12354page parameters (line length, title length, vertical spacing, 12355line spacing, indentation, line numbering, centering, right-justifying, 12356underlining, hyphenation data) 12357 12358@item 12359fill and adjust mode 12360 12361@item 12362tab stops, tab and leader characters, escape character, 12363no-break and hyphen indicators, margin character data 12364 12365@item 12366partially collected lines 12367 12368@item 12369input traps 12370 12371@item 12372drawing and fill colours 12373@end itemize 12374 12375These environments may be given arbitrary names (see @ref{Identifiers}, 12376for more info). Old versions of @code{troff} only had environments 12377named @samp{0}, @samp{1}, and @samp{2}. 12378 12379@DefreqList {ev, [@Var{env}]} 12380@DefregListEnd {.ev} 12381@cindex switching environments (@code{ev}) 12382@cindex environment, switching (@code{ev}) 12383@cindex environment number/name register (@code{.ev}) 12384Switch to another environment. The argument @var{env} is the name of 12385the environment to switch to. With no argument, @code{gtroff} switches 12386back to the previous environment. There is no limit on the number of 12387named environments; they are created the first time that they are 12388referenced. The @code{.ev} read-only register contains the name or 12389number of the current environment. This is a string-valued register. 12390 12391Note that a call to @code{ev} (with argument) pushes the previously 12392active environment onto a stack. If, say, environments @samp{foo}, 12393@samp{bar}, and @samp{zap} are called (in that order), the first 12394@code{ev} request without parameter switches back to environment 12395@samp{bar} (which is popped off the stack), and a second call 12396switches back to environment @samp{foo}. 12397 12398Here is an example: 12399 12400@Example 12401.ev footnote-env 12402.fam N 12403.ps 6 12404.vs 8 12405.ll -.5i 12406.ev 12407 12408... 12409 12410.ev footnote-env 12411\(dg Note the large, friendly letters. 12412.ev 12413@endExample 12414@endDefreq 12415 12416@Defreq {evc, env} 12417@cindex copying environment (@code{evc}) 12418@cindex environment, copying (@code{evc}) 12419Copy the environment @var{env} into the current environment. 12420 12421The following environment data is not copied: 12422 12423@itemize @bullet 12424@item 12425Partially filled lines. 12426 12427@item 12428The status whether the previous line was interrupted. 12429 12430@item 12431The number of lines still to center, or to right-justify, or to underline 12432(with or without underlined spaces); they are set to zero. 12433 12434@item 12435The status whether a temporary indentation is active. 12436 12437@item 12438Input traps and its associated data. 12439 12440@item 12441Line numbering mode is disabled; it can be reactivated with 12442@w{@samp{.nm +0}}. 12443 12444@item 12445The number of consecutive hyphenated lines (set to zero). 12446@end itemize 12447@endDefreq 12448 12449@DefregList {.w} 12450@DefregItem {.cht} 12451@DefregItem {.cdp} 12452@DefregListEnd {.csk} 12453@cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 12454@cindex width, of last glyph (@code{.w}) 12455@cindex height, of last glyph (@code{.cht}) 12456@cindex depth, of last glyph (@code{.cdp}) 12457@cindex skew, of last glyph (@code{.csk}) 12458@cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 12459@cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 12460The @code{\n[.w]} register contains the 12461width of the last glyph added to the current environment. 12462 12463The @code{\n[.cht]} register contains the 12464height of the last glyph added to the current environment. 12465 12466The @code{\n[.cdp]} register contains the 12467depth of the last glyph added to the current environment. 12468It is positive for glyphs extending below the baseline. 12469 12470The @code{\n[.csk]} register contains the 12471@dfn{skew} (how far to the right of the glyph's center 12472that @code{gtroff} should place an accent) 12473of the last glyph added to the current environment. 12474@endDefreg 12475 12476@Defreg {.n} 12477@cindex environment, previous line length (@code{.n}) 12478@cindex line length, previous (@code{.n}) 12479@cindex length of previous line (@code{.n}) 12480@cindex previous line length (@code{.n}) 12481The @code{\n[.n]} register contains the 12482length of the previous output line in the current environment. 12483@endDefreg 12484 12485 12486@c ===================================================================== 12487 12488@node Suppressing output, Colors, Environments, gtroff Reference 12489@section Suppressing output 12490 12491@Defesc {\\O, , num, } 12492@cindex suppressing output (@code{\O}) 12493@cindex output, suppressing (@code{\O}) 12494Disable or enable output depending on the value of @var{num}: 12495 12496@table @samp 12497@item \O0 12498Disable any glyphs from being emitted to the device driver, provided that 12499the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}). 12500Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}. 12501 12502@item \O1 12503Enable output of glyphs, provided that the escape occurs at the outer 12504level. 12505@end table 12506 12507@vindex opminx 12508@vindex opminy 12509@vindex opmaxx 12510@vindex opmaxy 12511@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 12512@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 12513@xref{Register Index}. These four registers mark the top left and 12514bottom right hand corners of a box which encompasses all written glyphs. 12515 12516For example the input text: 12517 12518@Example 12519Hello \O[0]world \O[1]this is a test. 12520@endExample 12521 12522@noindent 12523produces the following output: 12524 12525@Example 12526Hello this is a test. 12527@endExample 12528 12529@table @samp 12530@item \O2 12531Provided that the escape occurs at the outer level, enable output of 12532glyphs and also write out to @code{stderr} the page number and four 12533registers encompassing the glyphs previously written since the last call 12534to @code{\O}. 12535 12536@item \O3 12537Begin a nesting level. At start-up, @code{gtroff} is at outer level. 12538 12539@item \O4 12540End a nesting level. 12541 12542@item \O[5@var{P}@var{filename}] 12543This escape is @code{grohtml} specific. Provided that this escape 12544occurs at the outer nesting level write the @code{filename} to 12545@code{stderr}. The position of the image, @var{P}, must be specified 12546and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left, 12547right, centered, inline). @var{filename} will be associated with the 12548production of the next inline image. 12549@end table 12550@endDefesc 12551 12552@c ===================================================================== 12553 12554@node Colors, I/O, Suppressing output, gtroff Reference 12555@section Colors 12556@cindex colors 12557 12558@DefreqList {color, [@Var{n}]} 12559@DefregListEnd {.color} 12560If @var{n} is missing or non-zero, activate colors (this is the default); 12561otherwise, turn it off. 12562 12563The read-only number register @code{.color} is@tie{}1 if colors are active, 125640@tie{}otherwise. 12565 12566Internally, @code{color} sets a global flag; it does not produce a token. 12567Similar to the @code{cp} request, you should use it at the beginning of 12568your document to control color output. 12569 12570Colors can be also turned off with the @option{-c} command line option. 12571@endDefreq 12572 12573@Defreq {defcolor, ident scheme color_components} 12574Define color with name @var{ident}. @var{scheme} can be one of the 12575following values: @code{rgb} (three components), @code{cmy} (three 12576components), @code{cmyk} (four components), and @code{gray} or 12577@code{grey} (one component). 12578 12579@cindex default color 12580@cindex color, default 12581Color components can be given either as a hexadecimal string or as 12582positive decimal integers in the range 0--65535. A hexadecimal string 12583contains all color components concatenated. It must start with either 12584@code{#} or @code{##}; the former specifies hex values in the range 125850--255 (which are internally multiplied by@tie{}257), the latter in the 12586range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff} 12587(magenta). The default color name @c{default} can't be redefined; its 12588value is device-specific (usually black). It is possible that the 12589default color for @code{\m} and @code{\M} is not identical. 12590 12591@cindex @code{f} unit, and colors 12592@cindex unit, @code{f}, and colors 12593A new scaling indicator@tie{}@code{f} has been introduced which multiplies 12594its value by 65536; this makes it convenient to specify color components 12595as fractions in the range 0 to@tie{}1 (1f equals 65536u). Example: 12596 12597@Example 12598.defcolor darkgreen rgb 0.1f 0.5f 0.2f 12599@endExample 12600 12601Note that @code{f} is the default scaling indicator for the 12602@code{defcolor} request, thus the above statement is equivalent to 12603 12604@Example 12605.defcolor darkgreen rgb 0.1 0.5 0.2 12606@endExample 12607@endDefreq 12608 12609@DefreqList {gcolor, [@Var{color}]} 12610@DefescItem {\\m, , c, } 12611@DefescItem {\\m, @Lparen{}, co, } 12612@DefescItem {\\m, @Lbrack{}, color, @Rbrack{}} 12613@DefregListEnd {.m} 12614Set (glyph) drawing color. The following examples show how to turn the 12615next four words red. 12616 12617@Example 12618.gcolor red 12619these are in red 12620.gcolor 12621and these words are in black. 12622@endExample 12623 12624@Example 12625\m[red]these are in red\m[] and these words are in black. 12626@endExample 12627 12628The escape @code{\m[]} returns to the previous color, as does a call to 12629@code{gcolor} without an argument. 12630 12631@cindex drawing color name register (@code{.m}) 12632@cindex name, drawing color, register (@code{.m}) 12633@cindex color name, drawing, register (@code{.m}) 12634The name of the current drawing color is available in the read-only, 12635string-valued number register @samp{.m}. 12636 12637The drawing color is associated with the current environment 12638(@pxref{Environments}). 12639 12640Note that @code{\m} doesn't produce an input token in @code{gtroff}. 12641As a consequence, it can be used in requests like @code{mc} (which 12642expects a single character as an argument) to change the color on 12643the fly: 12644 12645@Example 12646.mc \m[red]x\m[] 12647@endExample 12648@endDefesc 12649 12650@DefreqList {fcolor, [@Var{color}]} 12651@DefescItem {\\M, , c, } 12652@DefescItem {\\M, @Lparen{}, co, } 12653@DefescItem {\\M, @Lbrack{}, color, @Rbrack{}} 12654@DefregListEnd {.M} 12655Set fill (background) color for filled objects drawn with the 12656@code{\D'@dots{}'} commands. 12657 12658A red ellipse can be created with the following code: 12659 12660@Example 12661\M[red]\h'0.5i'\D'E 2i 1i'\M[] 12662@endExample 12663 12664The escape @code{\M[]} returns to the previous fill color, as does a call to 12665@code{fcolor} without an argument. 12666 12667@cindex background color name register (@code{.M}) 12668@cindex name, background color, register (@code{.M}) 12669@cindex color name, background, register (@code{.M}) 12670@cindex fill color name register (@code{.M}) 12671@cindex name, fill color, register (@code{.M}) 12672@cindex color name, fill, register (@code{.M}) 12673The name of the current fill (background) color is available in the 12674read-only, string-valued number register @samp{.M}. 12675 12676The fill color is associated with the current environment 12677(@pxref{Environments}). 12678 12679Note that @code{\M} doesn't produce an input token in @code{gtroff}. 12680@endDefesc 12681 12682 12683@c ===================================================================== 12684 12685@node I/O, Postprocessor Access, Colors, gtroff Reference 12686@section I/O 12687@cindex i/o 12688@cindex input and output requests 12689@cindex requests for input and output 12690@cindex output and input requests 12691 12692@code{gtroff} has several requests for including files: 12693 12694@Defreq {so, file} 12695@cindex including a file (@code{so}) 12696@cindex file, inclusion (@code{so}) 12697Read in the specified @var{file} and 12698includes it in place of the @code{so} request. This is quite useful for 12699large documents, e.g.@: keeping each chapter in a separate file. 12700@xref{gsoelim}, for more information. 12701 12702Since @code{gtroff} replaces the @code{so} request with the contents 12703of @code{file}, it makes a difference whether the data is terminated with 12704a newline or not: Assuming that file @file{xxx} contains the word 12705@samp{foo} without a final newline, this 12706 12707@Example 12708This is 12709.so xxx 12710bar 12711@endExample 12712 12713@noindent 12714yields @samp{This is foobar}. 12715 12716The search path for @var{file} can be controlled with the @option{-I} command 12717line option. 12718@endDefreq 12719 12720@Defreq {pso, command} 12721Read the standard output from the specified @var{command} 12722and includes it in place of the @code{pso} request. 12723 12724@cindex safer mode 12725@cindex mode, safer 12726@cindex unsafe mode 12727@cindex mode, unsafe 12728This request causes an error if used in safer mode (which is the default). 12729Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12730mode. 12731 12732The comment regarding a final newline for the @code{so} request is valid 12733for @code{pso} also. 12734@endDefreq 12735 12736@Defreq {mso, file} 12737Identical to the @code{so} request except that @code{gtroff} searches for 12738the specified @var{file} in the same directories as macro files for the 12739the @option{-m} command line option. If the file name to be included 12740has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 12741to include @file{tmac.@var{name}} and vice versa. 12742@endDefreq 12743 12744@DefreqList {trf, file} 12745@DefreqListEnd {cf, file} 12746@cindex transparent output (@code{cf}, @code{trf}) 12747@cindex output, transparent (@code{cf}, @code{trf}) 12748Transparently output the contents of @var{file}. Each line is output 12749as if it were preceded by @code{\!}; however, the lines are not subject 12750to copy mode interpretation. If the file does not end with a newline, 12751then a newline is added (@code{trf} only). For example, to define a 12752macro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use 12753 12754@Example 12755.di x 12756.trf f 12757.di 12758@endExample 12759 12760Both @code{trf} and @code{cf}, when used in a diversion, 12761embeds an object in the diversion which, when reread, causes the 12762contents of @var{file} to be transparently copied through to the 12763output. In @acronym{UNIX} @code{troff}, the contents of @var{file} 12764is immediately copied through to the output regardless of whether there 12765is a current diversion; this behaviour is so anomalous that it must be 12766considered a bug. 12767 12768@cindex @code{trf} request, and invalid characters 12769@cindex characters, invalid for @code{trf} request 12770@cindex invalid characters for @code{trf} request 12771While @code{cf} copies the contents of @var{file} completely unprocessed, 12772@code{trf} disallows characters such as NUL that are not valid 12773@code{gtroff} input characters (@pxref{Identifiers}). 12774 12775Both requests cause a line break. 12776@endDefreq 12777 12778@Defreq {nx, [@Var{file}]} 12779@cindex processing next file (@code{nx}) 12780@cindex file, processing next (@code{nx}) 12781@cindex next file, processing (@code{nx}) 12782Force @code{gtroff} to continue processing of 12783the file specified as an argument. If no argument is given, immediately 12784jump to the end of file. 12785@endDefreq 12786 12787@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]} 12788@cindex reading from standard input (@code{rd}) 12789@cindex standard input, reading from (@code{rd}) 12790@cindex input, standard, reading from (@code{rd}) 12791Read from standard input, and include what is read as though it 12792were part of the input file. Text is read until a blank line 12793is encountered. 12794 12795If standard input is a TTY input device (keyboard), write @var{prompt} 12796to standard error, followed by a colon (or send BEL for a beep if no 12797argument is given). 12798 12799Arguments after @var{prompt} are available for the input. For example, 12800the line 12801 12802@Example 12803.rd data foo bar 12804@endExample 12805 12806with the input @w{@samp{This is \$2.}} prints 12807 12808@Example 12809This is bar. 12810@endExample 12811@endDefreq 12812 12813@cindex form letters 12814@cindex letters, form 12815Using the @code{nx} and @code{rd} requests, 12816it is easy to set up form letters. The form 12817letter template is constructed like this, putting the following lines 12818into a file called @file{repeat.let}: 12819 12820@Example 12821.ce 12822\*(td 12823.sp 2 12824.nf 12825.rd 12826.sp 12827.rd 12828.fi 12829Body of letter. 12830.bp 12831.nx repeat.let 12832@endExample 12833 12834@cindex @code{ex} request, used with @code{nx} and @code{rd} 12835@noindent 12836When this is run, a file containing the following lines should be 12837redirected in. Note that requests included in this file are executed 12838as though they were part of the form letter. The last block of input 12839is the @code{ex} request which tells @code{groff} to stop processing. If 12840this was not there, @code{groff} would not know when to stop. 12841 12842@Example 12843Trent A. Fisher 12844708 NW 19th Av., #202 12845Portland, OR 97209 12846 12847Dear Trent, 12848 12849Len Adollar 128504315 Sierra Vista 12851San Diego, CA 92103 12852 12853Dear Mr. Adollar, 12854 12855.ex 12856@endExample 12857 12858@Defreq {pi, pipe} 12859Pipe the output of @code{gtroff} to the shell command(s) 12860specified by @var{pipe}. This request must occur before 12861@code{gtroff} has a chance to print anything. 12862 12863@cindex safer mode 12864@cindex mode, safer 12865@cindex unsafe mode 12866@cindex mode, unsafe 12867@code{pi} causes an error if used in safer mode (which is the default). 12868Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12869mode. 12870 12871Multiple calls to @code{pi} are allowed, acting as a chain. For example, 12872 12873@Example 12874.pi foo 12875.pi bar 12876... 12877@endExample 12878 12879is the same as @w{@samp{.pi foo | bar}}. 12880 12881@cindex @code{groff}, and @code{pi} request 12882@cindex @code{pi} request, and @code{groff} 12883Note that the intermediate output format of @code{gtroff} is piped to 12884the specified commands. Consequently, calling @code{groff} without the 12885@option{-Z} option normally causes a fatal error. 12886@endDefreq 12887 12888@DefreqList {sy, cmds} 12889@DefregListEnd {systat} 12890Execute the shell command(s) specified by @var{cmds}. The output is not 12891saved anyplace, so it is up to the user to do so. 12892 12893@cindex safer mode 12894@cindex mode, safer 12895@cindex unsafe mode 12896@cindex mode, unsafe 12897This request causes an error if used in safer mode (which is the default). 12898Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12899mode. 12900 12901For example, the following code fragment introduces the current time into a 12902document: 12903 12904@cindex time, current 12905@cindex current time 12906@pindex perl 12907@Example 12908.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 12909 (localtime(time))[2,1,0]' > /tmp/x\n[$$] 12910.so /tmp/x\n[$$] 12911.sy rm /tmp/x\n[$$] 12912\nH:\nM:\nS 12913@endExample 12914 12915@noindent 12916Note that this works by having the @code{perl} script (run by @code{sy}) 12917print out the @code{nr} requests which set the number registers 12918@code{H}, @code{M}, and @code{S}, and then reads those commands in with 12919the @code{so} request. 12920 12921For most practical purposes, the number registers @code{seconds}, 12922@code{minutes}, and @code{hours} which are initialized at start-up of 12923@code{gtroff} should be sufficient. Use the @code{af} request to get a 12924formatted output: 12925 12926@Example 12927.af hours 00 12928.af minutes 00 12929.af seconds 00 12930\n[hours]:\n[minutes]:\n[seconds] 12931@endExample 12932 12933@cindex @code{system()} return value register (@code{systat}) 12934The @code{systat} read-write number register contains the return value 12935of the @code{system()} function executed by the last @code{sy} request. 12936@endDefreq 12937 12938@DefreqList {open, stream file} 12939@DefreqListEnd {opena, stream file} 12940@cindex opening file (@code{open}) 12941@cindex file, opening (@code{open}) 12942@cindex appending to a file (@code{opena}) 12943@cindex file, appending to (@code{opena}) 12944Open the specified @var{file} for writing and 12945associates the specified @var{stream} with it. 12946 12947The @code{opena} request is like @code{open}, but if the file exists, 12948append to it instead of truncating it. 12949 12950@cindex safer mode 12951@cindex mode, safer 12952@cindex unsafe mode 12953@cindex mode, unsafe 12954Both @code{open} and @code{opena} cause an error if used in safer mode 12955(which is the default). Use @code{groff}'s or @code{troff}'s @option{-U} 12956option to activate unsafe mode. 12957@endDefreq 12958 12959@DefreqList {write, stream data} 12960@DefreqListEnd {writec, stream data} 12961@cindex copy-in mode, and @code{write} requests 12962@cindex mode, copy-in, and @code{write} requests 12963@cindex writing to file (@code{write}) 12964@cindex file, writing to (@code{write}) 12965Write to the file associated with the specified @var{stream}. 12966The stream must previously have 12967been the subject of an open request. The remainder of the line is 12968interpreted as the @code{ds} request reads its second argument: A 12969leading @samp{"} is stripped, and it is read in copy-in mode. 12970 12971The @code{writec} request is like @code{write}, but only 12972@code{write} appends a newline to the data. 12973@endDefreq 12974 12975@Defreq {writem, stream xx} 12976@cindex @code{asciify} request, and @code{writem} 12977Write the contents of the macro or string @var{xx} 12978to the file associated with the specified @var{stream}. 12979 12980@var{xx} is read in copy mode, i.e., already formatted elements are 12981ignored. Consequently, diversions must be unformatted with the 12982@code{asciify} request before calling @code{writem}. Usually, this 12983means a loss of information. 12984@endDefreq 12985 12986@Defreq {close, stream} 12987@cindex closing file (@code{close}) 12988@cindex file, closing (@code{close}) 12989Close the specified @var{stream}; 12990the stream is no longer an acceptable argument to the 12991@code{write} request. 12992 12993Here a simple macro to write an index entry. 12994 12995@Example 12996.open idx test.idx 12997. 12998.de IX 12999. write idx \\n[%] \\$* 13000.. 13001. 13002.IX test entry 13003. 13004.close idx 13005@endExample 13006@endDefreq 13007 13008@DefescList {\\V, , e, } 13009@DefescItem {\\V, @Lparen{}, ev, } 13010@DefescListEnd {\\V, @Lbrack{}, env, @Rbrack{}} 13011Interpolate the contents of the specified environment variable 13012@var{env} (one-character name@tie{}@var{e}, two-character name @var{ev}) 13013as returned by the function @code{getenv}. @code{\V} is interpreted 13014in copy-in mode. 13015@endDefesc 13016 13017 13018@c ===================================================================== 13019 13020@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 13021@section Postprocessor Access 13022@cindex postprocessor access 13023@cindex access of postprocessor 13024 13025There are two escapes which give information directly to the 13026postprocessor. This is particularly useful for embedding 13027@sc{PostScript} into the final document. 13028 13029@Defesc {\\X, ', xxx, '} 13030Embeds its argument into the @code{gtroff} 13031output preceded with @w{@samp{x X}}. 13032 13033@cindex @code{\&}, in @code{\X} 13034@cindex @code{\)}, in @code{\X} 13035@cindex @code{\%}, in @code{\X} 13036@ifnotinfo 13037@cindex @code{\:}, in @code{\X} 13038@end ifnotinfo 13039@ifinfo 13040@cindex @code{\@r{<colon>}}, in @code{\X} 13041@end ifinfo 13042The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored 13043within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single 13044space characters. All other escapes (except @code{\\} which produces a 13045backslash) cause an error. 13046 13047@kindex use_charnames_in_special 13048@pindex DESC@r{, and @code{use_charnames_in_special}} 13049@cindex @code{\X}, and special characters 13050If the @samp{use_charnames_in_special} keyword is set in the @file{DESC} 13051file, special characters no longer cause an error; the name @var{xx} is 13052represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command. 13053Additionally, the backslash is represented as @code{\\}. 13054 13055@samp{use_charnames_in_special} is currently used by @code{grohtml} only. 13056@endDefesc 13057 13058@DefescList {\\Y, , n, } 13059@DefescItem {\\Y, @Lparen{}, nm, } 13060@DefescListEnd {\\Y, @Lbrack{}, name, @Rbrack{}} 13061This is approximately equivalent to @samp{\X'\*[@var{name}]'} 13062(one-character name@tie{}@var{n}, two-character name @var{nm}). 13063However, the contents of the string or macro @var{name} are not 13064interpreted; also it is permitted for @var{name} to have been defined 13065as a macro and thus contain newlines (it is not permitted for the 13066argument to @code{\X} to contain newlines). The inclusion of 13067newlines requires an extension to the @acronym{UNIX} @code{troff} 13068output format, and confuses drivers that do not know about this 13069extension (@pxref{Device Control Commands}). 13070@endDefesc 13071 13072@xref{Output Devices}. 13073 13074 13075@c ===================================================================== 13076 13077@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 13078@section Miscellaneous 13079 13080This section documents parts of @code{gtroff} which cannot (yet) be 13081categorized elsewhere in this manual. 13082 13083@Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]} 13084@cindex printing line numbers (@code{nm}) 13085@cindex line numbers, printing (@code{nm}) 13086@cindex numbers, line, printing (@code{nm}) 13087Print line numbers. 13088@var{start} is the line number of the @emph{next} 13089output line. @var{inc} indicates which line numbers are printed. 13090For example, the value@tie{}5 means to emit only line numbers which 13091are multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the 13092space to be left between the number and the text; this defaults to 13093one digit space. The fourth argument is the indentation of the line 13094numbers, defaulting to zero. Both @var{space} and @var{indent} are 13095given as multiples of digit spaces; they can be negative also. 13096Without any arguments, line numbers are turned off. 13097 13098@code{gtroff} reserves three digit spaces for the line number (which is 13099printed right-justified) plus the amount given by @var{indent}; the 13100output lines are concatenated to the line numbers, separated by 13101@var{space}, and @emph{without} reducing the line length. Depending 13102on the value of the horizontal page offset (as set with the 13103@code{po} request), line numbers which are longer than the reserved 13104space stick out to the left, or the whole line is moved to the right. 13105 13106Parameters corresponding to missing arguments are not changed; any 13107non-digit argument (to be more precise, any argument starting with a 13108character valid as a delimiter for identifiers) is also treated as 13109missing. 13110 13111If line numbering has been disabled with a call to @code{nm} without 13112an argument, it can be reactivated with @samp{.nm +0}, using the 13113previously active line numbering parameters. 13114 13115The parameters of @code{nm} are associated with the current environment 13116(@pxref{Environments}). The current output line number is available 13117in the number register @code{ln}. 13118 13119@Example 13120.po 1m 13121.ll 2i 13122This test shows how line numbering works with groff. 13123.nm 999 13124This test shows how line numbering works with groff. 13125.br 13126.nm xxx 3 2 13127.ll -\w'0'u 13128This test shows how line numbering works with groff. 13129.nn 2 13130This test shows how line numbering works with groff. 13131@endExample 13132 13133@noindent 13134And here the result: 13135 13136@Example 13137 This test shows how 13138 line numbering works 13139 999 with groff. This 131401000 test shows how line 131411001 numbering works with 131421002 groff. 13143 This test shows how 13144 line numbering 13145 works with groff. 13146 This test shows how 131471005 line numbering 13148 works with groff. 13149@endExample 13150@endDefreq 13151 13152@Defreq {nn, [@Var{skip}]} 13153Temporarily turn off line numbering. The argument is the number 13154of lines not to be numbered; this defaults to@tie{}1. 13155@endDefreq 13156 13157@Defreq {mc, glyph [@Var{dist}]} 13158@cindex margin glyph (@code{mc}) 13159@cindex glyph, for margins (@code{mc}) 13160Print a @dfn{margin character} to the right of the 13161text.@footnote{@dfn{Margin character} is a misnomer since it is an 13162output glyph.} The first argument is the glyph to be 13163printed. The second argument is the distance away from the right 13164margin. If missing, the previously set value is used; default is 1316510@dmn{pt}). For text lines that are too long (that is, longer than 13166the text length plus @var{dist}), the margin character is directly 13167appended to the lines. 13168 13169With no arguments the margin character is turned off. 13170If this occurs before a break, no margin character is printed. 13171 13172For compatibility with @acronym{AT&T} @code{troff}, a call to @code{mc} 13173to set the margin character can't be undone immediately; at least one 13174line gets a margin character. Thus 13175 13176@Example 13177.ll 1i 13178.mc \[br] 13179.mc 13180xxx 13181.br 13182xxx 13183@endExample 13184 13185@noindent 13186produces 13187 13188@Example 13189xxx | 13190xxx 13191@endExample 13192 13193@cindex @code{tl} request, and @code{mc} 13194For empty lines and lines produced by the @code{tl} request no margin 13195character is emitted. 13196 13197The margin character is associated with the current environment 13198(@pxref{Environments}). 13199 13200@pindex nrchbar 13201@pindex changebar 13202This is quite useful for indicating text that has changed, and, in fact, 13203there are programs available for doing this (they are called 13204@code{nrchbar} and @code{changebar} and can be found in any 13205@samp{comp.sources.unix} archive). 13206 13207@Example 13208.ll 3i 13209.mc | 13210This paragraph is highlighted with a margin 13211character. 13212.sp 13213Note that vertical space isn't marked. 13214.br 13215\& 13216.br 13217But we can fake it with `\&'. 13218@endExample 13219 13220Result: 13221 13222@Example 13223This paragraph is highlighted | 13224with a margin character. | 13225 13226Note that vertical space isn't | 13227marked. | 13228 | 13229But we can fake it with `\&'. | 13230@endExample 13231@endDefreq 13232 13233@DefreqList {psbb, filename} 13234@DefregItem {llx} 13235@DefregItem {lly} 13236@DefregItem {urx} 13237@DefregListEnd {ury} 13238@cindex PostScript, bounding box 13239@cindex bounding box 13240Retrieve the bounding box of the PostScript image 13241found in @var{filename}. 13242The file must conform to 13243Adobe's @dfn{Document Structuring Conventions} (DSC); 13244the command searches for a @code{%%BoundingBox} comment 13245and extracts the bounding box values into the number registers 13246@code{llx}, @code{lly}, @code{urx}, and @code{ury}. 13247If an error occurs (for example, @code{psbb} cannot find 13248the @code{%%BoundingBox} comment), 13249it sets the four number registers to zero. 13250 13251The search path for @var{filename} can be controlled with the @option{-I} 13252command line option. 13253@endDefreq 13254 13255 13256@c ===================================================================== 13257 13258@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 13259@section @code{gtroff} Internals 13260 13261@cindex input token 13262@cindex token, input 13263@cindex output node 13264@cindex node, output 13265@code{gtroff} processes input in three steps. One or more input 13266characters are converted to an @dfn{input token}.@footnote{Except the 13267escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R}, 13268@code{\s}, and @code{\S} which are processed immediately if not in 13269copy-in mode.} Then, one or more input tokens are converted to an 13270@dfn{output node}. Finally, output nodes are converted to the 13271intermediate output language understood by all output devices. 13272 13273Actually, before step one happens, @code{gtroff} converts certain 13274escape sequences into reserved input characters (not accessible by 13275the user); such reserved characters are used for other internal 13276processing also -- this is the very reason why not all characters 13277are valid input. @xref{Identifiers}, for more on this topic. 13278 13279For example, the input string @samp{fi\[:u]} is converted into a 13280character token @samp{f}, a character token @samp{i}, and a special 13281token @samp{:u} (representing u@tie{}umlaut). Later on, the character 13282tokens @samp{f} and @samp{i} are merged to a single output node 13283representing the ligature glyph @samp{fi} (provided the current font 13284has a glyph for this ligature); the same happens with @samp{:u}. All 13285output glyph nodes are `processed' which means that they are invariably 13286associated with a given font, font size, advance width, etc. During 13287the formatting process, @code{gtroff} itself adds various nodes to 13288control the data flow. 13289 13290Macros, diversions, and strings collect elements in two chained lists: 13291a list of input tokens which have been passed unprocessed, and a list 13292of output nodes. Consider the following the diversion. 13293 13294@Example 13295.di xxx 13296a 13297\!b 13298c 13299.br 13300.di 13301@endExample 13302 13303@noindent 13304It contains these elements. 13305 13306@multitable {@i{vertical size node}} {token list} {element number} 13307@item node list @tab token list @tab element number 13308 13309@item @i{line start node} @tab --- @tab 1 13310@item @i{glyph node @code{a}} @tab --- @tab 2 13311@item @i{word space node} @tab --- @tab 3 13312@item --- @tab @code{b} @tab 4 13313@item --- @tab @code{\n} @tab 5 13314@item @i{glyph node @code{c}} @tab --- @tab 6 13315@item @i{vertical size node} @tab --- @tab 7 13316@item @i{vertical size node} @tab --- @tab 8 13317@item --- @tab @code{\n} @tab 9 13318@end multitable 13319 13320@cindex @code{\v}, internal representation 13321@noindent 13322Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two 13323(which are always present) specify the vertical extent of the last 13324line, possibly modified by @code{\x}. The @code{br} request finishes 13325the current partial line, inserting a newline input token which is 13326subsequently converted to a space when the diversion is reread. Note 13327that the word space node has a fixed width which isn't stretchable 13328anymore. To convert horizontal space nodes back to input tokens, use 13329the @code{unformat} request. 13330 13331Macros only contain elements in the token list (and the node list is 13332empty); diversions and strings can contain elements in both lists. 13333 13334Note that the @code{chop} request simply reduces the number of elements in a 13335macro, string, or diversion by one. Exceptions are @dfn{compatibility save} 13336and @dfn{compatibility ignore} input tokens which are ignored. The 13337@code{substring} request also ignores those input tokens. 13338 13339Some requests like @code{tr} or @code{cflags} work on glyph 13340identifiers only; this means that the associated glyph can be changed 13341without destroying this association. This can be very helpful for 13342substituting glyphs. In the following example, we assume that 13343glyph @samp{foo} isn't available by default, so we provide a 13344substitution using the @code{fchar} request and map it to input 13345character @samp{x}. 13346 13347@Example 13348.fchar \[foo] foo 13349.tr x \[foo] 13350@endExample 13351 13352@noindent 13353Now let us assume that we install an additional special font 13354@samp{bar} which has glyph @samp{foo}. 13355 13356@Example 13357.special bar 13358.rchar \[foo] 13359@endExample 13360 13361@noindent 13362Since glyphs defined with @code{fchar} are searched before glyphs 13363in special fonts, we must call @code{rchar} to remove the definition 13364of the fallback glyph. Anyway, the translation is still active; 13365@samp{x} now maps to the real glyph @samp{foo}. 13366 13367@cindex compatibility mode, and parameters 13368@cindex mode, compatibility, and parameters 13369@cindex arguments, and compatibility mode 13370@cindex parameters, and compatibility mode 13371@cindex macro arguments, and compatibility mode 13372@cindex request arguments, and compatibility mode 13373Macro and request arguments preserve the compatibility mode: 13374 13375@Example 13376.cp 1 \" switch to compatibility mode 13377.de xx 13378\\$1 13379.. 13380.cp 0 \" switch compatibility mode off 13381.xx caf\['e] 13382 @result{} caf� 13383@endExample 13384 13385@noindent 13386Since compatibility mode is on while @code{de} is called, the macro 13387@code{xx} activates compatibility mode while executing. Argument 13388@code{$1} can still be handled properly because it inherits the 13389compatibility mode status which was active at the point where @code{xx} 13390is called. 13391 13392After expansion of the parameters, the compatibility save and restore 13393tokens are removed. 13394 13395 13396@c ===================================================================== 13397 13398@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 13399@section Debugging 13400@cindex debugging 13401 13402@code{gtroff} is not easy to debug, but there are some useful features 13403and strategies for debugging. 13404 13405@Defreq {lf, line [@Var{filename}]} 13406@pindex soelim 13407@cindex multi-file documents 13408@cindex documents, multi-file 13409@cindex setting input line number (@code{lf}) 13410@cindex input line number, setting (@code{lf}) 13411@cindex number, input line, setting (@code{lf}) 13412Change the line number and optionally the file name @code{gtroff} shall 13413use for error and warning messages. @var{line} is the input line number 13414of the @emph{next} line. 13415 13416Without argument, the request is ignored. 13417 13418This is a debugging aid for documents which are split into many files, 13419then put together with @code{soelim} and other preprocessors. Usually, 13420it isn't invoked manually. 13421 13422Note that other @code{troff} implementations (including the original 13423@acronym{AT&T} version) handle @code{lf} differently. For them, 13424@var{line} changes the line number of the @emph{current} line. 13425@endDefreq 13426 13427@DefreqList {tm, string} 13428@DefreqItem {tm1, string} 13429@DefreqListEnd {tmc, string} 13430@cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc}) 13431@cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc}) 13432Send @var{string} to the standard error output; 13433this is very useful for printing debugging messages among other things. 13434 13435@var{string} is read in copy mode. 13436 13437The @code{tm} request ignores leading spaces of @var{string}; @code{tm1} 13438handles its argument similar to the @code{ds} request: a leading double 13439quote in @var{string} is stripped to allow initial blanks. 13440 13441The @code{tmc} request is similar to @code{tm1} but does 13442not append a newline (as is done in @code{tm} and @code{tm1}). 13443@endDefreq 13444 13445@Defreq {ab, [@Var{string}]} 13446@cindex aborting (@code{ab}) 13447Similar to the @code{tm} request, except that 13448it causes @code{gtroff} to stop processing. With no argument it 13449prints @samp{User Abort.} to standard error. 13450@endDefreq 13451 13452@Defreq {ex, } 13453@cindex @code{ex} request, use in debugging 13454@cindex exiting (@code{ex}) 13455The @code{ex} request also causes @code{gtroff} to stop processing; 13456see also @ref{I/O}. 13457@endDefreq 13458 13459When doing something involved it is useful to leave the debugging 13460statements in the code and have them turned on by a command line flag. 13461 13462@Example 13463.if \n(DB .tm debugging output 13464@endExample 13465 13466@noindent 13467To activate these statements say 13468 13469@Example 13470groff -rDB=1 file 13471@endExample 13472 13473If it is known in advance that there will be many errors and no useful 13474output, @code{gtroff} can be forced to suppress formatted output with 13475the @option{-z} flag. 13476 13477@Defreq {pm, } 13478@cindex dumping symbol table (@code{pm}) 13479@cindex symbol table, dumping (@code{pm}) 13480Print the entire symbol table on @code{stderr}. Names of all defined 13481macros, strings, and diversions are print together with their size in 13482bytes. Since @code{gtroff} sometimes adds nodes by itself, the 13483returned size can be larger than expected. 13484 13485This request differs from @acronym{UNIX} @code{troff}: @code{gtroff} 13486reports the sizes of diversions, ignores an additional argument to 13487print only the total of the sizes, and the size isn't returned in 13488blocks of 128 characters. 13489@endDefreq 13490 13491@Defreq {pnr, } 13492@cindex dumping number registers (@code{pnr}) 13493@cindex number registers, dumping (@code{pnr}) 13494Print the names and contents of all 13495currently defined number registers on @code{stderr}. 13496@endDefreq 13497 13498@Defreq {ptr, } 13499@cindex dumping traps (@code{ptr}) 13500@cindex traps, dumping (@code{ptr}) 13501Print the names and positions of all traps 13502(not including input line traps and diversion traps) on @code{stderr}. 13503Empty slots in the page trap list are printed as well, because they can 13504affect the priority of subsequently planted traps. 13505@endDefreq 13506 13507@Defreq {fl, } 13508@cindex flush output (@code{fl}) 13509@cindex output, flush (@code{fl}) 13510@cindex interactive use of @code{gtroff} 13511@cindex @code{gtroff}, interactive use 13512Instruct @code{gtroff} to flush its output immediately. The intent 13513is for interactive use, but this behaviour is currently not 13514implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff}, 13515TTY output is sent to a device driver also (@code{grotty}), making it 13516non-trivial to communicate interactively. 13517 13518This request causes a line break. 13519@endDefreq 13520 13521@Defreq {backtrace, } 13522@cindex backtrace of input stack (@code{backtrace}) 13523@cindex input stack, backtrace (@code{backtrace}) 13524Print a backtrace of the input stack to the standard error stream. 13525 13526Consider the following in file @file{test}: 13527 13528@Example 13529.de xxx 13530. backtrace 13531.. 13532.de yyy 13533. xxx 13534.. 13535. 13536.yyy 13537@endExample 13538 13539@noindent 13540On execution, @code{gtroff} prints the following: 13541 13542@Example 13543test:2: backtrace: macro `xxx' 13544test:5: backtrace: macro `yyy' 13545test:8: backtrace: file `test' 13546@endExample 13547 13548The option @option{-b} of @code{gtroff} internally calls a variant of 13549this request on each error and warning. 13550@endDefreq 13551 13552@Defreg {slimit} 13553@cindex input stack, setting limit 13554Use the @code{slimit} number register 13555to set the maximum number of objects on the input stack. 13556If @code{slimit} is less than or equal to@tie{}0, 13557there is no limit set. 13558With no limit, a buggy recursive macro can exhaust virtual memory. 13559 13560The default value is 1000; this is a compile-time constant. 13561@endDefreg 13562 13563@Defreq {warnscale, si} 13564Set the scaling indicator used in warnings to @var{si}. Valid values for 13565@var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At 13566startup, it is set to @samp{i}. 13567@endDefreq 13568 13569@Defreq {spreadwarn, [@Var{limit}]} 13570Make @code{gtroff} emit a warning if the additional space inserted for 13571each space between words in an output line is larger or equal to 13572@var{limit}. A negative value is changed to zero; no argument toggles the 13573warning on and off without changing @var{limit}. The default scaling 13574indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and 13575@var{limit} is set to 3@dmn{m}. 13576 13577For example, 13578 13579@Example 13580.spreadwarn 0.2m 13581@endExample 13582 13583@noindent 13584will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each 13585interword space in a line. 13586 13587This request is active only if text is justified to both margins (using 13588@w{@samp{.ad b}}). 13589@endDefreq 13590 13591@cindex warnings 13592@code{gtroff} has command line options for printing out more warnings 13593(@option{-w}) and for printing backtraces (@option{-b}) when a warning 13594or an error occurs. The most verbose level of warnings is @option{-ww}. 13595 13596@DefreqList {warn, [@Var{flags}]} 13597@DefregListEnd {.warn} 13598@cindex level of warnings (@code{warn}) 13599@cindex warnings, level (@code{warn}) 13600Control the level of warnings checked for. The @var{flags} are the sum 13601of the numbers associated with each warning that is to be enabled; all 13602other warnings are disabled. The number associated with each warning is 13603listed below. For example, @w{@code{.warn 0}} disables all warnings, 13604and @w{@code{.warn 1}} disables all warnings except that about missing 13605glyphs. If no argument is given, all warnings are enabled. 13606 13607The read-only number register @code{.warn} contains the current warning 13608level. 13609@endDefreq 13610 13611@menu 13612* Warnings:: 13613@end menu 13614 13615@c --------------------------------------------------------------------- 13616 13617@node Warnings, , Debugging, Debugging 13618@subsection Warnings 13619@cindex warnings 13620 13621The warnings that can be given to @code{gtroff} are divided into the 13622following categories. The name associated with each warning is used by 13623the @option{-w} and @option{-W} options; the number is used by the 13624@code{warn} request and by the @code{.warn} register. 13625 13626@table @samp 13627@item char 13628@itemx 1 13629Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports 13630missing glyphs -- there aren't missing input characters, only invalid 13631ones.} This is enabled by default. 13632 13633@item number 13634@itemx 2 13635Invalid numeric expressions. This is enabled by default. 13636@xref{Expressions}. 13637 13638@item break 13639@itemx 4 13640@cindex fill mode 13641@cindex mode, fill 13642In fill mode, lines which could not be broken so that their length was 13643less than the line length. This is enabled by default. 13644 13645@item delim 13646@itemx 8 13647Missing or mismatched closing delimiters. 13648 13649@item el 13650@itemx 16 13651@cindex @code{ie} request, and warnings 13652@cindex @code{el} request, and warnings 13653Use of the @code{el} request with no matching @code{ie} request. 13654@xref{if-else}. 13655 13656@item scale 13657@itemx 32 13658Meaningless scaling indicators. 13659 13660@item range 13661@itemx 64 13662Out of range arguments. 13663 13664@item syntax 13665@itemx 128 13666Dubious syntax in numeric expressions. 13667 13668@item di 13669@itemx 256 13670@cindex @code{di} request, and warnings 13671@cindex @code{da} request, and warnings 13672Use of @code{di} or @code{da} without an argument when there is no 13673current diversion. 13674 13675@item mac 13676@itemx 512 13677@cindex @code{de}, @code{de1}, @code{dei} requests, and warnings 13678@cindex @code{am}, @code{am1}, @code{ami} requests, and warnings 13679@cindex @code{ds}, @code{ds1} requests, and warnings 13680@cindex @code{as}, @code{as1} requests, and warnings 13681@cindex @code{di} request, and warnings 13682@cindex @code{da} request, and warnings 13683@cindex @code{box}, @code{boxa} requests, and warnings 13684@cindex @code{\*}, and warnings 13685Use of undefined strings, macros and diversions. When an undefined 13686string, macro, or diversion is used, that string is automatically 13687defined as empty. So, in most cases, at most one warning is given 13688for each name. 13689 13690@item reg 13691@itemx 1024 13692@cindex @code{nr} request, and warnings 13693@cindex @code{\R}, and warnings 13694@cindex @code{\n}, and warnings 13695Use of undefined number registers. When an undefined number register is 13696used, that register is automatically defined to have a value of@tie{}0. 13697So, in most cases, at most one warning is given for use of a particular 13698name. 13699 13700@item tab 13701@itemx 2048 13702@cindex @code{\t}, and warnings 13703Use of a tab character where a number was expected. 13704 13705@item right-brace 13706@itemx 4096 13707@cindex @code{\@}}, and warnings 13708Use of @code{\@}} where a number was expected. 13709 13710@item missing 13711@itemx 8192 13712Requests that are missing non-optional arguments. 13713 13714@item input 13715@itemx 16384 13716Invalid input characters. 13717 13718@item escape 13719@itemx 32768 13720Unrecognized escape sequences. When an unrecognized escape sequence 13721@code{\@var{X}} is encountered, the escape character is ignored, and 13722@var{X} is printed. 13723 13724@item space 13725@itemx 65536 13726@cindex compatibility mode 13727Missing space between a request or macro and its argument. This warning 13728is given when an undefined name longer than two characters is 13729encountered, and the first two characters of the name make a defined 13730name. The request or macro is not invoked. When this warning is 13731given, no macro is automatically defined. This is enabled by default. 13732This warning never occurs in compatibility mode. 13733 13734@item font 13735@itemx 131072 13736Non-existent fonts. This is enabled by default. 13737 13738@item ig 13739@itemx 262144 13740Invalid escapes in text ignored with the @code{ig} request. These are 13741conditions that are errors when they do not occur in ignored text. 13742 13743@item color 13744@itemx 524288 13745Color related warnings. 13746 13747@item all 13748All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 13749intended that this covers all warnings that are useful with traditional 13750macro packages. 13751 13752@item w 13753All warnings. 13754@end table 13755 13756 13757@c ===================================================================== 13758 13759@node Implementation Differences, , Debugging, gtroff Reference 13760@section Implementation Differences 13761@cindex implementation differences 13762@cindex differences in implementation 13763@cindex incompatibilities with @acronym{AT&T} @code{troff} 13764@cindex compatibility mode 13765@cindex mode, compatibility 13766 13767GNU @code{troff} has a number of features which cause incompatibilities 13768with documents written with old versions of @code{troff}. 13769 13770@cindex long names 13771@cindex names, long 13772Long names cause some incompatibilities. @acronym{UNIX} @code{troff} 13773interprets 13774 13775@Example 13776.dsabcd 13777@endExample 13778 13779@cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff} 13780@cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff} 13781@noindent 13782as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 13783@code{troff} interprets this as a call of a macro named 13784@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 13785@code{\*[} or @code{\n[} as references to a string or number register 13786called @samp{[}. In GNU @code{troff}, however, this is normally 13787interpreted as the start of a long name. In compatibility mode GNU 13788@code{troff} interprets long names in the traditional way 13789(which means that they are not recognized as names). 13790 13791@DefreqList {cp, [@Var{n}]} 13792@DefreqItem {do, cmd} 13793@DefregListEnd {.C} 13794If @var{n} is missing or non-zero, turn on compatibility mode; 13795otherwise, turn it off. 13796 13797The read-only number register @code{.C} is@tie{}1 if compatibility mode is 13798on, 0@tie{}otherwise. 13799 13800Compatibility mode can be also turned on with the @option{-C} command line 13801option. 13802 13803The @code{do} request turns off compatibility mode 13804while executing its arguments as a @code{gtroff} command. 13805 13806@Example 13807.do fam T 13808@endExample 13809 13810@noindent 13811executes the @code{fam} request when compatibility mode 13812is enabled. 13813 13814@code{gtroff} restores the previous compatibility setting 13815before interpreting any files sourced by the @var{cmd}. 13816@endDefreq 13817 13818@cindex input level in delimited arguments 13819@cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff} 13820Two other features are controlled by @option{-C}. If not in 13821compatibility mode, GNU @code{troff} preserves the input level in 13822delimited arguments: 13823 13824@Example 13825.ds xx ' 13826\w'abc\*(xxdef' 13827@endExample 13828 13829@noindent 13830In compatibility mode, the string @samp{72def'} is returned; without 13831@option{-C} the resulting string is @samp{168} (assuming a TTY output 13832device). 13833 13834@cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff} 13835@cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff} 13836@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff} 13837@cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff} 13838Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M}, 13839@code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the 13840beginning of a line only in compatibility mode (this is a rather obscure 13841feature). For example, the code 13842 13843@Example 13844.de xx 13845Hallo! 13846.. 13847\fB.xx\fP 13848@endExample 13849 13850@noindent 13851prints @samp{Hallo!} in bold face if in compatibility mode, and 13852@samp{.xx} in bold face otherwise. 13853 13854@cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff} 13855@cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff} 13856@cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff} 13857@cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff} 13858@cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff} 13859@cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff} 13860@cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff} 13861@cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff} 13862@cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff} 13863@cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff} 13864@cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff} 13865@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 13866@cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff} 13867@cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff} 13868GNU @code{troff} does not allow the use of the escape sequences 13869@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 13870@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 13871@code{\%}, and @code{\c} in names of strings, macros, diversions, number 13872registers, fonts or environments; @acronym{UNIX} @code{troff} does. The 13873@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 13874avoiding use of these escape sequences in names. 13875 13876@cindex fractional point sizes 13877@cindex fractional type sizes 13878@cindex point sizes, fractional 13879@cindex type sizes, fractional 13880@cindex sizes, fractional 13881@cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff} 13882Fractional point sizes cause one noteworthy incompatibility. In 13883@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 13884indicators and thus 13885 13886@Example 13887.ps 10u 13888@endExample 13889 13890@noindent 13891sets the point size to 10@tie{}points, whereas in GNU @code{troff} it 13892sets the point size to 10@tie{}scaled points. @xref{Fractional Type 13893Sizes}, for more information. 13894 13895@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff} 13896@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff} 13897@cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff} 13898@cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff} 13899@cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff} 13900@cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff} 13901@cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff} 13902@cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff} 13903In GNU @code{troff} there is a fundamental difference between 13904(unformatted) input characters and (formatted) output glyphs. 13905Everything that affects how a glyph is output is stored 13906with the glyph node; once a glyph node has been constructed it is 13907unaffected by any subsequent requests that are executed, including 13908@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 13909Normally glyphs are constructed from input characters at the 13910moment immediately before the glyph is added to the current output 13911line. Macros, diversions and strings are all, in fact, the same type of 13912object; they contain lists of input characters and glyph nodes in 13913any combination. A glyph node does not behave like an input 13914character for the purposes of macro processing; it does not inherit any 13915of the special properties that the input character from which it was 13916constructed might have had. For example, 13917 13918@Example 13919.di x 13920\\\\ 13921.br 13922.di 13923.x 13924@endExample 13925 13926@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 13927@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 13928@cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff} 13929@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 13930@cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff} 13931@cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff} 13932@cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff} 13933@noindent 13934prints @samp{\\} in GNU @code{troff}; each pair of input backslashes 13935is turned into one output backslash and the resulting output backslashes 13936are not interpreted as escape characters when they are reread. 13937@acronym{UNIX} @code{troff} would interpret them as escape characters 13938when they were reread and would end up printing one @samp{\}. The 13939correct way to obtain a printable backslash is to use the @code{\e} 13940escape sequence: This always prints a single instance of the current 13941escape character, regardless of whether or not it is used in a 13942diversion; it also works in both GNU @code{troff} and @acronym{UNIX} 13943@code{troff}.@footnote{To be completely independent of the current 13944escape character, use @code{\(rs} which represents a reverse solidus 13945(backslash) glyph.} To store, for some reason, an escape sequence in a 13946diversion that will be interpreted when the diversion is reread, either 13947use the traditional @code{\!} transparent output facility, or, if this 13948is unsuitable, the new @code{\?} escape sequence. 13949 13950@xref{Diversions}, and @ref{Gtroff Internals}, for more information. 13951 13952 13953 13954@c ===================================================================== 13955@c ===================================================================== 13956 13957@node Preprocessors, Output Devices, gtroff Reference, Top 13958@chapter Preprocessors 13959@cindex preprocessors 13960 13961This chapter describes all preprocessors that come with @code{groff} or 13962which are freely available. 13963 13964@menu 13965* geqn:: 13966* gtbl:: 13967* gpic:: 13968* ggrn:: 13969* grap:: 13970* grefer:: 13971* gsoelim:: 13972@end menu 13973 13974 13975@c ===================================================================== 13976 13977@node geqn, gtbl, Preprocessors, Preprocessors 13978@section @code{geqn} 13979@cindex @code{eqn}, the program 13980@cindex @code{geqn}, the program 13981 13982@c XXX 13983 13984@menu 13985* Invoking geqn:: 13986@end menu 13987 13988@c --------------------------------------------------------------------- 13989 13990@node Invoking geqn, , geqn, geqn 13991@subsection Invoking @code{geqn} 13992@cindex invoking @code{geqn} 13993@cindex @code{geqn}, invoking 13994 13995@c XXX 13996 13997 13998@c ===================================================================== 13999 14000@node gtbl, gpic, geqn, Preprocessors 14001@section @code{gtbl} 14002@cindex @code{tbl}, the program 14003@cindex @code{gtbl}, the program 14004 14005@c XXX 14006 14007@menu 14008* Invoking gtbl:: 14009@end menu 14010 14011@c --------------------------------------------------------------------- 14012 14013@node Invoking gtbl, , gtbl, gtbl 14014@subsection Invoking @code{gtbl} 14015@cindex invoking @code{gtbl} 14016@cindex @code{gtbl}, invoking 14017 14018@c XXX 14019 14020 14021@c ===================================================================== 14022 14023@node gpic, ggrn, gtbl, Preprocessors 14024@section @code{gpic} 14025@cindex @code{pic}, the program 14026@cindex @code{gpic}, the program 14027 14028@c XXX 14029 14030@menu 14031* Invoking gpic:: 14032@end menu 14033 14034@c --------------------------------------------------------------------- 14035 14036@node Invoking gpic, , gpic, gpic 14037@subsection Invoking @code{gpic} 14038@cindex invoking @code{gpic} 14039@cindex @code{gpic}, invoking 14040 14041@c XXX 14042 14043 14044@c ===================================================================== 14045 14046@node ggrn, grap, gpic, Preprocessors 14047@section @code{ggrn} 14048@cindex @code{grn}, the program 14049@cindex @code{ggrn}, the program 14050 14051@c XXX 14052 14053@menu 14054* Invoking ggrn:: 14055@end menu 14056 14057@c --------------------------------------------------------------------- 14058 14059@node Invoking ggrn, , ggrn, ggrn 14060@subsection Invoking @code{ggrn} 14061@cindex invoking @code{ggrn} 14062@cindex @code{ggrn}, invoking 14063 14064@c XXX 14065 14066 14067@c ===================================================================== 14068 14069@node grap, grefer, ggrn, Preprocessors 14070@section @code{grap} 14071@cindex @code{grap}, the program 14072 14073A free implementation of @code{grap}, written by Ted Faber, 14074is available as an extra package from the following address: 14075 14076@display 14077@uref{http://www.lunabase.org/~faber/Vault/software/grap/} 14078@end display 14079 14080 14081@c ===================================================================== 14082 14083@node grefer, gsoelim, grap, Preprocessors 14084@section @code{grefer} 14085@cindex @code{refer}, the program 14086@cindex @code{grefer}, the program 14087 14088@c XXX 14089 14090@menu 14091* Invoking grefer:: 14092@end menu 14093 14094@c --------------------------------------------------------------------- 14095 14096@node Invoking grefer, , grefer, grefer 14097@subsection Invoking @code{grefer} 14098@cindex invoking @code{grefer} 14099@cindex @code{grefer}, invoking 14100 14101@c XXX 14102 14103 14104@c ===================================================================== 14105 14106@node gsoelim, , grefer, Preprocessors 14107@section @code{gsoelim} 14108@cindex @code{soelim}, the program 14109@cindex @code{gsoelim}, the program 14110 14111@c XXX 14112 14113@menu 14114* Invoking gsoelim:: 14115@end menu 14116 14117@c --------------------------------------------------------------------- 14118 14119@node Invoking gsoelim, , gsoelim, gsoelim 14120@subsection Invoking @code{gsoelim} 14121@cindex invoking @code{gsoelim} 14122@cindex @code{gsoelim}, invoking 14123 14124@c XXX 14125 14126 14127 14128@c ===================================================================== 14129@c ===================================================================== 14130 14131@node Output Devices, File formats, Preprocessors, Top 14132@chapter Output Devices 14133@cindex output devices 14134@cindex devices for output 14135 14136@c XXX 14137 14138@menu 14139* Special Characters:: 14140* grotty:: 14141* grops:: 14142* grodvi:: 14143* grolj4:: 14144* grolbp:: 14145* grohtml:: 14146* gxditview:: 14147@end menu 14148 14149 14150@c ===================================================================== 14151 14152@node Special Characters, grotty, Output Devices, Output Devices 14153@section Special Characters 14154@cindex special characters 14155@cindex characters, special 14156 14157@c XXX 14158 14159@xref{Font Files}. 14160 14161 14162@c ===================================================================== 14163 14164@node grotty, grops, Special Characters, Output Devices 14165@section @code{grotty} 14166@cindex @code{grotty}, the program 14167 14168@c XXX 14169 14170@menu 14171* Invoking grotty:: 14172@end menu 14173 14174@c --------------------------------------------------------------------- 14175 14176@node Invoking grotty, , grotty, grotty 14177@subsection Invoking @code{grotty} 14178@cindex invoking @code{grotty} 14179@cindex @code{grotty}, invoking 14180 14181@c XXX 14182 14183@c The following is no longer true; fix and extend it. 14184 14185@c @pindex less 14186@c @cindex Teletype 14187@c @cindex ISO 6249 SGR 14188@c @cindex terminal control sequences 14189@c @cindex control sequences, for terminals 14190@c For TTY output devices, underlining is done by emitting sequences of 14191@c @samp{_} and @samp{\b} (the backspace character) before the actual 14192@c character. Literally, this is printing an underline character, then 14193@c moving back one character position, and printing the actual character 14194@c at the same position as the underline character (similar to a 14195@c typewriter). Usually, a modern terminal can't interpret this (and the 14196@c original Teletype machines for which this sequence was appropriate are 14197@c no longer in use). You need a pager program like @code{less} which 14198@c translates this into ISO 6429 SGR sequences to control terminals. 14199 14200 14201@c ===================================================================== 14202 14203@node grops, grodvi, grotty, Output Devices 14204@section @code{grops} 14205@cindex @code{grops}, the program 14206 14207@c XXX 14208 14209@menu 14210* Invoking grops:: 14211* Embedding PostScript:: 14212@end menu 14213 14214@c --------------------------------------------------------------------- 14215 14216@node Invoking grops, Embedding PostScript, grops, grops 14217@subsection Invoking @code{grops} 14218@cindex invoking @code{grops} 14219@cindex @code{grops}, invoking 14220 14221@c XXX 14222 14223@c --------------------------------------------------------------------- 14224 14225@node Embedding PostScript, , Invoking grops, grops 14226@subsection Embedding @sc{PostScript} 14227@cindex embedding PostScript 14228@cindex PostScript, embedding 14229 14230@c XXX 14231 14232 14233@c ===================================================================== 14234 14235@node grodvi, grolj4, grops, Output Devices 14236@section @code{grodvi} 14237@cindex @code{grodvi}, the program 14238 14239@c XXX 14240 14241@menu 14242* Invoking grodvi:: 14243@end menu 14244 14245@c --------------------------------------------------------------------- 14246 14247@node Invoking grodvi, , grodvi, grodvi 14248@subsection Invoking @code{grodvi} 14249@cindex invoking @code{grodvi} 14250@cindex @code{grodvi}, invoking 14251 14252@c XXX 14253 14254 14255@c ===================================================================== 14256 14257@node grolj4, grolbp, grodvi, Output Devices 14258@section @code{grolj4} 14259@cindex @code{grolj4}, the program 14260 14261@c XXX 14262 14263@menu 14264* Invoking grolj4:: 14265@end menu 14266 14267@c --------------------------------------------------------------------- 14268 14269@node Invoking grolj4, , grolj4, grolj4 14270@subsection Invoking @code{grolj4} 14271@cindex invoking @code{grolj4} 14272@cindex @code{grolj4}, invoking 14273 14274@c XXX 14275 14276 14277@c ===================================================================== 14278 14279@node grolbp, grohtml, grolj4, Output Devices 14280@section @code{grolbp} 14281@cindex @code{grolbp}, the program 14282 14283@c XXX 14284 14285@menu 14286* Invoking grolbp:: 14287@end menu 14288 14289@c --------------------------------------------------------------------- 14290 14291@node Invoking grolbp, , grolbp, grolbp 14292@subsection Invoking @code{grolbp} 14293@cindex invoking @code{grolbp} 14294@cindex @code{grolbp}, invoking 14295 14296@c XXX 14297 14298 14299@c ===================================================================== 14300 14301@node grohtml, gxditview, grolbp, Output Devices 14302@section @code{grohtml} 14303@cindex @code{grohtml}, the program 14304 14305@c XXX 14306 14307@menu 14308* Invoking grohtml:: 14309* grohtml specific registers and strings:: 14310@end menu 14311 14312@c --------------------------------------------------------------------- 14313 14314@node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml 14315@subsection Invoking @code{grohtml} 14316@cindex invoking @code{grohtml} 14317@cindex @code{grohtml}, invoking 14318 14319@c XXX 14320 14321@c --------------------------------------------------------------------- 14322 14323@node grohtml specific registers and strings, , Invoking grohtml, grohtml 14324@subsection @code{grohtml} specific registers and strings 14325@cindex registers specific to @code{grohtml} 14326@cindex strings specific to @code{grohtml} 14327@cindex @code{grohtml}, registers and strings 14328 14329@DefmpregList {ps4html, grohtml} 14330@DefstrListEnd {www-image-template, grohtml} 14331The registers @code{ps4html} and @code{www-image-template} are defined 14332by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in 14333the @code{troff} input, marks up the inline equations and passes the 14334result firstly to 14335 14336@Example 14337troff -Tps -rps4html=1 -dwww-image-template=@var{template} 14338@endExample 14339 14340@noindent 14341and secondly to 14342 14343@Example 14344troff -Thtml 14345@endExample 14346 14347The PostScript device is used to create all the image files, and the 14348register @code{ps4html} enables the macro sets to ignore floating 14349keeps, footers, and headings. 14350 14351The register @code{www-image-template} is set to the user specified 14352template name or the default name. 14353@endDefmpreg 14354 14355 14356@c ===================================================================== 14357 14358@node gxditview, , grohtml, Output Devices 14359@section @code{gxditview} 14360@cindex @code{gxditview}, the program 14361 14362@c XXX 14363 14364@menu 14365* Invoking gxditview:: 14366@end menu 14367 14368@c --------------------------------------------------------------------- 14369 14370@node Invoking gxditview, , gxditview, gxditview 14371@subsection Invoking @code{gxditview} 14372@cindex invoking @code{gxditview} 14373@cindex @code{gxditview}, invoking 14374 14375@c XXX 14376@c X11's xditview 14377 14378 14379 14380@c ===================================================================== 14381@c ===================================================================== 14382 14383@node File formats, Installation, Output Devices, Top 14384@chapter File formats 14385@cindex file formats 14386@cindex formats, file 14387 14388All files read and written by @code{gtroff} are text files. The 14389following two sections describe their format. 14390 14391@menu 14392* gtroff Output:: 14393* Font Files:: 14394@end menu 14395 14396 14397@c ===================================================================== 14398 14399@node gtroff Output, Font Files, File formats, File formats 14400@section @code{gtroff} Output 14401@cindex @code{gtroff}, output 14402@cindex output, @code{gtroff} 14403 14404This section describes the intermediate output format of GNU 14405@code{troff}. This output is produced by a run of @code{gtroff} 14406before it is fed into a device postprocessor program. 14407 14408As @code{groff} is a wrapper program around @code{gtroff} that 14409automatically calls a postprocessor, this output does not show up 14410normally. This is why it is called @dfn{intermediate}. 14411@code{groff} provides the option @option{-Z} to inhibit postprocessing, 14412such that the produced intermediate output is sent to standard output 14413just like calling @code{gtroff} manually. 14414 14415@cindex troff output 14416@cindex output, troff 14417@cindex intermediate output 14418@cindex output, intermediate 14419Here, the term @dfn{troff output} describes what is output by 14420@code{gtroff}, while @dfn{intermediate output} refers to the language 14421that is accepted by the parser that prepares this output for the 14422postprocessors. This parser is smarter on whitespace and implements 14423obsolete elements for compatibility, otherwise both formats are the 14424same.@footnote{The parser and postprocessor for intermediate output 14425can be found in the file@* 14426@file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.} 14427 14428The main purpose of the intermediate output concept is to facilitate 14429the development of postprocessors by providing a common programming 14430interface for all devices. It has a language of its own that is 14431completely different from the @code{gtroff} language. While the 14432@code{gtroff} language is a high-level programming language for text 14433processing, the intermediate output language is a kind of low-level 14434assembler language by specifying all positions on the page for writing 14435and drawing. 14436 14437The intermediate output produced by @code{gtroff} is fairly readable, 14438while output from @acronym{AT&T} @code{troff} is rather hard to 14439understand because of strange habits that are still supported, but not 14440used any longer by @code{gtroff}. 14441 14442@menu 14443* Language Concepts:: 14444* Command Reference:: 14445* Intermediate Output Examples:: 14446* Output Language Compatibility:: 14447@end menu 14448 14449@c --------------------------------------------------------------------- 14450 14451@node Language Concepts, Command Reference, gtroff Output, gtroff Output 14452@subsection Language Concepts 14453 14454During the run of @code{gtroff}, the input data is cracked down to the 14455information on what has to be printed at what position on the intended 14456device. So the language of the intermediate output format can be quite 14457small. Its only elements are commands with and without arguments. 14458In this section, the term @dfn{command} always refers to the intermediate 14459output language, and never to the @code{gtroff} language used for document 14460formatting. There are commands for positioning and text writing, for drawing, and 14461for device controlling. 14462 14463@menu 14464* Separation:: 14465* Argument Units:: 14466* Document Parts:: 14467@end menu 14468 14469@node Separation, Argument Units, Language Concepts, Language Concepts 14470@subsubsection Separation 14471 14472@acronym{AT&T} @code{troff} output has strange requirements on whitespace. 14473The @code{gtroff} output parser, however, is smart about whitespace by 14474making it maximally optional. The whitespace characters, i.e., the 14475tab, space, and newline characters, always have a syntactical meaning. 14476They are never printable because spacing within the output is always 14477done by positioning commands. 14478 14479Any sequence of space or tab characters is treated as a single 14480@dfn{syntactical space}. It separates commands and arguments, but is 14481only required when there would occur a clashing between the command code 14482and the arguments without the space. Most often, this happens when 14483variable-length command names, arguments, argument lists, or command 14484clusters meet. Commands and arguments with a known, fixed length need 14485not be separated by syntactical space. 14486 14487A line break is a syntactical element, too. Every command argument can be 14488followed by whitespace, a comment, or a newline character. Thus a 14489@dfn{syntactical line break} is defined to consist of optional 14490syntactical space that is optionally followed by a comment, and a 14491newline character. 14492 14493The normal commands, those for positioning and text, consist of a 14494single letter taking a fixed number of arguments. For historical reasons, 14495the parser allows to stack such commands on the same line, but 14496fortunately, in @code{gtroff}'s intermediate output, every command with 14497at least one argument is followed by a line break, thus providing 14498excellent readability. 14499 14500The other commands -- those for drawing and device controlling -- 14501have a more complicated structure; some recognize long command names, 14502and some take a variable number of arguments. So all @samp{D} and 14503@samp{x} commands were designed to request a syntactical line break 14504after their last argument. Only one command, @w{@samp{x X}}, 14505has an argument that can stretch over several lines; all other 14506commands must have all of their arguments on the same line as the 14507command, i.e., the arguments may not be splitted by a line break. 14508 14509Empty lines (these are lines containing only space and/or a comment), can 14510occur everywhere. They are just ignored. 14511 14512@node Argument Units, Document Parts, Separation, Language Concepts 14513@subsubsection Argument Units 14514 14515Some commands take integer arguments that are assumed to represent 14516values in a measurement unit, but the letter for the corresponding 14517scale indicator is not written with the output command arguments. 14518Most commands assume the scale indicator @samp{u}, the basic unit of 14519the device, some use @samp{z}, the scaled point unit of the device, 14520while others, such as the color commands, expect plain integers. 14521 14522Note that single characters can have the eighth bit set, as can the 14523names of fonts and special characters. The names of characters and 14524fonts can be of arbitrary length. A character that is to be printed 14525will always be in the current font. 14526 14527A string argument is always terminated by the next whitespace 14528character (space, tab, or newline); an embedded @samp{#} character is 14529regarded as part of the argument, not as the beginning of a comment 14530command. An integer argument is already terminated by the next 14531non-digit character, which then is regarded as the first character of 14532the next argument or command. 14533 14534@node Document Parts, , Argument Units, Language Concepts 14535@subsubsection Document Parts 14536 14537A correct intermediate output document consists of two parts, the 14538@dfn{prologue} and the @dfn{body}. 14539 14540The task of the prologue is to set the general device parameters 14541using three exactly specified commands. @code{gtroff}'s prologue 14542is guaranteed to consist of the following three lines (in that order): 14543 14544@Example 14545x T @var{device} 14546x res @var{n} @var{h} @var{v} 14547x init 14548@endExample 14549 14550@noindent 14551with the arguments set as outlined in @ref{Device Control Commands}. 14552Note that the parser for the intermediate output format is able to 14553swallow additional whitespace and comments as well even in the 14554prologue. 14555 14556The body is the main section for processing the document data. 14557Syntactically, it is a sequence of any commands different from the 14558ones used in the prologue. Processing is terminated as soon as the 14559first @w{@samp{x stop}} command is encountered; the last line of any 14560@code{gtroff} intermediate output always contains such a command. 14561 14562Semantically, the body is page oriented. A new page is started by a 14563@samp{p} command. Positioning, writing, and drawing commands are 14564always done within the current page, so they cannot occur before the 14565first @samp{p} command. Absolute positioning (by the @samp{H} and 14566@samp{V} commands) is done relative to the current page; all other 14567positioning is done relative to the current location within this page. 14568 14569@c --------------------------------------------------------------------- 14570 14571@node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output 14572@subsection Command Reference 14573 14574This section describes all intermediate output commands, both from 14575@acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions. 14576 14577@menu 14578* Comment Command:: 14579* Simple Commands:: 14580* Graphics Commands:: 14581* Device Control Commands:: 14582* Obsolete Command:: 14583@end menu 14584 14585@node Comment Command, Simple Commands, Command Reference, Command Reference 14586@subsubsection Comment Command 14587 14588@table @code 14589@item #@var{anything}@angles{end of line} 14590A comment. Ignore any characters from the @samp{#} character up to 14591the next newline character. 14592 14593This command is the only possibility for commenting in the intermediate 14594output. Each comment can be preceded by arbitrary syntactical space; 14595every command can be terminated by a comment. 14596@end table 14597 14598@node Simple Commands, Graphics Commands, Comment Command, Command Reference 14599@subsubsection Simple Commands 14600 14601The commands in this subsection have a command code consisting of a 14602single character, taking a fixed number of arguments. Most of them 14603are commands for positioning and text writing. These commands are 14604smart about whitespace. Optionally, syntactical space can be inserted 14605before, after, and between the command letter and its arguments. 14606All of these commands are stackable, i.e., they can be preceded by 14607other simple commands or followed by arbitrary other commands on the 14608same line. A separating syntactical space is only necessary when two 14609integer arguments would clash or if the preceding argument ends with a 14610string argument. 14611 14612@table @code 14613@ignore 14614.if (\n[@USE_ENV_STACK] == 1) \{\ 14615.command { 14616Open a new environment by copying the actual device configuration data 14617to the environment stack. 14618. 14619The current environment is setup by the device specification and 14620manipulated by the setting commands. 14621. 14622. 14623.command } 14624Close the actual environment (opened by a preceding 14625.BR { \~command) 14626and restore the previous environment from the environment 14627stack as the actual device configuration data. 14628. 14629\} \" endif @USE_ENV_STACK 14630@end ignore 14631 14632@item C @var{xxx}@angles{whitespace} 14633Print a special character named @var{xxx}. The trailing 14634syntactical space or line break is necessary to allow glyph names 14635of arbitrary length. The glyph is printed at the current print 14636position; the glyph's size is read from the font file. The print 14637position is not changed. 14638 14639@item c @var{g} 14640Print glyph@tie{}@var{g} at the current print position;@footnote{@samp{c} 14641is actually a misnomer since it outputs a glyph.} the glyph's size is 14642read from the font file. The print position is not changed. 14643 14644@item f @var{n} 14645Set font to font number@tie{}@var{n} (a non-negative integer). 14646 14647@item H @var{n} 14648Move right to the absolute vertical position@tie{}@var{n} (a 14649non-negative integer in basic units @samp{u} relative to left edge 14650of current page. 14651 14652@item h @var{n} 14653Move @var{n} (a non-negative integer) basic units @samp{u} horizontally 14654to the right. The original @acronym{UNIX} troff manual allows negative 14655values for @var{n} also, but @code{gtroff} doesn't use this. 14656 14657@item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]} 14658Set the color for text (glyphs), line drawing, and the outline of 14659graphic objects using different color schemes; the analoguous command 14660for the filling color of graphic objects is @samp{DF}. The color 14661components are specified as integer arguments between 0 and 65536. 14662The number of color components and their meaning vary for the 14663different color schemes. These commands are generated by 14664@code{gtroff}'s escape sequence @code{\m}. No position changing. 14665These commands are a @code{gtroff} extension. 14666 14667@table @code 14668@item mc @var{cyan} @var{magenta} @var{yellow} 14669Set color using the CMY color scheme, having the 3@tie{}color components 14670@var{cyan}, @var{magenta}, and @var{yellow}. 14671 14672@item md 14673Set color to the default color value (black in most cases). 14674No component arguments. 14675 14676@item mg @var{gray} 14677Set color to the shade of gray given by the argument, an integer 14678between 0 (black) and 65536 (white). 14679 14680@item mk @var{cyan} @var{magenta} @var{yellow} @var{black} 14681Set color using the CMYK color scheme, having the 4@tie{}color components 14682@var{cyan}, @var{magenta}, @var{yellow}, and @var{black}. 14683 14684@item mr @var{red} @var{green} @var{blue} 14685Set color using the RGB color scheme, having the 3@tie{}color components 14686@var{red}, @var{green}, and @var{blue}. 14687@end table 14688 14689@item N @var{n} 14690Print glyph with index@tie{}@var{n} (a non-negative integer) of the 14691current font. This command is a @code{gtroff} extension. 14692 14693@item n @var{b} @var{a} 14694Inform the device about a line break, but no positioning is done by 14695this command. In @acronym{AT&T} @code{troff}, the integer arguments 14696@var{b} and@tie{}@var{a} informed about the space before and after the 14697current line to make the intermediate output more human readable 14698without performing any action. In @code{groff}, they are just ignored, but 14699they must be provided for compatibility reasons. 14700 14701@item p @var{n} 14702Begin a new page in the outprint. The page number is set 14703to@tie{}@var{n}. This page is completely independent of pages formerly 14704processed even if those have the same page number. The vertical 14705position on the outprint is automatically set to@tie{}0. All 14706positioning, writing, and drawing is always done relative to a page, 14707so a @samp{p} command must be issued before any of these commands. 14708 14709@item s @var{n} 14710Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}). 14711@acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead. 14712@xref{Output Language Compatibility}. 14713 14714@item t @var{xxx}@angles{whitespace} 14715@itemx t @var{xxx} @var{dummy-arg}@angles{whitespace} 14716Print a word, i.e., a sequence of characters @var{xxx} representing 14717output glyphs which names are single characters, terminated by 14718a space character or a line break; an optional second integer argument 14719is ignored (this allows the formatter to generate an even number of 14720arguments). The first glyph should be printed at the current 14721position, the current horizontal position should then be increased by 14722the width of the first glyph, and so on for each glyph. 14723The widths of the glyphs are read from the font file, scaled for the 14724current point size, and rounded to a multiple of the horizontal 14725resolution. Special characters cannot be printed using this command 14726(use the @samp{C} command for special characters). This command is a 14727@code{gtroff} extension; it is only used for devices whose @file{DESC} 14728file contains the @code{tcommand} keyword (@pxref{DESC File Format}). 14729 14730@item u @var{n} @var{xxx}@angles{whitespace} 14731Print word with track kerning. This is the same as the @samp{t} 14732command except that after printing each glyph, the current 14733horizontal position is increased by the sum of the width of that 14734glyph and@tie{}@var{n} (an integer in basic units @samp{u}). 14735This command is a @code{gtroff} extension; it is only used for devices 14736whose @file{DESC} file contains the @code{tcommand} keyword 14737(@pxref{DESC File Format}). 14738 14739@item V @var{n} 14740Move down to the absolute vertical position@tie{}@var{n} (a 14741non-negative integer in basic units @samp{u}) relative to upper edge 14742of current page. 14743 14744@item v @var{n} 14745Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative 14746integer). The original @acronym{UNIX} troff manual allows negative 14747values for @var{n} also, but @code{gtroff} doesn't use this. 14748 14749@item w 14750Informs about a paddable white space to increase readability. 14751The spacing itself must be performed explicitly by a move command. 14752@end table 14753 14754@node Graphics Commands, Device Control Commands, Simple Commands, Command Reference 14755@subsubsection Graphics Commands 14756 14757Each graphics or drawing command in the intermediate output starts 14758with the letter @samp{D}, followed by one or two characters that 14759specify a subcommand; this is followed by a fixed or variable number 14760of integer arguments that are separated by a single space character. 14761A @samp{D} command may not be followed by another command on the same line 14762(apart from a comment), so each @samp{D} command is terminated by a 14763syntactical line break. 14764 14765@code{gtroff} output follows the classical spacing rules (no space 14766between command and subcommand, all arguments are preceded by a 14767single space character), but the parser allows optional space between 14768the command letters and makes the space before the first argument 14769optional. As usual, each space can be any sequence of tab and space 14770characters. 14771 14772Some graphics commands can take a variable number of arguments. 14773In this case, they are integers representing a size measured in basic 14774units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{}, 14775@var{hn} stand for horizontal distances where positive means right, 14776negative left. The arguments called @var{v1}, @var{v2}, @dots{}, 14777@var{vn} stand for vertical distances where positive means down, 14778negative up. All these distances are offsets relative to the current 14779location. 14780 14781Each graphics command directly corresponds to a similar @code{gtroff} 14782@code{\D} escape sequence. @xref{Drawing Requests}. 14783 14784Unknown @samp{D} commands are assumed to be device-specific. 14785Its arguments are parsed as strings; the whole information is then 14786sent to the postprocessor. 14787 14788In the following command reference, the syntax element 14789@angles{line break} means a syntactical line break as defined above. 14790 14791@table @code 14792@item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14793Draw B-spline from current position to offset (@var{h1},@var{v1}), 14794then to offset (@var{h2},@var{v2}), if given, etc.@: up to 14795(@var{hn},@var{vn}). This command takes a variable number of argument 14796pairs; the current position is moved to the terminal point of the drawn 14797curve. 14798 14799@item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break} 14800Draw arc from current position to 14801(@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at 14802(@var{h1},@var{v1}); then move the current position to the final point 14803of the arc. 14804 14805@item DC @var{d}@angles{line break} 14806@itemx DC @var{d} @var{dummy-arg}@angles{line break} 14807Draw a solid circle using the current fill color with 14808diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost 14809point at the current position; then move the current position to the 14810rightmost point of the circle. An optional second integer argument is 14811ignored (this allows the formatter to generate an even number of 14812arguments). This command is a @code{gtroff} extension. 14813 14814@item Dc @var{d}@angles{line break} 14815Draw circle line with diameter@tie{}@var{d} (integer in basic units 14816@samp{u}) with leftmost point at the current position; then move the 14817current position to the rightmost point of the circle. 14818 14819@item DE @var{h} @var{v}@angles{line break} 14820Draw a solid ellipse in the current fill color with a horizontal 14821diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both 14822integers in basic units @samp{u}) with the leftmost point at the 14823current position; then move to the rightmost point of the ellipse. 14824This command is a @code{gtroff} extension. 14825 14826@item De @var{h} @var{v}@angles{line break} 14827Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h} 14828and a vertical diameter of@tie{}@var{v} (both integers in basic units 14829@samp{u}) with the leftmost point at current position; then move to 14830the rightmost point of the ellipse. 14831 14832@item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break} 14833Set fill color for solid drawing objects using different color 14834schemes; the analoguous command for setting the color of text, line 14835graphics, and the outline of graphic objects is @samp{m}. 14836The color components are specified as integer arguments between 0 and 1483765536. The number of color components and their meaning vary for the 14838different color schemes. These commands are generated by @code{gtroff}'s 14839escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other 14840corresponding graphics commands). No position changing. This command 14841is a @code{gtroff} extension. 14842 14843@table @code 14844@item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break} 14845Set fill color for solid drawing objects using the CMY color scheme, 14846having the 3@tie{}color components @var{cyan}, @var{magenta}, and 14847@var{yellow}. 14848 14849@item DFd@angles{line break} 14850Set fill color for solid drawing objects to the default fill color value 14851(black in most cases). No component arguments. 14852 14853@item DFg @var{gray}@angles{line break} 14854Set fill color for solid drawing objects to the shade of gray given by 14855the argument, an integer between 0 (black) and 65536 (white). 14856 14857@item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break} 14858Set fill color for solid drawing objects using the CMYK color scheme, 14859having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow}, 14860and @var{black}. 14861 14862@item DFr @var{red} @var{green} @var{blue}@angles{line break} 14863Set fill color for solid drawing objects using the RGB color scheme, 14864having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}. 14865@end table 14866 14867@item Df @var{n}@angles{line break} 14868The argument@tie{}@var{n} must be an integer in the range @math{-32767} 14869to 32767. 14870 14871@table @asis 14872@item @math{0 @LE{} @var{n} @LE{} 1000} 14873Set the color for filling solid drawing objects to a shade of gray, 14874where 0 corresponds to solid white, 1000 (the default) to solid black, 14875and values in between to intermediate shades of gray; this is 14876obsoleted by command @samp{DFg}. 14877 14878@item @math{@var{n} < 0} or @math{@var{n} > 1000} 14879Set the filling color to the color that is currently being used for 14880the text and the outline, see command @samp{m}. For example, the 14881command sequence 14882 14883@Example 14884mg 0 0 65536 14885Df -1 14886@endExample 14887 14888@noindent 14889sets all colors to blue. 14890@end table 14891 14892@noindent 14893No position changing. This command is a @code{gtroff} extension. 14894 14895@item Dl @var{h} @var{v}@angles{line break} 14896Draw line from current position to offset (@var{h},@var{v}) (integers 14897in basic units @samp{u}); then set current position to the end of the 14898drawn line. 14899 14900@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14901Draw a polygon line from current position to offset (@var{h1},@var{v1}), 14902from there to offset (@var{h2},@var{v2}), etc.@: up to offset 14903(@var{hn},@var{vn}), and from there back to the starting position. 14904For historical reasons, the position is changed by adding the sum of 14905all arguments with odd index to the actual horizontal position and the 14906even ones to the vertical position. Although this doesn't make sense 14907it is kept for compatibility. 14908@ignore 14909As the polygon is closed, the end of drawing is the starting point, so 14910the position doesn't change. 14911@end ignore 14912This command is a @code{gtroff} extension. 14913 14914@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14915Draw a solid polygon in the current fill color rather than an outlined 14916polygon, using the same arguments and positioning as the corresponding 14917@samp{Dp} command. 14918@ignore 14919No position changing. 14920@end ignore 14921This command is a @code{gtroff} extension. 14922 14923@item Dt @var{n}@angles{line break} 14924Set the current line thickness to@tie{}@var{n} (an integer in basic 14925units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the 14926smallest available line thickness; if @math{@var{n}<0} set the line 14927thickness proportional to the point size (this is the default before 14928the first @samp{Dt} command was specified). For historical reasons, 14929the horizontal position is changed by adding the argument to the actual 14930horizontal position, while the vertical position is not changed. 14931Although this doesn't make sense it is kept for compatibility. 14932@ignore 14933No position changing. 14934@end ignore 14935This command is a @code{gtroff} extension. 14936@end table 14937 14938@node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference 14939@subsubsection Device Control Commands 14940 14941Each device control command starts with the letter @samp{x}, 14942followed by a space character (optional or arbitrary space or tab in 14943@code{gtroff}) and a subcommand letter or word; each argument (if any) 14944must be preceded by a syntactical space. All @samp{x} commands are 14945terminated by a syntactical line break; no device control command can 14946be followed by another command on the same line (except a comment). 14947 14948The subcommand is basically a single letter, but to increase 14949readability, it can be written as a word, i.e., an arbitrary sequence 14950of characters terminated by the next tab, space, or newline character. 14951All characters of the subcommand word but the first are simply ignored. 14952For example, @code{gtroff} outputs the initialization command 14953@w{@samp{x i}} as @w{@samp{x init}} and the resolution command 14954@w{@samp{x r}} as @w{@samp{x res}}. 14955 14956In the following, the syntax element @angles{line break} means a 14957syntactical line break (@pxref{Separation}). 14958 14959@table @code 14960@item xF @var{name}@angles{line break} 14961The @samp{F} stands for @var{Filename}. 14962 14963Use @var{name} as the intended name for the current file in error 14964reports. This is useful for remembering the original file name when 14965@code{gtroff} uses an internal piping mechanism. The input file is 14966not changed by this command. This command is a @code{gtroff} extension. 14967 14968@item xf @var{n} @var{s}@angles{line break} 14969The @samp{f} stands for @var{font}. 14970 14971Mount font position@tie{}@var{n} (a non-negative integer) with font 14972named@tie{}@var{s} (a text word). @xref{Font Positions}. 14973 14974@item xH @var{n}@angles{line break} 14975The @samp{H} stands for @var{Height}. 14976 14977Set glyph height to@tie{}@var{n} (a positive integer in scaled 14978points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points 14979(@samp{p}) instead. @xref{Output Language Compatibility}. 14980 14981@item xi@angles{line break} 14982The @samp{i} stands for @var{init}. 14983 14984Initialize device. This is the third command of the prologue. 14985 14986@item xp@angles{line break} 14987The @samp{p} stands for @var{pause}. 14988 14989Parsed but ignored. The original @acronym{UNIX} troff manual writes 14990 14991@display 14992pause device, can be restarted 14993@end display 14994 14995@item xr @var{n} @var{h} @var{v}@angles{line break} 14996The @samp{r} stands for @var{resolution}. 14997 14998Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal 14999motion, and @var{v} the minimal vertical motion possible with this 15000device; all arguments are positive integers in basic units @samp{u} 15001per inch. This is the second command of the prologue. 15002 15003@item xS @var{n}@angles{line break} 15004The @samp{S} stands for @var{Slant}. 15005 15006Set slant to@tie{}@var{n} (an integer in basic units @samp{u}). 15007 15008@item xs@angles{line break} 15009The @samp{s} stands for @var{stop}. 15010 15011Terminates the processing of the current file; issued as the last 15012command of any intermediate troff output. 15013 15014@item xt@angles{line break} 15015The @samp{t} stands for @var{trailer}. 15016 15017Generate trailer information, if any. In @var{gtroff}, this is 15018actually just ignored. 15019 15020@item xT @var{xxx}@angles{line break} 15021The @samp{T} stands for @var{Typesetter}. 15022 15023Set name of device to word @var{xxx}, a sequence of characters ended 15024by the next white space character. The possible device names coincide 15025with those from the @code{groff} @option{-T} option. This is the first 15026command of the prologue. 15027 15028@item xu @var{n}@angles{line break} 15029The @samp{u} stands for @var{underline}. 15030 15031Configure underlining of spaces. If @var{n} is@tie{}1, start 15032underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces. 15033This is needed for the @code{cu} request in nroff mode and is ignored 15034otherwise. This command is a @code{gtroff} extension. 15035 15036@item xX @var{anything}@angles{line break} 15037The @samp{x} stands for @var{X-escape}. 15038 15039Send string @var{anything} uninterpreted to the device. If the line 15040following this command starts with a @samp{+} character this line is 15041interpreted as a continuation line in the following sense. The 15042@samp{+} is ignored, but a newline character is sent instead to the 15043device, the rest of the line is sent uninterpreted. The same applies 15044to all following lines until the first character of a line is not a 15045@samp{+} character. This command is generated by the @code{gtroff} 15046escape sequence @code{\X}. The line-continuing feature is a 15047@code{gtroff} extension. 15048@end table 15049 15050@node Obsolete Command, , Device Control Commands, Command Reference 15051@subsubsection Obsolete Command 15052In @acronym{AT&T} @code{troff} output, the writing of a single 15053glyph is mostly done by a very strange command that combines a 15054horizontal move and a single character giving the glyph name. It 15055doesn't have a command code, but is represented by a 3-character 15056argument consisting of exactly 2@tie{}digits and a character. 15057 15058@table @asis 15059@item @var{dd}@var{g} 15060Move right @var{dd} (exactly two decimal digits) basic units @samp{u}, 15061then print glyph@tie{}@var{g} (represented as a single character). 15062 15063In @code{gtroff}, arbitrary syntactical space around and within this 15064command is allowed to be added. Only when a preceding command on the 15065same line ends with an argument of variable length a separating space 15066is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these 15067and other commands are used, mostly without spaces; this made such output 15068almost unreadable. 15069@end table 15070 15071For modern high-resolution devices, this command does not make sense 15072because the width of the glyphs can become much larger than two 15073decimal digits. In @code{gtroff}, this is only used for the devices 15074@code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other 15075devices, the commands @samp{t} and @samp{u} provide a better 15076functionality. 15077 15078@c --------------------------------------------------------------------- 15079 15080@node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output 15081@subsection Intermediate Output Examples 15082 15083This section presents the intermediate output generated from the same 15084input for three different devices. The input is the sentence 15085@samp{hell world} fed into @code{gtroff} on the command line. 15086 15087@table @asis 15088@item High-resolution device @code{ps} 15089 15090This is the standard output of @code{gtroff} if no @option{-T} option 15091is given. 15092 15093@example 15094@group 15095shell> echo "hell world" | groff -Z -T ps 15096 15097x T ps 15098x res 72000 1 1 15099x init 15100@end group 15101p1 15102x font 5 TR 15103f5 15104s10000 15105V12000 15106H72000 15107thell 15108wh2500 15109tw 15110H96620 15111torld 15112n12000 0 15113@group 15114x trailer 15115V792000 15116x stop 15117@end group 15118@end example 15119 15120@noindent 15121This output can be fed into @code{grops} to get its representation as 15122a PostScript file. 15123 15124@item Low-resolution device @code{latin1} 15125 15126This is similar to the high-resolution device except that the 15127positioning is done at a minor scale. Some comments (lines starting 15128with @samp{#}) were added for clarification; they were not generated 15129by the formatter. 15130 15131@example 15132@group 15133shell> echo "hell world" | groff -Z -T latin1 15134 15135# prologue 15136x T latin1 15137x res 240 24 40 15138x init 15139@end group 15140# begin a new page 15141p1 15142# font setup 15143x font 1 R 15144f1 15145s10 15146# initial positioning on the page 15147V40 15148H0 15149# write text `hell' 15150thell 15151# inform about space, and issue a horizontal jump 15152wh24 15153# write text `world' 15154tworld 15155# announce line break, but do nothing because ... 15156n40 0 15157@group 15158# ... the end of the document has been reached 15159x trailer 15160V2640 15161x stop 15162@end group 15163@end example 15164 15165@noindent 15166This output can be fed into @code{grotty} to get a formatted text 15167document. 15168 15169@item @acronym{AT&T} @code{troff} output 15170Since a computer monitor has a very low resolution compared to modern 15171printers the intermediate output for the X@tie{}Window devices can use 15172the jump-and-write command with its 2-digit displacements. 15173 15174@example 15175@group 15176shell> echo "hell world" | groff -Z -T X100 15177 15178x T X100 15179x res 100 1 1 15180x init 15181@end group 15182p1 15183x font 5 TR 15184f5 15185s10 15186V16 15187H100 15188# write text with jump-and-write commands 15189ch07e07l03lw06w11o07r05l03dh7 15190n16 0 15191@group 15192x trailer 15193V1100 15194x stop 15195@end group 15196@end example 15197 15198@noindent 15199This output can be fed into @code{xditview} or @code{gxditview} 15200for displaying in@tie{}X. 15201 15202Due to the obsolete jump-and-write command, the text clusters in the 15203@acronym{AT&T} @code{troff} output are almost unreadable. 15204@end table 15205 15206@c --------------------------------------------------------------------- 15207 15208@node Output Language Compatibility, , Intermediate Output Examples, gtroff Output 15209@subsection Output Language Compatibility 15210 15211The intermediate output language of @acronym{AT&T} @code{troff} 15212was first documented in the @acronym{UNIX} troff manual, with later 15213additions documented in @cite{A Typesetter-indenpendent TROFF}, 15214written by Brian Kernighan. 15215 15216The @code{gtroff} intermediate output format is compatible with this 15217specification except for the following features. 15218 15219@itemize @bullet 15220@item 15221The classical quasi device independence is not yet implemented. 15222 15223@item 15224The old hardware was very different from what we use today. So the 15225@code{groff} devices are also fundamentally different from the ones in 15226@acronym{AT&T} @code{troff}. For example, the @acronym{AT&T} 15227PostScript device is called @code{post} and has a resolution of only 15228720 units per inch, suitable for printers 20 years ago, while 15229@code{groff}'s @code{ps} device has a resolution of 1523072000 units per inch. Maybe, by implementing some rescaling 15231mechanism similar to the classical quasi device independence, 15232@code{groff} could emulate @acronym{AT&T}'s @code{post} device. 15233 15234@item 15235The B-spline command @samp{D~} is correctly handled by the 15236intermediate output parser, but the drawing routines aren't 15237implemented in some of the postprocessor programs. 15238 15239@item 15240The argument of the commands @samp{s} and @w{@samp{x H}} has the 15241implicit unit scaled point @samp{z} in @code{gtroff}, while 15242@acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an 15243incompatibility but a compatible extension, for both units coincide 15244for all devices without a @code{sizescale} parameter in the @file{DESC} 15245file, including all postprocessors from @acronym{AT&T} and 15246@code{groff}'s text devices. The few @code{groff} devices with 15247a @code{sizescale} parameter either do not exist for @acronym{AT&T} 15248@code{troff}, have a different name, or seem to have a different 15249resolution. So conflicts are very unlikely. 15250 15251@item 15252The position changing after the commands @samp{Dp}, @samp{DP}, and 15253@samp{Dt} is illogical, but as old versions of @code{gtroff} used this 15254feature it is kept for compatibility reasons. 15255 15256@ignore 15257Temporarily, there existed some confusion on the positioning after the 15258@samp{D} commands that are groff extensions. This has been clarified 15259by establishing the classical rule for all @code{groff} drawing commands: 15260 15261@itemize 15262@item 15263The position after a graphic object has been drawn is at its end; 15264for circles and ellipses, the `end' is at the right side. 15265 15266@item 15267From this, the positionings specified for the drawing commands above 15268follow quite naturally. 15269@end itemize 15270@end ignore 15271 15272@end itemize 15273 15274 15275@c ===================================================================== 15276 15277@node Font Files, , gtroff Output, File formats 15278@section Font Files 15279@cindex font files 15280@cindex files, font 15281 15282The @code{gtroff} font format is roughly a superset of the 15283@code{ditroff} font format (as used in later versions of @acronym{AT&T} 15284@code{troff} and its descendants). Unlike the @code{ditroff} font 15285format, there is no associated binary format; all files are text 15286files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary 15287format.} The font files for device @var{name} are stored in a directory 15288@file{dev@var{name}}. There are two types of file: a device description 15289file called @file{DESC} and for each font@tie{}@var{f} a font file 15290called@tie{}@file{@var{f}}. 15291 15292@menu 15293* DESC File Format:: 15294* Font File Format:: 15295@end menu 15296 15297@c --------------------------------------------------------------------- 15298 15299@node DESC File Format, Font File Format, Font Files, Font Files 15300@subsection @file{DESC} File Format 15301@cindex @file{DESC} file, format 15302@cindex font description file, format 15303@cindex format of font description file 15304@pindex DESC@r{ file format} 15305 15306The @file{DESC} file can contain the following types of line. Except 15307for the @code{charset} keyword which must comes last (if at all), the 15308order of the lines is not important. 15309 15310@table @code 15311@item res @var{n} 15312@kindex res 15313@cindex device resolution 15314@cindex resolution, device 15315There are @var{n}@tie{}machine units per inch. 15316 15317@item hor @var{n} 15318@kindex hor 15319@cindex horizontal resolution 15320@cindex resolution, horizontal 15321The horizontal resolution is @var{n}@tie{}machine units. All horizontal 15322quantities are rounded to be multiples of this value. 15323 15324@item vert @var{n} 15325@kindex vert 15326@cindex vertical resolution 15327@cindex resolution, vertical 15328The vertical resolution is @var{n}@tie{}machine units. All vertical 15329quantities are rounded to be multiples of this value. 15330 15331@item sizescale @var{n} 15332@kindex sizescale 15333The scale factor for point sizes. By default this has a value of@tie{}1. 15334One scaled point is equal to one point/@var{n}. The arguments to the 15335@code{unitwidth} and @code{sizes} commands are given in scaled points. 15336@xref{Fractional Type Sizes}, for more information. 15337 15338@item unitwidth @var{n} 15339@kindex unitwidth 15340Quantities in the font files are given in machine units for fonts whose 15341point size is @var{n}@tie{}scaled points. 15342 15343@item prepro @var{program} 15344@kindex prepro 15345Call @var{program} as a preprocessor. Currently, this keyword is used 15346by @code{groff} with option @option{-Thtml} only. 15347 15348@item postpro @var{program} 15349@kindex postpro 15350Call @var{program} as a postprocessor. For example, the line 15351 15352@Example 15353postpro grodvi 15354@endExample 15355 15356@noindent 15357in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi} 15358if option @option{-Tdvi} is given (and @option{-Z} isn't used). 15359 15360@item tcommand 15361@kindex tcommand 15362This means that the postprocessor can handle the @samp{t} and @samp{u} 15363intermediate output commands. 15364 15365@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 15366@kindex sizes 15367This means that the device has fonts at @var{s1}, @var{s2}, @dots{} 15368@var{sn} scaled points. The list of sizes must be terminated by@tie{}0 15369(this is digit zero). Each @var{si} can also be a range of sizes 15370@var{m}-@var{n}. The list can extend over more than one line. 15371 15372@item styles @var{S1} @var{S2} @dots{} @var{Sm} 15373@kindex styles 15374The first @var{m}@tie{}font positions are associated with styles 15375@var{S1} @dots{} @var{Sm}. 15376 15377@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 15378@kindex fonts 15379Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 15380@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 15381styles. This command may extend over more than one line. A font name 15382of@tie{}0 means no font is mounted on the corresponding font position. 15383 15384@item family @var{fam} 15385@kindex family 15386The default font family is @var{fam}. 15387 15388@item use_charnames_in_special 15389@kindex use_charnames_in_special 15390This command indicates that @code{gtroff} should encode special 15391characters inside special commands. Currently, this is only used 15392by the @acronym{HTML} output device. @xref{Postprocessor Access}. 15393 15394@item papersize @var{string} @dots{} 15395@kindex papersize 15396Select a paper size. Valid values for @var{string} are the ISO paper 15397types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7}, 15398@code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter}, 15399@code{legal}, @code{tabloid}, @code{ledger}, @code{statement}, 15400@code{executive}, @code{com10}, and @code{monarch}. Case is not significant 15401for @var{string} if it holds predefined paper types. Alternatively, 15402@var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file 15403can be opened, @code{groff} reads the first line and tests for the above 15404paper sizes. Finally, @var{string} can be a custom paper size in the format 15405@code{@var{length},@var{width}} (no spaces before and after the comma). 15406Both @var{length} and @var{width} must have a unit appended; valid values 15407are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and 15408@samp{P} for picas. Example: @code{12c,235p}. An argument which starts 15409with a digit is always treated as a custom paper format. @code{papersize} 15410sets both the vertical and horizontal dimension of the output medium. 15411 15412More than one argument can be specified; @code{groff} scans from left to 15413right and uses the first valid paper specification. 15414 15415@item pass_filenames 15416@kindex pass_filenames 15417Tell @code{gtroff} to emit the name of the source file currently 15418being processed. This is achieved by the intermediate output command 15419@samp{F}. Currently, this is only used by the @acronym{HTML} output 15420device. 15421 15422@item print @var{program} 15423@kindex print 15424Use @var{program} as a spooler program for printing. If omitted, 15425the @option{-l} and @option{-L} options of @code{groff} are ignored. 15426 15427@item charset 15428@kindex charset 15429This line and everything following in the file are ignored. It is 15430allowed for the sake of backwards compatibility. 15431@end table 15432 15433The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines 15434are mandatory. Other commands are ignored by @code{gtroff} but may be 15435used by postprocessors to store arbitrary information about the device 15436in the @file{DESC} file. 15437 15438@kindex spare1 15439@kindex spare2 15440@kindex biggestfont 15441Here a list of obsolete keywords which are recognized by @code{groff} 15442but completely ignored: @code{spare1}, @code{spare2}, 15443@code{biggestfont}. 15444 15445@c --------------------------------------------------------------------- 15446 15447@node Font File Format, , DESC File Format, Font Files 15448@subsection Font File Format 15449@cindex font file, format 15450@cindex font description file, format 15451@cindex format of font files 15452@cindex format of font description files 15453 15454A @dfn{font file}, also (and probably better) called a @dfn{font 15455description file}, has two sections. The first section is a sequence 15456of lines each containing a sequence of blank delimited words; the first 15457word in the line is a key, and subsequent words give a value for that 15458key. 15459 15460@table @code 15461@item name @var{f} 15462@kindex name 15463The name of the font is@tie{}@var{f}. 15464 15465@item spacewidth @var{n} 15466@kindex spacewidth 15467The normal width of a space is@tie{}@var{n}. 15468 15469@item slant @var{n} 15470@kindex slant 15471The glyphs of the font have a slant of @var{n}@tie{}degrees. 15472(Positive means forward.) 15473 15474@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 15475@kindex ligatures 15476Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 15477possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 15478@samp{ffl}. For backwards compatibility, the list of ligatures may be 15479terminated with a@tie{}0. The list of ligatures may not extend over more 15480than one line. 15481 15482@item special 15483@cindex special fonts 15484@kindex special 15485The font is @dfn{special}; this means that when a glyph is requested 15486that is not present in the current font, it is searched for in any 15487special fonts that are mounted. 15488@end table 15489 15490Other commands are ignored by @code{gtroff} but may be used by 15491postprocessors to store arbitrary information about the font in the font 15492file. 15493 15494@cindex comments in font files 15495@cindex font files, comments 15496@kindex # 15497The first section can contain comments which start with the @samp{#} 15498character and extend to the end of a line. 15499 15500The second section contains one or two subsections. It must contain a 15501@code{charset} subsection and it may also contain a @code{kernpairs} 15502subsection. These subsections can appear in any order. Each 15503subsection starts with a word on a line by itself. 15504 15505@kindex charset 15506The word @code{charset} starts the character set 15507subsection.@footnote{This keyword is misnamed since it starts a list 15508of ordered glyphs, not characters.} The @code{charset} line is 15509followed by a sequence of lines. Each line gives information for one 15510glyph. A line comprises a number of fields separated by blanks or 15511tabs. The format is 15512 15513@quotation 15514@var{name} @var{metrics} @var{type} @var{code} 15515[@var{entity-name}] [@code{--} @var{comment}] 15516@end quotation 15517 15518@cindex 8-bit input 15519@cindex input, 8-bit 15520@cindex accessing unnamed glyphs with @code{\N} 15521@cindex unnamed glyphs, accessing with @code{\N} 15522@cindex characters, unnamed, accessing with @code{\N} 15523@cindex glyphs, unnamed, accessing with @code{\N} 15524@kindex --- 15525@noindent 15526@var{name} identifies the glyph name@footnote{The distinction between 15527input, characters, and output, glyphs, is not clearly separated in the 15528terminology of @code{groff}; for example, the @code{char} request 15529should be called @code{glyph} since it defines an output entity.}: 15530If @var{name} is a single character@tie{}@var{c} then it corresponds 15531to the @code{gtroff} input character@tie{}@var{c}; if it is of the form 15532@samp{\@var{c}} where @var{c} is a single character, then it 15533corresponds to the special character @code{\[@var{c}]}; otherwise it 15534corresponds to the special character @samp{\[@var{name}]}. If it 15535is exactly two characters @var{xx} it can be entered as 15536@samp{\(@var{xx}}. Note that single-letter special characters can't 15537be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which 15538is identical to @code{\[-]}. 15539 15540@code{gtroff} supports 8-bit input characters; however some utilities 15541have difficulties with eight-bit characters. For this reason, there is 15542a convention that the entity name @samp{char@var{n}} is equivalent to 15543the single input character whose code is@tie{}@var{n}. For example, 15544@samp{char163} would be equivalent to the character with code@tie{}163 15545which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set. 15546You shouldn't use @samp{char@var{n}} entities in font description files 15547since they are related to input, not output. Otherwise, you get 15548hard-coded connections between input and output encoding which 15549prevents use of different (input) character sets. 15550 15551The name @samp{---} is special and indicates that the glyph is 15552unnamed; such glyphs can only be used by means of the @code{\N} 15553escape sequence in @code{gtroff}. 15554 15555The @var{type} field gives the glyph type: 15556 15557@table @code 15558@item 1 15559the glyph has a descender, for example, @samp{p}; 15560 15561@item 2 15562the glyph has an ascender, for example, @samp{b}; 15563 15564@item 3 15565the glyph has both an ascender and a descender, for example, @samp{(}. 15566@end table 15567 15568The @var{code} field gives the code which the postprocessor uses to 15569print the glyph. The glyph can also be input to @code{gtroff} 15570using this code by means of the @code{\N} escape sequence. @var{code} 15571can be any integer. If it starts with @samp{0} it is interpreted as 15572octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 15573hexadecimal. Note, however, that the @code{\N} escape sequence only 15574accepts a decimal integer. 15575 15576The @var{entity-name} field gives an @acronym{ASCII} string 15577identifying the glyph which the postprocessor uses to print the 15578@code{gtroff} glyph @var{name}. This field is optional and has been 15579introduced so that the @acronym{HTML} device driver can encode its 15580character set. For example, the glyph @samp{\[Po]} is 15581represented as @samp{£} in @acronym{HTML} 4.0. 15582 15583Anything on the line after the @var{entity-name} field resp.@: after 15584@samp{--} will be ignored. 15585 15586The @var{metrics} field has the form: 15587 15588@display 15589@group 15590@var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction} 15591 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]] 15592@end group 15593@end display 15594 15595@noindent 15596There must not be any spaces between these subfields (it has been split 15597here into two lines for better legibility only). Missing subfields are 15598assumed to be@tie{}0. The subfields are all decimal integers. Since 15599there is no associated binary format, these values are not required to 15600fit into a variable of type @samp{char} as they are in @code{ditroff}. 15601The @var{width} subfield gives the width of the glyph. The @var{height} 15602subfield gives the height of the glyph (upwards is positive); if a 15603glyph does not extend above the baseline, it should be given a zero 15604height, rather than a negative height. The @var{depth} subfield gives 15605the depth of the glyph, that is, the distance from the baseline to the 15606lowest point below the baseline to which the glyph extends (downwards is 15607positive); if a glyph does not extend below the baseline, it should be 15608given a zero depth, rather than a negative depth. The 15609@var{italic-correction} subfield gives the amount of space that should 15610be added after the glyph when it is immediately to be followed by a 15611glyph from a roman font. The @var{left-italic-correction} subfield 15612gives the amount of space that should be added before the glyph when it 15613is immediately to be preceded by a glyph from a roman font. The 15614@var{subscript-correction} gives the amount of space that should be 15615added after a glyph before adding a subscript. This should be less 15616than the italic correction. 15617 15618A line in the @code{charset} section can also have the format 15619 15620@Example 15621@var{name} " 15622@endExample 15623 15624@noindent 15625This indicates that @var{name} is just another name for the glyph 15626mentioned in the preceding line. 15627 15628@kindex kernpairs 15629The word @code{kernpairs} starts the kernpairs section. This contains a 15630sequence of lines of the form: 15631 15632@Example 15633@var{c1} @var{c2} @var{n} 15634@endExample 15635 15636@noindent 15637This means that when glyph @var{c1} appears next to glyph @var{c2} 15638the space between them should be increased by@tie{}@var{n}. Most 15639entries in the kernpairs section have a negative value for@tie{}@var{n}. 15640 15641 15642 15643@c ===================================================================== 15644@c ===================================================================== 15645 15646@node Installation, Copying This Manual, File formats, Top 15647@chapter Installation 15648@cindex installation 15649 15650@c XXX 15651 15652 15653 15654@c ===================================================================== 15655@c ===================================================================== 15656 15657@node Copying This Manual, Request Index, Installation, Top 15658@appendix Copying This Manual 15659 15660@menu 15661* GNU Free Documentation License:: License for copying this manual. 15662@end menu 15663 15664@include fdl.texi 15665 15666 15667 15668@c ===================================================================== 15669@c ===================================================================== 15670 15671@node Request Index, Escape Index, Copying This Manual, Top 15672@appendix Request Index 15673 15674Requests appear without the leading control character (normally either 15675@samp{.} or @samp{'}). 15676 15677@printindex rq 15678 15679 15680 15681@c ===================================================================== 15682@c ===================================================================== 15683 15684@node Escape Index, Operator Index, Request Index, Top 15685@appendix Escape Index 15686 15687Any escape sequence @code{\@var{X}} with @var{X} not in the list below 15688emits a warning, printing glyph @var{X}. 15689 15690@printindex es 15691 15692 15693 15694@c ===================================================================== 15695@c ===================================================================== 15696 15697@node Operator Index, Register Index, Escape Index, Top 15698@appendix Operator Index 15699 15700@printindex op 15701 15702 15703 15704@c ===================================================================== 15705@c ===================================================================== 15706 15707@node Register Index, Macro Index, Operator Index, Top 15708@appendix Register Index 15709 15710The macro package or program a specific register belongs to is appended in 15711brackets. 15712 15713A register name@tie{}@code{x} consisting of exactly one character can be 15714accessed as @samp{\nx}. A register name @code{xx} consisting of exactly 15715two characters can be accessed as @samp{\n(xx}. Register names @code{xxx} 15716of any length can be accessed as @samp{\n[xxx]}. 15717 15718@printindex vr 15719 15720 15721 15722@c ===================================================================== 15723@c ===================================================================== 15724 15725@node Macro Index, String Index, Register Index, Top 15726@appendix Macro Index 15727 15728The macro package a specific macro belongs to is appended in brackets. 15729They appear without the leading control character (normally @samp{.}). 15730 15731@printindex ma 15732 15733 15734 15735@c ===================================================================== 15736@c ===================================================================== 15737 15738@node String Index, Glyph Name Index, Macro Index, Top 15739@appendix String Index 15740 15741The macro package or program a specific string belongs to is appended in 15742brackets. 15743 15744A string name@tie{}@code{x} consisting of exactly one character can be 15745accessed as @samp{\*x}. A string name @code{xx} consisting of exactly 15746two characters can be accessed as @samp{\*(xx}. String names @code{xxx} 15747of any length can be accessed as @samp{\*[xxx]}. 15748 15749 15750@printindex st 15751 15752 15753 15754@c ===================================================================== 15755@c ===================================================================== 15756 15757@node Glyph Name Index, Font File Keyword Index, String Index, Top 15758@appendix Glyph Name Index 15759 15760A glyph name @code{xx} consisting of exactly two characters can be 15761accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 15762accessed as @samp{\[xxx]}. 15763 15764@c XXX 15765 15766 15767 15768@c ===================================================================== 15769@c ===================================================================== 15770 15771@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 15772@appendix Font File Keyword Index 15773 15774@printindex ky 15775 15776 15777 15778@c ===================================================================== 15779@c ===================================================================== 15780 15781@node Program and File Index, Concept Index, Font File Keyword Index, Top 15782@appendix Program and File Index 15783 15784@printindex pg 15785 15786 15787 15788@c ===================================================================== 15789@c ===================================================================== 15790 15791@node Concept Index, , Program and File Index, Top 15792@appendix Concept Index 15793 15794@printindex cp 15795 15796 15797@bye 15798