groff.texinfo revision 104862
1\input texinfo @c -*-texinfo-*- 2 3@c 4@c Please convert this manual with `texi2dvi -e groff.texinfo' due to a bug 5@c in texinfo regarding expansion of user-defined macros. 6@c 7@c You need texinfo 4.2 or newer to format this document! 8@c 9 10@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 18@smallbook 19 20@finalout 21 22 23@copying 24This manual documents GNU @code{troff} version 1.18. 25 26Copyright @copyright{} 1994-2000, 2001, 2002 Free Software Foundation, Inc. 27 28@quotation 29Permission is granted to copy, distribute and/or modify this document 30under the terms of the GNU Free Documentation License, Version 1.1 or 31any later version published by the Free Software Foundation; with no 32Invariant Sections, with the Front-Cover texts being `A GNU Manual,'' 33and with the Back-Cover Texts as in (a) below. A copy of the 34license is included in the section entitled `GNU Free Documentation 35License.'' 36 37(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify 38this GNU Manual, like GNU software. Copies published by the Free 39Software Foundation raise funds for GNU development.'' 40@end quotation 41@end copying 42 43 44@c We use the following indices: 45@c 46@c cindex: concepts 47@c rqindex: requests 48@c esindex: escapes 49@c vindex: registers 50@c kindex: commands in font files 51@c pindex: programs and files 52@c tindex: environment variables 53@c maindex: macros 54@c stindex: strings 55@c opindex: operators 56@c 57@c tindex and cindex are merged. 58 59@defcodeindex rq 60@defcodeindex es 61@defcodeindex ma 62@defcodeindex st 63@defcodeindex op 64@syncodeindex tp cp 65 66 67@c to avoid uppercasing in @deffn while converting to info, we define 68@c our special @Var{} 69@c 70@c due to a (not officially documented) `feature' in makeinfo 4.0, 71@c macros are not expanded in @deffn (but the macro definition is 72@c properly removed), so we have to define @Var{} directly in TeX also 73 74@macro Var{arg} 75\arg\ 76@end macro 77@tex 78\gdef\Var#1{\var{#1}} 79@end tex 80 81 82@c To assure correct HTML translation, some ugly hacks are necessary. 83@c While processing a @def... request, the HTML translator looks at the 84@c next line to decide whether it should start indentation or not. If 85@c it is something starting with @def... (e.g. @deffnx), it doesn't. 86@c So we must assure during macro expansion that a @def... is seen. 87@c 88@c The following macros have to be used: 89@c 90@c One item: 91@c 92@c @Def... 93@c 94@c Two items: 95@c 96@c @Def...List 97@c @Def...ListEnd 98@c 99@c More than two: 100@c 101@c @Def...List 102@c @Def...Item 103@c @Def...Item 104@c ... 105@c @Def...ListEnd 106@c 107@c The definition block must end with 108@c 109@c @endDef... 110@c 111@c The above is valid for texinfo 4.0f. 112 113 114@c a dummy macro to assure the `@def...' 115 116@macro defdummy 117@end macro 118 119 120@c definition of requests 121 122@macro Defreq{name, arg} 123@deffn Request @t{.\name\} \arg\ 124@rqindex \name\ 125@end macro 126 127@macro DefreqList{name, arg} 128@deffn Request @t{.\name\} \arg\ 129@defdummy 130@rqindex \name\ 131@end macro 132 133@macro DefreqItem{name, arg} 134@deffnx Request @t{.\name\} \arg\ 135@defdummy 136@rqindex \name\ 137@end macro 138 139@macro DefreqListEnd{name, arg} 140@deffnx Request @t{.\name\} \arg\ 141@rqindex \name\ 142@end macro 143 144@macro endDefreq 145@end deffn 146@end macro 147 148 149@c definition of escapes 150 151@macro Defesc{name, delimI, arg, delimII} 152@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 153@esindex \name\ 154@end macro 155 156@macro DefescList{name, delimI, arg, delimII} 157@deffn Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 158@defdummy 159@esindex \name\ 160@end macro 161 162@macro DefescItem{name, delimI, arg, delimII} 163@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 164@defdummy 165@esindex \name\ 166@end macro 167 168@macro DefescListEnd{name, delimI, arg, delimII} 169@deffnx Escape @t{\name\\delimI\}@var{\arg\}@t{\delimII\} 170@esindex \name\ 171@end macro 172 173@macro endDefesc 174@end deffn 175@end macro 176 177 178@c definition of registers 179 180@macro Defreg{name} 181@deffn Register @t{\\n[\name\]} 182@vindex \name\ 183@end macro 184 185@macro DefregList{name} 186@deffn Register @t{\\n[\name\]} 187@defdummy 188@vindex \name\ 189@end macro 190 191@macro DefregItem{name} 192@deffnx Register @t{\\n[\name\]} 193@defdummy 194@vindex \name\ 195@end macro 196 197@macro DefregListEnd{name} 198@deffnx Register @t{\\n[\name\]} 199@vindex \name\ 200@end macro 201 202@macro endDefreg 203@end deffn 204@end macro 205 206 207@c definition of registers specific to macro packages, preprocessors, etc. 208 209@macro Defmpreg{name, package} 210@deffn Register @t{\\n[\name\]} 211@vindex \name\ @r{[}\package\@r{]} 212@end macro 213 214@macro DefmpregList{name, package} 215@deffn Register @t{\\n[\name\]} 216@defdummy 217@vindex \name\ @r{[}\package\@r{]} 218@end macro 219 220@macro DefmpregItem{name, package} 221@deffnx Register @t{\\n[\name\]} 222@defdummy 223@vindex \name\ @r{[}\package\@r{]} 224@end macro 225 226@macro DefmpregListEnd{name, package} 227@deffnx Register @t{\\n[\name\]} 228@vindex \name\ @r{[}\package\@r{]} 229@end macro 230 231@macro endDefmpreg 232@end deffn 233@end macro 234 235 236@c definition of macros 237 238@macro Defmac{name, arg, package} 239@defmac @t{.\name\} \arg\ 240@maindex \name\ @r{[}\package\@r{]} 241@end macro 242 243@macro DefmacList{name, arg, package} 244@defmac @t{.\name\} \arg\ 245@defdummy 246@maindex \name\ @r{[}\package\@r{]} 247@end macro 248 249@macro DefmacItem{name, arg, package} 250@defmacx @t{.\name\} \arg\ 251@defdummy 252@maindex \name\ @r{[}\package\@r{]} 253@end macro 254 255@macro DefmacListEnd{name, arg, package} 256@defmacx @t{.\name\} \arg\ 257@maindex \name\ @r{[}\package\@r{]} 258@end macro 259 260@macro endDefmac 261@end defmac 262@end macro 263 264 265@c definition of strings 266 267@macro Defstr{name, package} 268@deffn String @t{\\*[\name\]} 269@stindex \name\ @r{[}\package\@r{]} 270@end macro 271 272@macro DefstrList{name, package} 273@deffn String @t{\\*[\name\]} 274@defdummy 275@stindex \name\ @r{[}\package\@r{]} 276@end macro 277 278@macro DefstrItem{name, package} 279@deffnx String @t{\\*[\name\]} 280@defdummy 281@stindex \name\ @r{[}\package\@r{]} 282@end macro 283 284@macro DefstrListEnd{name, package} 285@deffnx String @t{\\*[\name\]} 286@stindex \name\ @r{[}\package\@r{]} 287@end macro 288 289@macro endDefstr 290@end deffn 291@end macro 292 293 294@c our example macro 295 296@macro Example 297@example 298@group 299@end macro 300 301@macro endExample 302@end group 303@end example 304@end macro 305 306 307@c <text> 308 309@tex 310\gdef\angles#1{\angleleft{}\r{#1}\angleright{}} 311@end tex 312 313@macro angles{text} 314<\text\> 315@end macro 316 317 318@c a <= sign 319 320@tex 321\gdef\LE{\le} 322@end tex 323 324@macro LE 325<= 326@end macro 327 328 329@c due to a bug in texinfo 4.2, the spacing of `<' is bad in @item 330 331@tex 332\gdef\LT{\string<} 333@end tex 334 335@macro LT 336< 337@end macro 338 339 340@c We need special parentheses and brackets: 341@c 342@c . Real parentheses in @deffn produce an error while compiling with 343@c TeX 344@c . Real brackets use the wrong font in @deffn, overriding @t{}. 345@c 346@c Since macros aren't expanded in @deffn during -E, the following 347@c definitions are for non-TeX only. 348@c 349@c This is true for texinfo 4.0. 350 351@macro lparen 352( 353@end macro 354@macro rparen 355) 356@end macro 357@macro lbrack 358[ 359@end macro 360@macro rbrack 361] 362@end macro 363 364 365@tex 366\gdef\gobblefirst#1#2{#2} 367\gdef\putwordAppendix{\gobblefirst} 368@end tex 369 370 371@c Note: We say `Roman numerals' but `roman font'. 372 373 374@dircategory Miscellaneous 375@direntry 376* Groff: (groff). The GNU troff document formatting system. 377@end direntry 378 379 380@titlepage 381@title groff 382@subtitle The GNU implementation of @code{troff} 383@subtitle Edition 1.18 384@subtitle Spring 2002 385@author by Trent A.@w{ }Fisher 386@author and Werner Lemberg (@email{bug-groff@@gnu.org}) 387 388@page 389@vskip 0pt plus 1filll 390@insertcopying 391@end titlepage 392 393 394@contents 395 396@ifinfo 397@node Top, Introduction, (dir), (dir) 398@top GNU troff 399 400@insertcopying 401@end ifinfo 402 403@ifhtml 404@node Top, Introduction, (dir), (dir) 405@top GNU troff 406 407@insertcopying 408@end ifhtml 409 410@menu 411* Introduction:: 412* Invoking groff:: 413* Tutorial for Macro Users:: 414* Macro Packages:: 415* gtroff Reference:: 416* Preprocessors:: 417* Output Devices:: 418* File formats:: 419* Installation:: 420* Copying This Manual:: 421* Request Index:: 422* Escape Index:: 423* Operator Index:: 424* Register Index:: 425* Macro Index:: 426* String Index:: 427* Glyph Name Index:: 428* Font File Keyword Index:: 429* Program and File Index:: 430* Concept Index:: 431@end menu 432 433 434 435@c ===================================================================== 436@c ===================================================================== 437 438@node Introduction, Invoking groff, Top, Top 439@chapter Introduction 440@cindex introduction 441 442GNU @code{troff} (or @code{groff}) is a system for typesetting 443documents. @code{troff} is very flexible and has been in existence (and 444use) for about 3@w{ }decades. It is quite widespread and firmly 445entrenched in the @acronym{UNIX} community. 446 447@menu 448* What Is groff?:: 449* History:: 450* groff Capabilities:: 451* Macro Package Intro:: 452* Preprocessor Intro:: 453* Output device intro:: 454* Credits:: 455@end menu 456 457 458@c ===================================================================== 459 460@node What Is groff?, History, Introduction, Introduction 461@section What Is @code{groff}? 462@cindex what is @code{groff}? 463@cindex @code{groff} -- what is it? 464 465@code{groff} belongs to an older generation of document preparation 466systems, which operate more like compilers than the more recent 467interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 468systems. @code{groff} and its contemporary counterpart, @TeX{}, both 469work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 470normal text files with embedded formatting commands. These files can 471then be processed by @code{groff} to produce a typeset document on a 472variety of devices. 473 474Likewise, @code{groff} should not be confused with a @dfn{word 475processor}, since that term connotes an integrated system that includes 476an editor and a text formatter. Also, many word processors follow the 477@acronym{WYSIWYG} paradigm discussed earlier. 478 479Although @acronym{WYSIWYG} systems may be easier to use, they have a 480number of disadvantages compared to @code{troff}: 481 482@itemize @bullet 483@item 484They must be used on a graphics display to work on a document. 485 486@item 487Most of the @acronym{WYSIWYG} systems are either non-free or are not 488very portable. 489 490@item 491@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 492 493@item 494It is difficult to have a wide range of capabilities available within 495the confines of a GUI/window system. 496 497@item 498It is more difficult to make global changes to a document. 499@end itemize 500 501@quotation 502``GUIs normally make it simple to accomplish simple actions and 503impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 504@code{comp.unix.wizards}) 505@end quotation 506 507 508@c ===================================================================== 509 510@node History, groff Capabilities, What Is groff?, Introduction 511@section History 512@cindex history 513 514@cindex @code{runoff}, the program 515@cindex @code{rf}, the program 516@code{troff} can trace its origins back to a formatting program called 517@code{runoff}, written by J.@w{ }E.@w{ }Saltzer, which ran on MIT's CTSS 518operating system in the mid-sixties. This name came from the common 519phrase of the time ``I'll run off a document.'' Bob Morris ported it to 520the 635 architecture and called the program @code{roff} (an abbreviation 521of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 522(before having @acronym{UNIX}), and at the same time (1969), Doug 523McIllroy rewrote an extended and simplified version of @code{roff} in 524the @acronym{BCPL} programming language. 525 526@cindex @code{roff}, the program 527The first version of @acronym{UNIX} was developed on a @w{PDP-7} which 528was sitting around Bell Labs. In 1971 the developers wanted to get a 529@w{PDP-11} for further work on the operating system. In order to 530justify the cost for this system, they proposed that they would 531implement a document formatting system for the @acronym{AT&T} patents 532division. This first formatting program was a reimplementation of 533McIllroy's @code{roff}, written by J.@w{ }F.@w{ }Ossanna. 534 535@cindex @code{nroff}, the program 536When they needed a more flexible language, a new version of @code{roff} 537called @code{nroff} (``Newer @code{roff}'') was written. It had a much 538more complicated syntax, but provided the basis for all future versions. 539When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 540version of @code{nroff} that would drive it. It was dubbed 541@code{troff}, for ``typesetter @code{roff}'', although many people have 542speculated that it actually means ``Times @code{roff}'' because of the 543use of the Times font family in @code{troff} by default. As such, the 544name @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 545 546With @code{troff} came @code{nroff} (they were actually the same program 547except for some @samp{#ifdef}s), which was for producing output for line 548printers and character terminals. It understood everything @code{troff} 549did, and ignored the commands which were not applicable (e.g.@: font 550changes). 551 552Since there are several things which cannot be done easily in 553@code{troff}, work on several preprocessors began. These programs would 554transform certain parts of a document into @code{troff}, which made a 555very natural use of pipes in @acronym{UNIX}. 556 557The @code{eqn} preprocessor allowed mathematical formul@ae{} to be 558specified in a much simpler and more intuitive manner. @code{tbl} is a 559preprocessor for formatting tables. The @code{refer} preprocessor (and 560the similar program, @code{bib}) processes citations in a document 561according to a bibliographic database. 562 563Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 564language and produced output specifically for the CAT phototypesetter. 565He rewrote it in C, although it was now 7000@w{ }lines of uncommented 566code and still dependent on the CAT. As the CAT became less common, and 567was no longer supported by the manufacturer, the need to make it support 568other devices became a priority. However, before this could be done, 569Ossanna was killed in a car accident. 570 571@pindex ditroff 572@cindex @code{ditroff}, the program 573So, Brian Kernighan took on the task of rewriting @code{troff}. The 574newly rewritten version produced device independent code which was 575very easy for postprocessors to read and translate to the appropriate 576printer codes. Also, this new version of @code{troff} (called 577@code{ditroff} for ``device independent @code{troff}'') had several 578extensions, which included drawing functions. 579 580Due to the additional abilities of the new version of @code{troff}, 581several new preprocessors appeared. The @code{pic} preprocessor 582provides a wide range of drawing functions. Likewise the @code{ideal} 583preprocessor did the same, although via a much different paradigm. The 584@code{grap} preprocessor took specifications for graphs, but, unlike 585other preprocessors, produced @code{pic} code. 586 587James Clark began work on a GNU implementation of @code{ditroff} in 588early@w{ }1989. The first version, @code{groff}@w{ }0.3.1, was released 589June@w{ }1990. @code{groff} included: 590 591@itemize @bullet 592@item 593A replacement for @code{ditroff} with many extensions. 594 595@item 596The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 597 598@item 599Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 600X@w{ }Windows. GNU @code{troff} also eliminated the need for a 601separate @code{nroff} program with a postprocessor which would produce 602@acronym{ASCII} output. 603 604@item 605A version of the @file{me} macros and an implementation of the 606@file{man} macros. 607@end itemize 608 609Also, a front-end was included which could construct the, sometimes 610painfully long, pipelines required for all the post- and preprocessors. 611 612Development of GNU @code{troff} progressed rapidly, and saw the 613additions of a replacement for @code{refer}, an implementation of the 614@file{ms} and @file{mm} macros, and a program to deduce how to format a 615document (@code{grog}). 616 617It was declared a stable (i.e.@: non-beta) package with the release of 618version@w{ }1.04 around November@w{ }1991. 619 620Beginning in@w{ }1999, @code{groff} has new maintainers (the package was 621an orphan for a few years). As a result, new features and programs like 622@code{grn}, a preprocessor for gremlin images, and an output device to 623produce @acronym{HTML} output have been added. 624 625 626@c ===================================================================== 627 628@node groff Capabilities, Macro Package Intro, History, Introduction 629@section @code{groff} Capabilities 630@cindex @code{groff} capabilities 631@cindex capabilities of @code{groff} 632 633So what exactly is @code{groff} capable of doing? @code{groff} provides 634a wide range of low-level text formatting operations. Using these, it 635is possible to perform a wide range of formatting tasks, such as 636footnotes, table of contents, multiple columns, etc. Here's a list of 637the most important operations supported by @code{groff}: 638 639@itemize @bullet 640@item 641text filling, adjusting, and centering 642 643@item 644hyphenation 645 646@item 647page control 648 649@item 650font and glyph size control 651 652@item 653vertical spacing (e.g.@: double-spacing) 654 655@item 656line length and indenting 657 658@item 659macros, strings, diversions, and traps 660 661@item 662number registers 663 664@item 665tabs, leaders, and fields 666 667@item 668input and output conventions and character translation 669 670@item 671overstrike, bracket, line drawing, and zero-width functions 672 673@item 674local horizontal and vertical motions and the width function 675 676@item 677three-part titles 678 679@item 680output line numbering 681 682@item 683conditional acceptance of input 684 685@item 686environment switching 687 688@item 689insertions from the standard input 690 691@item 692input/output file switching 693 694@item 695output and error messages 696@end itemize 697 698 699@c ===================================================================== 700 701@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 702@section Macro Packages 703@cindex macro packages 704 705Since @code{groff} provides such low-level facilities, it can be quite 706difficult to use by itself. However, @code{groff} provides a 707@dfn{macro} facility to specify how certain routine operations (e.g.@w{ 708}starting paragraphs, printing headers and footers, etc.)@: should be 709done. These macros can be collected together into a @dfn{macro 710package}. There are a number of macro packages available; the most 711common (and the ones described in this manual) are @file{man}, 712@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 713 714 715@c ===================================================================== 716 717@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 718@section Preprocessors 719@cindex preprocessors 720 721Although @code{groff} provides most functions needed to format a 722document, some operations would be unwieldy (e.g.@: to draw pictures). 723Therefore, programs called @dfn{preprocessors} were written which 724understand their own language and produce the necessary @code{groff} 725operations. These preprocessors are able to differentiate their own 726input from the rest of the document via markers. 727 728To use a preprocessor, @acronym{UNIX} pipes are used to feed the output 729from the preprocessor into @code{groff}. Any number of preprocessors 730may be used on a given document; in this case, the preprocessors are 731linked together into one pipeline. However, with @code{groff}, the user 732does not need to construct the pipe, but only tell @code{groff} what 733preprocessors to use. 734 735@code{groff} currently has preprocessors for producing tables 736(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 737(@code{pic} and @code{grn}), and for processing bibliographies 738(@code{refer}). An associated program which is useful when dealing with 739preprocessors is @code{soelim}. 740 741A free implementation of @code{grap}, a preprocessor for drawing graphs, 742can be obtained as an extra package; @code{groff} can use @code{grap} 743also. 744 745There are other preprocessors in existence, but, unfortunately, no free 746implementations are available. Among them are preprocessors for drawing 747mathematical pictures (@code{ideal}) and chemical structures 748(@code{chem}). 749 750 751@c ===================================================================== 752 753@node Output device intro, Credits, Preprocessor Intro, Introduction 754@section Output Devices 755@cindex postprocessors 756@cindex output devices 757@cindex devices for output 758 759@code{groff} actually produces device independent code which may be 760fed into a postprocessor to produce output for a particular device. 761Currently, @code{groff} has postprocessors for @sc{PostScript} 762devices, character terminals, X@w{ }Windows (for previewing), @TeX{} 763DVI format, HP LaserJet@w{ }4 and Canon LBP printers (which use 764@acronym{CAPSL}), and @acronym{HTML}. 765 766 767@c ===================================================================== 768 769@node Credits, , Output device intro, Introduction 770@section Credits 771@cindex credits 772 773Large portions of this manual were taken from existing documents, most 774notably, the manual pages for the @code{groff} package by James Clark, 775and Eric Allman's papers on the @file{me} macro package. 776 777The section on the @file{man} macro package is partly based on Susan@w{ 778}G.@: Kleinmann's @file{groff_man} manual page written for the Debian 779GNU/Linux system. 780 781Larry Kollar contributed the section in the @file{ms} macro package. 782 783 784 785@c ===================================================================== 786@c ===================================================================== 787 788@node Invoking groff, Tutorial for Macro Users, Introduction, Top 789@chapter Invoking @code{groff} 790@cindex invoking @code{groff} 791@cindex @code{groff} invocation 792 793This section focuses on how to invoke the @code{groff} front end. This 794front end takes care of the details of constructing the pipeline among 795the preprocessors, @code{gtroff} and the postprocessor. 796 797It has become a tradition that GNU programs get the prefix @samp{g} to 798distinguish it from its original counterparts provided by the host (see 799@ref{Environment}, for more details). Thus, for example, @code{geqn} is 800GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which 801don't contain proprietary versions of @code{troff}, and on 802MS-DOS/MS-Windows, where @code{troff} and associated programs are not 803available at all, this prefix is omitted since GNU @code{troff} is the 804only used incarnation of @code{troff}. Exception: @samp{groff} is never 805replaced by @samp{roff}. 806 807In this document, we consequently say @samp{gtroff} when talking about 808the GNU @code{troff} program. All other implementations of @code{troff} 809are called @acronym{AT&T} @code{troff} which is the common origin of 810all @code{troff} derivates (with more or less compatible changes). 811Similarly, we say @samp{gpic}, @samp{geqn}, etc. 812 813@menu 814* Groff Options:: 815* Environment:: 816* Macro Directories:: 817* Font Directories:: 818* Invocation Examples:: 819@end menu 820 821 822@c ===================================================================== 823 824@node Groff Options, Environment, Invoking groff, Invoking groff 825@section Options 826@cindex options 827 828@pindex groff 829@pindex gtroff 830@pindex gpic 831@pindex geqn 832@pindex ggrn 833@pindex grap 834@pindex gtbl 835@pindex grefer 836@pindex gsoelim 837@code{groff} normally runs the @code{gtroff} program and a postprocessor 838appropriate for the selected device. The default device is @samp{ps} 839(but it can be changed when @code{groff} is configured and built). It 840can optionally preprocess with any of @code{gpic}, @code{geqn}, 841@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 842 843This section only documents options to the @code{groff} front end. Many 844of the arguments to @code{groff} are passed on to @code{gtroff}, 845therefore those are also included. Arguments to pre- or postprocessors 846can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 847gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 848gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 849grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 850grolbp}, and @ref{Invoking gxditview}. 851 852The command line format for @code{groff} is: 853 854@Example 855groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 856 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 857 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 858 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 859 [ @var{files}@dots{} ] 860@endExample 861 862The command line format for @code{gtroff} is as follows. 863 864@Example 865gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 866 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 867 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 868 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 869@endExample 870 871@noindent 872Obviously, many of the options to @code{groff} are actually passed on to 873@code{gtroff}. 874 875Options without an argument can be grouped behind a single@w{ }@option{-}. 876A filename of@w{ }@file{-} denotes the standard input. It is possible to 877have whitespace between an option and its parameter. 878 879The @code{grog} command can be used to guess the correct @code{groff} 880command to format a file. 881 882Here's the description of the command-line options: 883 884@cindex command-line options 885@table @samp 886@item -h 887Print a help message. 888 889@item -e 890Preprocess with @code{geqn}. 891 892@item -t 893Preprocess with @code{gtbl}. 894 895@item -g 896Preprocess with @code{ggrn}. 897 898@item -G 899Preprocess with @code{grap}. 900 901@item -p 902Preprocess with @code{gpic}. 903 904@item -s 905Preprocess with @code{gsoelim}. 906 907@item -c 908Suppress color output. 909 910@item -R 911Preprocess with @code{grefer}. No mechanism is provided for passing 912arguments to @code{grefer} because most @code{grefer} options have 913equivalent commands which can be included in the file. @xref{grefer}, 914for more details. 915 916@pindex troffrc 917@pindex troffrc-end 918Note that @code{gtroff} also accepts a @option{-R} option, which is not 919accessible via @code{groff}. This option prevents the loading of the 920@file{troffrc} and @file{troffrc-end} files. 921 922@item -v 923Make programs run by @code{groff} print out their version number. 924 925@item -V 926Print the pipeline on @code{stdout} instead of executing it. 927 928@item -z 929Suppress output from @code{gtroff}. Only error messages are printed. 930 931@item -Z 932Do not postprocess the output of @code{gtroff}. Normally @code{groff} 933automatically runs the appropriate postprocessor. 934 935@item -P@var{arg} 936Pass @var{arg} to the postprocessor. Each argument should be passed 937with a separate @option{-P} option. Note that @code{groff} does not 938prepend @samp{-} to @var{arg} before passing it to the postprocessor. 939 940@item -l 941Send the output to a spooler for printing. The command used for this is 942specified by the @code{print} command in the device description file 943(see @ref{Font Files}, for more info). If not present, @option{-l} is 944ignored. 945 946@item -L@var{arg} 947Pass @var{arg} to the spooler. Each argument should be passed with a 948separate @option{-L} option. Note that @code{groff} does not prepend 949a @samp{-} to @var{arg} before passing it to the postprocessor. 950If the @code{print} keyword in the device description file is missing, 951@option{-L} is ignored. 952 953@item -T@var{dev} 954Prepare output for device @var{dev}. The default device is @samp{ps}, 955unless changed when @code{groff} was configured and built. The 956following are the output devices currently available: 957 958@table @code 959@item ps 960For @sc{PostScript} printers and previewers. 961 962@item dvi 963For @TeX{} DVI format. 964 965@item X75 966For a 75@dmn{dpi} X11 previewer. 967 968@item X75-12 969For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 970document. 971 972@item X100 973For a 100@dmn{dpi} X11 previewer. 974 975@item X100-12 976For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 977document. 978 979@item ascii 980@cindex encoding, @acronym{ASCII} 981@cindex @acronym{ASCII}, encoding 982For typewriter-like devices using the (7-bit) @acronym{ASCII} 983character set. 984 985@item latin1 986@cindex encoding, latin-1 987@cindex latin-1, encoding 988For typewriter-like devices that support the @w{Latin-1} (@w{ISO 9898859-1}) character set. 990 991@item utf8 992@cindex encoding, utf-8 993@cindex utf-8, encoding 994For typewriter-like devices which use the Unicode (@w{ISO 10646}) 995character set with @w{UTF-8} encoding. 996 997@item cp1047 998@cindex @acronym{EBCDIC} encoding 999@cindex encoding, @acronym{EBCDIC} 1000@cindex encoding, cp1047 1001@cindex cp1047 1002@cindex IBM cp1047 1003For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 1004cp1047. 1005 1006@item lj4 1007For HP LaserJet4-compatible (or other PCL5-compatible) printers. 1008 1009@item lbp 1010For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 1011printers). 1012 1013@pindex pre-grohtml 1014@pindex post-grohtml 1015@cindex @code{grohtml}, the program 1016@item html 1017To produce @acronym{HTML} output. Note that the @acronym{HTML} driver 1018consists of two parts, a preprocessor (@code{pre-grohtml}) and a 1019postprocessor (@code{post-grohtml}). 1020@end table 1021 1022@cindex output device name string register (@code{.T}) 1023@cindex output device usage number register (@code{.T}) 1024The predefined @code{gtroff} string register @code{.T} contains the 1025current output device; the read-only number register @code{.T} is set 1026to@w{ }1 if this option is used (which is always true if @code{groff} is 1027used to call @code{gtroff}). @xref{Built-in Registers}. 1028 1029The postprocessor to be used for a device is specified by the 1030@code{postpro} command in the device description file. (@xref{Font 1031Files}, for more info.) This can be overridden with the @option{-X} 1032option. 1033 1034@item -X 1035Preview with @code{gxditview} instead of using the usual postprocessor. 1036This is unlikely to produce good results except with @option{-Tps}. 1037 1038Note that this is not the same as using @option{-TX75} or 1039@option{-TX100} to view a document with @code{gxditview}: The former 1040uses the metrics of the specified device, whereas the latter uses 1041X-specific fonts and metrics. 1042 1043@item -N 1044Don't allow newlines with @code{eqn} delimiters. This is the same as 1045the @option{-N} option in @code{geqn}. 1046 1047@item -S 1048@cindex @code{open} request, and safer mode 1049@cindex @code{opena} request, and safer mode 1050@cindex @code{pso} request, and safer mode 1051@cindex @code{sy} request, and safer mode 1052@cindex @code{pi} request, and safer mode 1053@cindex safer mode 1054@cindex mode, safer 1055Safer mode. Pass the @option{-S} option to @code{gpic} and disable the 1056@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 1057requests. For security reasons, this is enabled by default. 1058 1059@item -U 1060@cindex mode, unsafe 1061@cindex unsafe mode 1062Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso}, 1063@code{sy}, and @code{pi} requests. 1064 1065@item -a 1066@cindex @acronym{ASCII} approximation output register (@code{.A}) 1067Generate an @acronym{ASCII} approximation of the typeset output. The 1068read-only register @code{.A} is then set to@w{ }1. @xref{Built-in 1069Registers}. A typical example is 1070 1071@Example 1072groff -a -man -Tdvi troff.man | less 1073@endExample 1074 1075@noindent 1076which shows how lines are broken for the DVI device. Note that this 1077option is rather useless today since graphic output devices are 1078available virtually everywhere. 1079 1080@item -b 1081Print a backtrace with each warning or error message. This backtrace 1082should help track down the cause of the error. The line numbers given 1083in the backtrace may not always be correct: @code{gtroff} can get 1084confused by @code{as} or @code{am} requests while counting line numbers. 1085 1086@item -i 1087Read the standard input after all the named input files have been 1088processed. 1089 1090@item -w@var{name} 1091Enable warning @var{name}. Available warnings are described in 1092@ref{Debugging}. Multiple @option{-w} options are allowed. 1093 1094@item -W@var{name} 1095Inhibit warning @var{name}. Multiple @option{-W} options are allowed. 1096 1097@item -E 1098Inhibit all error messages. 1099 1100@item -C 1101Enable compatibility mode. @xref{Implementation Differences}, for the 1102list of incompatibilities between @code{groff} and @acronym{AT&T} 1103@code{troff}. 1104 1105@item -d@var{c}@var{s} 1106@itemx -d@var{name}=@var{s} 1107Define @var{c} or @var{name} to be a string@w{ }@var{s}. @var{c}@w{ }must 1108be a one-letter name; @var{name} can be of arbitrary length. All string 1109assignments happen before loading any macro file (including the start-up 1110file). 1111 1112@item -f@var{fam} 1113Use @var{fam} as the default font family. @xref{Font Families}. 1114 1115@item -m@var{name} 1116Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches 1117for this in its macro directories. If it isn't found, it tries 1118@file{tmac.@var{name}} (searching in the same directories). 1119 1120@item -n@var{num} 1121Number the first page @var{num}. 1122 1123@item -o@var{list} 1124@cindex print current page register (@code{.P}) 1125Output only pages in @var{list}, which is a comma-separated list of page 1126ranges; @samp{@var{n}} means print page@w{ }@var{n}, @samp{@var{m}-@var{n}} 1127means print every page between @var{m} and@w{ }@var{n}, @samp{-@var{n}} 1128means print every page up to@w{ }@var{n}, @samp{@var{n}-} means print every 1129page beginning with@w{ }@var{n}. @code{gtroff} exits after printing the 1130last page in the list. All the ranges are inclusive on both ends. 1131 1132Within @code{gtroff}, this information can be extracted with the 1133@samp{.P} register. @xref{Built-in Registers}. 1134 1135If your document restarts page numbering at the beginning of each 1136chapter, then @code{gtroff} prints the specified page range for each 1137chapter. 1138 1139@item -r@var{c}@var{n} 1140@itemx -r@var{name}=@var{n} 1141Set number register@w{ }@var{c} or @var{name} to the value@w{ }@var{n}. 1142@var{c}@w{ }must be a one-letter name; @var{name} can be of arbitrary 1143length. @var{n}@w{ }can be any @code{gtroff} numeric expression. All 1144register assignments happen before loading any macro file (including 1145the start-up file). 1146 1147@item -F@var{dir} 1148Search @file{@var{dir}} for subdirectories @file{dev@var{name}} 1149(@var{name} is the name of the device), for the @file{DESC} file, and 1150for font files before looking in the standard directories (@pxref{Font 1151Directories}). This option is passed to all pre- and postprocessors 1152using the @env{GROFF_FONT_PATH} environment variable. 1153 1154@item -M@var{dir} 1155Search directory @file{@var{dir}} for macro files before the standard 1156directories (@pxref{Macro Directories}). 1157 1158@item -I@var{dir} 1159This option is as described in @ref{gsoelim}. It implies the 1160@option{-s} option. 1161@end table 1162 1163 1164@c ===================================================================== 1165 1166@node Environment, Macro Directories, Groff Options, Invoking groff 1167@section Environment 1168@cindex environment variables 1169@cindex variables in environment 1170 1171There are also several environment variables (of the operating system, 1172not within @code{gtroff}) which can modify the behavior of @code{groff}. 1173 1174@table @code 1175@item GROFF_COMMAND_PREFIX 1176@tindex GROFF_COMMAND_PREFIX@r{, environment variable} 1177@cindex command prefix 1178@cindex prefix, for commands 1179If this is set to@w{ }@var{X}, then @code{groff} runs @code{@var{X}troff} 1180instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 1181@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 1182apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 1183@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 1184 1185The default command prefix is determined during the installation process. 1186If a non-GNU troff system is found, prefix @samp{g} is used, none 1187otherwise. 1188 1189@item GROFF_TMAC_PATH 1190@tindex GROFF_TMAC_PATH@r{, environment variable} 1191A colon-separated list of directories in which to search for macro files 1192(before the default directories are tried). @xref{Macro Directories}. 1193 1194@item GROFF_TYPESETTER 1195@tindex GROFF_TYPESETTER@r{, environment variable} 1196The default output device. 1197 1198@item GROFF_FONT_PATH 1199@tindex GROFF_FONT_PATH@r{, environment variable} 1200A colon-separated list of directories in which to search for the 1201@code{dev}@var{name} directory (before the default directories are 1202tried). @xref{Font Directories}. 1203 1204@item GROFF_BIN_PATH 1205@tindex GROFF_BIN_PATH@r{, environment variable} 1206This search path, followed by @code{PATH}, is used for commands executed 1207by @code{groff}. 1208 1209@item GROFF_TMPDIR 1210@tindex GROFF_TMPDIR@r{, environment variable} 1211@tindex TMPDIR@r{, environment variable} 1212The directory in which @code{groff} creates temporary files. If this is 1213not set and @env{TMPDIR} is set, temporary files are created in that 1214directory. Otherwise temporary files are created in a system-dependent 1215default directory (on Unix and GNU/Linux systems, this is usually 1216@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 1217@code{post-grohtml} can create temporary files in this directory. 1218@end table 1219 1220Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 1221rather than colons, to separate the directories in the lists described 1222above. 1223 1224 1225@c ===================================================================== 1226 1227@node Macro Directories, Font Directories, Environment, Invoking groff 1228@section Macro Directories 1229@cindex macro directories 1230@cindex directories for macros 1231@cindex searching macros 1232@cindex macros, searching 1233 1234All macro file names must be named @code{@var{name}.tmac} or 1235@code{tmac.@var{name}} to make the @option{-m@var{name}} command line 1236option work. The @code{mso} request doesn't have this restriction; any 1237file name can be used, and @code{gtroff} won't try to append or prepend 1238the @samp{tmac} string. 1239 1240@cindex tmac, directory 1241@cindex directory, for tmac files 1242@cindex tmac, path 1243@cindex path, for tmac files 1244@cindex searching macro files 1245@cindex macro files, searching 1246@cindex files, macro, searching 1247Macro files are kept in the @dfn{tmac directories}, all of which 1248constitute the @dfn{tmac path}. The elements of the search path for 1249macro files are (in that order): 1250 1251@itemize @bullet 1252@item 1253The directories specified with @code{gtroff}'s or @code{groff}'s 1254@option{-M} command line option. 1255 1256@item 1257@tindex GROFF_TMAC_PATH@r{, environment variable} 1258The directories given in the @env{GROFF_TMAC_PATH} environment 1259variable. 1260 1261@item 1262@cindex safer mode 1263@cindex mode, safer 1264@cindex unsafe mode 1265@cindex mode, unsafe 1266@cindex current directory 1267@cindex directory, current 1268The current directory (only if in unsafe mode using the @option{-U} 1269command line switch). 1270 1271@item 1272@cindex home directory 1273@cindex directory, home 1274The home directory. 1275 1276@item 1277@cindex site-specific directory 1278@cindex directory, site-specific 1279@cindex platform-specific directory 1280@cindex directory, platform-specific 1281A platform-dependent directory, a site-specific (platform-independent) 1282directory, and the main tmac directory; the default locations are 1283 1284@Example 1285/usr/local/lib/groff/site-tmac 1286/usr/local/share/groff/site-tmac 1287/usr/local/share/groff/1.18/tmac 1288@endExample 1289 1290@noindent 1291assuming that the version of @code{groff} is 1.18, and the installation 1292prefix was @file{/usr/local}. It is possible to fine-tune those 1293directories during the installation process. 1294@end itemize 1295 1296 1297@c ===================================================================== 1298 1299@node Font Directories, Invocation Examples, Macro Directories, Invoking groff 1300@section Font Directories 1301@cindex font directories 1302@cindex directories for fonts 1303@cindex searching fonts 1304@cindex fonts, searching 1305 1306Basically, there is no restriction how font files for @code{groff} are 1307named and how long font names are; however, to make the font family 1308mechanism work (@pxref{Font Families}), fonts within a family should 1309start with the family name, followed by the shape. For example, the 1310Times family uses @samp{T} for the family name and @samp{R}, @samp{B}, 1311@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold', 1312`italic', and `bold italic', respectively. Thus the final font names 1313are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}. 1314 1315@cindex font path 1316@cindex path, for font files 1317All font files are kept in the @dfn{font directories} which constitute 1318the @dfn{font path}. The file search functions will always append the 1319directory @code{dev}@var{name}, where @var{name} is the name of the 1320output device. Assuming, say, DVI output, and @file{/foo/bar} as a 1321font directory, the font files for @code{grodvi} must be in 1322@file{/foo/bar/devdvi}. 1323 1324The elements of the search path for font files are (in that order): 1325 1326@itemize @bullet 1327@item 1328The directories specified with @code{gtroff}'s or @code{groff}'s 1329@option{-F} command line option. All device drivers and some 1330preprocessors also have this option. 1331 1332@item 1333@tindex GROFF_FONT_PATH@r{, environment variable} 1334The directories given in the @env{GROFF_FONT_PATH} environment 1335variable. 1336 1337@item 1338@cindex site-specific directory 1339@cindex directory, site-specific 1340A site-specific directory and the main font directory; the default 1341locations are 1342 1343@Example 1344/usr/local/share/groff/site-font 1345/usr/local/share/groff/1.18/font 1346@endExample 1347 1348@noindent 1349assuming that the version of @code{groff} is 1.18, and the installation 1350prefix was @file{/usr/local}. It is possible to fine-tune those 1351directories during the installation process. 1352@end itemize 1353 1354 1355@c ===================================================================== 1356 1357@node Invocation Examples, , Font Directories, Invoking groff 1358@section Invocation Examples 1359@cindex invocation examples 1360@cindex examples of invocation 1361 1362This section lists several common uses of @code{groff} and the 1363corresponding command lines. 1364 1365@Example 1366groff file 1367@endExample 1368 1369@noindent 1370This command processes @file{file} without a macro package or a 1371preprocessor. The output device is the default, @samp{ps}, and the 1372output is sent to @code{stdout}. 1373 1374@Example 1375groff -t -mandoc -Tascii file | less 1376@endExample 1377 1378@noindent 1379This is basically what a call to the @code{man} program does. 1380@code{gtroff} processes the manual page @file{file} with the 1381@file{mandoc} macro file (which in turn either calls the @file{man} or 1382the @file{mdoc} macro package), using the @code{tbl} preprocessor and 1383the @acronym{ASCII} output device. Finally, the @code{less} pager 1384displays the result. 1385 1386@Example 1387groff -X -m me file 1388@endExample 1389 1390@noindent 1391Preview @file{file} with @code{gxditview}, using the @file{me} macro 1392package. Since no @option{-T} option is specified, use the default 1393device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 1394@w{@samp{-me}}; the latter is an anachronism from the early days of 1395@acronym{UNIX}.@footnote{The same is true for the other main macro 1396packages that come with @code{groff}: @file{man}, @file{mdoc}, 1397@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 1398for example, to load @file{trace.tmac}, either @samp{-mtrace} or 1399@w{@samp{-m trace}} must be used.} 1400 1401@Example 1402groff -man -rD1 -z file 1403@endExample 1404 1405@noindent 1406Check @file{file} with the @file{man} macro package, forcing 1407double-sided printing -- don't produce any output. 1408 1409@menu 1410* grog:: 1411@end menu 1412 1413@c --------------------------------------------------------------------- 1414 1415@node grog, , Invocation Examples, Invocation Examples 1416@subsection @code{grog} 1417 1418@pindex grog 1419@code{grog} reads files, guesses which of the @code{groff} preprocessors 1420and/or macro packages are required for formatting them, and prints the 1421@code{groff} command including those options on the standard output. It 1422generates one or more of the options @option{-e}, @option{-man}, 1423@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc}, 1424@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 1425@option{-s}, and @option{-t}. 1426 1427A special file name@w{ }@file{-} refers to the standard input. Specifying 1428no files also means to read the standard input. Any specified options 1429are included in the printed command. No space is allowed between 1430options and their arguments. The only options recognized are 1431@option{-C} (which is also passed on) to enable compatibility mode, and 1432@option{-v} to print the version number and exit. 1433 1434For example, 1435 1436@Example 1437grog -Tdvi paper.ms 1438@endExample 1439 1440@noindent 1441guesses the appropriate command to print @file{paper.ms} and then prints 1442it to the command line after adding the @option{-Tdvi} option. For 1443direct execution, enclose the call to @code{grog} in backquotes at the 1444@acronym{UNIX} shell prompt: 1445 1446@Example 1447`grog -Tdvi paper.ms` > paper.dvi 1448@endExample 1449 1450@noindent 1451As seen in the example, it is still necessary to redirect the output to 1452something meaningful (i.e.@: either a file or a pager program like 1453@code{less}). 1454 1455 1456 1457@c ===================================================================== 1458@c ===================================================================== 1459 1460@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 1461@chapter Tutorial for Macro Users 1462@cindex tutorial for macro users 1463@cindex macros, tutorial for users 1464@cindex user's tutorial for macros 1465@cindex user's macro tutorial 1466 1467Most users tend to use a macro package to format their papers. This 1468means that the whole breadth of @code{groff} is not necessary for most 1469people. This chapter covers the material needed to efficiently use a 1470macro package. 1471 1472@menu 1473* Basics:: 1474* Common Features:: 1475@end menu 1476 1477 1478@c ===================================================================== 1479 1480@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 1481@section Basics 1482@cindex basics of macros 1483@cindex macro basics 1484 1485This section covers some of the basic concepts necessary to understand 1486how to use a macro package.@footnote{This section is derived from 1487@cite{Writing Papers with nroff using -me} by Eric P.@w{ }Allman.} 1488References are made throughout to more detailed information, if desired. 1489 1490@code{gtroff} reads an input file prepared by the user and outputs a 1491formatted document suitable for publication or framing. The input 1492consists of text, or words to be printed, and embedded commands 1493(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 1494format the output. For more detail on this, see @ref{Embedded 1495Commands}. 1496 1497The word @dfn{argument} is used in this chapter to mean a word or number 1498which appears on the same line as a request, and which modifies the 1499meaning of that request. For example, the request 1500 1501@Example 1502.sp 1503@endExample 1504 1505@noindent 1506spaces one line, but 1507 1508@Example 1509.sp 4 1510@endExample 1511 1512@noindent 1513spaces four lines. The number@w{ }4 is an argument to the @code{sp} 1514request which says to space four lines instead of one. Arguments are 1515separated from the request and from each other by spaces (@emph{no} 1516tabs). More details on this can be found in @ref{Request Arguments}. 1517 1518The primary function of @code{gtroff} is to collect words from input 1519lines, fill output lines with those words, justify the right-hand margin 1520by inserting extra spaces in the line, and output the result. For 1521example, the input: 1522 1523@Example 1524Now is the time 1525for all good men 1526to come to the aid 1527of their party. 1528Four score and seven 1529years ago, etc. 1530@endExample 1531 1532@noindent 1533is read, packed onto output lines, and justified to produce: 1534 1535@quotation 1536Now is the time for all good men to come to the aid of their party. 1537Four score and seven years ago, etc. 1538@end quotation 1539 1540@cindex break 1541@cindex line break 1542Sometimes a new output line should be started even though the current 1543line is not yet full; for example, at the end of a paragraph. To do 1544this it is possible to cause a @dfn{break}, which starts a new output 1545line. Some requests cause a break automatically, as normally do blank 1546input lines and input lines beginning with a space. 1547 1548Not all input lines are text to be formatted. Some input lines are 1549requests which describe how to format the text. Requests always have a 1550period (@samp{.}) or an apostrophe (@samp{'}) as the first character of 1551the input line. 1552 1553The text formatter also does more complex things, such as automatically 1554numbering pages, skipping over page boundaries, putting footnotes in the 1555correct place, and so forth. 1556 1557Here are a few hints for preparing text for input to @code{gtroff}. 1558 1559@itemize @bullet 1560@item 1561First, keep the input lines short. Short input lines are easier to 1562edit, and @code{gtroff} packs words onto longer lines anyhow. 1563 1564@item 1565In keeping with this, it is helpful to begin a new line after every 1566comma or phrase, since common corrections are to add or delete sentences 1567or phrases. 1568 1569@item 1570End each sentence with two spaces -- or better, start each sentence on a 1571new line. @code{gtroff} recognizes characters that usually end a 1572sentence, and inserts sentence space accordingly. 1573 1574@item 1575Do not hyphenate words at the end of lines -- @code{gtroff} is smart 1576enough to hyphenate words as needed, but is not smart enough to take 1577hyphens out and join a word back together. Also, words such as 1578``mother-in-law'' should not be broken over a line, since then a space 1579can occur where not wanted, such as ``@w{mother- in}-law''. 1580@end itemize 1581 1582@cindex double-spacing (@code{ls}) 1583@cindex spacing 1584@code{gtroff} double-spaces output text automatically if you use the 1585request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing 1586@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the 1587vertical space, use the @code{pvs} request (@pxref{Changing Type 1588Sizes}).} 1589 1590A number of requests allow to change the way the output looks, 1591sometimes called the @dfn{layout} of the output page. Most of these 1592requests adjust the placing of @dfn{whitespace} (blank lines or 1593spaces). 1594 1595@cindex new page (@code{bp}) 1596The @code{bp} request starts a new page, causing a line break. 1597 1598@cindex blank line (@code{sp}) 1599@cindex empty line (@code{sp}) 1600@cindex line, empty (@code{sp}) 1601The request @w{@samp{.sp @var{N}}} leaves @var{N}@w{ }lines of blank 1602space. @var{N}@w{ }can be omitted (meaning skip a single line) or can 1603be of the form @var{N}i (for @var{N}@w{ }inches) or @var{N}c (for 1604@var{N}@w{ }centimeters). For example, the input: 1605 1606@Example 1607.sp 1.5i 1608My thoughts on the subject 1609.sp 1610@endExample 1611 1612@noindent 1613leaves one and a half inches of space, followed by the line ``My 1614thoughts on the subject'', followed by a single blank line (more 1615measurement units are available, see @ref{Measurements}). 1616 1617@cindex centering lines (@code{ce}) 1618@cindex lines, centering (@code{ce}) 1619Text lines can be centered by using the @code{ce} request. The line 1620after @code{ce} is centered (horizontally) on the page. To center more 1621than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number 1622of lines to center), followed by the @var{N}@w{ }lines. To center many 1623lines without counting them, type: 1624 1625@Example 1626.ce 1000 1627lines to center 1628.ce 0 1629@endExample 1630 1631@noindent 1632The @w{@samp{.ce 0}} request tells @code{groff} to center zero more 1633lines, in other words, stop centering. 1634 1635@cindex line break (@code{br}) 1636@cindex break (@code{br}) 1637All of these requests cause a break; that is, they always start a new 1638line. To start a new line without performing any other action, use 1639@code{br}. 1640 1641 1642@c ===================================================================== 1643 1644@node Common Features, , Basics, Tutorial for Macro Users 1645@section Common Features 1646@cindex common features 1647@cindex features, common 1648 1649@code{gtroff} provides very low-level operations for formatting a 1650document. There are many common routine operations which are done in 1651all documents. These common operations are written into @dfn{macros} 1652and collected into a @dfn{macro package}. 1653 1654All macro packages provide certain common capabilities which fall into 1655the following categories. 1656 1657@menu 1658* Paragraphs:: 1659* Sections and Chapters:: 1660* Headers and Footers:: 1661* Page Layout Adjustment:: 1662* Displays:: 1663* Footnotes and Annotations:: 1664* Table of Contents:: 1665* Indices:: 1666* Paper Formats:: 1667* Multiple Columns:: 1668* Font and Size Changes:: 1669* Predefined Strings:: 1670* Preprocessor Support:: 1671* Configuration and Customization:: 1672@end menu 1673 1674@c --------------------------------------------------------------------- 1675 1676@node Paragraphs, Sections and Chapters, Common Features, Common Features 1677@subsection Paragraphs 1678@cindex paragraphs 1679 1680One of the most common and most used capability is starting a 1681paragraph. There are a number of different types of paragraphs, any 1682of which can be initiated with macros supplied by the macro package. 1683Normally, paragraphs start with a blank line and the first line 1684indented, like the text in this manual. There are also block style 1685paragraphs, which omit the indentation: 1686 1687@Example 1688Some men look at constitutions with sanctimonious 1689reverence, and deem them like the ark of the covenant, too 1690sacred to be touched. 1691@endExample 1692 1693@noindent 1694And there are also indented paragraphs which begin with a tag or label 1695at the margin and the remaining text indented. 1696 1697@Example 1698one This is the first paragraph. Notice how the first 1699 line of the resulting paragraph lines up with the 1700 other lines in the paragraph. 1701@endExample 1702@Example 1703longlabel 1704 This paragraph had a long label. The first 1705 character of text on the first line does not line up 1706 with the text on second and subsequent lines, 1707 although they line up with each other. 1708@endExample 1709 1710A variation of this is a bulleted list. 1711 1712@Example 1713. Bulleted lists start with a bullet. It is possible 1714 to use other glyphs instead of the bullet. In nroff 1715 mode using the ASCII character set for output, a dot 1716 is used instead of a real bullet. 1717@endExample 1718 1719 1720@c --------------------------------------------------------------------- 1721 1722@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features 1723@subsection Sections and Chapters 1724 1725Most macro packages supply some form of section headers. The simplest 1726kind is simply the heading on a line by itself in bold type. Others 1727supply automatically numbered section heading or different heading 1728styles at different levels. Some, more sophisticated, macro packages 1729supply macros for starting chapters and appendices. 1730 1731@c --------------------------------------------------------------------- 1732 1733@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features 1734@subsection Headers and Footers 1735 1736Every macro package gives some way to manipulate the @dfn{headers} and 1737@dfn{footers} (also called @dfn{titles}) on each page. This is text 1738put at the top and bottom of each page, respectively, which contain 1739data like the current page number, the current chapter title, and so 1740on. Its appearance is not affected by the running text. Some packages 1741allow for different ones on the even and odd pages (for material printed 1742in a book form). 1743 1744The titles are called @dfn{three-part titles}, that is, there is a 1745left-justified part, a centered part, and a right-justified part. An 1746automatically generated page number may be put in any of these fields 1747with the @samp{%} character (see @ref{Page Layout}, for more details). 1748 1749@c --------------------------------------------------------------------- 1750 1751@node Page Layout Adjustment, Displays, Headers and Footers, Common Features 1752@subsection Page Layout 1753 1754Most macro packages let the user specify top and bottom margins and 1755other details about the appearance of the printed pages. 1756 1757@c --------------------------------------------------------------------- 1758 1759@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features 1760@subsection Displays 1761@cindex displays 1762 1763@dfn{Displays} are sections of text to be set off from the body of 1764the paper. Major quotes, tables, and figures are types of displays, as 1765are all the examples used in this document. 1766 1767@cindex quotes, major 1768@cindex major quotes 1769@dfn{Major quotes} are quotes which are several lines long, and hence 1770are set in from the rest of the text without quote marks around them. 1771 1772@cindex list 1773A @dfn{list} is an indented, single-spaced, unfilled display. Lists 1774should be used when the material to be printed should not be filled and 1775justified like normal text, such as columns of figures or the examples 1776used in this paper. 1777 1778@cindex keep 1779A @dfn{keep} is a display of lines which are kept on a single page if 1780possible. An example for a keep might be a diagram. Keeps differ from 1781lists in that lists may be broken over a page boundary whereas keeps are 1782not. 1783 1784@cindex keep, floating 1785@cindex floating keep 1786@dfn{Floating keeps} move relative to the text. Hence, they are good for 1787things which are referred to by name, such as ``See figure@w{ }3''. A 1788floating keep appears at the bottom of the current page if it fits; 1789otherwise, it appears at the top of the next page. Meanwhile, the 1790surrounding text `flows' around the keep, thus leaving no blank areas. 1791 1792@c --------------------------------------------------------------------- 1793 1794@node Footnotes and Annotations, Table of Contents, Displays, Common Features 1795@subsection Footnotes and Annotations 1796@cindex footnotes 1797@cindex annotations 1798 1799There are a number of requests to save text for later printing. 1800 1801@dfn{Footnotes} are printed at the bottom of the current page. 1802 1803@cindex delayed text 1804@dfn{Delayed text} is very similar to a footnote except that it is 1805printed when called for explicitly. This allows a list of references to 1806appear (for example) at the end of each chapter, as is the convention in 1807some disciplines. 1808 1809Most macro packages which supply this functionality also supply a means 1810of automatically numbering either type of annotation. 1811 1812@c --------------------------------------------------------------------- 1813 1814@node Table of Contents, Indices, Footnotes and Annotations, Common Features 1815@subsection Table of Contents 1816@cindex table of contents 1817@cindex contents, table of 1818 1819@dfn{Tables of contents} are a type of delayed text having a tag 1820(usually the page number) attached to each entry after a row of dots. 1821The table accumulates throughout the paper until printed, usually after 1822the paper has ended. Many macro packages provide the ability to have 1823several tables of contents (e.g.@: a standard table of contents, a list 1824of tables, etc). 1825 1826@c --------------------------------------------------------------------- 1827 1828@node Indices, Paper Formats, Table of Contents, Common Features 1829@subsection Indices 1830@cindex index, in macro package 1831 1832While some macro packages use the term @dfn{index}, none actually 1833provide that functionality. The facilities they call indices are 1834actually more appropriate for tables of contents. 1835 1836@pindex makeindex 1837To produce a real index in a document, external tools like the 1838@code{makeindex} program are necessary. 1839 1840@c --------------------------------------------------------------------- 1841 1842@node Paper Formats, Multiple Columns, Indices, Common Features 1843@subsection Paper Formats 1844@cindex paper formats 1845 1846Some macro packages provide stock formats for various kinds of 1847documents. Many of them provide a common format for the title and 1848opening pages of a technical paper. The @file{mm} macros in particular 1849provide formats for letters and memoranda. 1850 1851@c --------------------------------------------------------------------- 1852 1853@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features 1854@subsection Multiple Columns 1855 1856Some macro packages (but not @file{man}) provide the ability to have two 1857or more columns on a page. 1858 1859@c --------------------------------------------------------------------- 1860 1861@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features 1862@subsection Font and Size Changes 1863 1864The built-in font and size functions are not always intuitive, so all 1865macro packages provide macros to make these operations simpler. 1866 1867@c --------------------------------------------------------------------- 1868 1869@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features 1870@subsection Predefined Strings 1871 1872Most macro packages provide various predefined strings for a variety of 1873uses; examples are sub- and superscripts, printable dates, quotes and 1874various special characters. 1875 1876@c --------------------------------------------------------------------- 1877 1878@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features 1879@subsection Preprocessor Support 1880 1881All macro packages provide support for various preprocessors and may 1882extend their functionality. 1883 1884For example, all macro packages mark tables (which are processed with 1885@code{gtbl}) by placing them between @code{TS} and @code{TE} macros. 1886The @file{ms} macro package has an option, @samp{.TS@w{ }H}, that prints 1887a caption at the top of a new page (when the table is too long to fit on 1888a single page). 1889 1890@c --------------------------------------------------------------------- 1891 1892@node Configuration and Customization, , Preprocessor Support, Common Features 1893@subsection Configuration and Customization 1894 1895Some macro packages provide means of customizing many of the details of 1896how the package behaves. This ranges from setting the default type size 1897to changing the appearance of section headers. 1898 1899 1900 1901@c ===================================================================== 1902@c ===================================================================== 1903 1904@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top 1905@chapter Macro Packages 1906@cindex macro packages 1907@cindex packages, macros 1908 1909This chapter documents the main macro packages that come with 1910@code{groff}. 1911 1912@menu 1913* man:: 1914* mdoc:: 1915* ms:: 1916* me:: 1917* mm:: 1918@end menu 1919 1920 1921@c ===================================================================== 1922 1923@node man, mdoc, Macro Packages, Macro Packages 1924@section @file{man} 1925@cindex manual pages 1926@cindex man pages 1927@pindex an.tmac 1928@pindex man.tmac 1929@pindex man-old.tmac 1930 1931This is the most popular and probably the most important macro package 1932of @code{groff}. It is easy to use, and a vast majority of manual pages 1933are based on it. 1934 1935@menu 1936* Man options:: 1937* Man usage:: 1938* Man font macros:: 1939* Miscellaneous man macros:: 1940* Predefined man strings:: 1941* Preprocessors in man pages:: 1942@end menu 1943 1944@c --------------------------------------------------------------------- 1945 1946@node Man options, Man usage, man, man 1947@subsection Options 1948 1949The command line format for using the @file{man} macros with 1950@code{groff} is: 1951 1952@Example 1953groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] 1954 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [ -rP@var{nnn} ] 1955 [ -rS@var{xx} ] [ -rX@var{nnn} ] [ @var{files}@dots{} ] 1956@endExample 1957 1958@noindent 1959It is possible to use @samp{-man} instead of @w{@samp{-m man}}. 1960 1961@table @code 1962@item -rLL=@var{length} 1963Set line length to @var{length}. If not specified, the line length 1964defaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per 1965line) and 6.5@w{ }inch otherwise. 1966 1967@item -rLT=@var{length} 1968Set title length to @var{length}. If not specified, the title length 1969defaults to 78@w{ }en in nroff mode (this is 78@w{ }characters per 1970line) and 6.5@w{ }inch otherwise. 1971 1972@item -rcR=1 1973This option (the default if a TTY output device is used) creates a 1974single, very long page instead of multiple pages. Use @code{-rcR=0} 1975to disable it. 1976 1977@item -rC1 1978If more than one manual page is given on the command line, number the 1979pages continuously, rather than starting each at@w{ }1. 1980 1981@item -rD1 1982Double-sided printing. Footers for even and odd pages are formatted 1983differently. 1984 1985@item -rP@var{nnn} 1986Page numbering starts with @var{nnn} rather than with@w{ }1. 1987 1988@item -rS@var{xx} 1989Use @var{xx} (which can be 10, 11, or@w{ }12@dmn{pt}) as the base 1990document font size instead of the default value of@w{ }10@dmn{pt}. 1991 1992@item -rX@var{nnn} 1993After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, 1994@var{nnn}c, etc. For example, the option @option{-rX2} produces the 1995following page numbers: 1, 2, 2a, 2b, 2c, etc. 1996@end table 1997 1998@c --------------------------------------------------------------------- 1999 2000@node Man usage, Man font macros, Man options, man 2001@subsection Usage 2002@cindex @code{man} macros 2003@cindex macros for manual pages [@code{man}] 2004 2005@pindex man.local 2006This section describes the available macros for manual pages. For 2007further customization, put additional macros and requests into the file 2008@file{man.local} which is loaded immediately after the @file{man} 2009package. 2010 2011@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man} 2012Set the title of the man page to @var{title} and the section to 2013@var{section}, which must have a value between 1 and@w{ }8. The value 2014of @var{section} may also have a string appended, e.g.@: @samp{.pm}, 2015to indicate a specific subsection of the man pages. 2016 2017Both @var{title} and @var{section} are positioned at the left and right 2018in the header line (with @var{section} in parentheses immediately 2019appended to @var{title}. @var{extra1} is positioned in the middle of 2020the footer line. @var{extra2} is positioned at the left in the footer 2021line (or at the left on even pages and at the right on odd pages if 2022double-sided printing is active). @var{extra3} is centered in the 2023header line. 2024 2025For @acronym{HTML} output, headers and footers are completely suppressed. 2026 2027Additionally, this macro starts a new page; the new line number is@w{ }1 2028again (except if the @option{-rC1} option is given on the command line) 2029-- this feature is intended only for formatting multiple man pages; a 2030single man page should contain exactly one @code{TH} macro at the 2031beginning of the file. 2032@endDefmac 2033 2034@Defmac {SH, [@Var{heading}], man} 2035Set up an unnumbered section heading sticking out to the left. Prints 2036out all the text following @code{SH} up to the end of the line (or the 2037text in the next line if there is no argument to @code{SH}) in bold 2038face, one size larger than the base document size. Additionally, the 2039left margin for the following text is reset to its default value. 2040@endDefmac 2041 2042@Defmac {SS, [@Var{heading}], man} 2043Set up an unnumbered (sub)section heading. Prints out all the text 2044following @code{SS} up to the end of the line (or the text in the next 2045line if there is no argument to @code{SS}) in bold face, at the same 2046size as the base document size. Additionally, the left margin for the 2047following text is reset to its default value. 2048@endDefmac 2049 2050@Defmac {TP, [@Var{nnn}], man} 2051Set up an indented paragraph with label. The indentation is set to 2052@var{nnn} if that argument is supplied (the default unit is @samp{n} 2053if omitted), otherwise it is set to the default indentation value. 2054 2055The first line of text following this macro is interpreted as a string 2056to be printed flush-left, as it is appropriate for a label. It is not 2057interpreted as part of a paragraph, so there is no attempt to fill the 2058first line with text from the following input lines. Nevertheless, if 2059the label is not as wide as the indentation, then the paragraph starts 2060at the same line (but indented), continuing on the following lines. 2061If the label is wider than the indentation, then the descriptive part 2062of the paragraph begins on the line following the label, entirely 2063indented. Note that neither font shape nor font size of the label is 2064set to a default value; on the other hand, the rest of the text has 2065default font settings. 2066@endDefmac 2067 2068@DefmacList {LP, , man} 2069@DefmacItem {PP, , man} 2070@DefmacListEnd {P, , man} 2071These macros are mutual aliases. Any of them causes a line break at 2072the current position, followed by a vertical space downwards by the 2073amount specified by the @code{PD} macro. The font size and shape are 2074reset to the default value (10@dmn{pt} roman if no @option{-rS} option 2075is given on the command line). Finally, the current left margin is 2076restored. 2077@endDefmac 2078 2079@Defmac {IP, [@Var{designator} [@Var{nnn}]], man} 2080Set up an indented paragraph, using @var{designator} as a tag to mark 2081its beginning. The indentation is set to @var{nnn} if that argument 2082is supplied (default unit is @samp{n}), otherwise the default 2083indentation value is used. Font size and face of the paragraph (but 2084not the designator) are reset to their default values. To start an 2085indented paragraph with a particular indentation but without a 2086designator, use @samp{""} (two double quotes) as the first argument of 2087@code{IP}. 2088 2089For example, to start a paragraph with bullets as the designator and 20904@w{ }en indentation, write 2091 2092@Example 2093.IP \(bu 4 2094@endExample 2095@endDefmac 2096 2097@Defmac {HP, [@Var{nnn}], man} 2098@cindex hanging indentation [@code{man}] 2099@cindex @code{man} macros, hanging indentation 2100Set up a paragraph with hanging left indentation. The indentation is 2101set to @var{nnn} if that argument is supplied (default unit is 2102@samp{n}), otherwise the default indentation value is used. Font size 2103and face are reset to their default values. 2104@endDefmac 2105 2106@Defmac {RS, [@Var{nnn}], man} 2107@cindex left margin, how to move [@code{man}] 2108@cindex @code{man} macros, moving left margin 2109Move the left margin to the right by the value @var{nnn} if specified 2110(default unit is @samp{n}); otherwise the default indentation value 2111is used. Calls to the @code{RS} macro can be nested. 2112@endDefmac 2113 2114@Defmac {RE, [@Var{nnn}], man} 2115Move the left margin back to level @var{nnn}; if no argument is given, 2116it moves one level back. The first level (i.e., no call to @code{RS} 2117yet) has number@w{ }1, and each call to @code{RS} increases the level 2118by@w{ }1. 2119@endDefmac 2120 2121@cindex line breaks, with vertical space [@code{man}] 2122@cindex @code{man} macros, line breaks with vertical space 2123To summarize, the following macros cause a line break with the insertion 2124of vertical space (which amount can be changed with the @code{PD} 2125macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, 2126@code{P}), @code{IP}, and @code{HP}. 2127 2128@cindex line breaks, without vertical space [@code{man}] 2129@cindex @code{man} macros, line breaks without vertical space 2130The macros @code{RS} and @code{RE} also cause a break but do not insert 2131vertical space. 2132 2133@cindex default indentation, resetting [@code{man}] 2134@cindex indentaion, resetting to default [@code{man}] 2135@cindex @code{man} macros, resetting default indentation 2136Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}), 2137and @code{RS} reset the indentation to its default value. 2138 2139@c --------------------------------------------------------------------- 2140 2141@node Man font macros, Miscellaneous man macros, Man usage, man 2142@subsection Macros to set fonts 2143@cindex font selection [@code{man}] 2144@cindex @code{man} macros, how to set fonts 2145 2146The standard font is roman; the default text size is 10@w{ }point. 2147If command line option @option{-rS=@var{n}} is given, use 2148@var{n}@dmn{pt} as the default text size. 2149 2150@Defmac {SM, [@Var{text}], man} 2151Set the text on the same line or the text on the next line in a font 2152that is one point size smaller than the default font. 2153@endDefmac 2154 2155@Defmac {SB, [@Var{text}], man} 2156@cindex bold face [@code{man}] 2157@cindex @code{man} macros, bold face 2158Set the text on the same line or the text on the next line in bold face 2159font, one point size smaller than the default font. 2160@endDefmac 2161 2162@Defmac {BI, text, man} 2163Set its arguments alternately in bold face and italic. Thus, 2164 2165@Example 2166.BI this "word and" that 2167@endExample 2168 2169@noindent 2170would set ``this'' and ``that'' in bold face, and ``word and'' in 2171italics. 2172@endDefmac 2173 2174@Defmac {IB, text, man} 2175Set its arguments alternately in italic and bold face. 2176@endDefmac 2177 2178@Defmac {RI, text, man} 2179Set its arguments alternately in roman and italic. 2180@endDefmac 2181 2182@Defmac {IR, text, man} 2183Set its arguments alternately in italic and roman. 2184@endDefmac 2185 2186@Defmac {BR, text, man} 2187Set its arguments alternately in bold face and roman. 2188@endDefmac 2189 2190@Defmac {RB, text, man} 2191Set its arguments alternately in roman and bold face. 2192@endDefmac 2193 2194@Defmac {B, [@Var{text}], man} 2195Set @var{text} in bold face. If no text is present on the line where 2196the macro is called, then the text of the next line appears in bold 2197face. 2198@endDefmac 2199 2200@Defmac {I, [@Var{text}], man} 2201@cindex italic fonts [@code{man}] 2202@cindex @code{man} macros, italic fonts 2203Set @var{text} in italic. If no text is present on the line where the 2204macro is called, then the text of the next line appears in italic. 2205@endDefmac 2206 2207@c --------------------------------------------------------------------- 2208 2209@node Miscellaneous man macros, Predefined man strings, Man font macros, man 2210@subsection Miscellaneous macros 2211 2212@pindex grohtml 2213@cindex @code{man} macros, default indentation 2214@cindex default indentation [@code{man}] 2215The default indentation is 7.2@w{ }en for all output devices except for 2216@code{grohtml} which ignores indentation. 2217 2218@Defmac {DT, , man} 2219@cindex tab stops [@code{man}] 2220@cindex @code{man} macros, tab stops 2221Set tabs every 0.5@w{ }inches. Since this macro is always executed 2222during a call to the @code{TH} macro, it makes sense to call it only if 2223the tab positions have been changed. 2224@endDefmac 2225 2226@Defmac {PD, [@Var{nnn}], man} 2227@cindex empty space before a paragraph [@code{man}] 2228@cindex @code{man} macros, empty space before a paragraph 2229Adjust the empty space before a new paragraph (or section). The 2230optional argument gives the amount of space (default unit is 2231@samp{v}); without parameter, the value is reset to its default value 2232(1@w{ }line for TTY devices, 0.4@dmn{v}@w{ }otherwise). 2233@endDefmac 2234 2235This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as 2236well as @code{PP} and @code{P}), @code{IP}, and @code{HP}. 2237 2238@c --------------------------------------------------------------------- 2239 2240@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man 2241@subsection Predefined strings 2242 2243The following strings are defined: 2244 2245@Defstr {S, man} 2246Switch back to the default font size. 2247@endDefstr 2248 2249@Defstr {R, man} 2250The `registered' sign. 2251@endDefstr 2252 2253@Defstr {Tm, man} 2254The `trademark' sign. 2255@endDefstr 2256 2257@DefstrList {lq, man} 2258@DefstrListEnd {rq, man} 2259@cindex @code{lq} glyph, and @code{lq} string [@code{man}] 2260@cindex @code{rq} glyph, and @code{rq} string [@code{man}] 2261Left and right quote. This is equal to @code{\(lq} and @code{\(rq}, 2262respectively. 2263@endDefstr 2264 2265@c --------------------------------------------------------------------- 2266 2267@node Preprocessors in man pages, , Predefined man strings, man 2268@subsection Preprocessors in @file{man} pages 2269 2270@cindex preprocessor, calling convention 2271@cindex calling convention of preprocessors 2272If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has 2273become common usage to make the first line of the man page look like 2274this: 2275 2276@Example 2277'\" @var{word} 2278@endExample 2279 2280@pindex geqn@r{, invocation in manual pages} 2281@pindex grefer@r{, invocation in manual pages} 2282@pindex gtbl@r{, invocation in manual pages} 2283@pindex man@r{, invocation of preprocessors} 2284@noindent 2285Note the single space character after the double quote. @var{word} 2286consists of letters for the needed preprocessors: @samp{e} for 2287@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. 2288Modern implementations of the @code{man} program read this first line 2289and automatically call the right preprocessor(s). 2290 2291 2292@c ===================================================================== 2293 2294@node mdoc, ms, man, Macro Packages 2295@section @file{mdoc} 2296@cindex @code{mdoc} macros 2297 2298@c XXX documentation 2299@c XXX this is a placeholder until we get stuff knocked into shape 2300See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc} 2301at the command line). 2302 2303 2304@c ===================================================================== 2305 2306@node ms, me, mdoc, Macro Packages 2307@section @file{ms} 2308@cindex @code{ms} macros 2309 2310The @file{-ms} 2311macros are suitable for reports, letters, books, 2312user manuals, and so forth. 2313The package provides macros for cover pages, section headings, 2314paragraphs, lists, footnotes, pagination, 2315and a table of contents. 2316 2317@menu 2318* ms Intro:: 2319* General ms Structure:: 2320* ms Document Control Registers:: 2321* ms Cover Page Macros:: 2322* ms Body Text:: 2323* ms Page Layout:: 2324* Differences from AT&T ms:: 2325@end menu 2326 2327@c --------------------------------------------------------------------- 2328 2329@node ms Intro, General ms Structure, ms, ms 2330@subsection Introduction to @file{ms} 2331 2332The original @file{-ms} macros were included with 2333@acronym{AT&T} @code{troff} as well as the 2334@file{man} macros. 2335While the @file{man} package is intended for brief documents 2336that can be read on-line as well as printed, the @file{ms} 2337macros are suitable for longer documents that are meant to be 2338printed rather than read on-line. 2339 2340The @file{ms} macro package included with @code{groff} 2341is a complete, bottom-up re-implementation. 2342Several macros (specific to @acronym{AT&T} 2343or Berkeley) are not included, while several new commands are. 2344@xref{Differences from AT&T ms}, for more information. 2345 2346@c --------------------------------------------------------------------- 2347 2348@node General ms Structure, ms Document Control Registers, ms Intro, ms 2349@subsection General structure of an @file{ms} document 2350@cindex @code{ms} macros, general structure 2351 2352The @file{ms} macro package expects a certain amount of structure, 2353but not as much as packages such as @file{man} or @file{mdoc}. 2354 2355The simplest documents can begin with a paragraph macro 2356(such as @code{LP} or @code{PP}), 2357and consist of text separated by paragraph macros 2358or even blank lines. 2359Longer documents have a structure as follows: 2360 2361@table @strong 2362@item Document type 2363If you invoke the @code{RP} 2364(report) macro on the first line of the document, 2365@code{groff} prints the cover page information on its own page; 2366otherwise it prints the information on the 2367first page with your document text immediately following. 2368Other document formats found in @acronym{AT&T} @code{troff} 2369are specific to @acronym{AT&T} or Berkeley, and are not supported in 2370@code{groff}. 2371 2372@item Format and layout 2373By setting number registers, 2374you can change your document's type (font and size), 2375margins, spacing, headers and footers, and footnotes. 2376@xref{ms Document Control Registers}, for more details. 2377 2378@item Cover page 2379A cover page consists of a title, the author's name and institution, 2380an abstract, and the date. 2381@footnote{Actually, only the title is required.} 2382@xref{ms Cover Page Macros}, for more details. 2383 2384@item Body 2385Following the cover page is your document. 2386You can use the @file{ms} 2387macros to write reports, letters, books, and so forth. 2388The package is designed for structured documents, 2389consisting of paragraphs interspersed with headings 2390and augmented by lists, footnotes, tables, and other 2391common constructs. 2392@xref{ms Body Text}, for more details. 2393 2394@item Table of contents 2395Longer documents usually include a table of contents, 2396which you can invoke by placing the 2397@code{TC} 2398macro at the end of your document. 2399The @file{ms} 2400macros have minimal indexing facilities, consisting of the 2401@code{IX} macro, which prints an entry on standard error. 2402Printing the table of contents at the end is necessary since 2403@code{groff} is a single-pass text formatter, 2404thus it cannot determine the page number of each section 2405until that section has actually been set and printed. 2406Since @file{ms} output is intended for hardcopy, 2407you can manually relocate the pages containing 2408the table of contents between the cover page and the 2409body text after printing. 2410@end table 2411 2412@c --------------------------------------------------------------------- 2413 2414@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms 2415@subsection Document control registers 2416@cindex @code{ms} macros, document control registers 2417 2418The following is a list of document control number registers. 2419For the sake of consistency, 2420set registers related to margins at the beginning of your document, 2421or just after the @code{RP} macro. 2422You can set other registers later in your document, 2423but you should keep them together at the beginning 2424to make them easy to find and edit as necessary. 2425 2426@unnumberedsubsubsec Margin Settings 2427 2428@Defmpreg {PO, ms} 2429Defines the page offset (i.e.@: the left margin). 2430There is no explicit right margin setting; the combination of 2431the @code{PO} and @code{LL} registers implicitly define the 2432right margin width. 2433 2434Effective: next page. 2435 2436Default value: 1@dmn{i}. 2437@endDefmpreg 2438 2439@Defmpreg {LL, ms} 2440Defines the line length (i.e.@: the width of the body text). 2441 2442Effective: next paragraph. 2443 2444Default: 6@dmn{i}. 2445@endDefmpreg 2446 2447@Defmpreg {LT, ms} 2448Defines the title length (i.e.@: the header and footer width). 2449This is usually the same as @code{LL}, but not necessarily. 2450 2451Effective: next paragraph. 2452 2453Default: 6@dmn{i}. 2454@endDefmpreg 2455 2456@Defmpreg {HM, ms} 2457Defines the header margin height at the top of the page. 2458 2459Effective: next page. 2460 2461Default: 1@dmn{i}. 2462@endDefmpreg 2463 2464@Defmpreg {FM, ms} 2465Defines the footer margin height at the bottom of the page. 2466 2467Effective: next page. 2468 2469Default: 1@dmn{i}. 2470@endDefmpreg 2471 2472@unnumberedsubsubsec Text Settings 2473 2474@Defmpreg {PS, ms} 2475Defines the point size of the body text. 2476 2477Effective: next paragraph. 2478 2479Default: 10@dmn{p}. 2480@endDefmpreg 2481 2482@Defmpreg {VS, ms} 2483Defines the space between lines (line height plus leading). 2484 2485Effective: next paragraph. 2486 2487Default: 12@dmn{p}. 2488@endDefmpreg 2489 2490@unnumberedsubsubsec Paragraph Settings 2491 2492@Defmpreg {PI, ms} 2493Defines the initial indent of a @code{.PP} paragraph. 2494 2495Effective: next paragraph. 2496 2497Default: 5@dmn{n}. 2498@endDefmpreg 2499 2500@Defmpreg {PD, ms} 2501Defines the space between paragraphs. 2502 2503Effective: next paragraph. 2504 2505Default: 0.3@dmn{v}. 2506@endDefmpreg 2507 2508@Defmpreg {QI, ms} 2509Defines the indent on both sides of a quoted (@code{.QP}) paragraph. 2510 2511Effective: next paragraph. 2512 2513Default: 5@dmn{n}. 2514@endDefmpreg 2515 2516@unnumberedsubsubsec Footnote Settings 2517 2518@Defmpreg {FL, ms} 2519Defines the length of a footnote. 2520 2521Effective: next footnote. 2522 2523Default: @math{@code{@\n[LL]} * 5 / 6}. 2524@endDefmpreg 2525 2526@Defmpreg {FI, ms} 2527Defines the footnote indent. 2528 2529Effective: next footnote. 2530 2531Default: 2@dmn{n}. 2532@endDefmpreg 2533 2534@Defmpreg {FF, ms} 2535The footnote format: 2536@table @code 2537@item 0 2538Prints the footnote number as a superscript; indents the footnote (default). 2539 2540@item 1 2541Prints the number followed by a period (like 1.) 2542and indents the footnote. 2543 2544@item 2 2545Like 1, without an indent. 2546 2547@item 3 2548Like 1, but prints the footnote number as a hanging paragraph. 2549@end table 2550 2551Effective: next footnote. 2552 2553Default: 0. 2554@endDefmpreg 2555 2556@unnumberedsubsubsec Miscellaneous Number Registers 2557 2558@Defmpreg {MINGW, ms} 2559Defines the minimum width between columns in a multi-column document. 2560 2561Effective: next page. 2562 2563Default: 2@dmn{n}. 2564@endDefmpreg 2565 2566@c --------------------------------------------------------------------- 2567 2568@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms 2569@subsection Cover page macros 2570@cindex @code{ms} macros, cover page 2571@cindex cover page macros, [@code{ms}] 2572 2573Use the following macros to create a cover page for your document 2574in the order shown. 2575 2576@Defmac {RP, [@code{no}], ms} 2577Specifies the report format for your document. 2578The report format creates a separate cover page. 2579The default action (no @code{.RP} 2580macro) is to print a subset of the 2581cover page on page 1 of your document. 2582 2583If you use the word @code{no} as an optional argument, 2584@code{groff} prints a title page but 2585does not repeat any of the title page information 2586(title, author, abstract, etc.) 2587on page 1 of the document. 2588@endDefmac 2589 2590@Defmac {DA, [@dots{}], ms} 2591(optional) Print the current date, or the arguments to the macro if any, 2592on the title page (if specified) and in the footers. 2593This is the default for @code{nroff}. 2594@endDefmac 2595 2596@Defmac {ND, [@dots{}], ms} 2597(optional) Print the current date, or the arguments to the macro if any, 2598on the title page (if specified) but not in the footers. 2599This is the default for @code{troff}. 2600@endDefmac 2601 2602@Defmac {TL, , ms} 2603Specifies the document title. 2604@code{groff} collects text following the @code{.TL} 2605macro into the title, until reaching the author name or abstract. 2606@endDefmac 2607 2608@Defmac {AU, , ms} 2609Specifies the author's name, which appears on the 2610line (or lines) immediately following. 2611You can specify multiple authors as follows: 2612 2613@Example 2614.AU 2615John Doe 2616.AI 2617University of West Bumblefuzz 2618.AU 2619Martha Buck 2620.AI 2621Monolithic Corporation 2622 2623... 2624@endExample 2625@endDefmac 2626 2627@Defmac {AI, , ms} 2628Specifies the author's institution. 2629You can specify multiple institutions in the same way 2630that you specify multiple authors. 2631@endDefmac 2632 2633@Defmac {AB, [@code{no}], ms} 2634Begins the abstract. 2635The default is to print the word @acronym{ABSTRACT}, 2636centered and in italics, above the text of the abstract. 2637The word @code{no} as an optional argument suppresses this heading. 2638@endDefmac 2639 2640@Defmac {AE, , ms} 2641End the abstract. 2642@endDefmac 2643 2644The following is example mark-up for a title page. 2645@cindex title page, example markup 2646@cindex example markup, title page 2647 2648@Example 2649@cartouche 2650.RP 2651.TL 2652The Inevitability of Code Bloat 2653in Commercial and Free Software 2654.AU 2655J. Random Luser 2656.AI 2657University of West Bumblefuzz 2658.AB 2659This report examines the long-term growth 2660of the code bases in two large, popular software 2661packages; the free Emacs and the commercial 2662Microsoft Word. 2663While differences appear in the type or order 2664of features added, due to the different 2665methodologies used, the results are the same 2666in the end. 2667.PP 2668The free software approach is shown to be 2669superior in that while free software can 2670become as bloated as commercial offerings, 2671free software tends to have fewer serious 2672bugs and the added features are in line with 2673user demand. 2674.AE 2675 2676... the rest of the paper follows ... 2677@end cartouche 2678@endExample 2679 2680@c --------------------------------------------------------------------- 2681 2682@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms 2683@subsection Body text 2684@cindex @code{ms} macros, body text 2685 2686This section describes macros used to mark up the body of your document. 2687Examples include paragraphs, sections, and other groups. 2688 2689@menu 2690* Paragraphs in ms:: 2691* Headings in ms:: 2692* Highlighting in ms:: 2693* Lists in ms:: 2694* Indents in ms:: 2695* Tabstops in ms:: 2696* ms Displays and Keeps:: 2697* ms Insertions:: 2698* Example multi-page table:: 2699* ms Footnotes:: 2700@end menu 2701 2702@c --------------------------------------------------------------------- 2703 2704@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text 2705@subsubsection Paragraphs 2706@cindex @code{ms} macros, paragraph handling 2707 2708The following paragraph types are available. 2709 2710@Defmac {PP, , ms} 2711Sets a paragraph with an initial indent. 2712@endDefmac 2713 2714@Defmac {LP, , ms} 2715Sets a paragraph with no initial indent. 2716@endDefmac 2717 2718@Defmac {QP, , ms} 2719Sets a paragraph that is indented at both left and right margins. 2720The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element. 2721The next paragraph or heading returns margins to normal. 2722@endDefmac 2723 2724@Defmac {XP, , ms} 2725Sets a paragraph whose lines are indented, 2726except for the first line. 2727This is a Berkeley extension. 2728@endDefmac 2729 2730The following markup uses all four paragraph macros. 2731 2732@Example 2733@cartouche 2734.NH 2 2735Cases used in the study 2736.LP 2737The following software and versions were 2738considered for this report. 2739.PP 2740For commercial software, we chose 2741.B "Microsoft Word for Windows" , 2742starting with version 1.0 through the 2743current version (Word 2000). 2744.PP 2745For free software, we chose 2746.B Emacs , 2747from its first appearance as a standalone 2748editor through the current version (v20). 2749See [Bloggs 2002] for details. 2750.QP 2751Franklin's Law applied to software: 2752software expands to outgrow both 2753RAM and disk space over time. 2754.LP 2755Bibliography: 2756.XP 2757Bloggs, Joseph R., 2758.I "Everyone's a Critic" , 2759Underground Press, March 2002. 2760A definitive work that answers all questions 2761and criticisms about the quality and usability of 2762free software. 2763 2764@end cartouche 2765@endExample 2766 2767@c --------------------------------------------------------------------- 2768 2769@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text 2770@subsubsection Headings 2771@cindex @code{ms} macros, headings 2772 2773Use headings to create a hierarchical structure for your document. 2774The @file{ms} macros print headings in @strong{bold}, 2775using the same font family and point size as the body text. 2776 2777The following describes the heading macros: 2778 2779@DefmacList {NH, @Var{curr-level}, ms} 2780@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms} 2781Numbered heading. 2782The argument is either a numeric argument to indicate the 2783level of the heading, or the letter@w{ }@code{S} followed by numeric 2784arguments to set the heading level explicitly. 2785 2786If you specify heading levels out of sequence, such as invoking 2787@samp{.NH 3} after @samp{.NH 1}, @code{groff} 2788prints a warning on standard error. 2789@endDefmac 2790 2791@Defmac {SH, , ms} 2792Unnumbered subheading. 2793@endDefmac 2794 2795@c --------------------------------------------------------------------- 2796 2797@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text 2798@subsubsection Highlighting 2799@cindex @code{ms} macros, highlighting 2800 2801The @file{ms} macros provide a variety of methods to highlight 2802or emphasize text: 2803 2804@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2805Sets its first argument in @strong{bold type}. 2806If you specify a second argument, @code{groff} prints it in the 2807previous font after the bold text, with no intervening space 2808(this allows you to set punctuation after the highlighted text 2809without highlighting the punctuation). 2810Similarly, it prints the third argument (if any) in the previous 2811font @strong{before} the first argument. 2812For example, 2813 2814@Example 2815.B foo ) ( 2816@endExample 2817 2818prints (@strong{foo}). 2819 2820If you give this macro no arguments, @code{groff} 2821prints all text following in bold until 2822the next highlighting, paragraph, or heading macro. 2823@endDefmac 2824 2825@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2826Sets its first argument in roman (or regular) type. 2827It operates similarly to the @code{B}@w{ }macro otherwise. 2828@endDefmac 2829 2830@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2831Sets its first argument in @emph{italic type}. 2832It operates similarly to the @code{B}@w{ }macro otherwise. 2833@endDefmac 2834 2835@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2836Sets its first argument in a @code{constant width face}. 2837It operates similarly to the @code{B}@w{ }macro otherwise. 2838@endDefmac 2839 2840@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 2841Sets its first argument in bold italic type. 2842It operates similarly to the @code{B}@w{ }macro otherwise. 2843@endDefmac 2844 2845@Defmac {BX, [@Var{txt}], ms} 2846Prints its argument and draws a box around it. 2847If you want to box a string that contains spaces, 2848use a digit-width space (@code{\0}). 2849@endDefmac 2850 2851@Defmac {UL, [@Var{txt} [@Var{post}]], ms} 2852Prints its first argument with an underline. 2853If you specify a second argument, @code{groff} 2854prints it in the previous font after 2855the underlined text, with no intervening space. 2856@endDefmac 2857 2858@Defmac {LG, , ms} 2859Prints all text following in larger type 2860(two points larger than the current point size) until 2861the next font size, highlighting, paragraph, or heading macro. 2862You can specify this macro multiple times 2863to enlarge the point size as needed. 2864@endDefmac 2865 2866@Defmac {SM, , ms} 2867Prints all text following in smaller type 2868(two points smaller than the current point size) until 2869the next type size, highlighting, paragraph, or heading macro. 2870You can specify this macro multiple times 2871to reduce the point size as needed. 2872@endDefmac 2873 2874@Defmac {NL, , ms} 2875Prints all text following in the normal point size 2876(that is, the value of the @code{PS} register). 2877@endDefmac 2878 2879@c --------------------------------------------------------------------- 2880 2881@node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text 2882@subsubsection Lists 2883@cindex @code{ms} macros, lists 2884 2885The @code{.IP} macro handles duties for all lists. 2886 2887@Defmac {IP, [@Var{marker} [@Var{width}]], ms} 2888The @var{marker} is usually a bullet glyph (@code{\[bu]}) 2889for unordered lists, a number (or auto-incrementing number 2890register) for numbered lists, or a word or phrase for indented 2891(glossary-style) lists. 2892 2893The @var{width} specifies the indent for the body of each list item; 2894its default unit is @samp{n}. 2895Once specified, the indent remains the same for all 2896list items in the document until specified again. 2897@endDefmac 2898 2899The following is an example of a bulleted list. 2900@cindex example markup, bulleted list [@code{ms}] 2901@cindex bulleted list, example markup [@code{ms}] 2902 2903@Example 2904A bulleted list: 2905.IP \[bu] 2 2906lawyers 2907.IP \[bu] 2908guns 2909.IP \[bu] 2910money 2911@endExample 2912 2913Produces: 2914 2915@Example 2916A bulleted list: 2917 2918o lawyers 2919 2920o guns 2921 2922o money 2923@endExample 2924 2925@sp 1 2926 2927The following is an example of a numbered list. 2928@cindex example markup, numbered list [@code{ms}] 2929@cindex numbered list, example markup [@code{ms}] 2930 2931@Example 2932.nr step 1 1 2933A numbered list: 2934.IP \n[step] 3 2935lawyers 2936.IP \n+[step] 2937guns 2938.IP \n+[step] 2939money 2940@endExample 2941 2942Produces: 2943 2944@Example 2945A numbered list: 2946 29471. lawyers 2948 29492. guns 2950 29513. money 2952@endExample 2953 2954Note the use of the auto-incrementing number 2955register in this example. 2956 2957@sp 1 2958The following is an example of a glossary-style list. 2959@cindex example markup, glossary-style list [@code{ms}] 2960@cindex glossary-style list, example markup [@code{ms}] 2961 2962@Example 2963A glossary-style list: 2964.IP lawyers 0.4i 2965Two or more attorneys. 2966.IP guns 2967Firearms, preferably 2968large-caliber. 2969.IP money 2970Gotta pay for those 2971lawyers and guns! 2972@endExample 2973 2974Produces: 2975 2976@Example 2977A glossary-style list: 2978 2979lawyers 2980 Two or more attorneys. 2981 2982guns Firearms, preferably large-caliber. 2983 2984money 2985 Gotta pay for those lawyers and guns! 2986@endExample 2987 2988In the last example, the @code{IP} macro places the definition 2989on the same line as the term if it has enough space; otherwise, 2990it breaks to the next line and starts the definition below the 2991term. 2992This may or may not be the effect you want, especially if some 2993of the definitions break and some do not. 2994The following examples show two possible ways to force a break. 2995 2996The first workaround uses the @code{br} 2997request to force a break after printing the term or label. 2998 2999@Example 3000@cartouche 3001A glossary-style list: 3002.IP lawyers 0.4i 3003Two or more attorneys. 3004.IP guns 3005.br 3006Firearms, preferably large-caliber. 3007.IP money 3008Gotta pay for those lawyers and guns! 3009@end cartouche 3010@endExample 3011 3012@sp 1 3013The second workaround uses the @code{\p} escape to force the break. 3014Note the space following the escape; this is important. 3015If you omit the space, @code{groff} prints the first word on 3016the same line as the term or label (if it fits) @strong{then} 3017breaks the line. 3018 3019@Example 3020@cartouche 3021A glossary-style list: 3022.IP lawyers 0.4i 3023Two or more attorneys. 3024.IP guns 3025\p Firearms, preferably large-caliber. 3026.IP money 3027Gotta pay for those lawyers and guns! 3028@end cartouche 3029@endExample 3030 3031@sp 1 3032To set nested lists, use the @code{RS} and @code{RE} macros. 3033@xref{Indents in ms}, for more information. 3034@cindex @code{ms} macros, nested lists 3035@cindex nested lists [@code{ms}] 3036 3037For example: 3038 3039@Example 3040@cartouche 3041.IP \[bu] 2 3042Lawyers: 3043.RS 3044.IP \[bu] 3045Dewey, 3046.IP \[bu] 3047Cheatham, 3048.IP \[bu] 3049and Howe. 3050.RE 3051.IP \[bu] 3052Guns 3053@end cartouche 3054@endExample 3055 3056Produces: 3057 3058@Example 3059o Lawyers: 3060 3061 o Dewey, 3062 3063 o Cheatham, 3064 3065 o and Howe. 3066 3067o Guns 3068@endExample 3069 3070@c --------------------------------------------------------------------- 3071 3072@node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text 3073@subsubsection Indents 3074 3075In many situations, 3076you may need to indent a section of text 3077while still wrapping and filling. 3078@xref{Lists in ms}, 3079for an example of nested lists. 3080 3081@DefmacList {RS, , ms} 3082@DefmacListEnd {RE, , ms} 3083These macros begin and end an indented section. 3084The @code{PI} register controls the amount of indent, 3085allowing the indented text to line up under hanging 3086and indented paragraphs. 3087@endDefmac 3088 3089@xref{ms Displays and Keeps}, 3090for macros to indent and turn off filling. 3091 3092@c --------------------------------------------------------------------- 3093 3094@node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text 3095@subsubsection Tab Stops 3096 3097Use the @code{ta} request to define tab stops as needed. 3098@xref{Tabs and Fields}. 3099 3100@Defmac{TA, , ms} 3101Use this macro to reset the tab stops to the default for @file{ms} 3102(every 5n). 3103You can redefine the @code{TA} macro to create a different set 3104of default tab stops. 3105@endDefmac 3106 3107@c --------------------------------------------------------------------- 3108 3109@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text 3110@subsubsection Displays and keeps 3111@cindex @code{ms} macros, displays 3112@cindex @code{ms} macros, keeps 3113@cindex keeps [@code{ms}] 3114@cindex displays [@code{ms}] 3115 3116Use displays to show text-based examples or figures 3117(such as code listings). 3118 3119Displays turn off filling, so lines of code are displayed 3120as-is without inserting @code{br} requests in between each line. 3121Displays can be @dfn{kept} on a single page, or allowed 3122to break across pages. 3123 3124@DefmacList {DS, @t{L}, ms} 3125@DefmacItem {LD, , ms} 3126@DefmacListEnd {DE, , ms} 3127Left-justified display. 3128The @samp{.DS L} call generates a page break, if necessary, 3129to keep the entire display on one page. 3130The @code{LD} macro allows the display to break across pages. 3131The @code{DE} macro ends the display. 3132@endDefmac 3133 3134@DefmacList {DS, @t{I}, ms} 3135@DefmacItem {ID, , ms} 3136@DefmacListEnd {DE, , ms} 3137Indents the display as defined by the @code{DI} register. 3138The @samp{.DS I} call generates a page break, if necessary, 3139to keep the entire display on one page. 3140The @code{ID} macro allows the display to break across pages. 3141The @code{DE} macro ends the display. 3142@endDefmac 3143 3144@DefmacList {DS, @t{B}, ms} 3145@DefmacItem {BD, , ms} 3146@DefmacListEnd {DE, , ms} 3147Sets a block-centered display: the entire display is left-justified, 3148but indented so that the longest line in the display is centered 3149on the page. 3150The @samp{.DS B} call generates a page break, if necessary, 3151to keep the entire display on one page. 3152The @code{BD} macro allows the display to break across pages. 3153The @code{DE} macro ends the display. 3154@endDefmac 3155 3156@DefmacList {DS, @t{C}, ms} 3157@DefmacItem {CD, , ms} 3158@DefmacListEnd {DE, , ms} 3159Sets a centered display: each line in the display is centered. 3160The @samp{.DS C} call generates a page break, if necessary, 3161to keep the entire display on one page. 3162The @code{CD} macro allows the display to break across pages. 3163The @code{DE} macro ends the display. 3164@endDefmac 3165 3166@DefmacList {DS, @t{R}, ms} 3167@DefmacItem {RD, , ms} 3168@DefmacListEnd {DE, , ms} 3169Right-justifies each line in the display. 3170The @samp{.DS R} call generates a page break, if necessary, 3171to keep the entire display on one page. 3172The @code{RD} macro allows the display to break across pages. 3173The @code{DE} macro ends the display. 3174@endDefmac 3175 3176@sp 1 3177On occasion, you may want to @dfn{keep} other text together on a page. 3178For example, you may want to keep two paragraphs together, or 3179a paragraph that refers to a table (or list, or other item) 3180immediately following. 3181The @file{ms} macros provide the @code{KS} and @code{KE} 3182macros for this purpose. 3183 3184@DefmacList {KS, , ms} 3185@DefmacListEnd {KE, , ms} 3186The @code{KS} macro begins a block of text to be kept on a 3187single page, and the @code{KE} macro ends the block. 3188@endDefmac 3189 3190@DefmacList {KF, , ms} 3191@DefmacListEnd {KE, , ms} 3192Specifies a @dfn{floating keep}; 3193if the keep cannot fit on the current page, @code{groff} 3194holds the contents of the keep and allows text following 3195the keep (in the source file) to fill in the remainder of 3196the current page. 3197When the page breaks, whether by an explicit @code{bp} 3198request or by reaching the end of the page, @code{groff} 3199prints the floating keep at the top of the new page. 3200This is useful for printing large graphics or tables 3201that do not need to appear exactly where specified. 3202@endDefmac 3203 3204You can also use the @code{ne} request to force a page break if 3205there is not enough vertical space remaining on the page. 3206 3207@sp 1 3208Use the following macros to draw a box around a section of 3209text (such as a display). 3210 3211@DefmacList {B1, , ms} 3212@DefmacListEnd {B2, , ms} 3213Marks the beginning and ending of text that is to have a 3214box drawn around it. 3215The @code{B1} macro begins the box; the @code{B2} macro ends it. 3216Text in the box is automatically placed in a diversion (keep). 3217@endDefmac 3218 3219@c --------------------------------------------------------------------- 3220 3221@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text 3222@subsubsection Tables, figures, equations, and references 3223@cindex @code{ms} macros, tables 3224@cindex @code{ms} macros, figures 3225@cindex @code{ms} macros, equations 3226@cindex @code{ms} macros, references 3227@cindex tables [@code{ms}] 3228@cindex figures [@code{ms}] 3229@cindex equations [@code{ms}] 3230@cindex references [@code{ms}] 3231 3232The @file{ms} macros support the standard 3233@code{groff} preprocessors: 3234@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}. 3235@pindex tbl 3236@pindex pic 3237@pindex eqn 3238@pindex refer 3239You mark text meant for preprocessors by enclosing it 3240in pairs of tags as follows. 3241 3242@DefmacList {TS, [@code{H}], ms} 3243@DefmacListEnd {TE, , ms} 3244Denotes a table, to be processed by the @code{tbl} preprocessor. 3245The optional argument@w{ }@code{H} to @code{TS} instructs @code{groff} 3246to create a running header with the information 3247up to the @code{TH} macro. 3248@code{groff} prints the header at the beginning of the 3249table; if the table runs onto another page, @code{groff} 3250prints the header on the next page as well. 3251@endDefmac 3252 3253@DefmacList {PS, , ms} 3254@DefmacListEnd {PE, , ms} 3255Denotes a graphic, to be processed by the @code{pic} preprocessor. 3256You can create a @code{pic} file by hand, using the @acronym{AT&T} 3257@code{pic} manual available on the Web as a reference, or by using 3258a graphics program such as @code{xfig}. 3259@endDefmac 3260 3261@DefmacList {EQ, [@Var{align}], ms} 3262@DefmacListEnd {EN, , ms} 3263Denotes an equation, to be processed by the @code{eqn} preprocessor. 3264The optional @var{align} argument can be @code{C}, @code{L}, or@w{ 3265}@code{I} to center (the default), left-justify, or indent the equation. 3266@endDefmac 3267 3268@DefmacList {[, , ms} 3269@DefmacListEnd {], , ms} 3270Denotes a reference, to be processed by the @code{refer} preprocessor. 3271The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive 3272reference to the preprocessor and the format of the bibliographic 3273database. 3274@endDefmac 3275 3276@menu 3277* Example multi-page table:: 3278@end menu 3279 3280@c --------------------------------------------------------------------- 3281 3282@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text 3283@subsubsection An example multi-page table 3284@cindex example markup, multi-page table [@code{ms}] 3285@cindex multi-page table, example markup [@code{ms}] 3286 3287The following is an example of how to set up a 3288table that may print across two or more pages. 3289 3290@Example 3291@cartouche 3292.TS H 3293allbox expand; 3294cb | cb . 3295Text ...of heading... 3296_ 3297.TH 3298.T& 3299l | l . 3300... the rest of the table follows... 3301.CW 3302.TE 3303@end cartouche 3304@endExample 3305 3306@c --------------------------------------------------------------------- 3307 3308@node ms Footnotes, , Example multi-page table, ms Body Text 3309@subsubsection Footnotes 3310@cindex @code{ms} macros, footnotes 3311@cindex footnotes [@code{ms}] 3312 3313The @file{ms} macro package has a flexible footnote system. 3314You can specify either numbered footnotes or symbolic footnotes 3315(that is, using a marker such as a dagger symbol). 3316 3317@Defstr {*, ms} 3318Specifies the location of a numbered footnote marker in the text. 3319@endDefesc 3320 3321@DefmacList {FS, , ms} 3322@DefmacListEnd {FE, , ms} 3323Specifies the text of the footnote. 3324The default action is to create a numbered footnote; 3325you can create a symbolic footnote by specifying 3326a @dfn{mark} glyph 3327(such as @code{\[dg]} for the dagger glyph) 3328in the body text and as an argument to the @code{FS} macro, 3329followed by the text of the footnote 3330and the @code{FE} macro. 3331@endDefmac 3332 3333You can control how @code{groff} 3334prints footnote numbers by changing the value of the 3335@code{FF} register. @xref{ms Document Control Registers}. 3336 3337@c --------------------------------------------------------------------- 3338 3339@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms 3340@subsection Page layout 3341@cindex @code{ms} macros, page layout 3342@cindex page layout [@code{ms}] 3343 3344The default output from the @file{ms} 3345macros provides a minimalist page layout: 3346it prints a single column, with the page number centered at the top 3347of each page. 3348It prints no footers. 3349 3350You can change the layout by setting 3351the proper number registers and strings. 3352 3353@menu 3354* ms Headers and Footers:: 3355* ms Margins:: 3356* ms Multiple Columns:: 3357* ms TOC:: 3358* ms Strings and Special Characters:: 3359@end menu 3360 3361@c --------------------------------------------------------------------- 3362 3363@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout 3364@subsubsection Headers and footers 3365@cindex @code{ms} macros, headers 3366@cindex @code{ms} macros, footers 3367@cindex headers [@code{ms}] 3368@cindex footers [@code{ms}] 3369 3370For documents that do not distinguish between odd and even pages, 3371set the following strings: 3372 3373@DefstrList {LH, ms} 3374@DefstrItem {CH, ms} 3375@DefstrListEnd {RH, ms} 3376Sets the left, center, and right headers. 3377@endDefstr 3378 3379@DefstrList {LF, ms} 3380@DefstrItem {CF, ms} 3381@DefstrListEnd {RF, ms} 3382Sets the left, center, and right footers. 3383@endDefstr 3384 3385@sp 1 3386For documents that need different information printed in the 3387even and odd pages, use the following macros: 3388 3389@DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3390@DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3391@DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3392@DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3393The @code{OH} and @code{EH} macros define headers for the odd and even pages; 3394the @code{OF} and @code{EF} macros define footers for the odd and even pages. 3395This is more flexible than defining the individual strings. 3396 3397You can replace the quote (@code{'}) marks with any character not 3398appearing in the header or footer text. 3399@endDefmac 3400 3401@c --------------------------------------------------------------------- 3402 3403@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout 3404@subsubsection Margins 3405@cindex @code{ms} macros, margins 3406 3407You control margins using a set of number registers. 3408@xref{ms Document Control Registers}, for details. 3409 3410@c --------------------------------------------------------------------- 3411 3412@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout 3413@subsubsection Multiple columns 3414@cindex @code{ms} macros, multiple columns 3415@cindex multiple columns [@code{ms}] 3416 3417The @file{ms} macros can set text in as many columns as will 3418reasonably fit on the page. 3419The following macros are available; 3420all of them force a page break if a multi-column mode is already set. 3421However, if the current mode is single-column, starting a multi-column 3422mode does @strong{not} force a page break. 3423 3424@Defmac {1C, , ms} 3425Single-column mode. 3426@endDefmac 3427 3428@Defmac {2C, , ms} 3429Two-column mode. 3430@endDefmac 3431 3432@Defmac {MC, [@Var{width} [@Var{gutter}]], ms} 3433Multi-column mode. 3434If you specify no arguments, it is equivalent to the 3435@code{2C} macro. 3436Otherwise, @var{width} is the width of each column and 3437@var{gutter} is the space between columns. 3438The @code{MINGW} number register controls the default gutter width. 3439@endDefmac 3440 3441@c --------------------------------------------------------------------- 3442 3443@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout 3444@subsubsection Creating a table of contents 3445@cindex @code{ms} macros, creating table of contents 3446@cindex table of contents, creating [@code{ms}] 3447 3448The facilities in the @file{ms} macro package for creating 3449a table of contents are semi-automated at best. 3450Assuming that you want the table of contents to consist of 3451the document's headings, you need to repeat those headings 3452wrapped in @code{XS} and @code{XE} macros. 3453 3454@DefmacList {XS, [@Var{page}], ms} 3455@DefmacItem {XA, [@Var{page}], ms} 3456@DefmacListEnd {XE, , ms} 3457These macros define a table of contents 3458or an individual entry in the table of contents, 3459depending on their use. 3460The macros are very simple; they cannot indent a heading based on its level. 3461The easiest way to work around this is to add tabs 3462to the table of contents string. 3463The following is an example: 3464 3465@Example 3466@cartouche 3467.NH 1 3468Introduction 3469.XS 3470Introduction 3471.XE 3472.LP 3473... 3474.CW 3475.NH 2 3476Methodology 3477.XS 3478 Methodology 3479.XE 3480.LP 3481... 3482@end cartouche 3483@endExample 3484 3485You can manually create a table of contents 3486by beginning with the @code{XS} macro for the first entry, 3487specifying the page number for that entry as the argument to @code{XS}. 3488Add subsequent entries using the @code{XA} macro, 3489specifying the page number for that entry as the argument to @code{XA}. 3490The following is an example: 3491 3492@Example 3493@cartouche 3494.XS 1 3495Introduction 3496.XA 2 3497A Brief History of the Universe 3498.XA 729 3499Details of Galactic Formation 3500... 3501.XE 3502@end cartouche 3503@endExample 3504@endDefmac 3505 3506@Defmac {TC, [@code{no}], ms} 3507Prints the table of contents on a new page, 3508setting the page number to@w{ }@strong{i} (Roman numeral one). 3509You should usually place this macro at the end of the 3510file, since @code{groff} is a single-pass formatter and 3511can only print what has been collected up to the point 3512that the @code{TC} macro appears. 3513 3514The optional argument @code{no} suppresses printing 3515the title specified by the string register @code{TOC}. 3516@endDefmac 3517 3518@Defmac{PX, [@code{no}], ms} 3519Prints the table of contents on a new page, 3520using the current page numbering sequence. 3521Use this macro to print a manually-generated table of contents 3522at the beginning of your document. 3523 3524The optional argument @code{no} suppresses printing 3525the title specified by the string register @code{TOC}. 3526@endDefmac 3527 3528The @cite{Groff and Friends HOWTO} 3529includes a @code{sed} script that automatically inserts 3530@code{XS} and @code{XE} macro entries after each heading in a document. 3531 3532Altering the @code{NH} macro to automatically build the table 3533of contents is perhaps initially more difficult, but would save 3534a great deal of time in the long run if you use @file{ms} regularly. 3535 3536@c --------------------------------------------------------------------- 3537 3538@node ms Strings and Special Characters, , ms TOC, ms Page Layout 3539@subsubsection Strings and Special Characters 3540@cindex @code{ms} macros, strings 3541@cindex @code{ms} macros, special characters 3542@cindex @code{ms} macros, accent marks 3543@cindex accent marks [@code{ms}] 3544@cindex special characters [@code{ms}] 3545@cindex strings [@code{ms}] 3546 3547The @file{ms} macros provide the following predefined strings. 3548You can change the string definitions to help in creating 3549documents in languages other than English. 3550 3551@Defstr {REFERENCES, ms} 3552Contains the string printed at the beginning of the 3553references (bibliography) page. 3554The default is @samp{References}. 3555@endDefstr 3556 3557@Defstr {ABSTRACT, ms} 3558Contains the string printed at the beginning of the abstract. 3559The default is @samp{ABSTRACT}. 3560@endDefstr 3561 3562@Defstr {TOC, ms} 3563Contains the string printed at the beginning of the table of contents. 3564@endDefstr 3565 3566@DefstrList {MONTH1, ms} 3567@DefstrItem {MONTH2, ms} 3568@DefstrItem {MONTH3, ms} 3569@DefstrItem {MONTH4, ms} 3570@DefstrItem {MONTH5, ms} 3571@DefstrItem {MONTH6, ms} 3572@DefstrItem {MONTH7, ms} 3573@DefstrItem {MONTH8, ms} 3574@DefstrItem {MONTH9, ms} 3575@DefstrItem {MONTH10, ms} 3576@DefstrItem {MONTH11, ms} 3577@DefstrListEnd {MONTH12, ms} 3578Prints the full name of the month in dates. 3579The default is @samp{January}, @samp{February}, etc. 3580@endDefstr 3581 3582The following special characters are available@footnote{For an 3583explanation what special characters are see @ref{Special Characters}.}: 3584 3585@Defstr {-, ms} 3586Prints an em dash. 3587@endDefstr 3588 3589@DefstrList {*Q, ms} 3590@DefstrListEnd {*U, ms} 3591Prints typographer's quotes in troff, 3592plain quotes in nroff. 3593@code{*Q} is the left quote and @code{*U} is the right quote. 3594@endDefstr 3595 3596Improved accent marks are available in the @file{ms} macros. 3597 3598@Defmac {AM, , ms} 3599Specify this macro at the beginning of your document 3600to enable extended accent marks and special characters. 3601This is a Berkeley extension. 3602 3603To use the accent marks, place them @strong{after} 3604the character being accented. 3605@endDefmac 3606 3607The following accent marks are available 3608after invoking the @code{AM} macro: 3609 3610@Defstr {\', ms} 3611Acute accent. 3612@endDefstr 3613 3614@Defstr {\`, ms} 3615Grave accent. 3616@endDefstr 3617 3618@Defstr {^, ms} 3619Circumflex. 3620@endDefstr 3621 3622@Defstr {\,, ms} 3623Cedilla. 3624@endDefstr 3625 3626@Defstr {~, ms} 3627Tilde. 3628@endDefstr 3629 3630@deffn String @t{\*[:]} 3631@ifnotinfo 3632@stindex : @r{[}ms@r{]} 3633@end ifnotinfo 3634@ifinfo 3635@stindex @r{<colon>} @r{[}ms@r{]} 3636@end ifinfo 3637Umlaut. 3638@end deffn 3639 3640@Defstr {v, ms} 3641Hacek. 3642@endDefstr 3643 3644@Defstr {_, ms} 3645Macron (overbar). 3646@endDefstr 3647 3648@Defstr {., ms} 3649Underdot. 3650@endDefstr 3651 3652@Defstr {o, ms} 3653Ring above. 3654@endDefstr 3655 3656The following are standalone characters 3657available after invoking the @code{AM} macro: 3658 3659@Defstr {?, ms} 3660Upside-down question mark. 3661@endDefstr 3662 3663@Defstr {!, ms} 3664Upside-down exclamation point. 3665@endDefstr 3666 3667@Defstr {8, ms} 3668German @ss{} ligature. 3669@endDefstr 3670 3671@Defstr {3, ms} 3672Yogh. 3673@endDefstr 3674 3675@Defstr {Th, ms} 3676Uppercase thorn. 3677@endDefstr 3678 3679@Defstr {th, ms} 3680Lowercase thorn. 3681@endDefstr 3682 3683@Defstr {D-, ms} 3684Uppercase eth. 3685@endDefstr 3686 3687@Defstr {d-, ms} 3688Lowercase eth. 3689@endDefstr 3690 3691@Defstr {q, ms} 3692Hooked o. 3693@endDefstr 3694 3695@Defstr {ae, ms} 3696Lowercase @ae{} ligature. 3697@endDefstr 3698 3699@Defstr {Ae, ms} 3700Uppercase @AE{} ligature. 3701@endDefstr 3702 3703@c --------------------------------------------------------------------- 3704 3705@node Differences from AT&T ms, , ms Page Layout, ms 3706@subsection Differences from @acronym{AT&T} @file{ms} 3707@cindex @code{ms} macros, differences from @acronym{AT&T} 3708@cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences 3709 3710This section lists the (minor) differences between the 3711@code{groff -ms} macros and @acronym{AT&T} 3712@code{troff -ms} macros. 3713 3714@menu 3715* Missing ms Macros:: 3716* Additional ms Macros:: 3717@end menu 3718 3719@c --------------------------------------------------------------------- 3720 3721@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms 3722@subsubsection @code{troff} macros not appearing in @code{groff} 3723 3724Macros missing from @code{groff -ms} 3725are cover page macros specific to Bell Labs. 3726The macros known to be missing are: 3727 3728@table @code 3729@item .TM 3730Technical memorandum; a cover sheet style 3731 3732@item .IM 3733Internal memorandum; a cover sheet style 3734 3735@item .MR 3736Memo for record; a cover sheet style 3737 3738@item .MF 3739Memo for file; a cover sheet style 3740 3741@item .EG 3742Engineer's notes; a cover sheet style 3743 3744@item .TR 3745Computing Science Tech Report; a cover sheet style 3746 3747@item .OK 3748Other keywords 3749 3750@item .CS 3751Cover sheet information 3752 3753@item .MH 3754A cover sheet macro 3755@end table 3756 3757@c --------------------------------------------------------------------- 3758 3759@node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms 3760@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff} 3761 3762The @code{groff -ms} macros have a few minor extensions 3763compared to the @acronym{AT&T} @code{troff -ms} macros. 3764 3765@Defmac {AM, , ms} 3766Improved accent marks. 3767@xref{ms Strings and Special Characters}, for details. 3768@endDefmac 3769 3770@Defmac {DS, @t{I}, ms} 3771Indented display. 3772The default behavior of @acronym{AT&T} @code{troff -ms} 3773was to indent; the @code{groff} default prints displays 3774flush left with the body text. 3775@endDefmac 3776 3777@Defmac {CW, , ms} 3778Print text in @code{constant width} (Courier) font. 3779@endDefmac 3780 3781@Defmac {IX, , ms} 3782Indexing term (printed on standard error). 3783You can write a script to capture and process an index 3784generated in this manner. 3785@endDefmac 3786 3787@sp 1 3788The following additional number registers 3789appear in @code{groff -ms}: 3790 3791@Defmpreg {MINGW, ms} 3792Specifies a minimum space 3793between columns (for multi-column output); this takes the 3794place of the @code{GW} register that was documented but apparently 3795not implemented in @acronym{AT&T} @code{troff}. 3796@endDefmpreg 3797 3798@sp 1 3799Several new string registers are available as well. 3800You can change these to handle (for example) the local language. 3801@xref{ms Strings and Special Characters}, for details. 3802 3803 3804@c ===================================================================== 3805 3806@node me, mm, ms, Macro Packages 3807@section @file{me} 3808@cindex @code{me} macro package 3809 3810@c XXX documentation 3811@c XXX this is a placeholder until we get stuff knocked into shape 3812See the @file{meintro.me} and @file{meref.me} documents in 3813groff's @file{doc} directory. 3814 3815 3816@c ===================================================================== 3817 3818@node mm, , me, Macro Packages 3819@section @file{mm} 3820@cindex @code{mm} macro package 3821 3822@c XXX documentation 3823@c XXX this is a placeholder until we get stuff knocked into shape 3824See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at 3825the command line). 3826 3827 3828@c ===================================================================== 3829@c ===================================================================== 3830 3831@node gtroff Reference, Preprocessors, Macro Packages, Top 3832@chapter @code{gtroff} Reference 3833@cindex reference, @code{gtroff} 3834@cindex @code{gtroff}, reference 3835 3836This chapter covers @strong{all} of the facilities of @code{gtroff}. 3837Users of macro packages may skip it if not interested in details. 3838 3839 3840@menu 3841* Text:: 3842* Input Conventions:: 3843* Measurements:: 3844* Expressions:: 3845* Identifiers:: 3846* Embedded Commands:: 3847* Registers:: 3848* Manipulating Filling and Adjusting:: 3849* Manipulating Hyphenation:: 3850* Manipulating Spacing:: 3851* Tabs and Fields:: 3852* Character Translations:: 3853* Troff and Nroff Mode:: 3854* Line Layout:: 3855* Line Control:: 3856* Page Layout:: 3857* Page Control:: 3858* Fonts:: 3859* Sizes:: 3860* Strings:: 3861* Conditionals and Loops:: 3862* Writing Macros:: 3863* Page Motions:: 3864* Drawing Requests:: 3865* Traps:: 3866* Diversions:: 3867* Environments:: 3868* Suppressing output:: 3869* Colors:: 3870* I/O:: 3871* Postprocessor Access:: 3872* Miscellaneous:: 3873* Gtroff Internals:: 3874* Debugging:: 3875* Implementation Differences:: 3876@end menu 3877 3878 3879@c ===================================================================== 3880 3881@node Text, Input Conventions, gtroff Reference, gtroff Reference 3882@section Text 3883@cindex text, @code{gtroff} processing 3884 3885@code{gtroff} input files contain text with control commands 3886interspersed throughout. But, even without control codes, @code{gtroff} 3887still does several things with the input text: 3888 3889@itemize @bullet 3890@item 3891filling and adjusting 3892 3893@item 3894adding additional space after sentences 3895 3896@item 3897hyphenating 3898 3899@item 3900inserting implicit line breaks 3901@end itemize 3902 3903@menu 3904* Filling and Adjusting:: 3905* Hyphenation:: 3906* Sentences:: 3907* Tab Stops:: 3908* Implicit Line Breaks:: 3909@end menu 3910 3911@c --------------------------------------------------------------------- 3912 3913@node Filling and Adjusting, Hyphenation, Text, Text 3914@subsection Filling and Adjusting 3915@cindex filling 3916@cindex adjusting 3917 3918When @code{gtroff} reads text, it collects words from the input and fits 3919as many of them together on one output line as it can. This is known as 3920@dfn{filling}. 3921 3922@cindex leading spaces 3923@cindex spaces, leading and trailing 3924@cindex extra spaces 3925@cindex trailing spaces 3926Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} 3927it. This means it widens the spacing between words until the text 3928reaches the right margin (in the default adjustment mode). Extra spaces 3929between words are preserved, but spaces at the end of lines are ignored. 3930Spaces at the front of a line cause a @dfn{break} (breaks are 3931explained in @ref{Implicit Line Breaks}). 3932 3933@xref{Manipulating Filling and Adjusting}. 3934 3935@c --------------------------------------------------------------------- 3936 3937@node Hyphenation, Sentences, Filling and Adjusting, Text 3938@subsection Hyphenation 3939@cindex hyphenation 3940 3941Since the odds are not great for finding a set of words, for every 3942output line, which fit nicely on a line without inserting excessive 3943amounts of space between words, @code{gtroff} hyphenates words so 3944that it can justify lines without inserting too much space between 3945words. It uses an internal hyphenation algorithm (a simplified version 3946of the algorithm used within @TeX{}) to indicate which words can be 3947hyphenated and how to do so. When a word is hyphenated, the first part 3948of the word is added to the current filled line being output (with 3949an attached hyphen), and the other portion is added to the next 3950line to be filled. 3951 3952@xref{Manipulating Hyphenation}. 3953 3954@c --------------------------------------------------------------------- 3955 3956@node Sentences, Tab Stops, Hyphenation, Text 3957@subsection Sentences 3958@cindex sentences 3959 3960Although it is often debated, some typesetting rules say there should be 3961different amounts of space after various punctuation marks. For 3962example, the @cite{Chicago typsetting manual} says that a period at the 3963end of a sentence should have twice as much space following it as would 3964a comma or a period as part of an abbreviation. 3965 3966@c XXX exact citation of Chicago manual 3967 3968@cindex sentence space 3969@cindex space between sentences 3970@cindex french-spacing 3971@code{gtroff} does this by flagging certain characters (normally 3972@samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters. 3973When @code{gtroff} encounters one of these characters at the end of a 3974line, it appends a normal space followed by a @dfn{sentence space} in 3975the formatted output. (This justifies one of the conventions mentioned 3976in @ref{Input Conventions}.) 3977 3978@cindex transparent characters 3979@cindex character, transparent 3980@cindex @code{dg} glyph, at end of sentence 3981@cindex @code{rq} glyph, at end of sentence 3982@cindex @code{"}, at end of sentence 3983@cindex @code{'}, at end of sentence 3984@cindex @code{)}, at end of sentence 3985@cindex @code{]}, at end of sentence 3986@cindex @code{*}, at end of sentence 3987In addition, the following characters and symbols are treated 3988transparently while handling end-of-sentence characters: @samp{"}, 3989@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}. 3990 3991See the @code{cflags} request in @ref{Using Symbols}, for more details. 3992 3993@cindex @code{\&}, at end of sentence 3994To prevent the insertion of extra space after an end-of-sentence 3995character (at the end of a line), append @code{\&}. 3996 3997@c --------------------------------------------------------------------- 3998 3999@node Tab Stops, Implicit Line Breaks, Sentences, Text 4000@subsection Tab Stops 4001@cindex tab stops 4002@cindex stops, tabulator 4003@cindex tab character 4004@cindex character, tabulator 4005 4006@cindex @acronym{EBCDIC} encoding 4007@cindex encoding, @acronym{EBCDIC} 4008@code{gtroff} translates @dfn{tabulator characters}, also called 4009@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or 4010@acronym{EBCDIC} @code{0x05}), in the input into movements to the next 4011tabulator stop. These tab stops are initially located every half inch 4012across the page. Using this, simple tables can be made easily. 4013However, it can often be deceptive as the appearance (and width) of the 4014text on a terminal and the results from @code{gtroff} can vary greatly. 4015 4016Also, a possible sticking point is that lines beginning with tab 4017characters are still filled, again producing unexpected results. 4018For example, the following input 4019 4020@multitable {12345678} {12345678} {12345678} {12345678} 4021@item 4022@tab 1 @tab 2 @tab 3 4023@item 4024@tab @tab 4 @tab 5 4025@end multitable 4026 4027@noindent 4028produces 4029 4030@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} 4031@item 4032@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5 4033@end multitable 4034 4035@xref{Tabs and Fields}. 4036 4037@c --------------------------------------------------------------------- 4038 4039@node Implicit Line Breaks, , Tab Stops, Text 4040@subsection Implicit Line Breaks 4041@cindex implicit line breaks 4042@cindex implicit breaks of lines 4043@cindex line, implicit breaks 4044@cindex break, implicit 4045@cindex line break 4046 4047An important concept in @code{gtroff} is the @dfn{break}. When a break 4048occurs, @code{gtroff} outputs the partially filled line 4049(unjustified), and resumes collecting and filling text on the next output 4050line. 4051 4052@cindex blank line 4053@cindex empty line 4054@cindex line, blank 4055@cindex blank line macro (@code{blm}) 4056There are several ways to cause a break in @code{gtroff}. A blank 4057line not only causes a break, but it also outputs a one-line vertical 4058space (effectively a blank line). Note that this behaviour can be 4059modified with the blank line macro request @code{blm}. 4060@xref{Blank Line Traps}. 4061 4062@cindex fill mode 4063@cindex mode, fill 4064A line that begins with a space causes a break and the space is 4065output at the beginning of the next line. Note that this space isn't 4066adjusted, even in fill mode. 4067 4068The end of file also causes a break -- otherwise the last line of 4069the document may vanish! 4070 4071Certain requests also cause breaks, implicitly or explicitly. This is 4072discussed in @ref{Manipulating Filling and Adjusting}. 4073 4074 4075@c ===================================================================== 4076 4077@node Input Conventions, Measurements, Text, gtroff Reference 4078@section Input Conventions 4079@cindex input conventions 4080@cindex conventions for input 4081 4082Since @code{gtroff} does filling automatically, it is traditional in 4083@code{groff} not to try and type things in as nicely formatted 4084paragraphs. These are some conventions commonly used when typing 4085@code{gtroff} text: 4086 4087@itemize @bullet 4088@item 4089Break lines after punctuation, particularly at the end of a sentence 4090and in other logical places. Keep separate phrases on lines by 4091themselves, as entire phrases are often added or deleted when editing. 4092 4093@item 4094Try to keep lines less than 40-60@w{ }characters, to allow space for 4095inserting more text. 4096 4097@item 4098Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., 4099don't try using spaces to get proper indentation). 4100@end itemize 4101 4102 4103@c ===================================================================== 4104 4105@node Measurements, Expressions, Input Conventions, gtroff Reference 4106@section Measurements 4107@cindex measurements 4108 4109@cindex units of measurement 4110@cindex basic unit (@code{u}) 4111@cindex machine unit (@code{u}) 4112@cindex measurement unit 4113@cindex @code{u} unit 4114@cindex unit, @code{u} 4115@code{gtroff} (like many other programs) requires numeric parameters to 4116specify various measurements. Most numeric parameters@footnote{those 4117that specify vertical or horizontal motion or a type size} may have a 4118@dfn{measurement unit} attached. These units are specified as a single 4119character which immediately follows the number or expression. Each of 4120these units are understood, by @code{gtroff}, to be a multiple of its 4121@dfn{basic unit}. So, whenever a different measurement unit is 4122specified @code{gtroff} converts this into its @dfn{basic units}. This 4123basic unit, represented by a @samp{u}, is a device dependent measurement 4124which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an 4125inch. The values may be given as fractional numbers; however, 4126fractional basic units are always rounded to integers. 4127 4128Some of the measurement units are completely independent of any of the 4129current settings (e.g.@: type size) of @code{gtroff}. 4130 4131@table @code 4132@item i 4133@cindex inch unit (@code{i}) 4134@cindex @code{i} unit 4135@cindex unit, @code{i} 4136Inches. An antiquated measurement unit still in use in certain 4137backwards countries with incredibly low-cost computer equipment. One 4138inch is equal to@w{ }2.54@dmn{cm}. 4139 4140@item c 4141@cindex centimeter unit (@code{c}) 4142@cindex @code{c} unit 4143@cindex unit, @code{c} 4144Centimeters. One centimeter is equal to@w{ }0.3937@dmn{in}. 4145 4146@item p 4147@cindex point unit (@code{p}) 4148@cindex @code{p} unit 4149@cindex unit, @code{p} 4150Points. This is a typesetter's measurement used for measure type size. 4151It is 72@w{ }points to an inch. 4152 4153@item P 4154@cindex pica unit (@code{P}) 4155@cindex @code{P} unit 4156@cindex unit, @code{P} 4157Pica. Another typesetting measurement. 6@w{ }Picas to an inch (and 415812@w{ }points to a pica). 4159 4160@item s 4161@itemx z 4162@cindex @code{s} unit 4163@cindex unit, @code{s} 4164@cindex @code{z} unit 4165@cindex unit, @code{z} 4166@xref{Fractional Type Sizes}, for a discussion of these units. 4167 4168@item f 4169@cindex @code{f} unit 4170@cindex unit, @code{f} 4171Fractions. Value is 65536. 4172@xref{Colors}, for usage. 4173@end table 4174 4175The other measurements understood by @code{gtroff} depend on 4176settings currently in effect in @code{gtroff}. These are very useful 4177for specifying measurements which should look proper with any size of 4178text. 4179 4180@table @code 4181@item m 4182@cindex em unit (@code{m}) 4183@cindex @code{m} unit 4184@cindex unit, @code{m} 4185Ems. This unit is equal to the current font size in points. So called 4186because it is @emph{approximately} the width of the letter@w{ }@samp{m} 4187in the current font. 4188 4189@item n 4190@cindex en unit (@code{n}) 4191@cindex @code{n} unit 4192@cindex unit, @code{n} 4193Ens. In @code{groff}, this is half of an em. 4194 4195@item v 4196@cindex vertical space unit (@code{v}) 4197@cindex space, vertical, unit (@code{v}) 4198@cindex @code{v} unit 4199@cindex unit, @code{v} 4200Vertical space. This is equivalent to the current line spacing. 4201@xref{Sizes}, for more information about this. 4202 4203@item M 4204@cindex @code{M} unit 4205@cindex unit, @code{M} 4206100ths of an em. 4207@end table 4208 4209@menu 4210* Default Units:: 4211@end menu 4212 4213@c --------------------------------------------------------------------- 4214 4215@node Default Units, , Measurements, Measurements 4216@subsection Default Units 4217@cindex default units 4218@cindex units, default 4219 4220Many requests take a default unit. While this can be helpful at times, 4221it can cause strange errors in some expressions. For example, the line 4222length request expects em units. Here are several attempts to get a 4223line length of 3.5@w{ }inches and their results: 4224 4225@Example 42263.5i @result{} 3.5i 42277/2 @result{} 0i 42287/2i @result{} 0i 4229(7 / 2)u @result{} 0i 42307i/2 @result{} 0.1i 42317i/2u @result{} 3.5i 4232@endExample 4233 4234@noindent 4235Everything is converted to basic units first. In the above example it 4236is assumed that 1@dmn{i} equals@w{ }240@dmn{u}, and 1@dmn{m} equals@w{ 4237}10@dmn{p} (thus 1@dmn{m} equals@w{ }33@dmn{u}). The value 7@dmn{i}/2 4238is first handled as 7@dmn{i}/2@dmn{m}, then converted to 42391680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 42400.1@dmn{i}. As can be seen, a scaling indicator after a closing 4241parenthesis is simply ignored. 4242 4243@cindex measurements, specifying safely 4244Thus, the safest way to specify measurements is to always 4245attach a scaling indicator. If you want to multiply or divide by a 4246certain scalar value, use @samp{u} as the unit for that value. 4247 4248 4249@c ===================================================================== 4250 4251@node Expressions, Identifiers, Measurements, gtroff Reference 4252@section Expressions 4253@cindex expressions 4254 4255@code{gtroff} has most arithmetic operators common to other languages: 4256 4257@itemize @bullet 4258@item 4259@cindex arithmetic operators 4260@cindex operators, arithmetic 4261@opindex + 4262@opindex - 4263@opindex / 4264@opindex * 4265@opindex % 4266Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} 4267(division), @samp{*} (multiplication), @samp{%} (modulo). 4268 4269@code{gtroff} only provides integer arithmetic. The internal type used 4270for computing results is @samp{int}, which is usually a 32@dmn{bit} 4271signed integer. 4272 4273@item 4274@cindex comparison operators 4275@cindex operators, comparison 4276@opindex < 4277@opindex > 4278@opindex >= 4279@opindex <= 4280@opindex = 4281@opindex == 4282Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} 4283(less than or equal), @samp{>=} (greater than or equal), @samp{=} 4284(equal), @samp{==} (the same as @samp{=}). 4285 4286@item 4287@cindex logical operators 4288@cindex operators, logical 4289@opindex & 4290@ifnotinfo 4291@opindex : 4292@end ifnotinfo 4293@ifinfo 4294@opindex @r{<colon>} 4295@end ifinfo 4296Logical: @samp{&} (logical and), @samp{:} (logical or). 4297 4298@item 4299@cindex unary operators 4300@cindex operators, unary 4301@opindex - 4302@opindex + 4303@opindex ! 4304@cindex @code{if} request, and the @samp{!} operator 4305@cindex @code{while} request, and the @samp{!} operator 4306Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} 4307(just for completeness; does nothing in expressions), @samp{!} (logical 4308not; this works only within @code{if} and @code{while} requests). See 4309below for the use of unary operators in motion requests. 4310 4311@item 4312@cindex extremum operators (@code{>?}, @code{<?}) 4313@cindex operators, extremum (@code{>?}, @code{<?}) 4314@opindex >? 4315@opindex <? 4316Extrema: @samp{>?} (maximum), @samp{<?} (minimum). 4317 4318Example: 4319 4320@Example 4321.nr x 5 4322.nr y 3 4323.nr z (\n[x] >? \n[y]) 4324@endExample 4325 4326@noindent 4327The register@w{ }@code{z} now contains@w{ }5. 4328 4329@item 4330@cindex scaling operator 4331@cindex operator, scaling 4332Scaling: @code{(@var{c};@var{e})}. Evaluate@w{ }@var{e} using@w{ }@var{c} 4333as the default scaling indicator. If @var{c} is missing, ignore scaling 4334indicators in the evaluation of@w{ }@var{e}. 4335@end itemize 4336 4337@cindex parentheses 4338@cindex order of evaluation in expressions 4339@cindex expression, order of evaluation 4340@opindex ( 4341@opindex ) 4342Parentheses may be used as in any other language. However, in 4343@code{gtroff} they are necessary to ensure order of evaluation. 4344@code{gtroff} has no operator precedence; expressions are evaluated left 4345to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were 4346parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be 4347expected. 4348 4349@cindex @code{+}, and page motion 4350@cindex @code{-}, and page motion 4351@cindex motion operators 4352@cindex operators, motion 4353For many requests which cause a motion on the page, the unary operators 4354@samp{+} and @samp{-} work differently if leading an expression. They 4355then indicate a motion relative to the current position (down or up, 4356respectively). 4357 4358@cindex @code{|}, and page motion 4359@cindex absolute position operator (@code{|}) 4360@cindex position, absolute, operator (@code{|}) 4361Similarly, a leading @samp{|} operator indicates an absolute position. 4362For vertical movements, it specifies the distance from the top of the 4363page; for horizontal movements, it gives the distance from the beginning 4364of the @emph{input} line. 4365 4366@cindex @code{bp} request, using @code{+} and@w{ }@code{-} 4367@cindex @code{in} request, using @code{+} and@w{ }@code{-} 4368@cindex @code{ll} request, using @code{+} and@w{ }@code{-} 4369@cindex @code{lt} request, using @code{+} and@w{ }@code{-} 4370@cindex @code{nm} request, using @code{+} and@w{ }@code{-} 4371@cindex @code{nr} request, using @code{+} and@w{ }@code{-} 4372@cindex @code{pl} request, using @code{+} and@w{ }@code{-} 4373@cindex @code{pn} request, using @code{+} and@w{ }@code{-} 4374@cindex @code{po} request, using @code{+} and@w{ }@code{-} 4375@cindex @code{ps} request, using @code{+} and@w{ }@code{-} 4376@cindex @code{pvs} request, using @code{+} and@w{ }@code{-} 4377@cindex @code{rt} request, using @code{+} and@w{ }@code{-} 4378@cindex @code{ti} request, using @code{+} and@w{ }@code{-} 4379@cindex @code{\H}, using @code{+} and@w{ }@code{-} 4380@cindex @code{\R}, using @code{+} and@w{ }@code{-} 4381@cindex @code{\s}, using @code{+} and@w{ }@code{-} 4382@samp{+} and @samp{-} are also treated differently by the following 4383requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, 4384@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, 4385@code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}. 4386Here, leading plus and minus signs indicate increments and decrements. 4387 4388@xref{Setting Registers}, for some examples. 4389 4390@Defesc {\\B, ', anything, '} 4391@cindex numeric expression, valid 4392@cindex valid numeric expression 4393Return@w{ }1 if @var{anything} is a valid numeric expression; 4394or@w{ }0 if @var{anything} is empty or not a valid numeric expression. 4395@endDefesc 4396 4397@cindex space characters, in expressions 4398@cindex expressions, and space characters 4399Due to the way arguments are parsed, spaces are not allowed in 4400expressions, unless the entire expression is surrounded by parentheses. 4401 4402@xref{Request Arguments}, and @ref{Conditionals and Loops}. 4403 4404 4405@c ===================================================================== 4406 4407@node Identifiers, Embedded Commands, Expressions, gtroff Reference 4408@section Identifiers 4409@cindex identifiers 4410 4411Like any other language, @code{gtroff} has rules for properly formed 4412@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of 4413almost any printable character, with the exception of the following 4414characters: 4415 4416@itemize @bullet 4417@item 4418@cindex whitespace characters 4419@cindex newline character 4420@cindex character, whitespace 4421Whitespace characters (spaces, tabs, and newlines). 4422 4423@item 4424@cindex character, backspace 4425@cindex backspace character 4426@cindex @acronym{EBCDIC} encoding of backspace 4427Backspace (@acronym{ASCII}@w{ }@code{0x08} or @acronym{EBCDIC}@w{ 4428}@code{0x16}) and character code @code{0x01}. 4429 4430@item 4431@cindex invalid input characters 4432@cindex input characters, invalid 4433@cindex characters, invalid input 4434@cindex Unicode 4435The following input characters are invalid and are ignored if 4436@code{groff} runs on a machine based on @acronym{ASCII}, causing a 4437warning message of type @samp{input} (see @ref{Debugging}, for more 4438details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F}, 4439@code{0x80}-@code{0x9F}. 4440 4441And here are the invalid input characters if @code{groff} runs on an 4442@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09}, 4443@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F}, 4444@code{0x30}-@code{0x3F}. 4445 4446Currently, some of these reserved codepoints are used internally, thus 4447making it non-trivial to extend @code{gtroff} to cover Unicode or other 4448character sets and encodings which use characters of these ranges. 4449 4450Note that invalid characters are removed before parsing; an 4451identifier @code{foo}, followed by an invalid character, followed by 4452@code{bar} is treated as @code{foobar}. 4453@end itemize 4454 4455For example, any of the following is valid. 4456 4457@Example 4458br 4459PP 4460(l 4461end-list 4462@@_ 4463@endExample 4464 4465@cindex @code{]}, as part of an identifier 4466@noindent 4467Note that identifiers longer than two characters with a closing bracket 4468(@samp{]}) in its name can't be accessed with escape sequences which 4469expect an identifier as a parameter. For example, @samp{\[foo]]} 4470accesses the glyph @samp{foo}, followed by @samp{]}, whereas 4471@samp{\C'foo]'} really asks for glyph @samp{foo]}. 4472 4473@cindex @code{refer}, and macro names starting with @code{[} or @code{]} 4474@cindex @code{[}, macro names starting with, and @code{refer} 4475@cindex @code{]}, macro names starting with, and @code{refer} 4476@cindex macro names, starting with @code{[} or @code{]}, and @code{refer} 4477To avoid problems with the @code{refer} preprocessor, macro names 4478should not start with @samp{[} or @samp{]}. Due to backwards 4479compatibility, everything after @samp{.[} and @samp{.]} is handled as 4480a special argument to @code{refer}. For example, @samp{.[foo} makes 4481@code{refer} to start a reference, using @samp{foo} as a parameter. 4482 4483@Defesc {\\A, ', ident, '} 4484Test whether an identifier @var{ident} is valid in @code{gtroff}. It 4485expands to the character@w{ }1 or@w{ }0 according to whether its 4486argument (usually delimited by quotes) is or is not acceptable as the 4487name of a string, macro, diversion, number register, environment, or 4488font. It returns@w{ }0 if no argument is given. This is useful for 4489looking up user input in some sort of associative table. 4490 4491@Example 4492\A'end-list' 4493 @result{} 1 4494@endExample 4495@endDefesc 4496 4497@xref{Escapes}, for details on parameter delimiting characters. 4498 4499Identifiers in @code{gtroff} can be any length, but, in some contexts, 4500@code{gtroff} needs to be told where identifiers end and text begins 4501(and in different ways depending on their length): 4502 4503@itemize @bullet 4504@item 4505Single character. 4506 4507@cindex @code{(}, starting a two-character identifier 4508@item 4509Two characters. Must be prefixed with @samp{(} in some situations. 4510 4511@cindex @code{[}, starting an identifier 4512@cindex @code{]}, ending an identifier 4513@item 4514Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} 4515and@w{ }@samp{]} in some situations. Any length identifier can be put 4516in brackets. 4517@end itemize 4518 4519@cindex undefined identifiers 4520@cindex identifiers, undefined 4521Unlike many other programming languages, undefined identifiers are 4522silently ignored or expanded to nothing. 4523When @code{gtroff} finds an undefined identifier, it emits a 4524warning, doing the following: 4525 4526@itemize @bullet 4527@item 4528If the identifier is a string, macro, or diversion, 4529@code{gtroff} defines it as empty. 4530 4531@item 4532If the identifier is a number register, @code{gtroff} 4533defines it with a value of@w{ }0. 4534@end itemize 4535 4536@xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}. 4537 4538Note that macros, strings, and diversions share the same name space. 4539 4540@Example 4541.de xxx 4542. nop foo 4543.. 4544. 4545.di xxx 4546bar 4547.br 4548.di 4549. 4550.xxx 4551 @result{} bar 4552@endExample 4553 4554@noindent 4555As can be seen in the previous example, @code{gtroff} reuses the 4556identifier @samp{xxx}, changing it from a macro to a diversion. 4557No warning is emitted! The contents of the first macro definition is 4558lost. 4559 4560@xref{Interpolating Registers}, and @ref{Strings}. 4561 4562 4563@c ===================================================================== 4564 4565@node Embedded Commands, Registers, Identifiers, gtroff Reference 4566@section Embedded Commands 4567@cindex embedded commands 4568@cindex commands, embedded 4569 4570Most documents need more functionality beyond filling, adjusting and 4571implicit line breaking. In order to gain further functionality, 4572@code{gtroff} allows commands to be embedded into the text, in two ways. 4573 4574The first is a @dfn{request} which takes up an entire line, and does 4575some large-scale operation (e.g.@: break lines, start new pages). 4576 4577The other is an @dfn{escape} which can be usually embedded anywhere 4578in the text; most requests can accept it even as an argument. 4579Escapes generally do more minor operations like sub- and superscripts, 4580print a symbol, etc. 4581 4582@menu 4583* Requests:: 4584* Macros:: 4585* Escapes:: 4586@end menu 4587 4588@c --------------------------------------------------------------------- 4589 4590@node Requests, Macros, Embedded Commands, Embedded Commands 4591@subsection Requests 4592@cindex requests 4593 4594@cindex control character (@code{.}) 4595@cindex character, control (@code{.}) 4596@cindex no-break control character (@code{'}) 4597@cindex character, no-break control (@code{'}) 4598@cindex control character, no-break (@code{'}) 4599A request line begins with a control character, which is either a single 4600quote (@samp{'}, the @dfn{no-break control character}) or a period 4601(@samp{.}, the normal @dfn{control character}). These can be changed; 4602see @ref{Character Translations}, for details. After this there may be 4603optional tabs or spaces followed by an identifier which is the name of 4604the request. This may be followed by any number of space-separated 4605arguments (@emph{no} tabs here). 4606 4607@cindex structuring source code of documents or macro packages 4608@cindex documents, structuring the source code 4609@cindex macro packages, structuring the source code 4610Since a control character followed by whitespace only is ignored, it 4611is common practice to use this feature for structuring the source code 4612of documents or macro packages. 4613 4614@Example 4615.de foo 4616. tm This is foo. 4617.. 4618. 4619. 4620.de bar 4621. tm This is bar. 4622.. 4623@endExample 4624 4625@cindex blank line 4626@cindex blank line macro (@code{blm}) 4627Another possibility is to use the blank line macro request @code{blm} 4628by assigning an empty macro to it. 4629 4630@Example 4631.de do-nothing 4632.. 4633.blm do-nothing \" activate blank line macro 4634 4635.de foo 4636. tm This is foo. 4637.. 4638 4639 4640.de bar 4641. tm This is bar. 4642.. 4643 4644.blm \" deactivate blank line macro 4645@endExample 4646 4647@xref{Blank Line Traps}. 4648 4649@cindex zero width space character (@code{\&}) 4650@cindex character, zero width space (@code{\&}) 4651@cindex space character, zero width (@code{\&}) 4652@cindex @code{\&}, escaping control characters 4653To begin a line with a control character without it being interpreted, 4654precede it with @code{\&}. This represents a zero width space, which 4655means it does not affect the output. 4656 4657In most cases the period is used as a control character. Several 4658requests cause a break implicitly; using the single quote control 4659character prevents this. 4660 4661@menu 4662* Request Arguments:: 4663@end menu 4664 4665@node Request Arguments, , Requests, Requests 4666@subsubsection Request Arguments 4667@cindex request arguments 4668@cindex arguments to requests 4669 4670Arguments to requests (and macros) are processed much like the shell: 4671The line is split into arguments according to 4672spaces.@footnote{Plan@w{ }9's @code{troff} implementation also allows 4673tabs for argument separation -- @code{gtroff} intentionally doesn't 4674support this.} An argument which is intended to contain spaces can 4675either be enclosed in double quotes, or have the spaces @dfn{escaped} 4676with backslashes. 4677 4678Here are a few examples: 4679 4680@Example 4681.uh The Mouse Problem 4682.uh "The Mouse Problem" 4683.uh The\ Mouse\ Problem 4684@endExample 4685 4686@cindex @code{\~}, difference to @code{\@key{SP}} 4687@cindex @code{\@key{SP}}, difference to @code{\~} 4688@noindent 4689The first line is the @code{uh} macro being called with 3 arguments, 4690@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the 4691same effect of calling the @code{uh} macro with one argument, @samp{The 4692Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces, 4693is ``classical'' in the sense that it can be found in most @code{troff} 4694documents. Nevertheless, it is not optimal in all situations, since 4695@w{@samp{\ }} inserts a fixed-width, non-breaking space character which 4696can't stretch. @code{gtroff} provides a different command @code{\~} to 4697insert a stretchable, non-breaking space.} 4698 4699@cindex @code{"}, in a macro argument 4700@cindex double quote, in a macro argument 4701A double quote which isn't preceded by a space doesn't start a macro 4702argument. If not closing a string, it is printed literally. 4703 4704For example, 4705 4706@Example 4707.xxx a" "b c" "de"fg" 4708@endExample 4709 4710@noindent 4711has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}. 4712Don't rely on this obscure behaviour! 4713 4714There are two possibilities to get a double quote reliably. 4715 4716@itemize @bullet 4717@item 4718Enclose the whole argument with double quotes and use two consecutive double 4719quotes to represent a single one. This traditional solution has the 4720disadvantage that double quotes don't survive argument expansion again if 4721called in compatibility mode (using the @option{-C} option of @code{groff}): 4722 4723@Example 4724.de xx 4725. tm xx: `\\$1' `\\$2' `\\$3' 4726. 4727. yy "\\$1" "\\$2" "\\$3" 4728.. 4729.de yy 4730. tm yy: `\\$1' `\\$2' `\\$3' 4731.. 4732.xx A "test with ""quotes""" . 4733 @result{} xx: `A' `test with "quotes"' `.' 4734 @result{} yy: `A' `test with ' `quotes""' 4735@endExample 4736 4737@noindent 4738If not in compatibility mode, you get the expected result 4739 4740@Example 4741xx: `A' `test with "quotes"' `.' 4742yy: `A' `test with "quotes"' `.' 4743@endExample 4744 4745@noindent 4746since @code{gtroff} preserves the input level. 4747 4748@item 4749Use the double quote glyph @code{\(dq}. This works with and without 4750compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq} 4751back to a double quote input character. 4752 4753Not that this method won't work with @acronym{UNIX} @code{troff} in general 4754since the glyph `dq' isn't defined normally. 4755@end itemize 4756 4757@cindex @code{ds} request, and double quotes 4758Double quotes in the @code{ds} request are handled differently. 4759@xref{Strings}, for more details. 4760 4761@c --------------------------------------------------------------------- 4762 4763@node Macros, Escapes, Requests, Embedded Commands 4764@subsection Macros 4765@cindex macros 4766 4767@code{gtroff} has a @dfn{macro} facility for defining a series of lines 4768which can be invoked by name. They are called in the same manner as 4769requests -- arguments also may be passed in the same manner. 4770 4771@xref{Writing Macros}, and @ref{Request Arguments}. 4772 4773@c --------------------------------------------------------------------- 4774 4775@node Escapes, , Macros, Embedded Commands 4776@subsection Escapes 4777@cindex escapes 4778 4779Escapes may occur anywhere in the input to @code{gtroff}. They usually 4780begin with a backslash and are followed by a single character which 4781indicates the function to be performed. The escape character can be 4782changed; see @ref{Character Translations}. 4783 4784Escape sequences which require an identifier as a parameter accept three 4785possible syntax forms. 4786 4787@itemize @bullet 4788@item 4789The next single character is the identifier. 4790 4791@cindex @code{(}, starting a two-character identifier 4792@item 4793If this single character is an opening parenthesis, take the following 4794two characters as the identifier. Note that there is no closing 4795parenthesis after the identifier. 4796 4797@cindex @code{[}, starting an identifier 4798@cindex @code{]}, ending an identifier 4799@item 4800If this single character is an opening bracket, take all characters 4801until a closing bracket as the identifier. 4802@end itemize 4803 4804@noindent 4805Examples: 4806 4807@Example 4808\fB 4809\n(XX 4810\*[TeX] 4811@endExample 4812 4813@cindex @code{'}, delimiting arguments 4814@cindex argument delimiting characters 4815@cindex characters, argument delimiting 4816@cindex delimiting characters for arguments 4817Other escapes may require several arguments and/or some special format. 4818In such cases the argument is traditionally enclosed in single quotes 4819(and quotes are always used in this manual for the definitions of escape 4820sequences). The enclosed text is then processed according to what that 4821escape expects. Example: 4822 4823@Example 4824\l'1.5i\(bu' 4825@endExample 4826 4827@cindex @code{\o}, possible quote characters 4828@cindex @code{\b}, possible quote characters 4829@cindex @code{\X}, possible quote characters 4830Note that the quote character can be replaced with any other character 4831which does not occur in the argument (even a newline or a space 4832character) in the following escapes: @code{\o}, @code{\b}, and 4833@code{\X}. This makes e.g. 4834 4835@Example 4836A caf 4837\o 4838e\' 4839 4840 4841in Paris 4842 @result{} A caf@'e in Paris 4843@endExample 4844 4845@noindent 4846possible, but it is better not to use this feature to avoid confusion. 4847 4848@cindex @code{\%}, used as delimiter 4849@cindex @code{\@key{SP}}, used as delimiter 4850@cindex @code{\|}, used as delimiter 4851@cindex @code{\^}, used as delimiter 4852@cindex @code{\@{}, used as delimiter 4853@cindex @code{\@}}, used as delimiter 4854@cindex @code{\'}, used as delimiter 4855@cindex @code{\`}, used as delimiter 4856@cindex @code{\-}, used as delimiter 4857@cindex @code{\_}, used as delimiter 4858@cindex @code{\!}, used as delimiter 4859@cindex @code{\?}, used as delimiter 4860@cindex @code{\@@}, used as delimiter 4861@cindex @code{\)}, used as delimiter 4862@cindex @code{\/}, used as delimiter 4863@cindex @code{\,}, used as delimiter 4864@cindex @code{\&}, used as delimiter 4865@ifnotinfo 4866@cindex @code{\:}, used as delimiter 4867@end ifnotinfo 4868@ifinfo 4869@cindex @code{\@r{<colon>}}, used as delimiter 4870@end ifinfo 4871@cindex @code{\~}, used as delimiter 4872@cindex @code{\0}, used as delimiter 4873@cindex @code{\a}, used as delimiter 4874@cindex @code{\c}, used as delimiter 4875@cindex @code{\d}, used as delimiter 4876@cindex @code{\e}, used as delimiter 4877@cindex @code{\E}, used as delimiter 4878@cindex @code{\p}, used as delimiter 4879@cindex @code{\r}, used as delimiter 4880@cindex @code{\t}, used as delimiter 4881@cindex @code{\u}, used as delimiter 4882The following escapes sequences (which are handled similarly to 4883characters since they don't take a parameter) are also allowed as 4884delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, 4885@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 4886@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, 4887@code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, 4888@code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. 4889Again, don't use these if possible. 4890 4891@cindex @code{\A}, allowed delimiters 4892@cindex @code{\B}, allowed delimiters 4893@cindex @code{\Z}, allowed delimiters 4894@cindex @code{\C}, allowed delimiters 4895@cindex @code{\w}, allowed delimiters 4896No newline characters as delimiters are allowed in the following 4897escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}. 4898 4899@cindex @code{\D}, allowed delimiters 4900@cindex @code{\h}, allowed delimiters 4901@cindex @code{\H}, allowed delimiters 4902@cindex @code{\l}, allowed delimiters 4903@cindex @code{\L}, allowed delimiters 4904@cindex @code{\N}, allowed delimiters 4905@cindex @code{\R}, allowed delimiters 4906@cindex @code{\s}, allowed delimiters 4907@cindex @code{\S}, allowed delimiters 4908@cindex @code{\v}, allowed delimiters 4909@cindex @code{\x}, allowed delimiters 4910Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l}, 4911@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, 4912and @code{\x} can't use the following characters as delimiters: 4913 4914@itemize @bullet 4915@item 4916@cindex numbers, and delimiters 4917@cindex digits, and delimiters 4918The digits @code{0}-@code{9}. 4919 4920@item 4921@cindex operators, as delimiters 4922@cindex @code{+}, as delimiter 4923@cindex @code{-}, as delimiter 4924@cindex @code{/}, as delimiter 4925@cindex @code{*}, as delimiter 4926@cindex @code{%}, as delimiter 4927@cindex @code{<}, as delimiter 4928@cindex @code{>}, as delimiter 4929@cindex @code{=}, as delimiter 4930@cindex @code{&}, as delimiter 4931@ifnotinfo 4932@cindex @code{:}, as delimiter 4933@end ifnotinfo 4934@ifinfo 4935@cindex <colon>, as delimiter 4936@end ifinfo 4937@cindex @code{(}, as delimiter 4938@cindex @code{)}, as delimiter 4939@cindex @code{.}, as delimiter 4940The (single-character) operators @samp{+-/*%<>=&:().}. 4941 4942@item 4943@cindex space character 4944@cindex character, space 4945@cindex tab character 4946@cindex character, tab 4947@cindex newline character 4948@cindex character, newline 4949The space, tab, and newline characters. 4950 4951@item 4952@cindex @code{\%}, used as delimiter 4953@ifnotinfo 4954@cindex @code{\:}, used as delimiter 4955@end ifnotinfo 4956@ifinfo 4957@cindex @code{\@r{<colon>}}, used as delimiter 4958@end ifinfo 4959@cindex @code{\@{}, used as delimiter 4960@cindex @code{\@}}, used as delimiter 4961@cindex @code{\'}, used as delimiter 4962@cindex @code{\`}, used as delimiter 4963@cindex @code{\-}, used as delimiter 4964@cindex @code{\_}, used as delimiter 4965@cindex @code{\!}, used as delimiter 4966@cindex @code{\@@}, used as delimiter 4967@cindex @code{\/}, used as delimiter 4968@cindex @code{\c}, used as delimiter 4969@cindex @code{\e}, used as delimiter 4970@cindex @code{\p}, used as delimiter 4971All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}}, 4972@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@}, 4973@code{\/}, @code{\c}, @code{\e}, and @code{\p}. 4974@end itemize 4975 4976@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 4977@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 4978To have a backslash (actually, the current escape character) appear in the 4979output several escapes are defined: @code{\\}, @code{\e} or @code{\E}. 4980These are very similar, and only differ with respect to being used in 4981macros or diversions. @xref{Character Translations}, for an exact 4982description of those escapes. 4983 4984@xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions}, 4985@ref{Identifiers}, for more information. 4986 4987@menu 4988* Comments:: 4989@end menu 4990 4991@node Comments, , Escapes, Escapes 4992@subsubsection Comments 4993@cindex comments 4994 4995Probably one of the most@footnote{Unfortunately, this is a lie. But 4996hopefully future @code{gtroff} hackers will believe it @code{:-)}} 4997common forms of escapes is the comment. 4998 4999@Defesc {\\", , , } 5000Start a comment. Everything to the end of the input line is ignored. 5001 5002This may sound simple, but it can be tricky to keep the comments from 5003interfering with the appearance of the final output. 5004 5005@cindex @code{ds}, @code{ds1} requests, and comments 5006@cindex @code{as}, @code{as1} requests, and comments 5007If the escape is to the right of some text or a request, that portion 5008of the line is ignored, but the space leading up to it is noticed by 5009@code{gtroff}. This only affects the @code{ds} and @code{as} 5010request and its variants. 5011 5012@cindex tabs, before comments 5013@cindex comments, lining up with tabs 5014One possibly irritating idiosyncracy is that tabs must not be used to 5015line up comments. Tabs are not treated as whitespace between the 5016request and macro arguments. 5017 5018@cindex undefined request 5019@cindex request, undefined 5020A comment on a line by itself is treated as a blank line, because 5021after eliminating the comment, that is all that remains: 5022 5023@Example 5024Test 5025\" comment 5026Test 5027@endExample 5028 5029@noindent 5030produces 5031 5032@Example 5033Test 5034 5035Test 5036@endExample 5037 5038To avoid this, it is common to start the line with @code{.\"} which 5039causes the line to be treated as an undefined request and thus ignored 5040completely. 5041 5042@cindex @code{'}, as a comment 5043Another commenting scheme seen sometimes is three consecutive single 5044quotes (@code{'''}) at the beginning of a line. This works, but 5045@code{gtroff} gives a warning about an undefined macro (namely 5046@code{''}), which is harmless, but irritating. 5047@endDefesc 5048 5049@Defesc {\\#, , , } 5050To avoid all this, @code{gtroff} has a new comment mechanism using the 5051@code{\#} escape. This escape works the same as @code{\"} except that 5052the newline is also ignored: 5053 5054@Example 5055Test 5056\# comment 5057Test 5058@endExample 5059 5060@noindent 5061produces 5062 5063@Example 5064Test Test 5065@endExample 5066 5067@noindent 5068as expected. 5069@endDefesc 5070 5071@Defreq {ig, yy} 5072Ignore all input until @code{gtroff} encounters the macro named 5073@code{.}@var{yy} on a line by itself (or @code{..} if @var{yy} is not 5074specified). This is useful for commenting out large blocks of text: 5075 5076@Example 5077text text text... 5078.ig 5079This is part of a large block 5080of text that has been 5081temporarily(?) commented out. 5082 5083We can restore it simply by removing 5084the .ig request and the ".." at the 5085end of the block. 5086.. 5087More text text text... 5088@endExample 5089 5090@noindent 5091produces 5092 5093@Example 5094text text text@dots{} More text text text@dots{} 5095@endExample 5096 5097@noindent 5098Note that the commented-out block of text does not 5099cause a break. 5100 5101The input is read in copy-mode; auto-incremented registers @emph{are} 5102affected (@pxref{Auto-increment}). 5103@endDefreq 5104 5105 5106@c ===================================================================== 5107 5108@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference 5109@section Registers 5110@cindex registers 5111 5112Numeric variables in @code{gtroff} are called @dfn{registers}. There 5113are a number of built-in registers, supplying anything from the date to 5114details of formatting parameters. 5115 5116@xref{Identifiers}, for details on register identifiers. 5117 5118@menu 5119* Setting Registers:: 5120* Interpolating Registers:: 5121* Auto-increment:: 5122* Assigning Formats:: 5123* Built-in Registers:: 5124@end menu 5125 5126@c --------------------------------------------------------------------- 5127 5128@node Setting Registers, Interpolating Registers, Registers, Registers 5129@subsection Setting Registers 5130@cindex setting registers (@code{nr}, @code{\R}) 5131@cindex registers, setting (@code{nr}, @code{\R}) 5132 5133Define or set registers using the @code{nr} request or the 5134@code{\R} escape. 5135 5136@DefreqList {nr, ident value} 5137@DefescListEnd {\\R, ', ident value, '} 5138Set number register @var{ident} to @var{value}. If @var{ident} 5139doesn't exist, @code{gtroff} creates it. 5140 5141The argument to @code{\R} usually has to be enclosed in quotes. 5142@xref{Escapes}, for details on parameter delimiting characters. 5143 5144The @code{\R} escape doesn't produce an input token in @code{gtroff}; 5145with other words, it vanishes completely after @code{gtroff} has 5146processed it. 5147@endDefreq 5148 5149For example, the following two lines are equivalent: 5150 5151@Example 5152.nr a (((17 + (3 * 4))) % 4) 5153\R'a (((17 + (3 * 4))) % 4)' 5154 @result{} 1 5155@endExample 5156 5157Both @code{nr} and @code{\R} have two additional special forms to 5158increment or decrement a register. 5159 5160@DefreqList {nr, ident @t{+}@Var{value}} 5161@DefreqItem {nr, ident @t{-}@Var{value}} 5162@DefescItem {\\R, ', ident @t{+}@Var{value}, '} 5163@DefescListEnd {\\R, ', ident @t{-}@Var{value}, '} 5164Increment (decrement) register @var{ident} by @var{value}. 5165 5166@Example 5167.nr a 1 5168.nr a +1 5169\na 5170 @result{} 2 5171@endExample 5172 5173@cindex negating register values 5174To assign the negated value of a register to another register, some care 5175must be taken to get the desired result: 5176 5177@Example 5178.nr a 7 5179.nr b 3 5180.nr a -\nb 5181\na 5182 @result{} 4 5183.nr a (-\nb) 5184\na 5185 @result{} -3 5186@endExample 5187 5188@noindent 5189The surrounding parentheses prevent the interpretation of the minus sign 5190as a decrementing operator. An alternative is to start the assignment 5191with a @samp{0}: 5192 5193@Example 5194.nr a 7 5195.nr b -3 5196.nr a \nb 5197\na 5198 @result{} 4 5199.nr a 0\nb 5200\na 5201 @result{} -3 5202@endExample 5203@endDefreq 5204 5205@Defreq {rr, ident} 5206@cindex removing number register (@code{rr}) 5207@cindex number register, removing (@code{rr}) 5208@cindex register, removing (@code{rr}) 5209Remove number register @var{ident}. If @var{ident} doesn't exist, the 5210request is ignored. 5211@endDefreq 5212 5213@Defreq {rnn, ident1 ident2} 5214@cindex renaming number register (@code{rnn}) 5215@cindex number register, renaming (@code{rnn}) 5216@cindex register, renaming (@code{rnn}) 5217Rename number register @var{ident1} to @var{ident2}. If either 5218@var{ident1} or @var{ident2} doesn't exist, the request is ignored. 5219@endDefreq 5220 5221@Defreq {aln, ident1 ident2} 5222@cindex alias, number register, creating (@code{aln}) 5223@cindex creating alias, for number register (@code{aln}) 5224@cindex number register, creating alias (@code{aln}) 5225@cindex register, creating alias (@code{aln}) 5226Create an alias @var{ident1} for a number register @var{ident2}. The 5227new name and the old name are exactly equivalent. If @var{ident1} is 5228undefined, a warning of type @samp{reg} is generated, and the request 5229is ignored. @xref{Debugging}, for information about warnings. 5230@endDefreq 5231 5232@c --------------------------------------------------------------------- 5233 5234@node Interpolating Registers, Auto-increment, Setting Registers, Registers 5235@subsection Interpolating Registers 5236@cindex interpolating registers (@code{\n}) 5237@cindex registers, interpolating (@code{\n}) 5238 5239Numeric registers can be accessed via the @code{\n} escape. 5240 5241@DefescList {\\n, , i, } 5242@DefescItem {\\n, @lparen{}, id, } 5243@DefescListEnd {\\n, @lbrack{}, ident, @rbrack} 5244@cindex nested assignments 5245@cindex assignments, nested 5246@cindex indirect assignments 5247@cindex assignments, indirect 5248Interpolate number register with name @var{ident} (one-character name@w{ 5249}@var{i}, two-character name @var{id}). This means that the value of the 5250register is expanded in-place while @code{gtroff} is parsing the input line. 5251Nested assignments (also called indirect assignments) are possible. 5252 5253@Example 5254.nr a 5 5255.nr as \na+\na 5256\n(as 5257 @result{} 10 5258@endExample 5259 5260@Example 5261.nr a1 5 5262.nr ab 6 5263.ds str b 5264.ds num 1 5265\n[a\n[num]] 5266 @result{} 5 5267\n[a\*[str]] 5268 @result{} 6 5269@endExample 5270@endDefesc 5271 5272@c --------------------------------------------------------------------- 5273 5274@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 5275@subsection Auto-increment 5276@cindex auto-increment 5277@cindex increment, automatic 5278 5279Number registers can also be auto-incremented and auto-decremented. 5280The increment or decrement value can be specified with a third 5281argument to the @code{nr} request or @code{\R} escape. 5282 5283@Defreq {nr, ident value incr} 5284@cindex @code{\R}, difference to @code{nr} 5285Set number register @var{ident} to @var{value}; the increment for 5286auto-incrementing is set to @var{incr}. Note that the @code{\R} 5287escape doesn't support this notation. 5288@endDefreq 5289 5290To activate auto-incrementing, the escape @code{\n} has a special 5291syntax form. 5292 5293@DefescList {\\n, +, i, } 5294@DefescItem {\\n, -, i, } 5295@DefescItem {\\n, @lparen{}+, id, } 5296@DefescItem {\\n, @lparen{}-, id, } 5297@DefescItem {\\n, +@lparen{}, id, } 5298@DefescItem {\\n, -@lparen{}, id, } 5299@DefescItem {\\n, @lbrack{}+, ident, @rbrack{}} 5300@DefescItem {\\n, @lbrack{}-, ident, @rbrack{}} 5301@DefescItem {\\n, +@lbrack{}, ident, @rbrack{}} 5302@DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}} 5303Before interpolating, increment or decrement @var{ident} 5304(one-character name@w{ }@var{i}, two-character name @var{id}) by the 5305auto-increment value as specified with the @code{nr} request (or the 5306@code{\R} escape). If no auto-increment value has been specified, 5307these syntax forms are identical to @code{\n}. 5308@endDefesc 5309 5310For example, 5311 5312@Example 5313.nr a 0 1 5314.nr xx 0 5 5315.nr foo 0 -2 5316\n+a, \n+a, \n+a, \n+a, \n+a 5317.br 5318\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 5319.br 5320\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 5321@endExample 5322 5323@noindent 5324produces 5325 5326@Example 53271, 2, 3, 4, 5 5328-5, -10, -15, -20, -25 5329-2, -4, -6, -8, -10 5330@endExample 5331 5332@cindex increment value without changing the register 5333@cindex value, incrementing without changing the register 5334To change the increment value without changing the value of a register 5335(@var{a} in the example), the following can be used: 5336 5337@Example 5338.nr a \na 10 5339@endExample 5340 5341@c --------------------------------------------------------------------- 5342 5343@node Assigning Formats, Built-in Registers, Auto-increment, Registers 5344@subsection Assigning Formats 5345@cindex assigning formats (@code{af}) 5346@cindex formats, assigning (@code{af}) 5347 5348When a register is used in the text of an input file (as opposed to 5349part of an expression), it is textually replaced (or interpolated) 5350with a representation of that number. This output format can be 5351changed to a variety of formats (numbers, Roman numerals, etc.). This 5352is done using the @code{af} request. 5353 5354@Defreq {af, ident format} 5355Change the output format of a number register. The first argument 5356@var{ident} is the name of the number register to be changed, and the 5357second argument @var{format} is the output format. The following 5358output formats are available: 5359 5360@table @code 5361@item 1 5362Decimal arabic numbers. This is the default format: 0, 1, 2, 3,@w{ 5363}@enddots{} 5364 5365@item 0@dots{}0 5366Decimal numbers with as many digits as specified. So, @samp{00} would 5367result in printing numbers as 01, 02, 03,@w{ }@enddots{} 5368 5369In fact, any digit instead of zero will do; @code{gtroff} only counts 5370how many digits are specified. As a consequence, @code{af}'s default 5371format @samp{1} could be specified as @samp{0} also (and exactly this is 5372returned by the @code{\g} escape, see below). 5373 5374@item I 5375@cindex Roman numerals 5376@cindex numerals, Roman 5377Upper-case Roman numerals: 0, I, II, III, IV,@w{ }@enddots{} 5378 5379@item i 5380Lower-case Roman numerals: 0, i, ii, iii, iv,@w{ }@enddots{} 5381 5382@item A 5383Upper-case letters: 0, A, B, C, @dots{},@w{ }Z, AA, AB,@w{ }@enddots{} 5384 5385@item a 5386Lower-case letters: 0, a, b, c, @dots{},@w{ }z, aa, ab,@w{ }@enddots{} 5387@end table 5388 5389Omitting the number register format causes a warning of type 5390@samp{missing}. @xref{Debugging}, for more details. Specifying a 5391nonexistent format causes an error. 5392 5393The following example produces @samp{10, X, j, 010}: 5394 5395@Example 5396.nr a 10 5397.af a 1 \" the default format 5398\na, 5399.af a I 5400\na, 5401.af a a 5402\na, 5403.af a 001 5404\na 5405@endExample 5406 5407@cindex Roman numerals, maximum and minimum 5408@cindex maximum values of Roman numerals 5409@cindex minimum values of Roman numerals 5410The largest number representable for the @samp{i} and @samp{I} formats 5411is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z} 5412and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does 5413@code{gtroff}. Currently, the correct glyphs of Roman numeral five 5414thousand and Roman numeral ten thousand (Unicode code points 5415@code{U+2182} and @code{U+2181}, respectively) are not available. 5416 5417If @var{ident} doesn't exist, it is created. 5418 5419@cindex read-only register, changing format 5420@cindex changing format, and read-only registers 5421Changing the output format of a read-only register causes an error. It 5422is necessary to first copy the register's value to a writeable register, 5423then apply the @code{af} request to this other register. 5424@endDefreq 5425 5426@DefescList {\\g, , i, } 5427@DefescItem {\\g, @lparen{}, id, } 5428@DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}} 5429@cindex format of register (@code{\g}) 5430@cindex register, format (@code{\g}) 5431Return the current format of the specified register @var{ident} 5432(one-character name@w{ }@var{i}, two-character name @var{id}). For 5433example, @samp{\ga} after the previous example would produce the 5434string @samp{000}. If the register hasn't been defined yet, nothing 5435is returned. 5436@endDefesc 5437 5438@c --------------------------------------------------------------------- 5439 5440@node Built-in Registers, , Assigning Formats, Registers 5441@subsection Built-in Registers 5442@cindex built-in registers 5443@cindex registers, built-in 5444 5445The following lists some built-in registers which are not described 5446elsewhere in this manual. Any register which begins with a @samp{.} is 5447read-only. A complete listing of all built-in registers can be found in 5448appendix@w{ }@ref{Register Index}. 5449 5450@table @code 5451@item .F 5452@cindex current input file name register (@code{.F}) 5453@cindex input file name, current, register (@code{.F}) 5454@vindex .F 5455This string-valued register returns the current input file name. 5456 5457@item .H 5458@cindex horizontal resolution register (@code{.H}) 5459@cindex resolution, horizontal, register (@code{.H}) 5460@vindex .H 5461Horizontal resolution in basic units. 5462 5463@item .V 5464@cindex vertical resolution register (@code{.V}) 5465@cindex resolution, vertical, register (@code{.V}) 5466@vindex .V 5467Vertical resolution in basic units. 5468 5469@item seconds 5470@cindex seconds, current time (@code{seconds}) 5471@cindex time, current, seconds (@code{seconds}) 5472@cindex current time, seconds (@code{seconds}) 5473@vindex seconds 5474The number of seconds after the minute, normally in the range@w{ }0 5475to@w{ }59, but can be up to@w{ }61 to allow for leap seconds. Initialized 5476at start-up of @code{gtroff}. 5477 5478@item minutes 5479@cindex minutes, current time (@code{minutes}) 5480@cindex time, current, minutes (@code{minutes}) 5481@cindex current time, minutes (@code{minutes}) 5482@vindex minutes 5483The number of minutes after the hour, in the range@w{ }0 to@w{ }59. 5484Initialized at start-up of @code{gtroff}. 5485 5486@item hours 5487@cindex hours, current time (@code{hours}) 5488@cindex time, current, hours (@code{hours}) 5489@cindex current time, hours (@code{hours}) 5490@vindex hours 5491The number of hours past midnight, in the range@w{ }0 to@w{ }23. 5492Initialized at start-up of @code{gtroff}. 5493 5494@item dw 5495@cindex day of the week register (@code{dw}) 5496@cindex date, day of the week register (@code{dw}) 5497@vindex dw 5498Day of the week (1-7). 5499 5500@item dy 5501@cindex day of the month register (@code{dy}) 5502@cindex date, day of the month register (@code{dy}) 5503@vindex dy 5504Day of the month (1-31). 5505 5506@item mo 5507@cindex month of the year register (@code{mo}) 5508@cindex date, month of the year register (@code{mo}) 5509@vindex mo 5510Current month (1-12). 5511 5512@item year 5513@cindex date, year register (@code{year}, @code{yr}) 5514@cindex year, current, register (@code{year}, @code{yr}) 5515@vindex year 5516The current year. 5517 5518@item yr 5519@vindex yr 5520The current year minus@w{ }1900. Unfortunately, the documentation of 5521@acronym{UNIX} Version@w{ }7's @code{troff} had a year@w{ }2000 bug: It 5522incorrectly claimed that @code{yr} contains the last two digits of the 5523year. That claim has never been true of either @acronym{AT&T} 5524@code{troff} or GNU @code{troff}. Old @code{troff} input that looks 5525like this: 5526 5527@Example 5528'\" The following line stopped working after 1999 5529This document was formatted in 19\n(yr. 5530@endExample 5531 5532@noindent 5533can be corrected as follows: 5534 5535@Example 5536This document was formatted in \n[year]. 5537@endExample 5538 5539@noindent 5540or, to be portable to older @code{troff} versions, as follows: 5541 5542@Example 5543.nr y4 1900+\n(yr 5544This document was formatted in \n(y4. 5545@endExample 5546 5547@item .c 5548@vindex .c 5549@itemx c. 5550@vindex c. 5551@cindex input line number register (@code{.c}, @code{c.}) 5552@cindex line number, input, register (@code{.c}, @code{c.}) 5553The current @emph{input} line number. Register @samp{.c} is read-only, 5554whereas @samp{c.} (a @code{gtroff} extension) is writable also, 5555affecting both @samp{.c} and @samp{c.}. 5556 5557@item ln 5558@vindex ln 5559@cindex output line number register (@code{ln}) 5560@cindex line number, output, register (@code{ln}) 5561The current @emph{output} line number after a call to the @code{nm} 5562request to activate line numbering. 5563 5564@xref{Miscellaneous}, for more information about line numbering. 5565 5566@item .x 5567@vindex .x 5568@cindex major version number register (@code{.x}) 5569@cindex version number, major, register (@code{.x}) 5570The major version number. For example, if the version number is@w{ 5571}1.03 then @code{.x} contains@w{ }@samp{1}. 5572 5573@item .y 5574@vindex .y 5575@cindex minor version number register (@code{.y}) 5576@cindex version number, minor, register (@code{.y}) 5577The minor version number. For example, if the version number is@w{ 5578}1.03 then @code{.y} contains@w{ }@samp{03}. 5579 5580@item .Y 5581@vindex .Y 5582@cindex revision number register (@code{.Y}) 5583The revision number of @code{groff}. 5584 5585@item $$ 5586@vindex $$ 5587@cindex process ID of @code{gtroff} register (@code{$$}) 5588@cindex @code{gtroff}, process ID register (@code{$$}) 5589The process ID of @code{gtroff}. 5590 5591@item .g 5592@vindex .g 5593@cindex @code{gtroff}, identification register (@code{.g}) 5594@cindex GNU-specific register (@code{.g}) 5595Always@w{ }1. Macros should use this to determine whether they are 5596running under GNU @code{troff}. 5597 5598@item .A 5599@vindex .A 5600@cindex @acronym{ASCII} approximation output register (@code{.A}) 5601If the command line option @option{-a} is used to produce an 5602@acronym{ASCII} approximation of the output, this is set to@w{ }1, zero 5603otherwise. @xref{Groff Options}. 5604 5605@item .P 5606@vindex .P 5607This register is set to@w{ }1 (and to@w{ }0 otherwise) if the current 5608page is actually being printed, i.e., if the @option{-o} option is being 5609used to only print selected pages. @xref{Groff Options}, for more 5610information. 5611 5612@item .T 5613@vindex .T 5614If @code{gtroff} is called with the @option{-T} command line option, the 5615number register @code{.T} is set to@w{ }1, and zero otherwise. 5616@xref{Groff Options}. 5617 5618@stindex .T 5619@cindex output device name string register (@code{.T}) 5620Additionally, @code{gtroff} predefines a single read-write string 5621register @code{.T} which contains the current output device (for 5622example, @samp{latin1} or @samp{ps}). 5623@end table 5624 5625 5626@c ===================================================================== 5627 5628@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference 5629@section Manipulating Filling and Adjusting 5630@cindex manipulating filling and adjusting 5631@cindex filling and adjusting, manipulating 5632@cindex adjusting and filling, manipulating 5633@cindex justifying text 5634@cindex text, justifying 5635 5636@cindex break 5637@cindex line break 5638@cindex @code{bp} request, causing implicit linebreak 5639@cindex @code{ce} request, causing implicit linebreak 5640@cindex @code{cf} request, causing implicit linebreak 5641@cindex @code{fi} request, causing implicit linebreak 5642@cindex @code{fl} request, causing implicit linebreak 5643@cindex @code{in} request, causing implicit linebreak 5644@cindex @code{nf} request, causing implicit linebreak 5645@cindex @code{rj} request, causing implicit linebreak 5646@cindex @code{sp} request, causing implicit linebreak 5647@cindex @code{ti} request, causing implicit linebreak 5648@cindex @code{trf} request, causing implicit linebreak 5649Various ways of causing @dfn{breaks} were given in @ref{Implicit Line 5650Breaks}. The @code{br} request likewise causes a break. Several 5651other requests also cause breaks, but implicitly. These are 5652@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, 5653@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. 5654 5655@Defreq {br, } 5656Break the current line, i.e., the input collected so far is emitted 5657without adjustment. 5658 5659If the no-break control character is used, @code{gtroff} suppresses 5660the break: 5661 5662@Example 5663a 5664'br 5665b 5666 @result{} a b 5667@endExample 5668@endDefreq 5669 5670Initially, @code{gtroff} fills and adjusts text to both margins. 5671Filling can be disabled via the @code{nf} request and re-enabled with 5672the @code{fi} request. 5673 5674@DefreqList {fi, } 5675@DefregListEnd {.u} 5676@cindex fill mode (@code{fi}) 5677@cindex mode, fill (@code{fi}) 5678Activate fill mode (which is the default). This request implicitly 5679enables adjusting; it also inserts a break in the text currently being 5680filled. The read-only number register @code{.u} is set to@w{ }1. 5681 5682The fill mode status is associated with the current environment 5683(@pxref{Environments}). 5684 5685See @ref{Line Control}, for interaction with the @code{\c} escape. 5686@endDefreq 5687 5688@Defreq {nf, } 5689@cindex no-fill mode (@code{nf}) 5690@cindex mode, no-fill (@code{nf}) 5691Activate no-fill mode. Input lines are output as-is, retaining line 5692breaks and ignoring the current line length. This command implicitly 5693disables adjusting; it also causes a break. The number register 5694@code{.u} is set to@w{ }0. 5695 5696The fill mode status is associated with the current environment 5697(@pxref{Environments}). 5698 5699See @ref{Line Control}, for interaction with the @code{\c} escape. 5700@endDefreq 5701 5702@DefreqList {ad, [@Var{mode}]} 5703@DefregListEnd {.j} 5704Set adjusting mode. 5705 5706Activation and deactivation of adjusting is done implicitly with 5707calls to the @code{fi} or @code{nf} requests. 5708 5709@var{mode} can have one of the following values: 5710 5711@table @code 5712@item l 5713@cindex ragged-right 5714Adjust text to the left margin. This produces what is traditionally 5715called ragged-right text. 5716 5717@item r 5718@cindex ragged-left 5719Adjust text to the right margin, producing ragged-left text. 5720 5721@item c 5722@cindex centered text 5723@cindex @code{ce} request, difference to @samp{.ad@w{ }c} 5724Center filled text. This is different to the @code{ce} request which 5725only centers text without filling. 5726 5727@item b 5728@itemx n 5729Justify to both margins. This is the default used by @code{gtroff}. 5730@end table 5731 5732With no argument, @code{gtroff} adjusts lines in the same way it did 5733before adjusting was deactivated (with a call to @code{na}, for 5734example). 5735 5736@Example 5737text 5738.ad r 5739text 5740.ad c 5741text 5742.na 5743text 5744.ad \" back to centering 5745text 5746@endExample 5747 5748@cindex adjustment mode register (@code{.j}) 5749The current adjustment mode is available in the read-only number 5750register @code{.j}; it can be stored and subsequently used to set 5751adjustment. 5752 5753The adjustment mode status is associated with the current environment 5754(@pxref{Environments}). 5755@endDefreq 5756 5757@Defreq {na, } 5758Disable adjusting. This request won't change the current adjustment 5759mode: A subsequent call to @code{ad} uses the previous adjustment 5760setting. 5761 5762The adjustment mode status is associated with the current environment 5763(@pxref{Environments}). 5764@endDefreq 5765 5766@DefreqList {brp, } 5767@DefescListEnd {\\p, , , } 5768Adjust the current line and cause a break. 5769 5770In most cases this produces very ugly results since @code{gtroff} 5771doesn't have a sophisticated paragraph building algorithm (as @TeX{} 5772have, for example); instead, @code{gtroff} fills and adjusts a paragraph 5773line by line: 5774 5775@Example 5776 This is an uninteresting sentence. 5777 This is an uninteresting sentence.\p 5778 This is an uninteresting sentence. 5779@endExample 5780 5781@noindent 5782is formatted as 5783 5784@Example 5785 This is an uninteresting sentence. This is an 5786 uninteresting sentence. 5787 This is an uninteresting sentence. 5788@endExample 5789@endDefreq 5790 5791@DefreqList {ss, word_space_size [@Var{sentence_space_size}]} 5792@DefregItem {.ss} 5793@DefregListEnd {.sss} 5794@cindex word space size register (@code{.ss}) 5795@cindex size of word space register (@code{.ss}) 5796@cindex space between words register (@code{.ss}) 5797@cindex sentence space size register (@code{.sss}) 5798@cindex size of sentence space register (@code{.sss}) 5799@cindex space between sentences register (@code{.sss}) 5800Change the minimum size of a space between filled words. It takes its 5801units as one twelfth of the space width parameter for the current 5802font. Initially both the @var{word_space_size} and 5803@var{sentence_space_size} are@w{ }12. 5804 5805@cindex fill mode 5806@cindex mode, fill 5807If two arguments are given to the @code{ss} request, the second 5808argument sets the sentence space size. If the second argument is not 5809given, sentence space size is set to @var{word_space_size}. The 5810sentence space size is used in two circumstances: If the end of a 5811sentence occurs at the end of a line in fill mode, then both an 5812inter-word space and a sentence space are added; if two spaces follow 5813the end of a sentence in the middle of a line, then the second space 5814is a sentence space. If a second argument is never given to the 5815@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the 5816same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as 5817in @acronym{UNIX} @code{troff}, a sentence should always be followed 5818by either a newline or two spaces. 5819 5820The read-only number registers @code{.ss} and @code{.sss} hold the 5821values of the parameters set by the first and second arguments of the 5822@code{ss} request. 5823 5824The word space and sentence space values are associated with the current 5825environment (@pxref{Environments}). 5826 5827Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not} 5828ignored if a TTY output device is used; the given values are then 5829rounded down to a multiple of@w{ }12 (@pxref{Implementation Differences}). 5830 5831The request is ignored if there is no parameter. 5832@endDefreq 5833 5834@DefreqList {ce, [@Var{nnn}]} 5835@DefregListEnd {.ce} 5836@cindex centering lines (@code{ce}) 5837@cindex lines, centering (@code{ce}) 5838Center text. While the @w{@samp{.ad c}} request also centers text, 5839it fills the text as well. @code{ce} does not fill the 5840text it affects. This request causes a break. The number of lines 5841still to be centered is associated with the current environment 5842(@pxref{Environments}). 5843 5844The following example demonstrates the differences. 5845Here the input: 5846 5847@Example 5848.ll 4i 5849.ce 1000 5850This is a small text fragment which shows the differences 5851between the `.ce' and the `.ad c' request. 5852.ce 0 5853 5854.ad c 5855This is a small text fragment which shows the differences 5856between the `.ce' and the `.ad c' request. 5857@endExample 5858 5859@noindent 5860And here the result: 5861 5862@Example 5863 This is a small text fragment which 5864 shows the differences 5865between the `.ce' and the `.ad c' request. 5866 5867 This is a small text fragment which 5868shows the differences between the `.ce' 5869 and the `.ad c' request. 5870@endExample 5871 5872With no arguments, @code{ce} centers the next line of text. @var{nnn} 5873specifies the number of lines to be centered. If the argument is zero 5874or negative, centering is disabled. 5875 5876The basic length for centering text is the line length (as set with the 5877@code{ll} request) minus the indentation (as set with the @code{in} 5878request). Temporary indentation is ignored. 5879 5880As can be seen in the previous example, it is a common idiom to turn 5881on centering for a large number of lines, and to turn off centering 5882after text to be centered. This is useful for any request which takes 5883a number of lines as an argument. 5884 5885The @code{.ce} read-only number register contains the number of lines 5886remaining to be centered, as set by the @code{ce} request. 5887@endDefreq 5888 5889@DefreqList {rj, [@Var{nnn}]} 5890@DefregListEnd {.rj} 5891@cindex justifying text (@code{rj}) 5892@cindex text, justifying (@code{rj}) 5893@cindex right-justifying (@code{rj}) 5894Justify unfilled text to the right margin. Arguments are identical to 5895the @code{ce} request. The @code{.rj} read-only number register is 5896the number of lines to be right-justified as set by the @code{rj} 5897request. This request causes a break. The number of lines still to be 5898right-justified is associated with the current environment 5899(@pxref{Environments}). 5900@endDefreq 5901 5902 5903@c ===================================================================== 5904 5905@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference 5906@section Manipulating Hyphenation 5907@cindex manipulating hyphenation 5908@cindex hyphenation, manipulating 5909 5910As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words. 5911There are a number of ways to influence hyphenation. 5912 5913@DefreqList {hy, [@Var{mode}]} 5914@DefregListEnd {.hy} 5915Enable hyphenation. The request has an optional numeric argument, 5916@var{mode}, to restrict hyphenation if necessary: 5917 5918@table @code 5919@item 1 5920The default argument if @var{mode} is omitted. Hyphenate without 5921restrictions. This is also the start-up value of @code{gtroff}. 5922 5923@item 2 5924Do not hyphenate the last word on a page or column. 5925 5926@item 4 5927Do not hyphenate the last two characters of a word. 5928 5929@item 8 5930Do not hyphenate the first two characters of a word. 5931@end table 5932 5933Values in the previous table are additive. For example, the value@w{ 5934}12 causes @code{gtroff} to neither hyphenate the last two nor the first 5935two characters of a word. 5936 5937@cindex hyphenation restrictions register (@code{.hy}) 5938The current hyphenation restrictions can be found in the read-only 5939number register @samp{.hy}. 5940 5941The hyphenation mode is associated with the current environment 5942(@pxref{Environments}). 5943@endDefreq 5944 5945@Defreq {nh, } 5946Disable hyphenation (i.e., set the hyphenation mode to zero). Note 5947that the hyphenation mode of the last call to @code{hy} is not 5948remembered. 5949 5950The hyphenation mode is associated with the current environment 5951(@pxref{Environments}). 5952@endDefreq 5953 5954@DefreqList {hlm, [@Var{nnn}]} 5955@DefregItem {.hlm} 5956@DefregListEnd {.hlc} 5957@cindex explicit hyphen (@code{\%}) 5958@cindex hyphen, explicit (@code{\%}) 5959@cindex consecutive hyphenated lines (@code{hlm}) 5960@cindex lines, consecutive hyphenated (@code{hlm}) 5961@cindex hyphenated lines, consecutive (@code{hlm}) 5962Set the maximum number of consecutive hyphenated lines to @var{nnn}. 5963If this number is negative, there is no maximum. The default value 5964is@w{ }@minus{}1 if @var{nnn} is omitted. This value is associated 5965with the current environment (@pxref{Environments}). Only lines 5966output from a given environment count towards the maximum associated 5967with that environment. Hyphens resulting from @code{\%} are counted; 5968explicit hyphens are not. 5969 5970The current setting of @code{hlm} is available in the @code{.hlm} 5971read-only number register. Also the number of immediately preceding 5972consecutive hyphenated lines are available in the read-only number 5973register @samp{.hlc}. 5974@endDefreq 5975 5976@Defreq {hw, word1 word2 @dots{}} 5977Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The 5978words must be given with hyphens at the hyphenation points. For 5979example: 5980 5981@Example 5982.hw in-sa-lub-rious 5983@endExample 5984 5985@noindent 5986Besides the space character, any character whose hyphenation code value 5987is zero can be used to separate the arguments of @code{hw} (see the 5988documentation for the @code{hcode} request below for more information). 5989In addition, this request can be used more than once. 5990 5991Hyphenation exceptions specified with the @code{hw} request are 5992associated with the current hyphenation language; it causes an error 5993if there is no current hyphenation language. 5994 5995This request is ignored if there is no parameter. 5996 5997In old versions of @code{troff} there was a limited amount of space to 5998store such information; fortunately, with @code{gtroff}, this is no 5999longer a restriction. 6000@endDefreq 6001 6002@DefescList {\\%, , , } 6003@deffnx Escape @t{\:} 6004@ifnotinfo 6005@esindex \: 6006@end ifnotinfo 6007@ifinfo 6008@esindex @r{<colon>} 6009@end ifinfo 6010@cindex hyphenation character (@code{\%}) 6011@cindex character, hyphenation (@code{\%}) 6012@cindex disabling hyphenation (@code{\%}) 6013@cindex hyphenation, disabling (@code{\%}) 6014To tell @code{gtroff} how to hyphenate words on the fly, use the 6015@code{\%} escape, also known as the @dfn{hyphenation character}. 6016Preceding a word with this character prevents it from being 6017hyphenated; putting it inside a word indicates to @code{gtroff} that 6018the word may be hyphenated at that point. Note that this mechanism 6019only affects that one occurrence of the word; to change the 6020hyphenation of a word for the entire document, use the @code{hw} 6021request. 6022 6023The @code{\:} escape inserts a zero-width break point 6024(that is, the word breaks but without adding a hyphen). 6025 6026@Example 6027... check the /var/log/\:httpd/\:access_log file ... 6028@endExample 6029 6030@cindex @code{\X}, followed by @code{\%} 6031@cindex @code{\Y}, followed by @code{\%} 6032@cindex @code{\%}, following @code{\X} or @code{\Y} 6033Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%} 6034escape in (say) @w{@samp{ \X'...'\%foobar}} and 6035@w{@samp{ \Y'...'\%foobar}} no longer prevents hyphenation but inserts 6036a hyphenation point at the beginning of @samp{foobar}; most likely 6037this isn't what you want to do. 6038@endDefesc 6039 6040@Defreq {hc, [@Var{char}]} 6041Change the hyphenation character to @var{char}. This character then 6042works the same as the @code{\%} escape, and thus, no longer appears in 6043the output. Without an argument, @code{hc} resets the hyphenation 6044character to be @code{\%} (the default) only. 6045 6046The hyphenation character is associated with the current environment 6047(@pxref{Environments}). 6048@endDefreq 6049 6050@DefreqList {hpf, pattern_file} 6051@DefreqItem {hpfa, pattern_file} 6052@DefreqListEnd {hpfcode, a b [c d @dots{}]} 6053@cindex hyphenation patterns (@code{hpf}) 6054@cindex patterns for hyphenation (@code{hpf}) 6055Read in a file of hyphenation patterns. This file is searched for in 6056the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is 6057searched for if the @option{-m@var{name}} option is specified. 6058 6059It should have the same format as (simple) @TeX{} patterns files. 6060More specifically, the following scanning rules are implemented. 6061 6062@itemize @bullet 6063@item 6064A percent sign starts a comment (up to the end of the line) 6065even if preceded by a backslash. 6066 6067@item 6068No support for `digraphs' like @code{\$}. 6069 6070@item 6071@code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character 6072code of @var{x} in the range 0-127) are recognized; other use of @code{^} 6073causes an error. 6074 6075@item 6076No macro expansion. 6077 6078@item 6079@code{hpf} checks for the expression @code{\patterns@{@dots{}@}} 6080(possibly with whitespace before and after the braces). 6081Everything between the braces is taken as hyphenation patterns. 6082Consequently, @code{@{} and @code{@}} are not allowed in patterns. 6083 6084@item 6085Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation 6086exceptions. 6087 6088@item 6089@code{\endinput} is recognized also. 6090 6091@item 6092For backwards compatibility, if @code{\patterns} is missing, 6093the whole file is treated as a list of hyphenation patterns 6094(only recognizing the @code{%} character as the start of a comment). 6095@end itemize 6096 6097If no @code{hpf} request is specified (either in the document or in a 6098macro package), @code{gtroff} won't hyphenate at all. 6099 6100The @code{hpfa} request appends a file of patterns to the current list. 6101 6102The @code{hpfcode} request defines mapping values for character codes in 6103hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping 6104(after reading the patterns) before replacing or appending them to 6105the current list of patterns. Its arguments are pairs of character codes 6106-- integers from 0 to@w{ }255. The request maps character code@w{ }@var{a} 6107to code@w{ }@var{b}, code@w{ }@var{c} to code@w{ }@var{d}, and so on. You 6108can use character codes which would be invalid otherwise. 6109 6110@pindex troffrc 6111@pindex troffrc-end 6112@pindex hyphen.us 6113The set of hyphenation patterns is associated with the current language 6114set by the @code{hla} request. The @code{hpf} request is usually 6115invoked by the @file{troffrc} or @file{troffrc-end} file; by default, 6116@file{troffrc} loads hyphenation patterns for American English (in file 6117@file{hyphen.us}). 6118 6119A second call to @code{hpf} (for the same language) will replace the 6120hyphenation patterns with the new ones. 6121 6122Invoking @code{hpf} causes an error if there is no current hyphenation 6123language. 6124@endDefreq 6125 6126@Defreq {hcode, c1 code1 c2 code2 @dots{}} 6127@cindex hyphenation code (@code{hcode}) 6128@cindex code, hyphenation (@code{hcode}) 6129Set the hyphenation code of character @var{c1} to @var{code1}, that of 6130@var{c2} to @var{code2}, etc. A hyphenation code must be a single 6131input character (not a special character) other than a digit or a 6132space. Initially each lower-case letter (@samp{a}-@samp{z}) has its 6133hyphenation code set to itself, and each upper-case letter 6134(@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case 6135version of itself. 6136 6137This request is ignored if it has no parameter. 6138@endDefreq 6139 6140@DefreqList {hym, [@Var{length}]} 6141@DefregListEnd {.hym} 6142@cindex hyphenation margin (@code{hym}) 6143@cindex margin for hyphenation (@code{hym}) 6144@cindex @code{ad} request, and hyphenation margin 6145Set the (right) hyphenation margin to @var{length}. If the current 6146adjustment mode is not @samp{b} or @samp{n}, the line is not 6147hyphenated if it is shorter than @var{length}. Without an argument, 6148the hyphenation margin is reset to its default value, which is@w{ }0. 6149The default scaling indicator for this request is @samp{m}. The 6150hyphenation margin is associated with the current environment 6151(@pxref{Environments}). 6152 6153A negative argument resets the hyphenation margin to zero, emitting 6154a warning of type @samp{range}. 6155 6156@cindex hyphenation margin register (@code{.hym}) 6157The current hyphenation margin is available in the @code{.hym} read-only 6158number register. 6159@endDefreq 6160 6161@DefreqList {hys, [@Var{hyphenation_space}]} 6162@DefregListEnd {.hys} 6163@cindex hyphenation space (@code{hys}) 6164@cindex @code{ad} request, and hyphenation space 6165Set the hyphenation space to @var{hyphenation_space}. If the current 6166adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line 6167if it can be justified by adding no more than @var{hyphenation_space} 6168extra space to each word space. Without argument, the hyphenation 6169space is set to its default value, which is@w{ }0. The default 6170scaling indicator for this request is @samp{m}. The hyphenation 6171space is associated with the current environment 6172(@pxref{Environments}). 6173 6174A negative argument resets the hyphenation space to zero, emitting a 6175warning of type @samp{range}. 6176 6177@cindex hyphenation space register (@code{.hys}) 6178The current hyphenation space is available in the @code{.hys} read-only 6179number register. 6180@endDefreq 6181 6182@Defreq {shc, [@Var{glyph}]} 6183@cindex soft hyphen character, setting (@code{shc}) 6184@cindex character, soft hyphen, setting (@code{shc}) 6185@cindex glyph, soft hyphen (@code{hy}) 6186@cindex soft hyphen glyph (@code{hy}) 6187@cindex @code{char} request, and soft hyphen character 6188@cindex @code{tr} request, and soft hyphen character 6189Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft 6190hyphen character} is a misnomer since it is an output glyph.} If the 6191argument is omitted, the soft hyphen character is set to the default 6192glyph @code{\(hy} (this is the start-up value of @code{gtroff} also). 6193The soft hyphen character is the glyph that is inserted when a word is 6194hyphenated at a line break. If the soft hyphen character does not 6195exist in the font of the character immediately preceding a potential 6196break point, then the line is not broken at that point. Neither 6197definitions (specified with the @code{char} request) nor translations 6198(specified with the @code{tr} request) are considered when finding the 6199soft hyphen character. 6200@endDefreq 6201 6202@DefreqList {hla, language} 6203@DefregListEnd {.hla} 6204@cindex @code{hpf} request, and hyphenation language 6205@cindex @code{hw} request, and hyphenation language 6206@pindex troffrc 6207@pindex troffrc-end 6208Set the current hyphenation language to the string @var{language}. 6209Hyphenation exceptions specified with the @code{hw} request and 6210hyphenation patterns specified with the @code{hpf} and @code{hpfa} 6211requests are both associated with the current hyphenation language. 6212The @code{hla} request is usually invoked by the @file{troffrc} or the 6213@file{troffrc-end} files; @file{troffrc} sets the default language to 6214@samp{us}. 6215 6216@cindex hyphenation language register (@code{.hla}) 6217The current hyphenation language is available as a string in the 6218read-only number register @samp{.hla}. 6219 6220@Example 6221.ds curr_language \n[.hla] 6222\*[curr_language] 6223 @result{} us 6224@endExample 6225@endDefreq 6226 6227 6228@c ===================================================================== 6229 6230@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference 6231@section Manipulating Spacing 6232@cindex manipulating spacing 6233@cindex spacing, manipulating 6234 6235@Defreq {sp, [@Var{distance}]} 6236Space downwards @var{distance}. With no argument it advances 1@w{ 6237}line. A negative argument causes @code{gtroff} to move up the page 6238the specified distance. If the argument is preceded by a @samp{|} 6239then @code{gtroff} moves that distance from the top of the page. This 6240request causes a line break. The default scaling indicator is @samp{v}. 6241@endDefreq 6242 6243@DefreqList {ls, [@Var{nnn}]} 6244@DefregListEnd {.L} 6245@cindex double-spacing (@code{ls}) 6246Output @w{@var{nnn}@minus{}1} blank lines after each line of text. 6247With no argument, @code{gtroff} uses the previous value before the 6248last @code{ls} call. 6249 6250@Example 6251.ls 2 \" This causes double-spaced output 6252.ls 3 \" This causes triple-spaced output 6253.ls \" Again double-spaced 6254@endExample 6255 6256The line spacing is associated with the current environment 6257(@pxref{Environments}). 6258 6259@cindex line spacing register (@code{.L}) 6260The read-only number register @code{.L} contains the current line 6261spacing setting. 6262@endDefreq 6263 6264@xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs} 6265as alternatives to @code{ls}. 6266 6267@DefescList {\\x, ', spacing, '} 6268@DefregListEnd {.a} 6269Sometimes, extra vertical spacing is only needed occasionally, e.g.@: 6270to allow space for a tall construct (like an equation). The @code{\x} 6271escape does this. The escape is given a numerical argument, usually 6272enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator 6273is @samp{v}. If this number is positive extra vertical space is 6274inserted below the current line. A negative number adds space above. 6275If this escape is used multiple times on the same line, the maximum of 6276the values is used. 6277 6278@xref{Escapes}, for details on parameter delimiting characters. 6279 6280@cindex extra post-vertical line space register (@code{.a}) 6281The @code{.a} read-only number register contains the most recent 6282(nonnegative) extra vertical line space. 6283 6284Using @code{\x} can be necessary in combination with the @code{\b} 6285escape, as the following example shows. 6286 6287@Example 6288This is a test with the \[rs]b escape. 6289.br 6290This is a test with the \[rs]b escape. 6291.br 6292This is a test with \b'xyz'\x'-1m'\x'1m'. 6293.br 6294This is a test with the \[rs]b escape. 6295.br 6296This is a test with the \[rs]b escape. 6297@endExample 6298 6299@noindent 6300produces 6301 6302@Example 6303This is a test with the \b escape. 6304This is a test with the \b escape. 6305 x 6306This is a test with y. 6307 z 6308This is a test with the \b escape. 6309This is a test with the \b escape. 6310@endExample 6311@endDefesc 6312 6313@DefreqList {ns, } 6314@DefreqItem {rs, } 6315@DefregListEnd {.ns} 6316@cindex @code{sp} request, and no-space mode 6317@cindex no-space mode (@code{ns}) 6318@cindex mode, no-space (@code{ns}) 6319@cindex blank lines, disabling 6320@cindex lines, blank, disabling 6321Enable @dfn{no-space mode}. In this mode, spacing (either via 6322@code{sp} or via blank lines) is disabled. The @code{bp} request to 6323advance to the next page is also disabled, except if it is accompanied 6324by a page number (see @ref{Page Control}, for more information). This 6325mode ends when actual text is output or the @code{rs} request is 6326encountered which ends no-space mode. The read-only number register 6327@code{.ns} is set to@w{ }1 as long as no-space mode is active. 6328 6329This request is useful for macros that conditionally 6330insert vertical space before the text starts 6331(for example, a paragraph macro could insert some space 6332except when it is the first paragraph after a section header). 6333@endDefreq 6334 6335 6336@c ===================================================================== 6337 6338@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 6339@section Tabs and Fields 6340@cindex tabs, and fields 6341@cindex fields, and tabs 6342 6343@cindex @acronym{EBCDIC} encoding of a tab 6344A tab character (@acronym{ASCII} char@w{ }9, @acronym{EBCDIC} char@w{ 6345}5) causes a horizontal movement to the next tab stop (much 6346like it did on a typewriter). 6347 6348@Defesc {\\t, , , } 6349@cindex tab character, non-interpreted (@code{\t}) 6350@cindex character, tab, non-interpreted (@code{\t}) 6351This escape is a non-interpreted tab character. In copy mode 6352(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 6353@endDefesc 6354 6355@DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 6356@DefregListEnd {.tabs} 6357Change tab stop positions. This request takes a series of tab 6358specifiers as arguments (optionally divided into two groups with the 6359letter @samp{T}) which indicate where each tab stop is to be 6360(overriding any previous settings). 6361 6362Tab stops can be specified absolutely, i.e., as the distance from the 6363left margin. For example, the following sets 6@w{ }tab stops every 6364one inch. 6365 6366@Example 6367.ta 1i 2i 3i 4i 5i 6i 6368@endExample 6369 6370Tab stops can also be specified using a leading @samp{+} 6371which means that the specified tab stop is set relative to 6372the previous tab stop. For example, the following is equivalent to the 6373previous example. 6374 6375@Example 6376.ta 1i +1i +1i +1i +1i +1i 6377@endExample 6378 6379@code{gtroff} supports an extended syntax to specify repeat values after 6380the @samp{T} mark (these values are always taken as relative) -- this is 6381the usual way to specify tabs set at equal intervals. The following is, 6382yet again, the same as the previous examples. It does even more since 6383it defines an infinite number of tab stops separated by one inch. 6384 6385@Example 6386.ta T 1i 6387@endExample 6388 6389Now we are ready to interpret the full syntax given at the beginning: 6390Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 6391tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 6392and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 6393@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 6394 6395Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 639620c 23c 28c 30c @dots{}}. 6397 6398The material in each tab column (i.e., the column between two tab stops) 6399may be justified to the right or left or centered in the column. This 6400is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 6401specifier. The default justification is @samp{L}. Example: 6402 6403@Example 6404.ta 1i 2iC 3iR 6405@endExample 6406 6407Some notes: 6408 6409@itemize @bullet 6410@item 6411The default unit of the @code{ta} request is @samp{m}. 6412 6413@item 6414A tab stop is converted into a non-breakable horizontal movement which 6415can be neither stretched nor squeezed. For example, 6416 6417@Example 6418.ds foo a\tb\tc 6419.ta T 5i 6420\*[foo] 6421@endExample 6422 6423@noindent 6424creates a single line which is a bit longer than 10@w{ }inches (a string 6425is used to show exactly where the tab characters are). Now consider the 6426following: 6427 6428@Example 6429.ds bar a\tb b\tc 6430.ta T 5i 6431\*[bar] 6432@endExample 6433 6434@noindent 6435@code{gtroff} first converts the tab stops of the line into unbreakable 6436horizontal movements, then splits the line after the second @samp{b} 6437(assuming a sufficiently short line length). Usually, this isn't what 6438the user wants. 6439 6440@item 6441Superfluous tabs (i.e., tab characters which do not correspond to a tab 6442stop) are ignored except the first one which delimits the characters 6443belonging to the last tab stop for right-justifying or centering. 6444Consider the following example 6445 6446@Example 6447.ds Z foo\tbar\tfoo 6448.ds ZZ foo\tbar\tfoobar 6449.ds ZZZ foo\tbar\tfoo\tbar 6450.ta 2i 4iR 6451\*[Z] 6452.br 6453\*[ZZ] 6454.br 6455\*[ZZZ] 6456.br 6457@endExample 6458 6459@noindent 6460which produces the following output: 6461 6462@Example 6463foo bar foo 6464foo bar foobar 6465foo bar foobar 6466@endExample 6467 6468@noindent 6469The first line right-justifies the second `foo' relative to the tab 6470stop. The second line right-justifies `foobar'. The third line finally 6471right-justifies only `foo' because of the additional tab character which 6472marks the end of the string belonging to the last defined tab stop. 6473 6474@item 6475Tab stops are associated with the current environment 6476(@pxref{Environments}). 6477 6478@item 6479Calling @code{ta} without an argument removes all tab stops. 6480 6481@item 6482@cindex tab stops, for TTY output devices 6483The start-up value of @code{gtroff} is @w{@samp{T 0.5i}} in troff mode 6484and @w{@samp{T 0.8i}} in nroff mode (the latter is done with an 6485explicit call to the @code{ta} request in the file @file{tty.tmac}. 6486@end itemize 6487 6488@cindex tab settings register (@code{.tabs}) 6489The read-only number register @code{.tabs} contains a string 6490representation of the current tab settings suitable for use as an 6491argument to the @code{ta} request. 6492 6493@Example 6494.ds tab-string \n[.tabs] 6495\*[tab-string] 6496 @result{} T120u 6497@endExample 6498 6499@cindex @code{.S} register, Plan@w{ }9 alias for @code{.tabs} 6500@cindex @code{.tabs} register, Plan@w{ }9 alias (@code{.S}) 6501The @code{troff} version of the Plan@w{ }9 operating system uses 6502register @code{.S} for the same purpose. 6503@endDefreq 6504 6505@Defreq {tc, [@Var{fill-glyph}]} 6506@cindex tab repetition character (@code{tc}) 6507@cindex character, tab repetition (@code{tc}) 6508@cindex glyph, tab repetition (@code{tc}) 6509Normally @code{gtroff} fills the space to the next tab stop with 6510whitespace. This can be changed with the @code{tc} request. With no 6511argument @code{gtroff} reverts to using whitespace, which is the 6512default. The value of this @dfn{tab repetition character} is 6513associated with the current environment 6514(@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a 6515misnomer since it is an output glyph.} 6516@endDefreq 6517 6518@DefreqList {linetabs, n} 6519@DefregListEnd {.linetabs} 6520@cindex tab, line-tabs mode 6521@cindex line-tabs mode 6522@cindex mode, line-tabs 6523If @var{n} is missing or not zero, enable @dfn{line-tabs} mode, 6524or disable it otherwise (the default). 6525In line-tabs mode, @code{gtroff} computes tab distances 6526relative to the (current) output line instead of the input line. 6527 6528For example, the following code: 6529 6530@Example 6531.ds x a\t\c 6532.ds y b\t\c 6533.ds z c 6534.ta 1i 3i 6535\*x 6536\*y 6537\*z 6538@endExample 6539 6540@noindent 6541in normal mode, results in the output 6542 6543@Example 6544a b c 6545@endExample 6546 6547@noindent 6548in line-tabs mode, the same code outputs 6549 6550@Example 6551a b c 6552@endExample 6553 6554Line-tabs mode is associated with the current environment. 6555The read-only register @code{.linetabs} is set to@w{ }1 if in line-tabs 6556mode, and 0 in normal mode. 6557@endDefreq 6558 6559@menu 6560* Leaders:: 6561* Fields:: 6562@end menu 6563 6564@c --------------------------------------------------------------------- 6565 6566@node Leaders, Fields, Tabs and Fields, Tabs and Fields 6567@subsection Leaders 6568@cindex leaders 6569 6570Sometimes it may may be desirable to use the @code{tc} request to fill a 6571particular tab stop with a given glyph (for example dots in a table 6572of contents), but also normal tab stops on the rest of the line. For 6573this @code{gtroff} provides an alternate tab mechanism, called 6574@dfn{leaders} which does just that. 6575 6576@cindex leader character 6577A leader character (character code@w{ }1) behaves similarly to a tab 6578character: It moves to the next tab stop. The only difference is that 6579for this movement, the fill glyph defaults to a period character and 6580not to space. 6581 6582@Defesc {\\a, , , } 6583@cindex leader character, non-interpreted (@code{\a}) 6584@cindex character, leader, non-interpreted (@code{\a}) 6585This escape is a non-interpreted leader character. In copy mode 6586(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 6587character. 6588@endDefesc 6589 6590@Defreq {lc, [@Var{fill-glyph}]} 6591@cindex leader repetition character (@code{lc}) 6592@cindex character, leader repetition (@code{lc}) 6593@cindex glyph, leader repetition (@code{lc}) 6594Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader 6595repetition character} is a misnomer since it is an output glyph.} 6596Without an argument, leaders act the same as tabs (i.e., using 6597whitespace for filling). @code{gtroff}'s start-up value is a dot 6598(@samp{.}). The value of the leader repetition character is 6599associated with the current environment (@pxref{Environments}). 6600@endDefreq 6601 6602@cindex table of contents 6603@cindex contents, table of 6604For a table of contents, to name an example, tab stops may be defined so 6605that the section number is one tab stop, the title is the second with 6606the remaining space being filled with a line of dots, and then the page 6607number slightly separated from the dots. 6608 6609@Example 6610.ds entry 1.1\tFoo\a\t12 6611.lc . 6612.ta 1i 5i +.25i 6613\*[entry] 6614@endExample 6615 6616@noindent 6617This produces 6618 6619@Example 66201.1 Foo.......................................... 12 6621@endExample 6622 6623@c --------------------------------------------------------------------- 6624 6625@node Fields, , Leaders, Tabs and Fields 6626@subsection Fields 6627@cindex fields 6628 6629@cindex field delimiting character (@code{fc}) 6630@cindex delimiting character, for fields (@code{fc}) 6631@cindex character, field delimiting (@code{fc}) 6632@cindex field padding character (@code{fc}) 6633@cindex padding character, for fields (@code{fc}) 6634@cindex character, field padding (@code{fc}) 6635@dfn{Fields} are a more general way of laying out tabular data. A field 6636is defined as the data between a pair of @dfn{delimiting characters}. 6637It contains substrings which are separated by @dfn{padding characters}. 6638The width of a field is the distance on the @emph{input} line from the 6639position where the field starts to the next tab stop. A padding 6640character inserts stretchable space similar to @TeX{}'s @code{\hss} 6641command (thus it can even be negative) to make the sum of all substring 6642lengths plus the stretchable space equal to the field width. If more 6643than one padding character is inserted, the available space is evenly 6644distributed among them. 6645 6646@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 6647Define a delimiting and a padding character for fields. If the latter 6648is missing, the padding character defaults to a space character. If 6649there is no argument at all, the field mechanism is disabled (which is 6650the default). Note that contrary to e.g.@: the tab repetition 6651character, delimiting and padding characters are @emph{not} associated 6652to the current environment (@pxref{Environments}). 6653 6654Example: 6655 6656@Example 6657.fc # ^ 6658.ta T 3i 6659#foo^bar^smurf# 6660.br 6661#foo^^bar^smurf# 6662@endExample 6663 6664@noindent 6665and here the result: 6666 6667@Example 6668foo bar smurf 6669foo bar smurf 6670@endExample 6671@endDefreq 6672 6673 6674@c ===================================================================== 6675 6676@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 6677@section Character Translations 6678@cindex character translations 6679@cindex translations of characters 6680 6681@cindex control character, changing (@code{cc}) 6682@cindex character, control, changing (@code{cc}) 6683@cindex no-break control character, changing (@code{c2}) 6684@cindex character, no-break control, changing (@code{c2}) 6685@cindex control character, no-break, changing (@code{c2}) 6686The control character (@samp{.}) and the no-break control character 6687(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 6688respectively. 6689 6690@Defreq {cc, [@Var{c}]} 6691Set the control character to@w{ }@var{c}. With no argument the default 6692control character @samp{.} is restored. The value of the control 6693character is associated with the current environment 6694(@pxref{Environments}). 6695@endDefreq 6696 6697@Defreq {c2, [@Var{c}]} 6698Set the no-break control character to@w{ }@var{c}. With no argument the 6699default control character @samp{'} is restored. The value of the 6700no-break control character is associated with the current environment 6701(@pxref{Environments}). 6702@endDefreq 6703 6704@Defreq {eo, } 6705@cindex disabling @code{\} (@code{eo}) 6706@cindex @code{\}, disabling (@code{eo}) 6707Disable the escape mechanism completely. After executing this 6708request, the backslash character @samp{\} no longer starts an escape 6709sequence. 6710 6711This request can be very helpful in writing macros since it is not 6712necessary then to double the escape character. Here an example: 6713 6714@Example 6715.\" This is a simplified version of the 6716.\" .BR request from the man macro package 6717.eo 6718.de BR 6719. ds result \& 6720. while (\n[.$] >= 2) \@{\ 6721. as result \fB\$1\fR\$2 6722. shift 2 6723. \@} 6724. if \n[.$] .as result \fB\$1 6725\*[result] 6726. ft R 6727.. 6728.ec 6729@endExample 6730@endDefreq 6731 6732@Defreq {ec, [@Var{c}]} 6733@cindex escape character, changing (@code{ec}) 6734@cindex character, escape, changing (@code{ec}) 6735Set the escape character to@w{ }@var{c}. With no argument the default 6736escape character @samp{\} is restored. It can be also used to 6737re-enable the escape mechanism after an @code{eo} request. 6738 6739Note that changing the escape character globally will likely break 6740macro packages since @code{gtroff} has no mechanism to `intern' macros, 6741i.e., to convert a macro definition into an internal form which is 6742independent of its representation (@TeX{} has this mechanism). 6743If a macro is called, it is executed literally. 6744@endDefreq 6745 6746@DefreqList {ecs, } 6747@DefreqListEnd {ecr, } 6748The @code{ecs} request saves the current escape character 6749in an internal register. 6750Use this request in combination with the @code{ec} request to 6751temporarily change the escape character. 6752 6753The @code{ecr} request restores the escape character 6754saved with @code{ecs}. 6755Without a previous call to @code{ecs}, this request 6756sets the escape character to @code{\}. 6757@endDefreq 6758 6759@DefescList {\\\\, , , } 6760@DefescItem {\\e, , , } 6761@DefescListEnd {\\E, , , } 6762Print the current escape character (which is the backslash character 6763@samp{\} by default). 6764 6765@code{\\} is a `delayed' backslash; more precisely, it is the default 6766escape character followed by a backslash, which no longer has special 6767meaning due to the leading escape character. It is @emph{not} an escape 6768sequence in the usual sense! In any unknown escape sequence 6769@code{\@var{X}} the escape character is ignored and @var{X} is printed. 6770But if @var{X} is equal to the current escape character, no warning is 6771emitted. 6772 6773As a consequence, only at top-level or in a diversion a backslash glyph is 6774printed; in copy-in mode, it expands to a single backslash which then 6775combines with the following character to an escape sequence. 6776 6777The @code{\E} escape differs from @code{\e} by printing an escape 6778character that is not interpreted in copy mode. 6779Use this to define strings with escapes that work 6780when used in copy mode (for example, as a macro argument). 6781The following example defines strings to begin and end 6782a superscript: 6783 6784@Example 6785.ds @{ \v'-.3m'\s'\Es[.s]*60/100' 6786.ds @} \s0\v'.3m' 6787@endExample 6788 6789Another example to demonstrate the differences between the various escape 6790sequences, using a strange escape character, @samp{-}. 6791 6792@Example 6793.ec - 6794.de xxx 6795--A'123' 6796.. 6797.xxx 6798 @result{} -A'foo' 6799@endExample 6800 6801@noindent 6802The result is surprising for most users, expecting @samp{1} since 6803@samp{foo} is a valid identifier. What has happened? As mentioned 6804above, the leading escape character makes the following character 6805ordinary. Written with the default escape character the sequence 6806@samp{--} becomes @samp{\-} -- this is the minus sign. 6807 6808If the escape character followed by itself is a valid escape sequence, 6809only @code{\E} yields the expected result: 6810 6811@Example 6812.ec - 6813.de xxx 6814-EA'123' 6815.. 6816.xxx 6817 @result{} 1 6818@endExample 6819@endDefesc 6820 6821@Defesc {\\., , , } 6822Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence. 6823As before, a warning message is suppressed if the escape character is 6824followed by a dot, and the dot itself is printed. 6825 6826@Example 6827.de foo 6828. nop foo 6829. 6830. de bar 6831. nop bar 6832\\.. 6833. 6834.. 6835.foo 6836.bar 6837 @result{} foo bar 6838@endExample 6839 6840@noindent 6841The first backslash is consumed while the macro is read, and the second 6842is swallowed while exexuting macro @code{foo}. 6843@endDefesc 6844 6845A @dfn{translation} is a mapping of an input character to an output 6846glyph. The mapping occurs at output time, i.e., the input character 6847gets assigned the metric information of the mapped output character 6848right before input tokens are converted to nodes (@pxref{Gtroff 6849Internals}, for more on this process). 6850 6851@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 6852@DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 6853Translate character @var{a} to glyph@w{ }@var{b}, character @var{c} to 6854glyph@w{ }@var{d}, etc. If there is an odd number of arguments, the 6855last one is translated to an unstretchable space (@w{@samp{\ }}). 6856 6857The @code{trin} request is identical to @code{tr}, 6858but when you unformat a diversion with @code{asciify} 6859it ignores the translation. 6860@xref{Diversions}, for details about the @code{asciify} request. 6861 6862Some notes: 6863 6864@itemize @bullet 6865@item 6866@cindex @code{\(}, and translations 6867@cindex @code{\[}, and translations 6868@cindex @code{\'}, and translations 6869@cindex @code{\`}, and translations 6870@cindex @code{\-}, and translations 6871@cindex @code{\_}, and translations 6872@cindex @code{\C}, and translations 6873@cindex @code{\N}, and translations 6874@cindex @code{char} request, and translations 6875@cindex special characters 6876@cindex character, special 6877@cindex numbered glyph (@code{\N}) 6878@cindex glyph, numbered (@code{\N}) 6879Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 6880@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 6881glyphs defined with the @code{char} request, and numbered glyphs 6882(@code{\N'@var{xxx}'}) can be translated also. 6883 6884@item 6885@cindex @code{\e}, and translations 6886The @code{\e} escape can be translated also. 6887 6888@item 6889@cindex @code{\%}, and translations 6890@cindex @code{\~}, and translations 6891Characters can be mapped onto the @code{\%} and @code{\~} escapes (but 6892@code{\%} and @code{\~} can't be mapped onto another glyph). 6893 6894@item 6895@cindex backspace character, and translations 6896@cindex character, backspace, and translations 6897@cindex leader character, and translations 6898@cindex character, leader, and translations 6899@cindex newline character, and translations 6900@cindex character, newline, and translations 6901@cindex tab character, and translations 6902@cindex character, tab, and translations 6903@cindex @code{\a}, and translations 6904@cindex @code{\t}, and translations 6905The following characters can't be translated: space (with one exception, 6906see below), backspace, newline, leader (and @code{\a}), tab (and 6907@code{\t}). 6908 6909@item 6910@cindex @code{shc} request, and translations 6911Translations are not considered for finding the soft hyphen character 6912set with the @code{shc} request. 6913 6914@item 6915@cindex @code{\&}, and translations 6916The pair @samp{@var{c}\&} (this is an arbitrary character@w{ 6917}@var{c} followed by the zero width space character) maps this 6918character to nothing. 6919 6920@Example 6921.tr a\& 6922foo bar 6923 @result{} foo br 6924@endExample 6925 6926@noindent 6927It is even possible to map the space character to nothing: 6928 6929@Example 6930.tr aa \& 6931foo bar 6932 @result{} foobar 6933@endExample 6934 6935@noindent 6936As shown in the example, the space character can't be the first 6937character/glyph pair as an argument of @code{tr}. Additionally, it is 6938not possible to map the space character to any other glyph; requests 6939like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 6940 6941If justification is active, lines are justified in spite of the 6942`empty' space character (but there is no minimal distance, i.e.@: the 6943space character, between words). 6944 6945@item 6946After an output glyph has been constructed (this happens at the 6947moment immediately before the glyph is appended to an output 6948glyph list, either by direct output, in a macro, diversion, or 6949string), it is no longer affected by @code{tr}. 6950 6951@item 6952Translating character to glyphs where one of them or both are 6953undefined is possible also; @code{tr} does not check whether the 6954entities in its argument do exist. 6955 6956@xref{Gtroff Internals}. 6957 6958@item 6959@code{troff} no longer has a hard-coded dependency on @w{Latin-1}; 6960all @code{char@var{XXX}} entities have been removed from the font 6961description files. This has a notable consequence which shows up in 6962warnings like @code{can't find character with input code @var{XXX}} 6963if the @code{tr} request isn't handled properly. 6964 6965Consider the following translation: 6966 6967@Example 6968.tr @'e@'E 6969@endExample 6970 6971@noindent 6972This maps input character @code{@'e} onto glyph @code{@'E}, which is 6973identical to glyph @code{char201}. But this glyph intentionally 6974doesn't exist! Instead, @code{\[char201]} is treated as an input 6975character entity and is by default mapped onto @code{\['E]}, and 6976@code{gtroff} doesn't handle translations of translations. 6977 6978The right way to write the above translation is 6979 6980@Example 6981.tr @'e\['E] 6982@endExample 6983 6984@noindent 6985With other words, the first argument of @code{tr} should be an input 6986character or entity, and the second one a glyph entity. 6987 6988@item 6989Without an argument, the @code{tr} request is ignored. 6990@end itemize 6991@endDefreq 6992 6993@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 6994@cindex @code{\!}, and @code{trnt} 6995@code{trnt} is the same as the @code{tr} request except that the 6996translations do not apply to text that is transparently throughput 6997into a diversion with @code{\!}. @xref{Diversions}, for more 6998information. 6999 7000For example, 7001 7002@Example 7003.tr ab 7004.di x 7005\!.tm a 7006.di 7007.x 7008@endExample 7009 7010@noindent 7011prints @samp{b} to the standard error stream; if @code{trnt} is used 7012instead of @code{tr} it prints @samp{a}. 7013@endDefreq 7014 7015 7016@c ===================================================================== 7017 7018@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 7019@section Troff and Nroff Mode 7020@cindex troff mode 7021@cindex mode, troff 7022@cindex nroff mode 7023@cindex mode, nroff 7024 7025Originally, @code{nroff} and @code{troff} were two separate programs, 7026the former for TTY output, the latter for everything else. With GNU 7027@code{troff}, both programs are merged into one executable, sending 7028its output to a device driver (@code{grotty} for TTY devices, 7029@code{grops} for @sc{PostScript}, etc.) which interprets the 7030intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 7031it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 7032since the differences are hardcoded. For GNU @code{troff}, this 7033distinction is not appropriate because @code{gtroff} simply takes the 7034information given in the font files for a particular device without 7035handling requests specially if a TTY output device is used. 7036 7037Usually, a macro package can be used with all output devices. 7038Nevertheless, it is sometimes necessary to make a distinction between 7039TTY and non-TTY devices: @code{gtroff} provides two built-in 7040conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 7041@code{while} requests to decide whether @code{gtroff} shall behave 7042like @code{nroff} or like @code{troff}. 7043 7044@Defreq {troff, } 7045@pindex troffrc 7046@pindex troffrc-end 7047Make the @samp{t} built-in condition true (and the @samp{n} built-in 7048condition false) for @code{if}, @code{ie}, and @code{while} 7049conditional requests. This is the default if @code{gtroff} 7050(@emph{not} @code{groff}) is started with the @option{-R} switch to 7051avoid loading of the start-up files @file{troffrc} and 7052@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 7053mode if the output device is not a TTY (e.g.@: `ps'). 7054@endDefreq 7055 7056@Defreq {nroff, } 7057@pindex tty.tmac 7058Make the @samp{n} built-in condition true (and the @samp{t} built-in 7059condition false) for @code{if}, @code{ie}, and @code{while} 7060conditional requests. This is the default if @code{gtroff} uses a TTY 7061output device; the code for switching to nroff mode is in the file 7062@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 7063@endDefreq 7064 7065@xref{Conditionals and Loops}, for more details on built-in 7066conditions. 7067 7068 7069@c ===================================================================== 7070 7071@node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference 7072@section Line Layout 7073@cindex line layout 7074@cindex layout, line 7075 7076@cindex dimensions, line 7077@cindex line dimensions 7078The following drawing shows the dimensions which @code{gtroff} uses for 7079placing a line of output onto the page. They are labeled with the 7080request which manipulates each dimension. 7081 7082@Example 7083 -->| in |<-- 7084 |<-----------ll------------>| 7085 +----+----+----------------------+----+ 7086 | : : : | 7087 +----+----+----------------------+----+ 7088 -->| po |<-- 7089 |<--------paper width---------------->| 7090@endExample 7091 7092@noindent 7093These dimensions are: 7094 7095@ftable @code 7096@item po 7097@cindex left margin (@code{po}) 7098@cindex margin, left (@code{po}) 7099@cindex page offset (@code{po}) 7100@cindex offset, page (@code{po}) 7101@dfn{Page offset} -- this is the leftmost position of text on the final 7102output, defining the @dfn{left margin}. 7103 7104@item in 7105@cindex indentation (@code{in}) 7106@cindex line indentation (@code{in}) 7107@dfn{Indentation} -- this is the distance from the left margin where 7108text is printed. 7109 7110@item ll 7111@cindex line length (@code{ll}) 7112@cindex length of line (@code{ll}) 7113@dfn{Line length} -- this is the distance from the left margin to right 7114margin. 7115@end ftable 7116 7117A simple demonstration: 7118 7119@Example 7120.ll 3i 7121This is text without indentation. 7122The line length has been set to 3\~inch. 7123.in +.5i 7124.ll -.5i 7125Now the left and right margins are both increased. 7126.in 7127.ll 7128Calling .in and .ll without parameters restore 7129the previous values. 7130@endExample 7131 7132Result: 7133 7134@Example 7135This is text without indenta- 7136tion. The line length has 7137been set to 3 inch. 7138 Now the left and 7139 right margins are 7140 both increased. 7141Calling .in and .ll without 7142parameters restore the previ- 7143ous values. 7144@endExample 7145 7146@DefreqList {po, [@Var{offset}]} 7147@DefreqItem {po, @t{+}@Var{offset}} 7148@DefreqItem {po, @t{-}@Var{offset}} 7149@DefregListEnd {.o} 7150@pindex troffrc 7151Set horizontal page offset to @var{offset} (or increment or decrement 7152the current value by @var{offset}). Note that this request does not 7153cause a break, so changing the page offset in the middle of text being 7154filled may not yield the expected result. The initial value is 71551@dmn{i}. For TTY output devices, it is set to 0 in the startup file 7156@file{troffrc}; the default scaling indicator is @samp{m} (and 7157not @samp{v} as incorrectly documented in the original 7158@acronym{UNIX} troff manual). 7159 7160The current page offset can be found in the read-only number register 7161@samp{.o}. 7162 7163If @code{po} is called without an argument, the page offset is reset to 7164the previous value before the last call to @code{po}. 7165 7166@Example 7167.po 3i 7168\n[.o] 7169 @result{} 720 7170.po -1i 7171\n[.o] 7172 @result{} 480 7173.po 7174\n[.o] 7175 @result{} 720 7176@endExample 7177@endDefreq 7178 7179@DefreqList {in, [@Var{indent}]} 7180@DefreqItem {in, @t{+}@Var{indent}} 7181@DefreqItem {in, @t{-}@Var{indent}} 7182@DefregListEnd {.i} 7183Set indentation to @var{indent} (or increment or decrement the 7184current value by @var{indent}). This request causes a break. 7185Initially, there is no indentation. 7186 7187If @code{in} is called without an argument, the indentation is reset to 7188the previous value before the last call to @code{in}. The default 7189scaling indicator is @samp{m}. 7190 7191The indentation is associated with the current environment 7192(@pxref{Environments}). 7193 7194If a negative indentation value is specified (which is not allowed), 7195@code{gtroff} emits a warning of type @samp{range} and sets the 7196indentation to zero. 7197 7198The effect of @code{in} is delayed until a partially collected line (if 7199it exists) is output. A temporary indent value is reset to zero also. 7200 7201The current indentation (as set by @code{in}) can be found in the 7202read-only number register @samp{.i}. 7203@endDefreq 7204 7205@DefreqList {ti, offset} 7206@DefreqItem {ti, @t{+}@Var{offset}} 7207@DefreqItem {ti, @t{-}@Var{offset}} 7208@DefregListEnd {.in} 7209Temporarily indent the next output line by @var{offset}. If an 7210increment or decrement value is specified, adjust the temporary 7211indentation relative to the value set by the @code{in} request. 7212 7213This request causes a break; its value is associated with the current 7214environment (@pxref{Environments}). The default scaling indicator 7215is @samp{m}. A call of @code{ti} without an argument is ignored. 7216 7217If the total indentation value is negative (which is not allowed), 7218@code{gtroff} emits a warning of type @samp{range} and sets the 7219temporary indentation to zero. `Total indentation' is either 7220@var{offset} if specified as an absolute value, or the temporary plus 7221normal indentation, if @var{offset} is given as a relative value. 7222 7223The effect of @code{ti} is delayed until a partially collected line (if 7224it exists) is output. 7225 7226The read-only number register @code{.in} is the indentation that applies 7227to the current output line. 7228 7229The difference between @code{.i} and @code{.in} is that the latter takes 7230into account whether a partially collected line still uses the old 7231indentation value or a temporary indentation value is active. 7232@endDefreq 7233 7234@DefreqList {ll, [@Var{length}]} 7235@DefreqItem {ll, @t{+}@Var{length}} 7236@DefreqItem {ll, @t{-}@Var{length}} 7237@DefregItem {.l} 7238@DefregListEnd {.ll} 7239Set the line length to @var{length} (or increment or decrement the 7240current value by @var{length}). Initially, the line length is set to 72416.5@dmn{i}. The effect of @code{ll} is delayed until a partially 7242collected line (if it exists) is output. The default scaling 7243indicator is @samp{m}. 7244 7245If @code{ll} is called without an argument, the line length is reset to 7246the previous value before the last call to @code{ll}. If a negative 7247line length is specified (which is not allowed), @code{gtroff} emits a 7248warning of type @samp{range} and sets the line length to zero. 7249 7250The line length is associated with the current environment 7251(@pxref{Environments}). 7252 7253@cindex line length register (@code{.l}) 7254The current line length (as set by @code{ll}) can be found in the 7255read-only number register @samp{.l}. The read-only number register 7256@code{.ll} is the line length that applies to the current output line. 7257 7258Similar to @code{.i} and @code{.in}, the difference between @code{.l} 7259and @code{.ll} is that the latter takes into account whether a partially 7260collected line still uses the old line length value. 7261@endDefreq 7262 7263 7264@c ===================================================================== 7265 7266@node Line Control, Page Layout, Line Layout, gtroff Reference 7267@section Line Control 7268@cindex line control 7269@cindex control, line 7270 7271It is important to understand how @code{gtroff} handles input and output 7272lines. 7273 7274Many escapes use positioning relative to the input line. For example, 7275this 7276 7277@Example 7278This is a \h'|1.2i'test. 7279 7280This is a 7281\h'|1.2i'test. 7282@endExample 7283 7284@noindent 7285produces 7286 7287@Example 7288This is a test. 7289 7290This is a test. 7291@endExample 7292 7293The main usage of this feature is to define macros which act exactly 7294at the place where called. 7295 7296@Example 7297.\" A simple macro to underline a word 7298.de underline 7299. nop \\$1\l'|0\[ul]' 7300.. 7301@endExample 7302 7303@noindent 7304In the above example, @samp{|0} specifies a negative distance from the 7305current position (at the end of the just emitted argument @code{\$1}) back 7306to the beginning of the input line. Thus, the @samp{\l} escape draws a 7307line from right to left. 7308 7309@cindex input line continuation (@code{\}) 7310@cindex line, input, continuation (@code{\}) 7311@cindex continuation, input line (@code{\}) 7312@cindex output line, continuation (@code{\c}) 7313@cindex line, output, continuation (@code{\c}) 7314@cindex continuation, output line (@code{\c}) 7315@cindex interrupted line 7316@cindex line, interrupted 7317@code{gtroff} makes a difference between input and output line 7318continuation; the latter is also called @dfn{interrupting} a line. 7319 7320@DefescList {\\@key{RET}, , ,} 7321@DefescItem {\\c, , ,} 7322@DefregListEnd{.int} 7323Continue a line. @code{\@key{RET}} (this is a backslash at the end 7324of a line immediately followed by a newline) works on the input level, 7325suppressing the effects of the following newline in the input. 7326 7327@Example 7328This is a \ 7329.test 7330 @result{} This is a .test 7331@endExample 7332 7333The @samp{|} operator is also affected. 7334 7335@cindex @code{\R}, after @code{\c} 7336@code{\c} works on the output level. Anything after this escape on the 7337same line is ignored, except @code{\R} which works as usual. Anything 7338before @code{\c} on the same line will be appended to the current partial 7339output line. The next non-command line after an interrupted line counts 7340as a new input line. 7341 7342The visual results depend on whether no-fill mode is active. 7343 7344@itemize @bullet 7345@item 7346@cindex @code{\c}, and no-fill mode 7347@cindex no-fill mode, and @code{\c} 7348@cindex mode, no-fill, and @code{\c} 7349If no-fill mode is active (using the @code{nf} request), the next input 7350text line after @code{\c} will be handled as a continuation of the same 7351input text line. 7352 7353@Example 7354.nf 7355This is a \c 7356test. 7357 @result{} This is a test. 7358@endExample 7359 7360@item 7361@cindex @code{\c}, and fill mode 7362@cindex fill mode, and @code{\c} 7363@cindex mode, fill, and @code{\c} 7364If fill mode is active (using the @code{fi} request), a word interrupted 7365with @code{\c} will be continued with the text on the next input text line, 7366without an intervening space. 7367 7368@Example 7369This is a te\c 7370st. 7371 @result{} This is a test. 7372@endExample 7373@end itemize 7374 7375Note that an intervening control line which causes a break is stronger 7376than @code{\c}, flushing out the current partial line in the usual way. 7377 7378@cindex interrupted line register (@code{.int}) 7379The @code{.int} register contains a positive value 7380if the last output line was interrupted with @code{\c}; this is 7381associated with the current environment (@pxref{Environments}). 7382 7383@endDefesc 7384 7385@c ===================================================================== 7386 7387@node Page Layout, Page Control, Line Control, gtroff Reference 7388@section Page Layout 7389@cindex page layout 7390@cindex layout, page 7391 7392@code{gtroff} provides some very primitive operations for controlling 7393page layout. 7394 7395@DefreqList {pl, [@Var{length}]} 7396@DefreqItem {pl, @t{+}@Var{length}} 7397@DefreqItem {pl, @t{-}@Var{length}} 7398@DefregListEnd {.p} 7399@cindex page length (@code{pl}) 7400@cindex length of page (@code{pl}) 7401Set the @dfn{page length} to @var{length} (or increment or decrement 7402the current value by @var{length}). This is the length of the 7403physical output page. The default scaling indicator is @samp{v}. 7404 7405@cindex page length register (@code{.p}) 7406The current setting can be found in the read-only number register 7407@samp{.p}. 7408 7409@cindex top margin 7410@cindex margin, top 7411@cindex bottom margin 7412@cindex margin, bottom 7413Note that this only specifies the size of the page, not the top and 7414bottom margins. Those are not set by @code{gtroff} directly. 7415@xref{Traps}, for further information on how to do this. 7416 7417Negative @code{pl} values are possible also, but not very useful: No 7418trap is sprung, and each line is output on a single page (thus 7419suppressing all vertical spacing). 7420 7421If no argument or an invalid argument is given, @code{pl} sets the page 7422length to 11@dmn{i}. 7423@endDefreq 7424 7425@cindex headers 7426@cindex footers 7427@cindex titles 7428@code{gtroff} provides several operations which help in setting up top 7429and bottom titles (or headers and footers). 7430 7431@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 7432@cindex title line (@code{tl}) 7433@cindex three-part title (@code{tl}) 7434@cindex page number character (@code{%}) 7435Print a @dfn{title line}. It consists of three parts: a left 7436justified portion, a centered portion, and a right justified portion. 7437The argument separator @samp{'} can be replaced with any character not 7438occurring in the title line. The @samp{%} character is replaced with 7439the current page number. This character can be changed with the 7440@code{pc} request (see below). 7441 7442Without argument, @code{tl} is ignored. 7443 7444Some notes: 7445 7446@itemize @bullet 7447@item 7448A title line is not restricted to the top or bottom of a page. 7449 7450@item 7451@code{tl} prints the title line immediately, ignoring a partially filled 7452line (which stays untouched). 7453 7454@item 7455It is not an error to omit closing delimiters. For example, 7456@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 7457title line with the left justified word @samp{foo}; the centered and 7458right justfied parts are empty. 7459 7460@item 7461@code{tl} accepts the same parameter delimiting characters as the 7462@code{\A} escape; see @ref{Escapes}. 7463@end itemize 7464@endDefreq 7465 7466@DefreqList {lt, [@Var{length}]} 7467@DefreqItem {lt, @t{+}@Var{length}} 7468@DefreqItem {lt, @t{-}@Var{length}} 7469@DefregListEnd {.lt} 7470@cindex length of title line (@code{lt}) 7471@cindex title line, length (@code{lt}) 7472@cindex title line length register (@code{.lt}) 7473The title line is printed using its own line length, which is 7474specified (or incremented or decremented) with the @code{lt} request. 7475Initially, the title line length is set to 6.5@dmn{i}. If a negative 7476line length is specified (which is not allowed), @code{gtroff} emits a 7477warning of type @samp{range} and sets the title line length to zero. 7478The default scaling indicator is @samp{m}. If @code{lt} is called 7479without an argument, the title length is reset to the previous value 7480before the last call to @code{lt}. 7481 7482The current setting of this is available in the @code{.lt} read-only 7483number register; it is associated with the current environment 7484(@pxref{Environments}). 7485 7486@endDefreq 7487 7488@DefreqList {pn, page} 7489@DefreqItem {pn, @t{+}@Var{page}} 7490@DefreqItem {pn, @t{-}@Var{page}} 7491@DefregListEnd {.pn} 7492@cindex page number (@code{pn}) 7493@cindex number, page (@code{pn}) 7494Change (increase or decrease) the page number of the @emph{next} page. 7495The only argument is the page number; the request is ignored without a 7496parameter. 7497 7498The read-only number register @code{.pn} contains the number of the next 7499page: either the value set by a @code{pn} request, or the number of the 7500current page plus@w{ }1. 7501@endDefreq 7502 7503@Defreg {%} 7504@cindex page number register (@code{%}) 7505A read-write register holding the current page number. 7506@endDefreg 7507 7508@Defreq {pc, [@Var{char}]} 7509@cindex changing the page number character (@code{pc}) 7510@cindex page number character, changing (@code{pc}) 7511@vindex % 7512Change the page number character (used by the @code{tl} request) to a 7513different character. With no argument, this mechanism is disabled. 7514Note that this doesn't affect the number register@w{ }@code{%}. 7515@endDefreq 7516 7517@xref{Traps}. 7518 7519 7520@c ===================================================================== 7521 7522@node Page Control, Fonts, Page Layout, gtroff Reference 7523@section Page Control 7524@cindex page control 7525@cindex control, page 7526 7527@DefreqList {bp, [@Var{page}]} 7528@DefreqItem {bp, @t{+}@Var{page}} 7529@DefreqListEnd {bp, @t{-}@Var{page}} 7530@cindex new page (@code{bp}) 7531@cindex page, new (@code{bp}) 7532Stop processing the current page and move to the next page. This 7533request causes a break. It can also take an argument to set 7534(increase, decrease) the page number of the next page. The only 7535difference between @code{bp} and @code{pn} is that @code{pn} does not 7536cause a break or actually eject a page. 7537 7538@Example 7539.de newpage \" define macro 7540'bp \" begin page 7541'sp .5i \" vertical space 7542.tl 'left top'center top'right top' \" title 7543'sp .3i \" vertical space 7544.. \" end macro 7545@endExample 7546 7547@cindex @code{bp} request, and top-level diversion 7548@cindex top-level diversion, and @code{bp} 7549@cindex diversion, top-level, and @code{bp} 7550@code{bp} has no effect if not called within the top-level diversion 7551(@pxref{Diversions}). 7552@endDefreq 7553 7554@Defreq {ne, [@Var{space}]} 7555@cindex orphan lines, preventing with @code{ne} 7556@cindex conditional page break (@code{ne}) 7557@cindex page break, conditional (@code{ne}) 7558It is often necessary to force a certain amount of space before a new 7559page occurs. This is most useful to make sure that there is not a 7560single @dfn{orphan} line left at the bottom of a page. The @code{ne} 7561request ensures that there is a certain distance, specified by the 7562first argument, before the next page is triggered (see @ref{Traps}, 7563for further information). The default scaling indicator for @code{ne} 7564is @samp{v}; the default value of @var{space} is@w{ }1@dmn{v} if no 7565argument is given. 7566 7567For example, to make sure that no fewer than 2@w{ }lines get orphaned, 7568do the following before each paragraph: 7569 7570@Example 7571.ne 2 7572text text text 7573@endExample 7574 7575@code{ne} will then automatically cause a page break if there is space 7576for one line only. 7577@endDefreq 7578 7579@DefreqList {sv, [@Var{space}]} 7580@DefreqListEnd {os, } 7581@cindex @code{ne} request, comparison with @code{sv} 7582@code{sv} is similar to the @code{ne} request; it reserves the 7583specified amount of vertical space. If the desired amount of space 7584exists before the next trap (or the bottom page boundary if no trap is 7585set), the space is output immediately (ignoring a partially filled line 7586which stays untouched). If there is not enough space, it is stored for 7587later output via the @code{os} request. The default value is@w{ }1@dmn{v} 7588if no argument is given; the default scaling indicator is @samp{v}. 7589 7590@cindex @code{sv} request, and no-space mode 7591@cindex @code{os} request, and no-space mode 7592Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv} 7593request allows negative values for @var{space}, @code{os} will ignore 7594them. 7595@endDefreq 7596 7597@Defreg {nl} 7598This register contains the current vertical position. If the vertical 7599position is zero and the top of page transition hasn't happened yet, 7600@code{nl} is set to negative value. @code{gtroff} itself does this at 7601the very beginning of a document before anything has been printed, but 7602the main usage is to plant a header trap on a page if this page has 7603already started. 7604 7605Consider the following: 7606 7607@Example 7608.de xxx 7609. sp 7610. tl ''Header'' 7611. sp 7612.. 7613. 7614First page. 7615.bp 7616.wh 0 xxx 7617.nr nl (-1) 7618Second page. 7619@endExample 7620 7621@noindent 7622Result: 7623 7624@Example 7625First page. 7626 7627... 7628 7629 Header 7630 7631Second page. 7632 7633... 7634@endExample 7635 7636@noindent 7637Without resetting @code{nl} to a negative value, the just planted trap 7638would be active beginning with the @emph{next} page, not the current 7639one. 7640 7641@xref{Diversions}, for a comparison with the @code{.h} and @code{.d} 7642registers. 7643@endDefreg 7644 7645@c ===================================================================== 7646 7647@node Fonts, Sizes, Page Control, gtroff Reference 7648@section Fonts 7649@cindex fonts 7650 7651@code{gtroff} can switch fonts at any point in the text. 7652 7653The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 7654These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY 7655devices, there is also at least one symbol font which contains various 7656special symbols (Greek, mathematics). 7657 7658@menu 7659* Changing Fonts:: 7660* Font Families:: 7661* Font Positions:: 7662* Using Symbols:: 7663* Special Fonts:: 7664* Artificial Fonts:: 7665* Ligatures and Kerning:: 7666@end menu 7667 7668@c --------------------------------------------------------------------- 7669 7670@node Changing Fonts, Font Families, Fonts, Fonts 7671@subsection Changing Fonts 7672@cindex fonts 7673 7674@DefreqList {ft, [@Var{font}]} 7675@DefescItem {\\f, , f, } 7676@DefescItem {\\f, @lparen{}, fn, } 7677@DefescListEnd {\\f, @lbrack{}, font, @rbrack} 7678@cindex changing fonts (@code{ft}, @code{\f}) 7679@cindex fonts, changing (@code{ft}, @code{\f}) 7680@cindex @code{sty} request, and changing fonts 7681@cindex @code{fam} request, and changing fonts 7682@cindex @code{\F}, and changing fonts 7683@kindex styles 7684@kindex family 7685@pindex DESC 7686The @code{ft} request and the @code{\f} escape change the current font 7687to @var{font} (one-character name@w{ }@var{f}, two-character name 7688@var{fn}). 7689 7690If @var{font} is a style name (as set with the @code{sty} request or 7691with the @code{styles} command in the @file{DESC} file), use it within 7692the current font family (as set with the @code{fam} request, @code{\F} 7693escape, or with the @code{family} command in the @file{DESC} file). 7694 7695@cindex previous font (@code{ft}, @code{\f[]}, @code{\fP}) 7696@cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP}) 7697With no argument or using @samp{P} as an argument, @code{.ft} switches 7698to the previous font. Use @code{\f[]} to do this with the escape. The 7699old syntax forms @code{\fP} or @code{\f[P]} are also supported. 7700 7701Fonts are generally specified as upper-case strings, which are usually 77021@w{ }to 4 characters representing an abbreviation or acronym of the 7703font name. This is no limitation, just a convention. 7704 7705The example below produces two identical lines. 7706 7707@Example 7708eggs, bacon, 7709.ft B 7710spam 7711.ft 7712and sausage. 7713 7714eggs, bacon, \fBspam\fP and sausage. 7715@endExample 7716 7717Note that @code{\f} doesn't produce an input token in @code{gtroff}. 7718As a consequence, it can be used in requests like @code{mc} (which 7719expects a single character as an argument) to change the font on 7720the fly: 7721 7722@Example 7723.mc \f[I]x\f[] 7724@endExample 7725 7726@xref{Font Positions}, for an alternative syntax. 7727@endDefreq 7728 7729@Defreq {ftr, f [@Var{g}]} 7730@cindex @code{ft} request, and font translations 7731@cindex @code{ul} request, and font translations 7732@cindex @code{bd} request, and font translations 7733@cindex @code{\f}, and font translations 7734@cindex @code{cs} request, and font translations 7735@cindex @code{tkf} request, and font translations 7736@cindex @code{special} request, and font translations 7737@cindex @code{fspecial} request, and font translations 7738@cindex @code{fp} request, and font translations 7739@cindex @code{sty} request, and font translations 7740Translate font@w{ }@var{f} to font@w{ }@var{g}. Whenever a font named@w{ 7741}@var{f} is referred to in a @code{\f} escape sequence, or in the 7742@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 7743@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests, 7744font@w{ }@var{g} is used. If @var{g} is missing or equal to@w{ }@var{f} 7745the translation is undone. 7746@endDefreq 7747 7748@c --------------------------------------------------------------------- 7749 7750@node Font Families, Font Positions, Changing Fonts, Fonts 7751@subsection Font Families 7752@cindex font families 7753@cindex families, font 7754@cindex font styles 7755@cindex styles, font 7756 7757Due to the variety of fonts available, @code{gtroff} has added the 7758concept of @dfn{font families} and @dfn{font styles}. The fonts are 7759specified as the concatenation of the font family and style. Specifying 7760a font without the family part causes @code{gtroff} to use that style of 7761the current family. 7762 7763@cindex PostScript fonts 7764@cindex fonts, PostScript 7765Currently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and 7766@option{-Tlbp} are set up to this mechanism. 7767By default, @code{gtroff} uses the Times family with the four styles 7768@samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 7769 7770This way, it is possible to use the basic four fonts and to select a 7771different font family on the command line (@pxref{Groff Options}). 7772 7773@DefreqList {fam, [@Var{family}]} 7774@DefregItem {.fam} 7775@DefescItem {\\F, , f, } 7776@DefescItem {\\F, @lparen{}, fm, } 7777@DefescItem {\\F, @lbrack{}, family, @rbrack} 7778@DefregListEnd {.fn} 7779@cindex changing font family (@code{fam}, @code{\F}) 7780@cindex font family, changing (@code{fam}, @code{\F}) 7781Switch font family to @var{family} (one-character name@w{ }@var{f}, 7782two-character name @var{fm}). If no argument is given, switch 7783back to the previous font family. Use @code{\F[]} to do this with the 7784escape. Note that @code{\FP} doesn't work; it selects font family 7785@samp{P} instead. 7786 7787The value at start-up is @samp{T}. 7788The current font family is available in the read-only number register 7789@samp{.fam} (this is a string-valued register); it is associated with 7790the current environment. 7791 7792@Example 7793spam, 7794.fam H \" helvetica family 7795spam, \" used font is family H + style R = HR 7796.ft B \" family H + style B = font HB 7797spam, 7798.fam T \" times family 7799spam, \" used font is family T + style B = TB 7800.ft AR \" font AR (not a style) 7801baked beans, 7802.ft R \" family T + style R = font TR 7803and spam. 7804@endExample 7805 7806Note that @code{\F} doesn't produce an input token in @code{gtroff}. 7807As a consequence, it can be used in requests like @code{mc} (which 7808expects a single character as an argument) to change the font family on 7809the fly: 7810 7811@Example 7812.mc \F[P]x\F[] 7813@endExample 7814 7815The @samp{.fn} register contains the current @dfn{real font name} 7816of the current font. 7817This is a string-valued register. 7818If the current font is a style, the value of @code{\n[.fn]} 7819is the proper concatenation of family and style name. 7820@endDefreq 7821 7822@Defreq {sty, n style} 7823@cindex changing font style (@code{sty}) 7824@cindex font style, changing (@code{sty}) 7825@cindex @code{cs} request, and font styles 7826@cindex @code{bd} request, and font styles 7827@cindex @code{tkf} request, and font styles 7828@cindex @code{uf} request, and font styles 7829@cindex @code{fspecial} request, and font styles 7830Associate @var{style} with font position@w{ }@var{n}. A font position 7831can be associated either with a font or with a style. The current 7832font is the index of a font position and so is also either a font or a 7833style. If it is a style, the font that is actually used is the font 7834which name is the concatenation of the name of the current 7835family and the name of the current style. For example, if the current 7836font is@w{ }1 and font position@w{ }1 is associated with style 7837@samp{R} and the current font family is @samp{T}, then font 7838@samp{TR} will be used. If the current font is not a style, then the 7839current family is ignored. If the requests @code{cs}, @code{bd}, 7840@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, 7841they will instead be applied to the member of the current family 7842corresponding to that style. 7843 7844@var{n}@w{ }must be a non-negative integer value. 7845 7846@pindex DESC 7847@kindex styles 7848The default family can be set with the @option{-f} option 7849(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 7850file controls which font positions (if any) are initially associated 7851with styles rather than fonts. For example, the default setting for 7852@sc{PostScript} fonts 7853 7854@Example 7855styles R I B BI 7856@endExample 7857 7858@noindent 7859is equivalent to 7860 7861@Example 7862.sty 1 R 7863.sty 2 I 7864.sty 3 B 7865.sty 4 BI 7866@endExample 7867 7868@code{fam} and @code{\F} always check whether the current font position 7869is valid; this can give surprising results if the current font position is 7870associated with a style. 7871 7872In the following example, we want to access the @sc{PostScript} font 7873@code{FooBar} from the font family @code{Foo}: 7874 7875@Example 7876.sty \n[.fp] Bar 7877.fam Foo 7878 @result{} warning: can't find font `FooR' 7879@endExample 7880 7881@noindent 7882The default font position at start-up is@w{ }1; for the 7883@sc{PostScript} device, this is associated with style @samp{R}, so 7884@code{gtroff} tries to open @code{FooR}. 7885 7886A solution to this problem is to use a dummy font like the following: 7887 7888@Example 7889.fp 0 dummy TR \" set up dummy font at position 0 7890.sty \n[.fp] Bar \" register style `Bar' 7891.ft 0 \" switch to font at position 0 7892.fam Foo \" activate family `Foo' 7893.ft Bar \" switch to font `FooBar' 7894@endExample 7895 7896@xref{Font Positions}. 7897@endDefreq 7898 7899@c --------------------------------------------------------------------- 7900 7901@node Font Positions, Using Symbols, Font Families, Fonts 7902@subsection Font Positions 7903@cindex font positions 7904@cindex positions, font 7905 7906For the sake of old phototypesetters and compatibility with old versions 7907of @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 7908on which various fonts are mounted. 7909 7910@DefreqList {fp, pos font [@Var{external-name}]} 7911@DefregItem {.f} 7912@DefregListEnd {.fp} 7913@cindex mounting font (@code{fp}) 7914@cindex font, mounting (@code{fp}) 7915Mount font @var{font} at position @var{pos} (which must be a 7916non-negative integer). This numeric position can then be referred to 7917with font changing commands. When @code{gtroff} starts it is using 7918font position@w{ }1 (which must exist; position@w{ }0 is unused 7919usually at start-up). 7920 7921@cindex font position register (@code{.f}) 7922The current font in use, as a font position, is available in the 7923read-only number register @samp{.f}. This can be useful to remember the 7924current font for later recall. It is associated with the current 7925environment (@pxref{Environments}). 7926 7927@Example 7928.nr save-font \n[.f] 7929.ft B 7930... text text text ... 7931.ft \n[save-font] 7932@endExample 7933 7934@cindex next free font position register (@code{.fp}) 7935The number of the next free font position is available in the read-only 7936number register @samp{.fp}. This is useful when mounting a new font, 7937like so: 7938 7939@Example 7940.fp \n[.fp] NEATOFONT 7941@endExample 7942 7943@pindex DESC@r{, and font mounting} 7944Fonts not listed in the @file{DESC} file are automatically mounted on 7945the next available font position when they are referenced. If a font 7946is to be mounted explicitly with the @code{fp} request on an unused 7947font position, it should be mounted on the first unused font position, 7948which can be found in the @code{.fp} register. Although @code{gtroff} 7949does not enforce this strictly, it is not allowed to mount a font at a 7950position whose number is much greater (approx.@: 1000 positions) than 7951that of any currently used position. 7952 7953The @code{fp} request has an optional third argument. This argument 7954gives the external name of the font, which is used for finding the font 7955description file. The second argument gives the internal name of the 7956font which is used to refer to the font in @code{gtroff} after it has 7957been mounted. If there is no third argument then the internal name is 7958used as the external name. This feature makes it possible to use 7959fonts with long names in compatibility mode. 7960@endDefreq 7961 7962Both the @code{ft} request and the @code{\f} escape have alternative 7963syntax forms to access font positions. 7964 7965@DefreqList {ft, nnn} 7966@DefescItem {\\f, , n, } 7967@DefescItem {\\f, @lparen{}, nn, } 7968@DefescListEnd {\\f, @lbrack{}, nnn, @rbrack} 7969@cindex changing font position (@code{\f}) 7970@cindex font position, changing (@code{\f}) 7971@cindex @code{sty} request, and font positions 7972@cindex @code{fam} request, and font positions 7973@cindex @code{\F}, and font positions 7974@kindex styles 7975@kindex family 7976@pindex DESC 7977Change the current font position to @var{nnn} (one-digit position@w{ 7978}@var{n}, two-digit position @var{nn}), which must be a non-negative 7979integer. 7980 7981If @var{nnn} is associated with a style (as set with the @code{sty} 7982request or with the @code{styles} command in the @file{DESC} file), use 7983it within the current font family (as set with the @code{fam} request, 7984the @code{\F} escape, or with the @code{family} command in the @file{DESC} 7985file). 7986 7987@Example 7988this is font 1 7989.ft 2 7990this is font 2 7991.ft \" switch back to font 1 7992.ft 3 7993this is font 3 7994.ft 7995this is font 1 again 7996@endExample 7997 7998@xref{Changing Fonts}, for the standard syntax form. 7999@endDefreq 8000 8001@c --------------------------------------------------------------------- 8002 8003@node Using Symbols, Special Fonts, Font Positions, Fonts 8004@subsection Using Symbols 8005@cindex using symbols 8006@cindex symbols, using 8007 8008@cindex glyph 8009@cindex character 8010@cindex ligature 8011A @dfn{glyph} is a graphical representation of a @dfn{character}. 8012While a character is an abstract entity containing semantic 8013information, a glyph is something which can be actually seen on screen 8014or paper. It is possible that a character has multiple glyph 8015representation forms (for example, the character `A' can be either 8016written in a roman or an italic font, yielding two different glyphs); 8017sometimes more than one character maps to a single glyph (this is a 8018@dfn{ligature} -- the most common is `fi'). 8019 8020@cindex symbol 8021@cindex special fonts 8022@kindex fonts 8023@pindex DESC 8024A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 8025glyph names of a particular font are defined in its font file. If the 8026user requests a glyph not available in this font, @code{gtroff} looks 8027up an ordered list of @dfn{special fonts}. By default, the 8028@sc{PostScript} output device supports the two special fonts @samp{SS} 8029(slanted symbols) and @samp{S} (symbols) (the former is looked up 8030before the latter). Other output devices use different names for 8031special fonts. Fonts mounted with the @code{fonts} keyword in the 8032@file{DESC} file are globally available. To install additional 8033special fonts locally (i.e.@: for a particular font), use the 8034@code{fspecial} request. 8035 8036In summary, @code{gtroff} tries the following to find a given symbol: 8037 8038@itemize @bullet 8039@item 8040If the symbol has been defined with the @code{char} request, use it. 8041This hides a symbol with the same name in the current font. 8042 8043@item 8044Check the current font. 8045 8046@item 8047If the symbol has been defined with the @code{fchar} request, use it. 8048 8049@item 8050Check all fonts given with the @code{fspecial} request, in the order 8051of appearance in @code{fspecial} calls. 8052 8053@item 8054Check all fonts given with the @code{special} request, in the order 8055of appearance in @code{special} calls (inclusively the special fonts 8056defined in the @file{DESC} file, which come first). 8057 8058@item 8059As a last resort, consult all fonts loaded up to now (in the order they 8060have been called the first time) for special fonts and check them. 8061@end itemize 8062 8063@xref{Font Files}, and @ref{Special Fonts}, for more details. 8064 8065@DefescList {\\, @lparen{}, nm, } 8066@DefescListEnd {\\, @lbrack{}, name, @rbrack} 8067Insert a symbol @var{name} (two-character name @var{nm}). There is no 8068special syntax for one-character names -- the natural form 8069@samp{\@var{n}} would collide with escapes.@footnote{Note that a 8070one-character symbol is not the same as an input character, i.e., the 8071character @code{a} is not the same as @code{\[a]}. By default, 8072@code{groff} defines only a single one-character symbol, @code{\[-]}; 8073it is usually accessed as @code{\-}. On the other hand, @code{gtroff} 8074has the special feature that @code{\[char@var{XXX}]} is the same as the 8075input character with character code @var{XXX}. For example, 8076@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII} 8077encoding is active.} 8078 8079If @var{name} is undefined, a warning of type @samp{char} is generated, 8080and the escape is ignored. @xref{Debugging}, for information about 8081warnings. 8082 8083@cindex list of available glyphs (@cite{groff_char(7)} man page) 8084@cindex available glyphs, list (@cite{groff_char(7)} man page) 8085@cindex glyphs, available, list (@cite{groff_char(7)} man page) 8086The list of available symbols is device dependent; see the 8087@cite{groff_char(7)} man page for a complete list for the given output 8088device. For example, say 8089 8090@Example 8091man -Tdvi groff_char > groff_char.dvi 8092@endExample 8093 8094@noindent 8095for a list using the default DVI fonts (not all versions of the 8096@code{man} program support the @option{-T} option). If you want to 8097use an additional macro package to change the used fonts, @code{groff} 8098must be called directly: 8099 8100@Example 8101groff -Tdvi -mec -man groff_char.7 > groff_char.dvi 8102@endExample 8103 8104@c XXX list of common symbols 8105@endDefesc 8106 8107@Defesc {\\C, ', xxx, '} 8108@cindex named character (@code{\C}) 8109@cindex character, named (@code{\C}) 8110Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a 8111misnomer since it accesses an output glyph.} Normally it is more 8112convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage 8113that it is compatible with newer versions of @acronym{AT&T} 8114@code{troff} and is available in compatibility mode. 8115@endDefesc 8116 8117@Defesc {\\N, ', n, '} 8118@cindex numbered glyph (@code{\N}) 8119@cindex glyph, numbered (@code{\N}) 8120@cindex @code{char} request, used with @code{\N} 8121@cindex Unicode 8122Typeset the glyph with code@w{ }@var{n} in the current font 8123(@code{n}@w{ }is @strong{not} the input character code). The 8124number @var{n}@w{ }can be any non-negative decimal integer. Most devices 8125only have glyphs with codes between 0 and@w{ }255; the Unicode 8126output device uses codes in the range 0--65535. If the current 8127font does not contain a glyph with that code, special fonts are 8128@emph{not} searched. The @code{\N} escape sequence can be 8129conveniently used in conjunction with the @code{char} request: 8130 8131@Example 8132.char \[phone] \f[ZD]\N'37' 8133@endExample 8134 8135@noindent 8136@pindex DESC 8137@cindex unnamed glyphs 8138@cindex glyphs, unnamed 8139The code of each glyph is given in the fourth column in the font 8140description file after the @code{charset} command. It is possible to 8141include unnamed glyphs in the font description file by using a 8142name of @samp{---}; the @code{\N} escape sequence is the only way to 8143use these. 8144@endDefesc 8145 8146Some escape sequences directly map onto special glyphs. 8147 8148@Defesc {\\', , , } 8149This is a backslash followed by the apostrophe character, @acronym{ASCII} 8150character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same 8151as @code{\[aa]}, the acute accent. 8152@endDefesc 8153 8154@Defesc {\\`, , , } 8155This is a backslash followed by @acronym{ASCII} character @code{0x60} 8156(@acronym{EBCDIC} character @code{0x79} usually). The same as 8157@code{\[ga]}, the grave accent. 8158@endDefesc 8159 8160@Defesc {\\-, , , } 8161This is the same as @code{\[-]}, the minus sign in the current font. 8162@endDefesc 8163 8164@Defreq {cflags, n c1 c2 @dots{}} 8165@cindex glyph properties (@code{cflags}) 8166@cindex character properties (@code{cflags}) 8167@cindex properties of glyphs (@code{cflags}) 8168@cindex properties of characters (@code{cflags}) 8169Input characters and symbols have certain properties associated 8170with it.@footnote{Note that the output glyphs themselves don't have 8171such properties. For @code{gtroff}, a glyph is a numbered box with 8172a given width, depth, and height, nothing else. All manipulations 8173with the @code{cflags} request work on the input level.} These 8174properties can be modified with the @code{cflags} request. The 8175first argument is the sum of the desired flags and the remaining 8176arguments are the characters or symbols to have those properties. 8177It is possible to omit the spaces between the characters or symbols. 8178 8179@table @code 8180@item 1 8181@cindex end-of-sentence characters 8182@cindex characters, end-of-sentence 8183The character ends sentences (initially characters @samp{.?!} have this 8184property). 8185 8186@item 2 8187@cindex hyphenating characters 8188@cindex characters, hyphenation 8189Lines can be broken before the character (initially no characters have 8190this property). 8191 8192@item 4 8193@cindex @code{hy} glyph, and @code{cflags} 8194@cindex @code{em} glyph, and @code{cflags} 8195Lines can be broken after the character (initially the character 8196@samp{-} and the symbols @samp{\(hy} and @samp{\(em} have this property). 8197 8198@item 8 8199@cindex overlapping characters 8200@cindex characters, overlapping 8201@cindex @code{ul} glyph, and @code{cflags} 8202@cindex @code{rn} glyph, and @code{cflags} 8203@cindex @code{ru} glyph, and @code{cflags} 8204The character overlaps horizontally (initially the symbols 8205@samp{\(ul\(rn\(ru} have this property). 8206 8207@item 16 8208@cindex @code{br} glyph, and @code{cflags} 8209The character overlaps vertically (initially symbol @samp{\(br} has 8210this property). 8211 8212@item 32 8213@cindex transparent characters 8214@cindex character, transparent 8215@cindex @code{"}, at end of sentence 8216@cindex @code{'}, at end of sentence 8217@cindex @code{)}, at end of sentence 8218@cindex @code{]}, at end of sentence 8219@cindex @code{*}, at end of sentence 8220@cindex @code{dg} glyph, at end of sentence 8221@cindex @code{rq} glyph, at end of sentence 8222An end-of-sentence character followed by any number of characters with 8223this property is treated as the end of a sentence if followed by a 8224newline or two spaces; in other words the character is 8225@dfn{transparent} for the purposes of end-of-sentence recognition -- 8226this is the same as having a zero space factor in @TeX{} (initially 8227characters @samp{"')]*} and the symbols @samp{\(dg\(rq} have this 8228property). 8229@end table 8230@endDefreq 8231 8232@DefreqList {char, g [@Var{string}]} 8233@DefreqListEnd {fchar, g [@Var{string}]} 8234@cindex defining character (@code{char}) 8235@cindex character, defining (@code{char}) 8236@cindex creating new characters (@code{char}) 8237@cindex defining symbol (@code{char}) 8238@cindex symbol, defining (@code{char}) 8239@cindex defining glyph (@code{char}) 8240@cindex glyph, defining (@code{char}) 8241@cindex escape character, while defining glyph 8242@cindex character, escape, while defining glyph 8243@cindex @code{tr} request, and glyph definitions 8244@cindex @code{cp} request, and glyph definitions 8245@cindex @code{rc} request, and glyph definitions 8246@cindex @code{lc} request, and glyph definitions 8247@cindex @code{\l}, and glyph definitions 8248@cindex @code{\L}, and glyph definitions 8249@cindex @code{\&}, and glyph definitions 8250@cindex @code{\e}, and glyph definitions 8251@cindex @code{hcode} request, and glyph definitions 8252Define a new glyph@w{ }@var{g} to be @var{string} (which can be 8253empty).@footnote{@code{char} is a misnomer since an output glyph is 8254defined.} Every time glyph@w{ }@var{g} needs to be printed, 8255@var{string} is processed in a temporary environment and the result is 8256wrapped up into a single object. Compatibility mode is turned off and 8257the escape character is set to @samp{\} while @var{string} is being 8258processed. Any emboldening, constant spacing or track kerning is 8259applied to this object rather than to individual characters in 8260@var{string}. 8261 8262A glyph defined by this request can be used just 8263like a normal glyph provided by the output device. In particular, 8264other characters can be translated to it with the @code{tr} or 8265@code{trin} requests; it can be made the leader character by the 8266@code{lc} request; repeated patterns can be drawn with the glyph 8267using the @code{\l} and @code{\L} escape sequences; words containing 8268the glyph can be hyphenated correctly if the @code{hcode} request 8269is used to give the glyph's symbol a hyphenation code. 8270 8271There is a special anti-recursion feature: Use of @code{g} within 8272the glyph's definition is handled like normal characters and symbols 8273not defined with @code{char}. 8274 8275Note that the @code{tr} and @code{trin} requests take precedence if 8276@code{char} accesses the same symbol. 8277 8278@Example 8279.tr XY 8280X 8281 @result{} Y 8282.char X Z 8283X 8284 @result{} Y 8285.tr XX 8286X 8287 @result{} Z 8288@endExample 8289 8290The @code{fchar} request defines a fallback glyph: 8291@code{gtroff} only checks for glyphs defined with @code{fchar} 8292if it cannot find the glyph in the current font. 8293@code{gtroff} carries out this test before checking special fonts. 8294@endDefreq 8295 8296@Defreq {rchar, c1 c2 @dots{}} 8297@cindex removing glyph definition (@code{rchar}) 8298@cindex glyph, removing definition (@code{rchar}) 8299Remove the definitions of glyphs @var{c1}, @var{c2},@w{ 8300}@enddots{} This undoes the effect of a @code{char} or @code{fchar} 8301request. 8302 8303It is possible to omit the whitespace between arguments. 8304@endDefreq 8305 8306@xref{Special Characters}. 8307 8308@c --------------------------------------------------------------------- 8309 8310@node Special Fonts, Artificial Fonts, Using Symbols, Fonts 8311@subsection Special Fonts 8312@cindex special fonts 8313@cindex fonts, special 8314 8315Special fonts are those that @code{gtroff} searches 8316when it cannot find the requested glyph in the current font. 8317The Symbol font is usually a special font. 8318 8319@code{gtroff} provides the following two requests to add more special 8320fonts. @xref{Using Symbols}, for a detailed description of the glyph 8321searching mechanism in @code{gtroff}. 8322 8323Usually, only non-TTY devices have special fonts. 8324 8325@DefreqList {special, s1 s2 @dots{}} 8326@DefreqListEnd {fspecial, f s1 s2 @dots{}} 8327@kindex fonts 8328@pindex DESC 8329Use the @code{special} request to define special fonts. They are 8330appended to the list of global special fonts in the given order. 8331The first entries in this list are the fonts defined with the 8332@code{fonts} command in the @file{DESC} file which are marked as 8333special in the corresponding font description files. 8334 8335Use the @code{fspecial} request to designate special fonts 8336only when font@w{ }@var{f} font is active. They are appended to the 8337list of special fonts for @var{f} in the given order. Initially, this 8338list is empty. 8339@endDefreq 8340 8341@c --------------------------------------------------------------------- 8342 8343@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts 8344@subsection Artificial Fonts 8345@cindex artificial fonts 8346@cindex fonts, artificial 8347 8348There are a number of requests and escapes for artificially creating 8349fonts. These are largely vestiges of the days when output devices 8350did not have a wide variety of fonts, and when @code{nroff} and 8351@code{troff} were separate programs. Most of them are no longer 8352necessary in GNU @code{troff}. Nevertheless, they are supported. 8353 8354@DefescList {\\H, ', height, '} 8355@DefescItem {\\H, ', @t{+}@Var{height}, '} 8356@DefescListEnd {\\H, ', @t{-}@Var{height}, '} 8357@cindex changing the font height (@code{\H}) 8358@cindex font height, changing (@code{\H}) 8359@cindex height, font, changing (@code{\H}) 8360Change (increment, decrement) the height of the current font, but not 8361the width. If @var{height} is zero, restore the original height. 8362Default scaling indicator is @samp{z}. 8363 8364Currently, only the @option{-Tps} device supports this feature. 8365 8366Note that @code{\H} doesn't produce an input token in @code{gtroff}. 8367As a consequence, it can be used in requests like @code{mc} (which 8368expects a single character as an argument) to change the font on 8369the fly: 8370 8371@Example 8372.mc \H'+5z'x\H'0' 8373@endExample 8374 8375In compatibility mode, @code{gtroff} behaves differently: If an 8376increment or decrement is used, it is always taken relative to the 8377current point size and not relative to the previously selected font 8378height. Thus, 8379 8380@Example 8381.cp 1 8382\H'+5'test \H'+5'test 8383@endExample 8384 8385@noindent 8386prints the word @samp{test} twice with the same font height (five 8387points larger than the current font size). 8388@endDefesc 8389 8390@DefescList {\\S, ', slant, '} 8391@cindex changing the font slant (@code{\S}) 8392@cindex font slant, changing (@code{\S}) 8393@cindex slant, font, changing (@code{\S}) 8394Slant the current font by @var{slant} degrees. Positive values slant 8395to the right. 8396 8397Currently, only the @option{-Tps} device supports this feature. 8398 8399Note that @code{\S} doesn't produce an input token in @code{gtroff}. 8400As a consequence, it can be used in requests like @code{mc} (which 8401expects a single character as an argument) to change the font on 8402the fly: 8403 8404@Example 8405.mc \S'20'x\S'0' 8406@endExample 8407 8408This request is incorrectly documented in the original @acronym{UNIX} 8409troff manual; the slant is always set to an absolute value. 8410@endDefesc 8411 8412@Defreq {ul, [@Var{lines}]} 8413@cindex underlining (@code{ul}) 8414The @code{ul} request normally underlines subsequent lines if a TTY 8415output device is used. Otherwise, the lines are printed in italics 8416(only the term `underlined' is used in the following). The single 8417argument is the number of input lines to be underlined; with no 8418argument, the next line is underlined. If @var{lines} is zero or 8419negative, stop the effects of @code{ul} (if it was active). Requests 8420and empty lines do not count for computing the number of underlined 8421input lines, even if they produce some output like @code{tl}. Lines 8422inserted by macros (e.g.@: invoked by a trap) do count. 8423 8424At the beginning of @code{ul}, the current font is stored and the 8425underline font is activated. Within the span of a @code{ul} request, 8426it is possible to change fonts, but after the last line affected by 8427@code{ul} the saved font is restored. 8428 8429This number of lines still to be underlined is associated with the 8430current environment (@pxref{Environments}). The underline font can be 8431changed with the @code{uf} request. 8432 8433@c XXX @xref should be changed to grotty 8434 8435@c @xref{Troff and Nroff Mode}, for a discussion how underlining is 8436@c implemented in for TTY output devices, and which problems can arise. 8437 8438The @code{ul} request does not underline spaces. 8439@endDefreq 8440 8441@Defreq {cu, [@Var{lines}]} 8442@cindex continuous underlining (@code{cu}) 8443@cindex underlining, continuous (@code{cu}) 8444The @code{cu} request is similar to @code{ul} but underlines spaces as 8445well (if a TTY output device is used). 8446@endDefreq 8447 8448@Defreq {uf, font} 8449@cindex underline font (@code{uf}) 8450@cindex font for underlining (@code{uf}) 8451Set the underline font (globally) used by @code{ul} and @code{cu}. By 8452default, this is the font at position@w{ }2. @var{font} can be either 8453a non-negative font position or the name of a font. 8454@endDefreq 8455 8456@DefreqList {bd, font [@Var{offset}]} 8457@DefreqItem {bd, font1 font2 [@Var{offset}]} 8458@DefregListEnd {.b} 8459@cindex imitating bold face (@code{bd}) 8460@cindex bold face, imitating (@code{bd}) 8461Artificially create a bold font by printing each glyph twice, 8462slightly offset. 8463 8464Two syntax forms are available. 8465 8466@itemize @bullet 8467@item 8468Imitate a bold font unconditionally. The first argument specifies the 8469font to embolden, and the second is the number of basic units, minus 8470one, by which the two glyphs are offset. If the second argument is 8471missing, emboldening is turned off. 8472 8473@var{font} can be either a non-negative font position or the name of a 8474font. 8475 8476@var{offset} is available in the @code{.b} read-only register if a 8477special font is active; in the @code{bd} request, its default unit is 8478@samp{u}. 8479 8480@cindex @code{fspecial} request, and imitating bold 8481@kindex special 8482@cindex embolding of special fonts 8483@cindex special fonts, emboldening 8484@item 8485Imitate a bold form conditionally. Embolden @var{font1} by 8486@var{offset} only if font @var{font2} is the current font. This 8487command can be issued repeatedly to set up different emboldening 8488values for different current fonts. If the second argument is 8489missing, emboldening is turned off for this particular current font. 8490 8491This affects special fonts only (either set up with the @code{special} 8492command in font files or with the @code{fspecial} request). 8493@end itemize 8494@endDefreq 8495 8496@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 8497@cindex constant glyph space mode (@code{cs}) 8498@cindex mode for constant glyph space (@code{cs}) 8499@cindex glyph, constant space 8500@cindex @code{ps} request, and constant glyph space mode 8501Switch to and from @dfn{constant glyph space mode}. If activated, the 8502width of every glyph is @math{@var{width}/36} ems. The em size is 8503given absolutely by @var{em-size}; if this argument is missing, the em 8504value is taken from the current font size (as set with the @code{ps} 8505request) when the font is effectively in use. Without second and 8506third argument, constant glyph space mode is deactivated. 8507 8508Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is 8509an integer. 8510@endDefreq 8511 8512@c --------------------------------------------------------------------- 8513 8514@node Ligatures and Kerning, , Artificial Fonts, Fonts 8515@subsection Ligatures and Kerning 8516@cindex ligatures and kerning 8517@cindex kerning and ligatures 8518 8519Ligatures are groups of characters that are run together, i.e, producing 8520a single glyph. For example, the letters `f' and `i' can form a 8521ligature `fi' as in the word `file'. This produces a cleaner look 8522(albeit subtle) to the printed output. Usually, ligatures are not 8523available in fonts for TTY output devices. 8524 8525Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 8526typesetter that was the target of @acronym{AT&T} @code{troff} also 8527supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or 8528`expert' fonts may include ligatures for `ft' and `ct', although GNU 8529@code{troff} does not support these (yet). 8530 8531@DefreqList {lg, [@Var{flag}]} 8532@DefregListEnd {.lg} 8533@cindex activating ligatures (@code{lg}) 8534@cindex ligatures, activating (@code{lg}) 8535@cindex ligatures enabled register (@code{.lg}) 8536Switch the ligature mechanism on or off; if the parameter is non-zero 8537or missing, ligatures are enabled, otherwise disabled. Default is on. 8538The current ligature mode can be found in the read-only number register 8539@code{.lg} (set to 1 or@w{ }2 if ligatures are enabled, 0@w{ }otherwise). 8540 8541Setting the ligature mode to@w{ }2 enables the two-character ligatures 8542(fi, fl, and ff) and disables the three-character ligatures (ffi and 8543ffl). 8544@endDefreq 8545 8546@dfn{Pairwise kerning} is another subtle typesetting mechanism that 8547modifies the distance between a glyph pair to improve readability. 8548In most cases (but not always) the distance is decreased. 8549@ifnotinfo 8550For example, compare the combination of the letters `V' and `A'. With 8551kerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 8552@end ifnotinfo 8553Typewriter-like fonts and fonts for terminals where all glyphs 8554have the same width don't use kerning. 8555 8556@DefreqList {kern, [@Var{flag}]} 8557@DefregListEnd {.kern} 8558@cindex activating kerning (@code{kern}) 8559@cindex kerning, activating (@code{kern}) 8560@cindex kerning enabled register (@code{.kern}) 8561Switch kerning on or off. If the parameter is non-zero or missing, 8562enable pairwise kerning, otherwise disable it. The read-only number 8563register @code{.kern} is set to@w{ }1 if pairwise kerning is enabled, 85640@w{ }otherwise. 8565 8566@cindex zero width space character (@code{\&}) 8567@cindex character, zero width space (@code{\&}) 8568@cindex space character, zero width (@code{\&}) 8569If the font description file contains pairwise kerning information, 8570glyphs from that font are kerned. Kerning between two glyphs 8571can be inhibited by placing @code{\&} between them: @samp{V\&A}. 8572 8573@xref{Font File Format}. 8574@endDefreq 8575 8576@cindex track kerning 8577@cindex kerning, track 8578@dfn{Track kerning} expands or reduces the space between glyphs. 8579This can be handy, for example, if you need to squeeze a long word 8580onto a single line or spread some text to fill a narrow column. It 8581must be used with great care since it is usually considered bad 8582typography if the reader notices the effect. 8583 8584@Defreq {tkf, f s1 n1 s2 n2} 8585@cindex activating track kerning (@code{tkf}) 8586@cindex track kerning, activating (@code{tkf}) 8587Enable track kerning for font@w{ }@var{f}. If the current font is@w{ 8588}@var{f} the width of every glyph is increased by an amount 8589between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 8590the current point size is less than or equal to @var{s1} the width is 8591increased by @var{n1}; if it is greater than or equal to @var{s2} the 8592width is increased by @var{n2}; if the point size is greater than or 8593equal to @var{s1} and less than or equal to @var{s2} the increase in 8594width is a linear function of the point size. 8595 8596The default scaling indicator is @samp{z} for @var{s1} and @var{s2}, 8597@samp{p} for @var{n1} and @var{n2}. 8598 8599Note that the track kerning amount is added even to the rightmost glyph 8600in a line; for large values it is thus recommended to increase the line 8601length by the same amount to compensate it. 8602@endDefreq 8603 8604Sometimes, when typesetting letters of different fonts, more or less 8605space at such boundaries are needed. There are two escapes to help 8606with this. 8607 8608@Defesc {\\/, , , } 8609@cindex italic correction (@code{\/}) 8610@cindex correction, italic (@code{\/}) 8611@cindex correction between italic and roman glyph (@code{\/}, @code{\,}) 8612@cindex roman glyph, correction after italic glyph (@code{\/}) 8613@cindex italic glyph, correction before roman glyph (@code{\/}) 8614@cindex glyph, italic correction (@code{\/}) 8615Increase the width of the preceding glyph so that the spacing 8616between that glyph and the following glyph is correct if the 8617following glyph is a roman glyph. For example, if an 8618italic@w{ }@code{f} is immediately followed by a roman right 8619parenthesis, then in many fonts the top right portion of the@w{ }@code{f} 8620overlaps the top left of the right parenthesis. Use this escape 8621sequence whenever an italic glyph is immediately followed by a 8622roman glyph without any intervening space. This small amount of 8623space is also called @dfn{italic correction}. 8624 8625@iftex 8626@example 8627@group 8628\f[I]f\f[R]) 8629 @result{} {@it f}@r{)} 8630\f[I]f\/\f[R]) 8631 @result{} @i{f}@r{)} 8632@end group 8633@end example 8634@end iftex 8635@endDefesc 8636 8637@Defesc {\\\,, , , } 8638@cindex left italic correction (@code{\,}) 8639@cindex correction, left italic (@code{\,}) 8640@cindex glyph, left italic correction (@code{\,}) 8641@cindex roman glyph, correction before italic glyph (@code{\,}) 8642@cindex italic glyph, correction after roman glyph (@code{\,}) 8643Modify the spacing of the following glyph so that the spacing 8644between that glyph and the preceding glyph is correct if the 8645preceding glyph is a roman glyph. Use this escape sequence 8646whenever a roman glyph is immediately followed by an italic 8647glyph without any intervening space. In analogy to above, this 8648space could be called @dfn{left italic correction}, but this term 8649isn't used widely. 8650 8651@iftex 8652@example 8653@group 8654q\f[I]f 8655 @result{} @r{q}@i{f} 8656q\,\f[I]f 8657 @result{} @r{q}@math{@ptexcomma}@i{f} 8658@end group 8659@end example 8660@end iftex 8661@endDefesc 8662 8663@Defesc {\\&, , , } 8664Insert a zero-width character, which is invisible. Its intended use 8665is to stop interaction of a character with its surrounding. 8666 8667@itemize @bullet 8668@item 8669It prevents the insertion of extra space after an end-of-sentence 8670character. 8671 8672@Example 8673Test. 8674Test. 8675 @result{} Test. Test. 8676Test.\& 8677Test. 8678 @result{} Test. Test. 8679@endExample 8680 8681@item 8682It prevents interpretation of a control character at the beginning of 8683an input line. 8684 8685@Example 8686.Test 8687 @result{} warning: `Test' not defined 8688\&.Test 8689 @result{} .Test 8690@endExample 8691 8692@item 8693It prevents kerning between two glyphs. 8694 8695@ifnotinfo 8696@example 8697@group 8698VA 8699 @result{} @r{VA} 8700V\&A 8701 @result{} @r{V@w{}A} 8702@end group 8703@end example 8704@end ifnotinfo 8705 8706@item 8707It is needed to map an arbitrary character to nothing in the @code{tr} 8708request (@pxref{Character Translations}). 8709@end itemize 8710@endDefesc 8711 8712@Defesc {\\), , , } 8713This escape is similar to @code{\&} except that it behaves like a 8714character declared with the @code{cflags} request to be transparent 8715for the purposes of an end-of-sentence character. 8716 8717Its main usage is in macro definitions to protect against arguments 8718starting with a control character. 8719 8720@Example 8721.de xxx 8722\)\\$1 8723.. 8724.de yyy 8725\&\\$1 8726.. 8727This is a test.\c 8728.xxx ' 8729This is a test. 8730 @result{}This is a test.' This is a test. 8731This is a test.\c 8732.yyy ' 8733This is a test. 8734 @result{}This is a test.' This is a test. 8735@endExample 8736@endDefesc 8737 8738 8739@c ===================================================================== 8740 8741@node Sizes, Strings, Fonts, gtroff Reference 8742@section Sizes 8743@cindex sizes 8744 8745@cindex baseline 8746@cindex type size 8747@cindex size of type 8748@cindex vertical spacing 8749@cindex spacing, vertical 8750@code{gtroff} uses two dimensions with each line of text, type size 8751and vertical spacing. The @dfn{type size} is approximately the height 8752of the tallest glyph.@footnote{This is usually the parenthesis. 8753Note that in most cases the real dimensions of the glyphs in a font 8754are @emph{not} related to its type size! For example, the standard 8755@sc{PostScript} font families `Times Roman', `Helvetica', and 8756`Courier' can't be used together at 10@dmn{pt}; to get acceptable 8757output, the size of `Helvetica' has to be reduced by one point, and 8758the size of `Courier' must be increased by one point.} @dfn{Vertical 8759spacing} is the amount of space @code{gtroff} allows for a line of 8760text; normally, this is about 20%@w{ }larger than the current type 8761size. Ratios smaller than this can result in hard-to-read text; 8762larger than this, it spreads the text out more vertically (useful for 8763term papers). By default, @code{gtroff} uses 10@w{ }point type on 876412@w{ }point spacing. 8765 8766@cindex leading 8767The difference between type size and vertical spacing is known, by 8768typesetters, as @dfn{leading} (this is pronounced `ledding'). 8769 8770@menu 8771* Changing Type Sizes:: 8772* Fractional Type Sizes:: 8773@end menu 8774 8775@c --------------------------------------------------------------------- 8776 8777@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 8778@subsection Changing Type Sizes 8779 8780@DefreqList {ps, [@Var{size}]} 8781@DefreqItem {ps, @t{+}@Var{size}} 8782@DefreqItem {ps, @t{-}@Var{size}} 8783@DefescItem {\\s, , size, } 8784@DefregListEnd {.s} 8785@cindex changing type sizes (@code{ps}, @code{\s}) 8786@cindex type sizes, changing (@code{ps}, @code{\s}) 8787@cindex point sizes, changing (@code{ps}, @code{\s}) 8788Use the @code{ps} request or the @code{\s} escape to change (increase, 8789decrease) the type size (in points). Specify @var{size} as either an 8790absolute point size, or as a relative change from the current size. 8791The size@w{ }0, or no argument, goes back to the previous size. 8792 8793Default scaling indicator of @code{size} is @samp{z}. If @code{size} 8794is zero or negative, it is set to 1@dmn{u}. 8795 8796@cindex type size registers (@code{.s}, @code{.ps}) 8797@cindex point size registers (@code{.s}, @code{.ps}) 8798The read-only number register @code{.s} returns the point size in 8799points as a decimal fraction. This is a string. To get the point 8800size in scaled points, use the @code{.ps} register instead. 8801 8802@code{.s} is associated with the current environment 8803(@pxref{Environments}). 8804 8805@Example 8806snap, snap, 8807.ps +2 8808grin, grin, 8809.ps +2 8810wink, wink, \s+2nudge, nudge,\s+8 say no more! 8811.ps 10 8812@endExample 8813 8814The @code{\s} escape may be called in a variety of ways. Much like 8815other escapes there must be a way to determine where the argument ends 8816and the text begins. Any of the following forms are valid: 8817 8818@table @code 8819@item \s@var{n} 8820Set the point size to @var{n}@w{ }points. @var{n}@w{ }must be either 88210 or in the range 4 to@w{ }39. 8822 8823@item \s+@var{n} 8824@itemx \s-@var{n} 8825Increase or decrease the point size by @var{n}@w{ }points. @var{n}@w{ 8826}must be exactly one digit. 8827 8828@item \s(@var{nn} 8829Set the point size to @var{nn}@w{ }points. @var{nn} must be exactly 8830two digits. 8831 8832@item \s+(@var{nn} 8833@itemx \s-(@var{nn} 8834@itemx \s(+@var{nn} 8835@itemx \s(-@var{nn} 8836Increase or decrease the point size by @var{nn}@w{ }points. @var{nn} 8837must be exactly two digits. 8838@end table 8839 8840Note that @code{\s} doesn't produce an input token in @code{gtroff}. 8841As a consequence, it can be used in requests like @code{mc} (which 8842expects a single character as an argument) to change the font on 8843the fly: 8844 8845@Example 8846.mc \s[20]x\s[0] 8847@endExample 8848 8849@xref{Fractional Type Sizes}, for yet another syntactical form of 8850using the @code{\s} escape. 8851@endDefreq 8852 8853@Defreq {sizes, s1 s2 @dots{} sn [0]} 8854Some devices may only have certain permissible sizes, in which case 8855@code{gtroff} rounds to the nearest permissible size. 8856The @file{DESC} file specifies which sizes are permissible for the device. 8857 8858Use the @code{sizes} request to change the permissible sizes 8859for the current output device. 8860Arguments are in scaled points; 8861the @code{sizescale} line in the 8862@file{DESC} file for the output device 8863provides the scaling factor. 8864For example, if the scaling factor is 1000, 8865then the value 12000 is 12@w{ }points. 8866 8867Each argument can be a single point size (such as @samp{12000}), 8868or a range of sizes (such as @samp{4000-72000}). 8869You can optionally end the list with a zero. 8870@endDefreq 8871 8872@DefreqList {vs, [@Var{space}]} 8873@DefreqItem {vs, @t{+}@Var{space}} 8874@DefreqItem {vs, @t{-}@Var{space}} 8875@DefregListEnd {.v} 8876@cindex changing vertical line spacing (@code{vs}) 8877@cindex vertical line spacing, changing (@code{vs}) 8878@cindex vertical line spacing register (@code{.v}) 8879Change (increase, decrease) the vertical spacing by @var{space}. The 8880default scaling indicator is @samp{p}. 8881 8882If @code{vs} is called without an argument, the vertical spacing is 8883reset to the previous value before the last call to @code{vs}. 8884 8885@cindex @code{.V} register, and @code{vs} 8886@code{gtroff} creates a warning of type @samp{range} if @var{space} is 8887zero or negative; the vertical spacing is then set to the vertical 8888resolution (as given in the @code{.V} register). 8889 8890The read-only number register @code{.v} contains the current vertical 8891spacing; it is associated with the current environment 8892(@pxref{Environments}). 8893@endDefreq 8894 8895@cindex vertical line spacing, effective value 8896The effective vertical line spacing consists of four components. 8897 8898@itemize @bullet 8899@item 8900The vertical line spacing as set with the @code{vs} request. 8901 8902@cindex post-vertical line spacing 8903@cindex line spacing, post-vertical (@code{pvs}) 8904@item 8905The @dfn{post-vertical line spacing} as set with the @code{pvs} request. 8906This is vertical space which will be added after a line has been 8907output. 8908 8909@cindex extra pre-vertical line space (@code{\x}) 8910@cindex line space, extra pre-vertical (@code{\x}) 8911@item 8912The @dfn{extra pre-vertical line space} as set with the @code{\x} request, 8913using a negative value. This is vertical space which will be added once 8914before the current line has been output. 8915 8916@cindex extra post-vertical line space (@code{\x}) 8917@cindex line space, extra post-vertical (@code{\x}) 8918@item 8919The @dfn{extra post-vertical line space} as set with the @code{\x} request, 8920using a positive value. This is vertical space which will be added once 8921after the current line has been output. 8922@end itemize 8923 8924@cindex double-spacing (@code{vs}, @code{pvs}) 8925It is usually better to use @code{vs} or @code{pvs} instead of @code{ls} 8926to produce double-spaced documents: @code{vs} and @code{pvs} have a finer 8927granularity for the inserted vertical space compared to @code{ls}; 8928furthermore, certain preprocessors assume single-spacing. 8929 8930@xref{Manipulating Spacing}, for more details on the @code{\x} escape 8931and the @code{ls} request. 8932 8933@DefreqList {pvs, [@Var{space}]} 8934@DefreqItem {pvs, @t{+}@Var{space}} 8935@DefreqItem {pvs, @t{-}@Var{space}} 8936@DefregListEnd {.pvs} 8937@cindex @code{ls} request, alternative to (@code{pvs}) 8938@cindex post-vertical line spacing, changing (@code{pvs}) 8939@cindex post-vertical line spacing register (@code{.pvs}) 8940Change (increase, decrease) the post-vertical spacing by 8941@var{space}. The default scaling indicator is @samp{p}. 8942 8943If @code{pvs} is called without an argument, the post-vertical spacing is 8944reset to the previous value before the last call to @code{pvs}. 8945 8946@code{gtroff} creates a warning of type @samp{range} if @var{space} is 8947zero or negative; the vertical spacing is then set to zero. 8948 8949The read-only number register @code{.pvs} contains the current 8950post-vertical spacing; it is associated with the current environment 8951(@pxref{Environments}). 8952@endDefreq 8953 8954 8955@c --------------------------------------------------------------------- 8956 8957@node Fractional Type Sizes, , Changing Type Sizes, Sizes 8958@subsection Fractional Type Sizes 8959@cindex fractional type sizes 8960@cindex fractional point sizes 8961@cindex type sizes, fractional 8962@cindex point sizes, fractional 8963@cindex sizes, fractional 8964 8965@cindex @code{s} unit 8966@cindex unit, @code{s} 8967@cindex @code{z} unit 8968@cindex unit, @code{z} 8969@cindex @code{ps} request, with fractional type sizes 8970@cindex @code{cs} request, with fractional type sizes 8971@cindex @code{tkf} request, with fractional type sizes 8972@cindex @code{\H}, with fractional type sizes 8973@cindex @code{\s}, with fractional type sizes 8974A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 8975where @var{sizescale} is specified in the @file{DESC} file (1@w{ }by 8976default). There is a new scale indicator @samp{z} which has the 8977effect of multiplying by @var{sizescale}. Requests and escape 8978sequences in @code{gtroff} interpret arguments that represent a point 8979size as being in units of scaled points, but they evaluate each such 8980argument using a default scale indicator of @samp{z}. Arguments 8981treated in this way are the argument to the @code{ps} request, the 8982third argument to the @code{cs} request, the second and fourth 8983arguments to the @code{tkf} request, the argument to the @code{\H} 8984escape sequence, and those variants of the @code{\s} escape sequence 8985that take a numeric expression as their argument (see below). 8986 8987For example, suppose @var{sizescale} is@w{ }1000; then a scaled point 8988is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 8989equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 899010250@w{ }scaled points, which is equal to 10.25@w{ }points. 8991 8992@code{gtroff} disallows the use of the @samp{z} scale indicator in 8993instances where it would make no sense, such as a numeric 8994expression whose default scale indicator was neither @samp{u} nor 8995@samp{z}. Similarly it would make 8996no sense to use a scaling indicator other than @samp{z} or @samp{u} in a 8997numeric expression whose default scale indicator was @samp{z}, and so 8998@code{gtroff} disallows this as well. 8999 9000There is also new scale indicator @samp{s} which multiplies by the 9001number of units in a scaled point. So, for example, @samp{\n[.ps]s} is 9002equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 9003scale indicators. 9004 9005@Defreg {.ps} 9006A read-only number register returning the point size in scaled points. 9007 9008@code{.ps} is associated with the current environment 9009(@pxref{Environments}). 9010@endDefreg 9011 9012@DefregList {.psr} 9013@DefregListEnd {.sr} 9014@cindex last-requested point size registers (@code{.psr}, @code{.sr}) 9015@cindex point size registers, last-requested (@code{.psr}, @code{.sr}) 9016@cindex @code{.ps} register, in comparison with @code{.psr} 9017@cindex @code{.s} register, in comparison with @code{.sr} 9018The last-requested point size in scaled points is contained in the 9019@code{.psr} read-only number register. The last requested point size 9020in points as a decimal fraction can be found in @code{.sr}. This is a 9021string-valued read-only number register. 9022 9023Note that the requested point sizes are device-independent, whereas 9024the values returned by the @code{.ps} and @code{.s} registers are not. 9025For example, if a point size of 11@dmn{pt} is requested, and a 9026@code{sizes} request (or a @code{sizescale} line in a @file{DESC} file) 9027specifies 10.95@dmn{pt} instead, this value is actually used. 9028 9029Both registers are associated with the current environment 9030(@pxref{Environments}). 9031@endDefreg 9032 9033The @code{\s} escape has the following syntax for working with 9034fractional type sizes: 9035 9036@table @code 9037@item \s[@var{n}] 9038@itemx \s'@var{n}' 9039Set the point size to @var{n}@w{ }scaled points; @var{n}@w{ }is a numeric 9040expression with a default scale indicator of @samp{z}. 9041 9042@item \s[+@var{n}] 9043@itemx \s[-@var{n}] 9044@itemx \s+[@var{n}] 9045@itemx \s-[@var{n}] 9046@itemx \s'+@var{n}' 9047@itemx \s'-@var{n}' 9048@itemx \s+'@var{n}' 9049@itemx \s-'@var{n}' 9050Increase or or decrease the point size by @var{n}@w{ }scaled points; 9051@var{n}@w{ }is a numeric expression with a default scale indicator of 9052@samp{z}. 9053@end table 9054 9055@xref{Font Files}. 9056 9057 9058@c ===================================================================== 9059 9060@node Strings, Conditionals and Loops, Sizes, gtroff Reference 9061@section Strings 9062@cindex strings 9063 9064@code{gtroff} has string variables, which are entirely for user 9065convenience (i.e.@: there are no built-in strings exept @code{.T}, but 9066even this is a read-write string variable). 9067 9068@DefreqList {ds, name [@Var{string}]} 9069@DefreqItem {ds1, name [@Var{string}]} 9070@DefescItem {\\*, , n, } 9071@DefescItem {\\*, @lparen{}, nm, } 9072@DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}} 9073@cindex string interpolation (@code{\*}) 9074@cindex string expansion (@code{\*}) 9075@cindex interpolation of strings (@code{\*}) 9076@cindex expansion of strings (@code{\*}) 9077@cindex string arguments 9078@cindex arguments, of strings 9079Define and access a string variable @var{name} (one-character name@w{ 9080}@var{n}, two-character name @var{nm}). If @var{name} already exists, 9081@code{ds} overwrites the previous definition. Only the syntax form 9082using brackets can take arguments which are handled identically to 9083macro arguments; the single exception is that a closing bracket as an 9084argument must be enclosed in double quotes. @xref{Request Arguments}, 9085and @ref{Parameters}. 9086 9087Example: 9088 9089@Example 9090.ds foo a \\$1 test 9091. 9092This is \*[foo nice]. 9093 @result{} This is a nice test. 9094@endExample 9095 9096The @code{\*} escape @dfn{interpolates} (expands in-place) a 9097previously-defined string variable. To be more precise, the stored 9098string is pushed onto the input stack which is then parsed by 9099@code{gtroff}. Similar to number registers, it is possible to nest 9100strings, i.e. string variables can be called within string variables. 9101 9102If the string named by the @code{\*} escape does not exist, it is 9103defined as empty, and a warning of type @samp{mac} is emitted (see 9104@ref{Debugging}, for more details). 9105 9106@cindex comments, with @code{ds} 9107@cindex @code{ds} request, and comments 9108@strong{Caution:} Unlike other requests, the second argument to the 9109@code{ds} request takes up the entire line including trailing spaces. 9110This means that comments on a line with such a request can introduce 9111unwanted space into a string. 9112 9113@Example 9114.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 9115@endExample 9116 9117@noindent 9118Instead the comment should be put on another line or have the comment 9119escape adjacent with the end of the string. 9120 9121@Example 9122.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 9123@endExample 9124 9125@cindex trailing quotes 9126@cindex quotes, trailing 9127@cindex leading spaces with @code{ds} 9128@cindex spaces with @code{ds} 9129@cindex @code{ds} request, and leading spaces 9130To produce leading space the string can be started with a double 9131quote. No trailing quote is needed; in fact, any trailing quote is 9132included in your string. 9133 9134@Example 9135.ds sign " Yours in a white wine sauce, 9136@endExample 9137 9138@cindex multi-line strings 9139@cindex strings, multi-line 9140@cindex newline character, in strings, escaping 9141@cindex escaping newline characters, in strings 9142Strings are not limited to a single line of text. A string can span 9143several lines by escaping the newlines with a backslash. The 9144resulting string is stored @emph{without} the newlines. 9145 9146@Example 9147.ds foo lots and lots \ 9148of text are on these \ 9149next several lines 9150@endExample 9151 9152It is not possible to have real newlines in a string. To put a single 9153double quote character into a string, use two consecutive double quote 9154characters. 9155 9156The @code{ds1} request turns off compatibility mode 9157while interpreting a string. To be more precise, a @dfn{compatibility 9158save} input token is inserted at the beginning of the string, and a 9159@dfn{compatibility restore} input token at the end. 9160 9161@Example 9162.nr xxx 12345 9163.ds aa The value of xxx is \\n[xxx]. 9164.ds1 bb The value of xxx ix \\n[xxx]. 9165. 9166.cp 1 9167. 9168\*(aa 9169 @result{} warning: number register `[' not defined 9170 @result{} The value of xxx is 0xxx]. 9171\*(bb 9172 @result{} The value of xxx ix 12345. 9173@endExample 9174 9175@cindex name space, common, of macros, diversions, and strings 9176@cindex common name space of macros, diversions, and strings 9177@cindex macros, shared name space with strings and diversions 9178@cindex strings, shared name space with macros and diversions 9179@cindex diversions, shared name space with macros and strings 9180Strings, macros, and diversions (and boxes) share the same name space. 9181Internally, even the same mechanism is used to store them. This has 9182some interesting consequences. For example, it is possible to call a 9183macro with string syntax and vice versa. 9184 9185@Example 9186.de xxx 9187a funny test. 9188.. 9189This is \*[xxx] 9190 @result{} This is a funny test. 9191 9192.ds yyy a funny test 9193This is 9194.yyy 9195 @result{} This is a funny test. 9196@endExample 9197 9198Diversions and boxes can be also called with string syntax. 9199 9200Another consequence is that you can copy one-line diversions or boxes 9201to a string. 9202 9203@Example 9204.di xxx 9205a \fItest\fR 9206.br 9207.di 9208.ds yyy This is \*[xxx]\c 9209\*[yyy]. 9210 @result{} @r{This is a }@i{test}. 9211@endExample 9212 9213@noindent 9214As the previous example shows, it is possible to store formatted 9215output in strings. The @code{\c} escape prevents the insertion of an 9216additional blank line in the output. 9217 9218Copying diversions longer than a single output line produces 9219unexpected results. 9220 9221@Example 9222.di xxx 9223a funny 9224.br 9225test 9226.br 9227.di 9228.ds yyy This is \*[xxx]\c 9229\*[yyy]. 9230 @result{} test This is a funny. 9231@endExample 9232 9233Usually, it is not predictable whether a diversion contains one or 9234more output lines, so this mechanism should be avoided. With 9235@acronym{UNIX} @code{troff}, this was the only solution to strip off a 9236final newline from a diversion. Another disadvantage is that the 9237spaces in the copied string are already formatted, making them 9238unstretchable. This can cause ugly results. 9239 9240@cindex stripping final newline in diversions 9241@cindex diversion, stripping final newline 9242@cindex final newline, stripping in diversions 9243@cindex newline, final, stripping in diversions 9244@cindex horizontal space, unformatting 9245@cindex space, horizontal, unformatting 9246@cindex unformatting horizontal space 9247A clean solution to this problem is available in GNU @code{troff}, 9248using the requests @code{chop} to remove the final newline of a 9249diversion, and @code{unformat} to make the horizontal spaces 9250stretchable again. 9251 9252@Example 9253.box xxx 9254a funny 9255.br 9256test 9257.br 9258.box 9259.chop xxx 9260.unformat xxx 9261This is \*[xxx]. 9262 @result{} This is a funny test. 9263@endExample 9264 9265@xref{Gtroff Internals}, for more information. 9266@endDefreq 9267 9268@DefreqList {as, name [@Var{string}]} 9269@DefreqListEnd {as1, name [@Var{string}]} 9270@cindex appending to a string (@code{as}) 9271@cindex string, appending (@code{as}) 9272The @code{as} request is similar to @code{ds} but appends @var{string} 9273to the string stored as @var{name} instead of redefining it. If 9274@var{name} doesn't exist yet, it is created. 9275 9276@Example 9277.as sign " with shallots, onions and garlic, 9278@endExample 9279 9280The @code{as1} request is similar to @code{as}, but compatibility mode 9281is switched off while the appended string is interpreted. To be more 9282precise, a @dfn{compatibility save} input token is inserted at the 9283beginning of the appended string, and a @dfn{compatibility restore} 9284input token at the end. 9285@endDefreq 9286 9287Rudimentary string manipulation routines are given with the next two 9288requests. 9289 9290@Defreq {substring, str n1 [@Var{n2}]} 9291@cindex substring (@code{substring}) 9292Replace the string named @var{str} with the substring 9293defined by the indices @var{n1} and@w{ }@var{n2}. The first character 9294in the string has index@w{ }0. If @var{n2} is omitted, it is taken to 9295be equal to the string's length. If the index value @var{n1} or 9296@var{n2} is negative, it is counted from the end of the 9297string, going backwards: The last character has index@w{ }@minus{}1, the 9298character before the last character has index@w{ }@minus{}2, etc. 9299 9300@Example 9301.ds xxx abcdefgh 9302.substring xxx 1 -4 9303\*[xxx] 9304 @result{} bcde 9305@endExample 9306@endDefreq 9307 9308@Defreq {length, reg str} 9309@cindex length of a string (@code{length}) 9310@cindex string, length of (@code{length}) 9311Compute the number of characters of @var{str} and return it in the 9312number register @var{reg}. If @var{reg} doesn't exist, it is created. 9313@code{str} is read in copy mode. 9314 9315@Example 9316.ds xxx abcd\h'3i'efgh 9317.length yyy \n[xxx] 9318\n[yyy] 9319 @result{} 14 9320@endExample 9321@endDefreq 9322 9323@Defreq {rn, xx yy} 9324@cindex renaming request (@code{rn}) 9325@cindex request, renaming (@code{rn}) 9326@cindex renaming macro (@code{rn}) 9327@cindex macro, renaming (@code{rn}) 9328@cindex renaming string (@code{rn}) 9329@cindex string, renaming (@code{rn}) 9330@cindex renaming diversion (@code{rn}) 9331@cindex diversion, renaming (@code{rn}) 9332Rename the request, macro, diversion, or string @var{xx} to @var{yy}. 9333@endDefreq 9334 9335@Defreq {rm, xx} 9336@cindex removing request (@code{rm}) 9337@cindex request, removing (@code{rm}) 9338@cindex removing macro (@code{rm}) 9339@cindex macro, removing (@code{rm}) 9340@cindex removing string (@code{rm}) 9341@cindex string, removing (@code{rm}) 9342@cindex removing diversion (@code{rm}) 9343@cindex diversion, removing (@code{rm}) 9344Remove the request, macro, diversion, or string @var{xx}. @code{gtroff} 9345treats subsequent invocations as if the object had never been defined. 9346@endDefreq 9347 9348@Defreq {als, new old} 9349@cindex alias, string, creating (@code{als}) 9350@cindex alias, macro, creating (@code{als}) 9351@cindex alias, diversion, creating (@code{als}) 9352@cindex creating alias, for string (@code{als}) 9353@cindex creating alias, for macro (@code{als}) 9354@cindex creating alias, for diversion (@code{als}) 9355@cindex string, creating alias (@code{als}) 9356@cindex macro, creating alias (@code{als}) 9357@cindex diversion, creating alias (@code{als}) 9358Create an alias named @var{new} for the request, string, macro, or 9359diversion object named @var{old}. The new name and the old name are 9360exactly equivalent (it is similar to a hard rather than a soft 9361link). If @var{old} is undefined, @code{gtroff} generates a warning of 9362type @samp{mac} and ignores the request. 9363@endDefreq 9364 9365@Defreq {chop, xx} 9366Remove (chop) the last character from the macro, string, or diversion 9367named @var{xx}. This is useful for removing the newline from the end 9368of diversions that are to be interpolated as strings. This command 9369can be used repeatedly; see @ref{Gtroff Internals}, for details on 9370nodes inserted additionally by @code{gtroff}. 9371@endDefreq 9372 9373@xref{Identifiers}, and @ref{Comments}. 9374 9375 9376@c ===================================================================== 9377 9378@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 9379@section Conditionals and Loops 9380@cindex conditionals and loops 9381@cindex loops and conditionals 9382 9383@menu 9384* Operators in Conditionals:: 9385* if-else:: 9386* while:: 9387@end menu 9388 9389@c --------------------------------------------------------------------- 9390 9391@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 9392@subsection Operators in Conditionals 9393 9394@cindex @code{if} request, operators to use with 9395@cindex @code{while} request, operators to use with 9396In @code{if} and @code{while} requests, there are several more 9397operators available: 9398 9399@table @code 9400@item e 9401@itemx o 9402True if the current page is even or odd numbered (respectively). 9403 9404@item n 9405True if the document is being processed in nroff mode (i.e., the 9406@code{.nroff} command has been issued). 9407 9408@item t 9409True if the document is being processed in troff mode (i.e., the 9410@code{.troff} command has been issued). 9411 9412@item v 9413Always false. This condition is for compatibility with other 9414@code{troff} versions only. 9415 9416@item '@var{xxx}'@var{yyy}' 9417True if the string @var{xxx} is equal to the string @var{yyy}. Other 9418characters can be used in place of the single quotes; the same set of 9419delimiters as for the @code{\D} escape is used (@pxref{Escapes}). 9420@code{gtroff} formats the strings before being compared: 9421 9422@Example 9423.ie "|"\fR|\fP" \ 9424true 9425.el \ 9426false 9427 @result{} true 9428@endExample 9429 9430@noindent 9431The resulting motions, glyph sizes, and fonts have to 9432match,@footnote{The created output nodes must be identical. 9433@xref{Gtroff Internals}.} and not the individual motion, size, and 9434font requests. In the previous example, @samp{|} and @samp{\fR|\fP} 9435both result in a roman @samp{|} glyph with the same point size and 9436at the same location on the page, so the strings are equal. If 9437@samp{.ft@w{ }I} had been added before the @samp{.ie}, the result 9438would be ``false'' because (the first) @samp{|} produces an italic 9439@samp{|} rather than a roman one. 9440 9441@item r @var{xxx} 9442True if there is a number register named @var{xxx}. 9443 9444@item d @var{xxx} 9445True if there is a string, macro, diversion, or request named @var{xxx}. 9446 9447@item m @var{xxx} 9448True if there is a color named @var{xxx}. 9449 9450@item c @var{g} 9451True if there is a glyph @var{g} available@footnote{The name of this 9452conditional operator is a misnomer since it tests names of output 9453glyphs.}; @var{g} is either an @acronym{ASCII} character or a special 9454character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition 9455is also true if @var{g} has been defined by the @code{char} request. 9456@end table 9457 9458Note that these operators can't be combined with other operators like 9459@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 9460between the exclamation mark and the operator) can be used to negate 9461the result. 9462 9463@Example 9464.nr xxx 1 9465.ie !r xxx \ 9466true 9467.el \ 9468false 9469 @result{} false 9470@endExample 9471 9472A whitespace after @samp{!} always evaluates to zero (this bizarre 9473behaviour is due to compatibility with @acronym{UNIX} @code{troff}). 9474 9475@Example 9476.nr xxx 1 9477.ie ! r xxx \ 9478true 9479.el \ 9480false 9481 @result{} r xxx true 9482@endExample 9483 9484It is possible to omit the whitespace before the argument to the 9485@samp{r}, @samp{d}, and @samp{c} operators. 9486 9487@xref{Expressions}. 9488 9489@c --------------------------------------------------------------------- 9490 9491@node if-else, while, Operators in Conditionals, Conditionals and Loops 9492@subsection if-else 9493@cindex if-else 9494 9495@code{gtroff} has if-then-else constructs like other languages, although 9496the formatting can be painful. 9497 9498@Defreq {if, expr anything} 9499Evaluate the expression @var{expr}, and executes @var{anything} (the 9500remainder of the line) if @var{expr} evaluates to non-zero (true). 9501@var{anything} is interpreted as though it was on a line by itself 9502(except that leading spaces are swallowed). @xref{Expressions}, for 9503more info. 9504 9505@Example 9506.nr xxx 1 9507.nr yyy 2 9508.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 9509 @result{} true 9510@endExample 9511@endDefreq 9512 9513@Defreq{nop, anything} 9514Executes @var{anything}. 9515This is similar to @code{.if@w{ }1}. 9516@endDefreq 9517 9518@DefreqList {ie, expr anything} 9519@DefreqListEnd {el, anything} 9520Use the @code{ie} and @code{el} requests to write an if-then-else. 9521The first request is the `if' part and the latter is the `else' part. 9522 9523@Example 9524.ie n .ls 2 \" double-spacing in nroff 9525.el .ls 1 \" single-spacing in troff 9526@endExample 9527@endDefreq 9528 9529@c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument 9530@c to @deffn 9531@c 9532@c and in 4.2 you still can't use @{ in macros. 9533 9534@c @DefescList {\@{, , , } 9535@c @DefescListEnd {\@}, , , } 9536@deffn Escape @t{\@{} 9537@deffnx Escape @t{\@}} 9538@esindex \@{ 9539@esindex \@} 9540@cindex begin of conditional block (@code{\@{}) 9541@cindex end of conditional block (@code{\@}}) 9542@cindex conditional block, begin (@code{\@{}) 9543@cindex conditional block, end (@code{\@}}) 9544@cindex block, conditional, begin (@code{\@{}) 9545@cindex block, condititional, end (@code{\@}}) 9546In many cases, an if (or if-else) construct needs to execute more than 9547one request. This can be done using the @code{\@{} and @code{\@}} 9548escapes. The following example shows the possible ways to use these 9549escapes (note the position of the opening and closing braces). 9550 9551@Example 9552.ie t \@{\ 9553. ds lq `` 9554. ds rq '' 9555.\@} 9556.el \ 9557.\@{\ 9558. ds lq " 9559. ds rq "\@} 9560@endExample 9561@c @endDefesc 9562@end deffn 9563 9564@xref{Expressions}. 9565 9566@c --------------------------------------------------------------------- 9567 9568@node while, , if-else, Conditionals and Loops 9569@subsection while 9570@cindex while 9571 9572@code{gtroff} provides a looping construct using the @code{while} 9573request, which is used much like the @code{if} (and related) requests. 9574 9575@Defreq {while, expr anything} 9576Evaluate the expression @var{expr}, and repeatedly execute 9577@var{anything} (the remainder of the line) until @var{expr} evaluates 9578to@w{ }0. 9579 9580@Example 9581.nr a 0 1 9582.while (\na < 9) \@{\ 9583\n+a, 9584.\@} 9585\n+a 9586 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 9587@endExample 9588 9589Some remarks. 9590 9591@cindex @code{de} request, and @code{while} 9592@itemize @bullet 9593@item 9594The body of a @code{while} request is treated like the body of a 9595@code{de} request: @code{gtroff} temporarily stores it in a macro 9596which is deleted after the loop has been exited. It can considerably 9597slow down a macro if the body of the @code{while} request (within the 9598macro) is large. Each time the macro is executed, the @code{while} 9599body is parsed and stored again as a temporary macro. 9600 9601@Example 9602.de xxx 9603. nr num 10 9604. while (\\n[num] > 0) \@{\ 9605. \" many lines of code 9606. nr num -1 9607. \@} 9608.. 9609@endExample 9610 9611@cindex recursive macros 9612@cindex macros, recursive 9613@noindent 9614The traditional and ofter better solution (@acronym{UNIX} @code{troff} 9615doesn't have the @code{while} request) is to use a recursive macro 9616instead which is parsed only once during its definition. 9617 9618@Example 9619.de yyy 9620. if (\\n[num] > 0) \@{\ 9621. \" many lines of code 9622. nr num -1 9623. yyy 9624. \@} 9625.. 9626. 9627.de xxx 9628. nr num 10 9629. yyy 9630.. 9631@endExample 9632 9633@noindent 9634Note that the number of available recursion levels is set to@w{ }1000 9635(this is a compile-time constant value of @code{gtroff}). 9636 9637@item 9638The closing brace of a @code{while} body must end a line. 9639 9640@Example 9641.if 1 \@{\ 9642. nr a 0 1 9643. while (\n[a] < 10) \@{\ 9644. nop \n+[a] 9645.\@}\@} 9646 @result{} unbalanced \@{ \@} 9647@endExample 9648@end itemize 9649@endDefreq 9650 9651@Defreq {break, } 9652@cindex @code{while} request, confusing with @code{br} 9653@cindex @code{break} request, in a @code{while} loop 9654@cindex @code{continue} request, in a @code{while} loop 9655Break out of a @code{while} loop. Be sure not to confuse this with 9656the @code{br} request (causing a line break). 9657@endDefreq 9658 9659@Defreq {continue, } 9660Finish the current iteration of a @code{while} loop, immediately 9661restarting the next iteration. 9662@endDefreq 9663 9664@xref{Expressions}. 9665 9666 9667@c ===================================================================== 9668 9669@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 9670@section Writing Macros 9671@cindex writing macros 9672@cindex macros, writing 9673 9674A @dfn{macro} is a collection of text and embedded commands which can 9675be invoked multiple times. Use macros to define common operations. 9676 9677@DefreqList {de, name [@Var{end}]} 9678@DefreqItem {de1, name [@Var{end}]} 9679@DefreqListEnd {dei, name [@Var{end}]} 9680Define a new macro named @var{name}. @code{gtroff} copies subsequent 9681lines (starting with the next one) into an internal buffer until it 9682encounters the line @samp{..} (two dots). The optional second 9683argument to @code{de} changes this to a macro to @samp{.@var{end}}. 9684 9685There can be whitespace after the first dot in the line containing the 9686ending token (either @samp{.} or macro @samp{@var{end}}). 9687 9688Here a small example macro called @samp{P} which causes a break and 9689inserts some vertical space. It could be used to separate paragraphs. 9690 9691@Example 9692.de P 9693. br 9694. sp .8v 9695.. 9696@endExample 9697 9698The following example defines a macro within another. Remember that 9699expansion must be protected twice; once for reading the macro and 9700once for executing. 9701 9702@Example 9703\# a dummy macro to avoid a warning 9704.de end 9705.. 9706. 9707.de foo 9708. de bar end 9709. nop \f[B]Hallo \\\\$1!\f[] 9710. end 9711.. 9712. 9713.foo 9714.bar Joe 9715 @result{} @b{Hallo Joe!} 9716@endExample 9717 9718@noindent 9719Since @code{\f} has no expansion, it isn't necessary to protect its 9720backslash. Had we defined another macro within @code{bar} which takes 9721a parameter, eight backslashes would be necessary before @samp{$1}. 9722 9723The @code{de1} request turns off compatibility mode 9724while executing the macro. On entry, the current compatibility mode 9725is saved and restored at exit. 9726 9727@Example 9728.nr xxx 12345 9729. 9730.de aa 9731The value of xxx is \\n[xxx]. 9732.. 9733.de1 bb 9734The value of xxx ix \\n[xxx]. 9735.. 9736. 9737.cp 1 9738. 9739.aa 9740 @result{} warning: number register ' not defined 9741 @result{} The value of xxx is 0xxx]. 9742.bb 9743 @result{} The value of xxx ix 12345. 9744@endExample 9745 9746The @code{dei} request defines a macro indirectly. 9747That is, it expands strings whose names 9748are @var{name} or @var{end} before performing the append. 9749 9750This: 9751 9752@Example 9753.ds xx aa 9754.ds yy bb 9755.dei xx yy 9756@endExample 9757 9758@noindent 9759is equivalent to: 9760 9761@Example 9762.de aa bb 9763@endExample 9764 9765@pindex trace.tmac 9766Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}. 9767 9768Note that macro identifiers are shared with identifiers for strings and 9769diversions. 9770@endDefreq 9771 9772@DefreqList {am, xx} 9773@DefreqItem {am1, xx} 9774@DefreqListEnd {ami, xx yy} 9775@cindex appending to a macro (@code{am}) 9776@cindex macro, appending (@code{am}) 9777Works similarly to @code{de} except it appends onto the macro named 9778@var{xx}. So, to make the previously defined @samp{P} macro actually 9779do indented instead of block paragraphs, add the necessary code to the 9780existing macro like this: 9781 9782@Example 9783.am P 9784.ti +5n 9785.. 9786@endExample 9787 9788The @code{am1} request turns off compatibility mode 9789while executing the appended macro piece. To be more precise, a 9790@dfn{compatibility save} input token is inserted at the beginning of 9791the appended code, and a @dfn{compatibility restore} input token at 9792the end. 9793 9794The @code{ami} request appends indirectly, 9795meaning that @code{gtroff} expands strings whose names 9796are @var{xx} or @var{yy} before performing the append. 9797 9798@pindex trace.tmac 9799Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}. 9800@endDefreq 9801 9802@xref{Strings}, for the @code{als} request to rename a macro. 9803 9804The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and 9805@code{as} requests (together with its variants) only create a new object 9806if the name of the macro, diversion or string diversion is currently 9807undefined or if it is defined to be a request; normally they modify the 9808value of an existing object. 9809 9810@Defreq {return, } 9811Exit a macro, immediately returning to the caller. 9812@endDefreq 9813 9814@menu 9815* Copy-in Mode:: 9816* Parameters:: 9817@end menu 9818 9819@c --------------------------------------------------------------------- 9820 9821@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 9822@subsection Copy-in Mode 9823@cindex copy-in mode 9824@cindex mode, copy-in 9825 9826@cindex @code{\n}, when reading text for a macro 9827@cindex @code{\$}, when reading text for a macro 9828@cindex @code{\*}, when reading text for a macro 9829@cindex @code{\\}, when reading text for a macro 9830@cindex \@key{RET}, when reading text for a macro 9831When @code{gtroff} reads in the text for a macro, string, or diversion, 9832it copies the text (including request lines, but excluding escapes) into 9833an internal buffer. Escapes are converted into an internal form, 9834except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 9835@code{\@key{RET}} which are evaluated and inserted into the text where 9836the escape was located. This is known as @dfn{copy-in} mode or 9837@dfn{copy} mode. 9838 9839What this means is that you can specify when these escapes are to be 9840evaluated (either at copy-in time or at the time of use) by insulating 9841the escapes with an extra backslash. Compare this to the @code{\def} 9842and @code{\edef} commands in @TeX{}. 9843 9844The following example prints the numbers 20 and@w{ }10: 9845 9846@Example 9847.nr x 20 9848.de y 9849.nr x 10 9850\&\nx 9851\&\\nx 9852.. 9853.y 9854@endExample 9855 9856@c --------------------------------------------------------------------- 9857 9858@node Parameters, , Copy-in Mode, Writing Macros 9859@subsection Parameters 9860@cindex parameters 9861 9862The arguments to a macro or string can be examined using a variety of 9863escapes. 9864 9865@Defreg {.$} 9866@cindex number of arguments register (@code{.$}) 9867The number of arguments passed to a macro or string. This is a read-only 9868number register. 9869@endDefreg 9870 9871Any individual argument can be retrieved with one of the following 9872escapes: 9873 9874@DefescList {\\$, , n, } 9875@DefescItem {\\$, @lparen{}, nn, } 9876@DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}} 9877@cindex copy-in mode, and macro arguments 9878@cindex macro, arguments (@code{\$}) 9879@cindex arguments, macro (@code{\$}) 9880Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th} 9881argument. As usual, the first form only accepts a single number 9882(larger than zero), the second a two-digit number (larger or equal 9883to@w{ }10), and the third any positive integer value (larger 9884than zero). Macros and strings can have an unlimited number of arguments. 9885Note that due to copy-in mode, use two backslashes on these in actual use 9886to prevent interpolation until the macro is actually invoked. 9887@endDefesc 9888 9889@Defreq {shift, [@Var{n}]} 9890Shift the arguments 1@w{ }position, or as 9891many positions as specified by its argument. After executing this 9892request, argument@w{ }@var{i} becomes argument @math{@var{i}-@var{n}}; 9893arguments 1 to@w{ }@var{n} are no longer available. Shifting by 9894negative amounts is currently undefined. 9895@endDefreq 9896 9897@DefescList {\\$*, , , } 9898@DefescListEnd {\\$@@, , , } 9899In some cases it is convenient to use all of the arguments at once (for 9900example, to pass the arguments along to another macro). The @code{\$*} 9901escape concatenates all the arguments separated by spaces. A 9902similar escape is @code{\$@@}, which concatenates all the 9903arguments with each surrounded by double quotes, and separated by 9904spaces. If not in compatibility mode, the input level of double quotes 9905is preserved (see @ref{Request Arguments}). 9906@endDefesc 9907 9908@Defesc {\\$0, , , } 9909@cindex macro name register (@code{\$0}) 9910@cindex @code{als} request, and @code{\$0} 9911The name used to invoke the current macro. 9912The @code{als} request can make a macro have more than one name. 9913 9914@Example 9915.de generic-macro 9916. ... 9917. if \\n[error] \@{\ 9918. tm \\$0: Houston, we have a problem. 9919. return 9920. \@} 9921.. 9922. 9923.als foo generic-macro 9924.als bar generic-macro 9925@endExample 9926@endDefesc 9927 9928@xref{Request Arguments}. 9929 9930 9931@c ===================================================================== 9932 9933@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 9934@section Page Motions 9935@cindex page motions 9936@cindex motions, page 9937 9938@xref{Manipulating Spacing}, for a discussion of the main request for 9939vertical motion, @code{sp}. 9940 9941@DefreqList {mk, [@Var{reg}]} 9942@DefreqListEnd {rt, [@Var{dist}]} 9943@cindex marking vertical page location (@code{mk}) 9944@cindex page location, vertical, marking (@code{mk}) 9945@cindex location, vertical, page, marking (@code{mk}) 9946@cindex vertical page location, marking (@code{mk}) 9947@cindex returning to marked vertical page location (@code{rt}) 9948@cindex page location, vertical, returning to marked (@code{rt}) 9949@cindex location, vertical, page, returning to marked (@code{rt}) 9950@cindex vertical page location, returning to marked (@code{rt}) 9951The request @code{mk} can be used to mark a location on a page, for 9952movement to later. This request takes a register name as an argument 9953in which to store the current page location. With no argument it 9954stores the location in an internal register. The results of this can 9955be used later by the @code{rt} or the @code{sp} request (or the 9956@code{\v} escape). 9957 9958The @code{rt} request returns @emph{upwards} to the location marked 9959with the last @code{mk} request. If used with an argument, return to 9960a position which distance from the top of the page is @var{dist} (no 9961previous call to @code{mk} is necessary in this case). Default scaling 9962indicator is @samp{v}. 9963 9964Here a primitive solution for a two-column macro. 9965 9966@Example 9967.nr column-length 1.5i 9968.nr column-gap 4m 9969.nr bottom-margin 1m 9970. 9971@endExample 9972@Example 9973.de 2c 9974. br 9975. mk 9976. ll \\n[column-length]u 9977. wh -\\n[bottom-margin]u 2c-trap 9978. nr right-side 0 9979.. 9980. 9981@endExample 9982@Example 9983.de 2c-trap 9984. ie \\n[right-side] \@{\ 9985. nr right-side 0 9986. po -(\\n[column-length]u + \\n[column-gap]u) 9987. \" remove trap 9988. wh -\\n[bottom-margin]u 9989. \@} 9990. el \@{\ 9991. \" switch to right side 9992. nr right-side 1 9993. po +(\\n[column-length]u + \\n[column-gap]u) 9994. rt 9995. \@} 9996.. 9997. 9998@endExample 9999@Example 10000.pl 1.5i 10001.ll 4i 10002This is a small test which shows how the 10003rt request works in combination with mk. 10004 10005.2c 10006Starting here, text is typeset in two columns. 10007Note that this implementation isn't robust 10008and thus not suited for a real two-column 10009macro. 10010@endExample 10011 10012Result: 10013 10014@Example 10015This is a small test which shows how the 10016rt request works in combination with mk. 10017 10018Starting here, isn't robust 10019text is typeset and thus not 10020in two columns. suited for a 10021Note that this real two-column 10022implementation macro. 10023@endExample 10024@endDefreq 10025 10026The following escapes give fine control of movements about the page. 10027 10028@Defesc {\\v, ', e, '} 10029@cindex vertical motion (@code{\v}) 10030@cindex motion, vertical (@code{\v}) 10031Move vertically, usually from the current location on the page (if no 10032absolute position operator @samp{|} is used). The 10033argument@w{ }@var{e} specifies the distance to move; positive is 10034downwards and negative upwards. The default scaling indicator for this 10035escape is @samp{v}. Beware, however, that @code{gtroff} continues text 10036processing at the point where the motion ends, so you should always 10037balance motions to avoid interference with text processing. 10038 10039@code{\v} doesn't trigger a trap. This can be quite useful; for example, 10040consider a page bottom trap macro which prints a marker in the margin to 10041indicate continuation of a footnote or something similar. 10042@endDefesc 10043 10044There are some special-case escapes for vertical motion. 10045 10046@Defesc {\\r, , , } 10047Move upwards@w{ }1@dmn{v}. 10048@endDefesc 10049 10050@Defesc {\\u, , , } 10051Move upwards@w{ }.5@dmn{v}. 10052@endDefesc 10053 10054@Defesc {\\d, , , } 10055Move down@w{ }.5@dmn{v}. 10056@endDefesc 10057 10058@Defesc {\\h, ', e, '} 10059@cindex inserting horizontal space (@code{\h}) 10060@cindex horizontal space (@code{\h}) 10061@cindex space, horizontal (@code{\h}) 10062@cindex horizontal motion (@code{\h}) 10063@cindex motion, horizontal (@code{\h}) 10064Move horizontally, usually from the current location (if no absolute 10065position operator @samp{|} is used). The expression@w{ }@var{e} 10066indicates how far to move: positive is rightwards and negative 10067leftwards. The default scaling indicator for this escape is @samp{m}. 10068@endDefesc 10069 10070There are a number of special-case escapes for horizontal motion. 10071 10072@Defesc {\\@key{SP}, , , } 10073@cindex space, unbreakable 10074@cindex unbreakable space 10075An unbreakable and unpaddable (i.e.@: not expanded during filling) 10076space. (Note: This is a backslash followed by a space.) 10077@endDefesc 10078 10079@Defesc {\\~, , , } 10080An unbreakable space that stretches like a normal inter-word space 10081when a line is adjusted. 10082@endDefesc 10083 10084@Defesc {\\|, , , } 10085A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to 10086zero). 10087@endDefesc 10088 10089@Defesc {\\^, , , } 10090A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to 10091zero). 10092@endDefesc 10093 10094@Defesc {\\0, , , } 10095@cindex space, width of a digit (@code{\0}) 10096@cindex digit width space (@code{\0}) 10097A space the size of a digit. 10098@endDefesc 10099 10100The following string sets the @TeX{} logo: 10101 10102@Example 10103.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 10104@endExample 10105 10106@DefescList {\\w, ', text, '} 10107@DefregItem {st} 10108@DefregItem {sb} 10109@DefregItem {rst} 10110@DefregItem {rsb} 10111@DefregItem {ct} 10112@DefregItem {ssc} 10113@DefregListEnd {skw} 10114@cindex width escape (@code{\w}) 10115Return the width of the specified @var{text} in basic units. 10116This allows horizontal movement based on the width of some 10117arbitrary text (e.g.@: given as an argument to a macro). 10118 10119@Example 10120The length of the string `abc' is \w'abc'u. 10121 @result{} The length of the string `abc' is 72u. 10122@endExample 10123 10124Font changes may occur in @var{text} which don't affect current 10125settings. 10126 10127After use, @code{\w} sets several registers: 10128 10129@table @code 10130@item st 10131@itemx sb 10132The highest and lowest point of the baseline, respectively, in @var{text}. 10133 10134@item rst 10135@itemx rsb 10136Like the @code{st} and @code{sb} registers, but takes account of the 10137heights and depths of glyphs. With other words, this gives the 10138highest and lowest point of @var{text}. 10139 10140@item ct 10141Defines the kinds of glyphs occurring in @var{text}: 10142 10143@table @asis 10144@item 0 10145only short glyphs, no descenders or tall glyphs. 10146 10147@item 1 10148at least one descender. 10149 10150@item 2 10151at least one tall glyph. 10152 10153@item 3 10154at least one each of a descender and a tall glyph. 10155@end table 10156 10157@item ssc 10158The amount of horizontal space (possibly negative) that should be added 10159to the last glyph before a subscript. 10160 10161@item skw 10162How far to right of the center of the last glyph in the @code{\w} 10163argument, the center of an accent from a roman font should be placed 10164over that glyph. 10165@end table 10166@endDefesc 10167 10168@DefescList {\\k, , p, } 10169@DefescItem {\\k, @lparen{}, ps, } 10170@DefescListEnd {\\k, @lbrack{}, position, @rbrack} 10171@cindex saving horizontal input line position (@code{\k}) 10172@cindex horizontal input line position, saving (@code{\k}) 10173@cindex input line position, horizontal, saving (@code{\k}) 10174@cindex position, horizontal input line, saving (@code{\k}) 10175@cindex line, input, horizontal position, saving (@code{\k}) 10176Store the current horizontal position in the @emph{input} line in 10177number register with name @var{position} (one-character name@w{ }@var{p}, 10178two-character name @var{ps}). Use this, for example, to return to the 10179beginning of a string for highlighting or other decoration. 10180@endDefesc 10181 10182@Defreg {hp} 10183@cindex horizontal input line position register (@code{hp}) 10184@cindex input line, horizontal position, register (@code{hp}) 10185@cindex position, horizontal, in input line, register (@code{hp}) 10186@cindex line, input, horizontal position, register (@code{hp}) 10187The current horizontal position at the input line. 10188@endDefreg 10189 10190@Defreg {.k} 10191@cindex horizontal output line position register (@code{.k}) 10192@cindex output line, horizontal position, register (@code{.k}) 10193@cindex position, horizontal, in output line, register (@code{.k}) 10194@cindex line, output, horizontal position, register (@code{.k}) 10195A read-only number register containing the current horizontal output 10196position. 10197@endDefreg 10198 10199@Defesc {\\o, ', @Var{a}@Var{b}@Var{c}, '} 10200@cindex overstriking glyphs (@code{\o}) 10201@cindex glyphs, overstriking (@code{\o}) 10202Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs 10203are centered, and the resulting spacing is the largest width of the 10204affected glyphs. 10205@endDefesc 10206 10207@Defesc {\\z, , g, , } 10208@cindex zero-width printing (@code{\z}, @code{\Z}) 10209@cindex printing, zero-width (@code{\z}, @code{\Z}) 10210Print glyph @var{g} with zero width, i.e., without spacing. Use 10211this to overstrike glyphs left-aligned. 10212@endDefesc 10213 10214@Defesc {\\Z, ', anything, '} 10215@cindex zero-width printing (@code{\z}, @code{\Z}) 10216@cindex printing, zero-width (@code{\z}, @code{\Z}) 10217Print @var{anything}, then restore the horizontal and vertical position. 10218The argument may not contain tabs or leaders. 10219 10220The following is an example of a strike-through macro: 10221 10222@Example 10223.de ST 10224.nr ww \w'\\$1' 10225\Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1 10226.. 10227. 10228This is 10229.ST "a test" 10230an actual emergency! 10231@endExample 10232@endDefesc 10233 10234 10235@c ===================================================================== 10236 10237@node Drawing Requests, Traps, Page Motions, gtroff Reference 10238@section Drawing Requests 10239@cindex drawing requests 10240@cindex requests for drawing 10241 10242@code{gtroff} provides a number of ways to draw lines and other figures 10243on the page. Used in combination with the page motion commands (see 10244@ref{Page Motions}, for more info), a wide variety of figures can be 10245drawn. However, for complex drawings these operations can be quite 10246cumbersome, and it may be wise to use graphic preprocessors like 10247@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 10248information. 10249 10250All drawing is done via escapes. 10251 10252@DefescList {\\l, ', @Var{l}, '} 10253@DefescListEnd {\\l, ', @Var{l}@Var{g}, '} 10254@cindex drawing horizontal lines (@code{\l}) 10255@cindex horizontal line, drawing (@code{\l}) 10256@cindex line, horizontal, drawing (@code{\l}) 10257Draw a line horizontally. @var{l} is the length of the line to be 10258drawn. If it is positive, start the line at the current location and 10259draw to the right; its end point is the new current location. Negative 10260values are handled differently: The line starts at the current location 10261and draws to the left, but the current location doesn't move. 10262 10263@var{l} can also be specified absolutely (i.e.@: with a leading 10264@samp{|}) which draws back to the beginning of the input line. 10265Default scaling indicator is @samp{m}. 10266 10267@cindex underscore glyph (@code{\[ru]}) 10268@cindex glyph, underscore (@code{\[ru]}) 10269@cindex line drawing glyph 10270@cindex glyph, for line drawing 10271The optional second parameter@w{ }@var{g} is a glyph to draw the line 10272with. If this second argument is not specified, @code{gtroff} uses 10273the underscore glyph, @code{\[ru]}. 10274 10275@cindex zero width space character (@code{\&}) 10276@cindex character, zero width space (@code{\&}) 10277@cindex space character, zero width (@code{\&}) 10278To separate the two arguments (to prevent @code{gtroff} from 10279interpreting a drawing glyph as a scaling indicator if the glyph is 10280represented by a single character) use @code{\&}. 10281 10282Here a small useful example: 10283 10284@Example 10285.de box 10286\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' 10287.. 10288@endExample 10289 10290@noindent 10291Note that this works by outputting a box rule (a vertical line), then 10292the text given as an argument and then another box rule. Finally, the 10293line drawing escapes both draw from the current location to the 10294beginning of the @emph{input} line -- this works because the line 10295length is negative, not moving the current point. 10296@endDefesc 10297 10298@DefescList {\\L, ', @Var{l}, '} 10299@DefescListEnd {\\L, ', @Var{l}@Var{g}, '} 10300@cindex drawing vertical lines (@code{\L}) 10301@cindex vertical line drawing (@code{\L}) 10302@cindex line, vertical, drawing (@code{\L}) 10303@cindex line drawing glyph 10304@cindex glyph for line drawing 10305@cindex box rule glyph (@code{\[br]}) 10306@cindex glyph, box rule (@code{\[br]}) 10307Draw vertical lines. Its parameters are 10308similar to the @code{\l} escape, except that the default scaling 10309indicator is @samp{v}. The movement is downwards for positive values, 10310and upwards for negative values. The default glyph is the box rule 10311glyph, @code{\[br]}. As with the vertical motion escapes, text 10312processing blindly continues where the line ends. 10313 10314@Example 10315This is a \L'3v'test. 10316@endExample 10317 10318@noindent 10319Here the result, produced with @code{grotty}. 10320 10321@Example 10322This is a 10323 | 10324 | 10325 |test. 10326@endExample 10327@endDefesc 10328 10329@Defesc {\\D, ', command arg @dots{}, '} 10330The @code{\D} escape provides a variety of drawing functions. 10331Note that on character devices, only vertical and horizontal lines are 10332supported within @code{grotty}; other devices may only support a subset 10333of the available drawing functions. 10334 10335The default scaling indicator for all subcommands of @code{\D} is 10336@samp{m} for horizontal distances and @samp{v} for vertical ones. 10337Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}} 10338which use @code{u} as the default. 10339 10340@table @code 10341@item \D'l @var{dx} @var{dy}' 10342@cindex line, drawing (@w{@code{\D'l @dots{}'}}) 10343@cindex drawing a line (@w{@code{\D'l @dots{}'}}) 10344Draw a line from the current location to the relative point specified by 10345(@var{dx},@var{dy}). 10346 10347The following example is a macro for creating a box around a text string; 10348for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}. 10349 10350@Example 10351.de BOX 10352. nr @@wd \w'\\$1' 10353\h'.2m'\ 10354\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 10355\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ 10356\D'l (\\n[@@wd]u + .4m) 0'\ 10357\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ 10358\D'l -(\\n[@@wd]u + .4m) 0'\ 10359\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 10360\\$1\ 10361\h'.2m' 10362.. 10363@endExample 10364 10365@noindent 10366First, the width of the string is stored in register @code{@@wd}. Then, 10367four lines are drawn to form a box, properly offset by the box margin. 10368The registers @code{rst} and @code{rsb} are set by the @code{\w} escape, 10369containing the largest height and depth of the whole string. 10370 10371@item \D'c @var{d}' 10372@cindex circle, drawing (@w{@code{\D'c @dots{}'}}) 10373@cindex drawing a circle (@w{@code{\D'c @dots{}'}}) 10374Draw a circle with a diameter of@w{ }@var{d} with the leftmost point at the 10375current position. 10376 10377@item \D'C @var{d}' 10378@cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}}) 10379@cindex drawing a solid circle (@w{@code{\D'C @dots{}'}}) 10380@cindex solid circle, drawing (@w{@code{\D'C @dots{}'}}) 10381Draw a solid circle with the same parameters as an outlined circle. No 10382outline is drawn. 10383 10384@item \D'e @var{x} @var{y}' 10385@cindex drawing an ellipse (@w{@code{\D'e @dots{}'}}) 10386@cindex ellipse, drawing (@w{@code{\D'e @dots{}'}}) 10387Draw an ellipse with a horizontal diameter of @var{x} and a vertical 10388diameter of @var{y} with the leftmost point at the current position. 10389 10390@item \D'E @var{x} @var{y}' 10391@cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}}) 10392@cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}}) 10393@cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}}) 10394Draw a solid ellipse with the same parameters as an outlined ellipse. 10395No outline is drawn. 10396 10397@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 10398@cindex arc, drawing (@w{@code{\D'a @dots{}'}}) 10399@cindex drawing an arc (@w{@code{\D'a @dots{}'}}) 10400Draw an arc clockwise from the current location through the two 10401specified relative locations (@var{dx1},@var{dy1}) and 10402(@var{dx2},@var{dy2}). The coordinates of the first point are relative 10403to the current position, and the coordinates of the second point are 10404relative to the first point. 10405 10406@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 10407@cindex drawing a spline (@w{@code{\D'~ @dots{}'}}) 10408@cindex spline, drawing (@w{@code{\D'~ @dots{}'}}) 10409Draw a spline from the current location to the relative point 10410(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on. 10411 10412@item \D'f @var{n}' 10413@cindex gray shading (@w{@code{\D'f @dots{}'}}) 10414@cindex shading filled objects (@w{@code{\D'f @dots{}'}}) 10415Set the shade of gray to be used for filling solid objects to@w{ 10416}@var{n}; @var{n}@w{ }must be an integer between 0 and@w{ }1000, where 0 10417corresponds solid white and 1000 to solid black, and values in between 10418correspond to intermediate shades of gray. This applies only to solid 10419circles, solid ellipses, and solid polygons. By default, a level of 104201000 is used. 10421 10422@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 10423@cindex drawing a polygon (@w{@code{\D'p @dots{}'}}) 10424@cindex polygon, drawing (@w{@code{\D'p @dots{}'}}) 10425Draw a polygon from the current location to the relative position 10426(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on. 10427When the specified data points are exhausted, a line is drawn back 10428to the starting point. 10429 10430@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 10431@cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}}) 10432@cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}}) 10433@cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}}) 10434Draw a solid polygon with the same parameters as an outlined polygon. 10435No outline is drawn. 10436 10437Here a better variant of the box macro to fill the box with some color. 10438Note that the box must be drawn before the text since colors in 10439@code{gtroff} are not transparent; the filled polygon would hide the 10440text completely. 10441 10442@Example 10443.de BOX 10444. nr @@wd \w'\\$1' 10445\h'.2m'\ 10446\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 10447\M[lightcyan]\ 10448\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ 10449 (\\n[@@wd]u + .4m) 0 \ 10450 0 (\\n[rst]u - \\n[rsb]u + .4m) \ 10451 -(\\n[@@wd]u + .4m) 0'\ 10452\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 10453\M[]\ 10454\\$1\ 10455\h'.2m' 10456.. 10457@endExample 10458 10459@item \D't @var{n}' 10460@cindex line thickness (@w{@code{\D't @dots{}'}}) 10461@cindex thickness of lines (@w{@code{\D't @dots{}'}}) 10462Set the current line thickness to @var{n}@w{ }machine units. A value of 10463zero selects the smallest available line thickness. A negative value 10464makes the line thickness proportional to the current point size (this is 10465the default behaviour of @acronym{AT&T} @code{troff}). 10466@end table 10467@endDefesc 10468 10469@xref{Graphics Commands}. 10470 10471@Defesc {\\b, ', string, '} 10472@cindex pile, glyph (@code{\b}) 10473@cindex glyph pile (@code{\b}) 10474@cindex stacking glyphs (@code{\b}) 10475@dfn{Pile} a sequence of glyphs vertically, and center it vertically 10476on the current line. Use it to build large brackets and braces. 10477 10478Here an example how to create a large opening brace: 10479 10480@Example 10481\b'\[lt]\[bv]\[lk]\[bv]\[lb]' 10482@endExample 10483 10484@cindex @code{\b}, limitations 10485@cindex limitations of @code{\b} escape 10486The first glyph is on the top, the last glyph in @var{string} is 10487at the bottom. Note that @code{gtroff} separates the glyphs 10488vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m} 10489above the current baseline; the largest glyph width is used as the 10490width for the whole object. This rather unflexible positioning 10491algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary 10492in height for this device. Instead, use the @code{eqn} preprocessor. 10493 10494@xref{Manipulating Spacing}, how to adjust the vertical spacing with 10495the @code{\x} escape. 10496@endDefesc 10497 10498 10499@c ===================================================================== 10500 10501@node Traps, Diversions, Drawing Requests, gtroff Reference 10502@section Traps 10503@cindex traps 10504 10505@dfn{Traps} are locations, which, when reached, call a specified 10506macro. These traps can occur at a given location on the page, at a 10507given location in the current diversion, at a blank line, 10508after a certain number of input lines, or at the end of input. 10509 10510@cindex planting a trap 10511@cindex trap, planting 10512Setting a trap is also called @dfn{planting}. 10513@cindex trap, springing 10514@cindex springing a trap 10515It is also said that a trap is @dfn{sprung} if the associated macro 10516is executed. 10517 10518@menu 10519* Page Location Traps:: 10520* Diversion Traps:: 10521* Input Line Traps:: 10522* Blank Line Traps:: 10523* End-of-input Traps:: 10524@end menu 10525 10526@c --------------------------------------------------------------------- 10527 10528@node Page Location Traps, Diversion Traps, Traps, Traps 10529@subsection Page Location Traps 10530@cindex page location traps 10531@cindex traps, page location 10532 10533@dfn{Page location traps} perform an action when @code{gtroff} 10534reaches or passes a certain vertical location on the page. Page 10535location traps have a variety of purposes, including: 10536 10537@itemize 10538@item 10539setting headers and footers 10540 10541@item 10542setting body text in multiple columns 10543 10544@item 10545setting footnotes 10546@end itemize 10547 10548@DefreqList {vpt, flag} 10549@DefregListEnd {.vpt} 10550@cindex enabling vertical position traps (@code{vpt}) 10551@cindex vertical position traps, enabling (@code{vpt}) 10552@cindex vertical position trap enable register (@code{.vpt}) 10553Enable vertical position traps if @var{flag} is non-zero, or disables 10554them otherwise. Vertical position traps are traps set by the @code{wh} 10555or @code{dt} requests. Traps set by the @code{it} request are not 10556vertical position traps. The parameter that controls whether vertical 10557position traps are enabled is global. Initially vertical position traps 10558are enabled. The current setting of this is available in the 10559@code{.vpt} read-only number register. 10560@endDefreq 10561 10562@Defreq {wh, dist [@Var{macro}]} 10563Set a page location trap. Positive values for @var{dist} set 10564the trap relative to the top of the page; negative values set 10565the trap relative to the bottom of the page. Default scaling 10566indicator is @samp{v}. 10567 10568@var{macro} is the name of the macro to execute when the 10569trap is sprung. If @var{macro} is missing, remove the first trap 10570(if any) at @var{dist}. 10571 10572@cindex page headers 10573@cindex page footers 10574@cindex headers 10575@cindex footers 10576The following is a simple example of how many macro packages 10577set headers and footers. 10578 10579@Example 10580.de hd \" Page header 10581' sp .5i 10582. tl 'Title''date' 10583' sp .3i 10584.. 10585. 10586.de fo \" Page footer 10587' sp 1v 10588. tl ''%'' 10589' bp 10590.. 10591. 10592.wh 0 hd \" trap at top of the page 10593.wh -1i fo \" trap one inch from bottom 10594@endExample 10595 10596A trap at or below the bottom of the page is ignored; it can be made 10597active by either moving it up or increasing the page length so that the 10598trap is on the page. 10599 10600It is possible to have more than one trap at the same location; to do so, 10601the traps must be defined at different locations, then moved together with 10602the @code{ch} request; otherwise the second trap would replace the first 10603one. Earlier defined traps hide later defined traps if moved to the same 10604position (the many empty lines caused by the @code{bp} request are omitted): 10605 10606@Example 10607.de a 10608. nop a 10609.. 10610.de b 10611. nop b 10612.. 10613.de c 10614. nop c 10615.. 10616. 10617.wh 1i a 10618.wh 2i b 10619.wh 3i c 10620.bp 10621 @result{} a b c 10622@endExample 10623@Example 10624.ch b 1i 10625.ch c 1i 10626.bp 10627 @result{} a 10628@endExample 10629@Example 10630.ch a 0.5i 10631.bp 10632 @result{} a b 10633@endExample 10634@endDefreq 10635 10636@Defreg {.t} 10637@cindex distance to next trap register (@code{.t}) 10638@cindex trap, distance, register (@code{.t}) 10639A read-only number register holding the distance to the next trap. 10640 10641If there are no traps between the current position and the bottom of the 10642page, it contains the distance to the page bottom. In a diversion, the 10643distance to the page bottom is infinite (the returned value is the biggest 10644integer which can be represented in @code{groff}) if there are no diversion 10645traps. 10646@endDefreg 10647 10648@Defreq {ch, macro dist} 10649@cindex changing trap location (@code{ch}) 10650@cindex trap, changing location (@code{ch}) 10651Change the location of a trap. 10652The first argument is the name of the macro to be invoked at 10653the trap, and the second argument is the new location for the trap 10654(note that the parameters are specified the opposite of the @code{wh} 10655request). This is useful for building up footnotes in a diversion to 10656allow more space at the bottom of the page for them. 10657 10658Default scaling indicator for @var{dist} is @samp{v}. If @var{dist} 10659is missing, the trap is removed. 10660 10661@c XXX 10662 10663@ignore 10664@Example 10665... (simplified) footnote example ... 10666@endExample 10667@end ignore 10668@endDefreq 10669 10670@Defreg {.ne} 10671The read-only number register @code{.ne} contains the amount of space 10672that was needed in the last @code{ne} request that caused a trap to be 10673sprung. Useful in conjunction with the @code{.trunc} register. 10674@xref{Page Control}, for more information. 10675@endDefreg 10676 10677@Defreg {.trunc} 10678@cindex @code{ne} request, and the @code{.trunc} register 10679@cindex truncated vertical space register (@code{.trunc}) 10680A read-only register containing the amount of vertical space truncated 10681by the most recently sprung vertical position trap, or, if the trap was 10682sprung by an @code{ne} request, minus the amount of vertical motion 10683produced by the @code{ne} request. In other words, at the point a trap 10684is sprung, it represents the difference of what the vertical position 10685would have been but for the trap, and what the vertical position 10686actually is. 10687@endDefreg 10688 10689@c --------------------------------------------------------------------- 10690 10691@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 10692@subsection Diversion Traps 10693@cindex diversion traps 10694@cindex traps, diversion 10695 10696@Defreq {dt, dist macro} 10697@cindex @code{.t} register, and diversions 10698@cindex setting diversion trap (@code{dt}) 10699@cindex diversion trap, setting (@code{dt}) 10700@cindex trap, diversion, setting (@code{dt}) 10701Set a trap @emph{within} a diversion. 10702@var{dist} is the location of the trap 10703(identical to the @code{.wh} request; default scaling indicator is 10704@samp{v}) and @var{macro} is the name of the macro to be invoked. The 10705number register @code{.t} still works within diversions. 10706@xref{Diversions}, for more information. 10707@endDefreq 10708 10709@c --------------------------------------------------------------------- 10710 10711@node Input Line Traps, Blank Line Traps, Diversion Traps, Traps 10712@subsection Input Line Traps 10713@cindex input line traps 10714@cindex traps, input line 10715 10716@DefreqList {it, n macro} 10717@DefreqItem {itc, n macro} 10718@cindex setting input line trap (@code{it}) 10719@cindex input line trap, setting (@code{it}) 10720@cindex trap, input line, setting (@code{it}) 10721Set an input line trap. 10722@var{n}@w{ }is the number of lines of input which may be read before 10723springing the trap, @var{macro} is the macro to be invoked. 10724Request lines are not counted as input lines. 10725 10726For example, one possible use is to have a macro which prints the 10727next @var{n}@w{ }lines in a bold font. 10728 10729@Example 10730.de B 10731. it \\$1 B-end 10732. ft B 10733.. 10734. 10735.de B-end 10736. ft R 10737.. 10738@endExample 10739 10740@cindex input line traps and interrupted lines (@code{itc}) 10741@cindex interrupted lines and input line traps (@code{itc}) 10742@cindex traps, input line, and interrupted lines (@code{itc}) 10743@cindex lines, interrupted, and input line traps (@code{itc}) 10744The @code{itc} request is identical, 10745except that a line interrupted with @code{\c} 10746counts as one input line. 10747 10748Both requests are associated with the current environment 10749(@pxref{Environments}); switching to another environment disables the 10750current input trap, and going back reactivates it, restoring the number 10751of already processed lines. 10752@endDefreq 10753 10754@c --------------------------------------------------------------------- 10755 10756@node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps 10757@subsection Blank Line Traps 10758@cindex blank line traps 10759@cindex traps, blank line 10760 10761@Defreq {blm, macro} 10762@cindex blank line macro (@code{blm}) 10763Set a blank line trap. 10764@code{gtroff} executes @var{macro} when it encounters a blank line in 10765the input file. 10766@endDefreq 10767 10768@c --------------------------------------------------------------------- 10769 10770@node End-of-input Traps, , Blank Line Traps, Traps 10771@subsection End-of-input Traps 10772@cindex end-of-input traps 10773@cindex traps, end-of-input 10774 10775@Defreq {em, macro} 10776@cindex setting end-of-input trap (@code{em}) 10777@cindex end-of-input trap, setting (@code{em}) 10778@cindex trap, end-of-input, setting (@code{em}) 10779@cindex end-of-input macro (@code{em}) 10780@cindex macro, end-of-input (@code{em}) 10781Set a trap at the end of input. @var{macro} is executed after the 10782last line of the input file has been processed. 10783 10784For example, if the document had to have a section at the bottom of the 10785last page for someone to approve it, the @code{em} request could be 10786used. 10787 10788@Example 10789.de approval 10790. ne 5v 10791. sp |(\\n[.t] - 6v) 10792. in +4i 10793. lc _ 10794. br 10795Approved:\t\a 10796. sp 10797Date:\t\t\a 10798.. 10799. 10800.em approval 10801@endExample 10802@endDefreq 10803 10804 10805@c ===================================================================== 10806 10807@node Diversions, Environments, Traps, gtroff Reference 10808@section Diversions 10809@cindex diversions 10810 10811In @code{gtroff} it is possible to @dfn{divert} text into a named 10812storage area. Due to the similarity to defining macros it is sometimes 10813said to be stored in a macro. This is used for saving text for output 10814at a later time, which is useful for keeping blocks of text on the same 10815page, footnotes, tables of contents, and indices. 10816 10817@cindex top-level diversion 10818@cindex diversion, top-level 10819For orthogonality it is said that @code{gtroff} is in the @dfn{top-level 10820diversion} if no diversion is active (i.e., the data is diverted to the 10821output device). 10822 10823@DefreqList {di, macro} 10824@DefreqListEnd {da, macro} 10825@cindex beginning diversion (@code{di}) 10826@cindex diversion, beginning (@code{di}) 10827@cindex ending diversion (@code{di}) 10828@cindex diversion, ending (@code{di}) 10829@cindex appending to a diversion (@code{da}) 10830@cindex diversion, appending (@code{da}) 10831Begin a diversion. Like the @code{de} 10832request, it takes an argument of a macro name to divert subsequent text 10833into. The @code{da} macro appends to an existing diversion. 10834 10835@code{di} or @code{da} without an argument ends the diversion. 10836@endDefreq 10837 10838@DefreqList {box, macro} 10839@DefreqListEnd {boxa, macro} 10840Begin (or appends to) a diversion like the 10841@code{di} and @code{da} requests. 10842The difference is that @code{box} and @code{boxa} 10843do not include a partially-filled line in the diversion. 10844 10845Compare this: 10846 10847@Example 10848Before the box. 10849.box xxx 10850In the box. 10851.br 10852.box 10853After the box. 10854.br 10855 @result{} Before the box. After the box. 10856.xxx 10857 @result{} In the box. 10858@endExample 10859 10860@noindent 10861with this: 10862 10863@Example 10864Before the diversion. 10865.di yyy 10866In the diversion. 10867.br 10868.di 10869After the diversion. 10870.br 10871 @result{} After the diversion. 10872.yyy 10873 @result{} Before the diversion. In the diversion. 10874@endExample 10875 10876@code{box} or @code{boxa} without an argument ends the diversion. 10877@endDefreq 10878 10879@DefregList {.z} 10880@DefregListEnd {.d} 10881@cindex @code{nl} register, and @code{.d} 10882@cindex nested diversions 10883@cindex diversion, nested 10884@cindex diversion name register (@code{.z}) 10885@cindex vertical position in diversion register (@code{.d}) 10886@cindex position, vertical, in diversion, register (@code{.d}) 10887@cindex diversion, vertical position in, register (@code{.d}) 10888Diversions may be nested. The read-only number register @code{.z} 10889contains the name of the current diversion (this is a string-valued 10890register). The read-only number register @code{.d} contains the current 10891vertical place in the diversion. If not in a diversion it is the same 10892as the register @code{nl}. 10893@endDefreg 10894 10895@Defreg {.h} 10896@cindex high-water mark register (@code{.h}) 10897@cindex mark, high-water, register (@code{.h}) 10898@cindex position of lowest text line (@code{.h}) 10899@cindex text line, position of lowest (@code{.h}) 10900The @dfn{high-water mark} on the current page. It corresponds to the 10901text baseline of the lowest line on the page. This is a read-only 10902register. 10903 10904@Example 10905.tm .h==\n[.h], nl==\n[nl] 10906 @result{} .h==0, nl==-1 10907This is a test. 10908.br 10909.sp 2 10910.tm .h==\n[.h], nl==\n[nl] 10911 @result{} .h==40, nl==120 10912@endExample 10913 10914@cindex @code{.h} register, difference to @code{nl} 10915@cindex @code{nl} register, difference to @code{.h} 10916@noindent 10917As can be seen in the previous example, empty lines are not considered 10918in the return value of the @code{.h} register. 10919@endDefreg 10920 10921@DefregList {dn} 10922@DefregListEnd {dl} 10923After completing a diversion, the read-write number registers @code{dn} 10924and @code{dl} contain the vertical and horizontal size of the diversion. 10925 10926@Example 10927.\" Center text both horizontally & vertically 10928. 10929.\" Enclose macro definitions in .eo and .ec 10930.\" to avoid the doubling of the backslash 10931.eo 10932.\" macro .(c starts centering mode 10933.de (c 10934. br 10935. ev (c 10936. evc 0 10937. in 0 10938. nf 10939. di @@c 10940.. 10941@endExample 10942@Example 10943.\" macro .)c terminates centering mode 10944.de )c 10945. br 10946. ev 10947. di 10948. nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v) 10949. sp \n[@@s]u 10950. ce 1000 10951. @@c 10952. ce 0 10953. sp \n[@@s]u 10954. br 10955. fi 10956. rr @@s 10957. rm @@s 10958. rm @@c 10959.. 10960.\" End of macro definitions, restore escape mechanism 10961.ec 10962@endExample 10963@endDefreg 10964 10965@DefescList {\\!, , , } 10966@DefescListEnd {\\?, , @Var{anything}, \\?} 10967@cindex transparent output (@code{\!}, @code{\?}) 10968@cindex output, transparent (@code{\!}, @code{\?}) 10969Prevent requests, macros, and escapes from being 10970interpreted when read into a diversion. This takes the given text 10971and @dfn{transparently} embeds it into the diversion. This is useful for 10972macros which shouldn't be invoked until the diverted text is actually 10973output. 10974 10975The @code{\!} escape transparently embeds text up to 10976and including the end of the line. 10977The @code{\?} escape transparently embeds text until the next 10978occurrence of the @code{\?} escape. For example: 10979 10980@Example 10981\?@var{anything}\? 10982@endExample 10983 10984@noindent 10985@var{anything} may not contain newlines; use @code{\!} to embed 10986newlines in a diversion. The escape sequence @code{\?} is also 10987recognized in copy mode and turned into a single internal code; it is 10988this code that terminates @var{anything}. Thus the following example 10989prints@w{ }4. 10990 10991@Example 10992.nr x 1 10993.nf 10994.di d 10995\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 10996.di 10997.nr x 2 10998.di e 10999.d 11000.di 11001.nr x 3 11002.di f 11003.e 11004.di 11005.nr x 4 11006.f 11007@endExample 11008 11009Both escapes read the data in copy mode. 11010 11011@cindex @code{\!}, in top-level diversion 11012@cindex top-level diversion, and @code{\!} 11013@cindex diversion, top-level, and @code{\!} 11014If @code{\!} is used in the top-level diversion, its argument is 11015directly embedded into the @code{gtroff} intermediate output. This can 11016be used for example to control a postprocessor which processes the data 11017before it is sent to the device driver. 11018 11019@cindex @code{\?}, in top-level diversion 11020@cindex top-level diversion, and @code{\?} 11021@cindex diversion, top-level, and @code{\?} 11022The @code{\?} escape used in the top-level diversion produces no output 11023at all; its argument is simply ignored. 11024@endDefesc 11025 11026@cindex @code{\!}, and @code{output} 11027@cindex @code{output} request, and @code{\!} 11028@Defreq {output, string} 11029Emit @var{string} directly to the @code{gtroff} intermediate output 11030(subject to copy-mode interpretation); this is similar to @code{\!} used 11031at the top level. An initial double quote in @var{string} is stripped off 11032to allow initial blanks. 11033 11034This request can't be used before the first page has started -- if you get 11035an error, simply insert @code{.br} before the @code{output} request. 11036 11037Without argument, @code{output} is ignored. 11038 11039Use with caution! It is normally only needed for mark-up used by a 11040postprocessor which does something with the output before sending it to 11041the output device, filtering out @code{string} again. 11042@endDefreq 11043 11044@Defreq {asciify, div} 11045@cindex unformatting diversions (@code{asciify}) 11046@cindex diversion, unformatting (@code{asciify}) 11047@cindex @code{trin} request, and @code{asciify} 11048@dfn{Unformat} the diversion specified by @var{div} 11049in such a way that @acronym{ASCII} characters, characters translated with 11050the @code{trin} request, space characters, and some escape sequences that 11051were formatted and diverted are treated like ordinary input 11052characters when the diversion is reread. It can be also used for gross 11053hacks; for example, the following sets register@w{ }@code{n} to@w{ }1. 11054 11055@Example 11056.tr @@. 11057.di x 11058@@nr n 1 11059.br 11060.di 11061.tr @@@@ 11062.asciify x 11063.x 11064@endExample 11065 11066@xref{Copy-in Mode}. 11067@endDefreq 11068 11069@Defreq {unformat, div} 11070Like @code{asciify}, unformat the specified diversion. 11071However, @code{unformat} only unformats spaces and tabs 11072between words. 11073Unformatted tabs are treated as input tokens, 11074and spaces are stretchable again. 11075 11076The vertical size of lines is not preserved; glyph information (font, 11077font size, space width, etc.)@: is retained. 11078@endDefreq 11079 11080 11081@c ===================================================================== 11082 11083@node Environments, Suppressing output, Diversions, gtroff Reference 11084@section Environments 11085@cindex environments 11086 11087It happens frequently that some text should be printed in a certain 11088format regardless of what may be in effect at the time, for example, in 11089a trap invoked macro to print headers and footers. To solve this 11090@code{gtroff} processes text in @dfn{environments}. An 11091environment contains most of the parameters that control text 11092processing. It is possible to switch amongst these environments; by 11093default @code{gtroff} processes text in environment@w{ }0. The 11094following is the information kept in an environment. 11095 11096@itemize @bullet 11097@item 11098font parameters (size, family, style, glyph height and slant, space 11099and sentence space size) 11100 11101@item 11102page parameters (line length, title length, vertical spacing, 11103line spacing, indentation, line numbering, centering, right-justifying, 11104underlining, hyphenation data) 11105 11106@item 11107fill and adjust mode 11108 11109@item 11110tab stops, tab and leader characters, escape character, 11111no-break and hyphen indicators, margin character data 11112 11113@item 11114partially collected lines 11115 11116@item 11117input traps 11118 11119@item 11120drawing and fill colours 11121@end itemize 11122 11123These environments may be given arbitrary names (see @ref{Identifiers}, 11124for more info). Old versions of @code{troff} only had environments 11125named @samp{0}, @samp{1}, and @samp{2}. 11126 11127@DefreqList {ev, [@Var{env}]} 11128@DefregListEnd {.ev} 11129@cindex switching environments (@code{ev}) 11130@cindex environment, switching (@code{ev}) 11131@cindex environment number/name register (@code{.ev}) 11132Switch to another environment. The argument @var{env} is the name of 11133the environment to switch to. With no argument, @code{gtroff} switches 11134back to the previous environment. There is no limit on the number of 11135named environments; they are created the first time that they are 11136referenced. The @code{.ev} read-only register contains the name or 11137number of the current environment. This is a string-valued register. 11138 11139Note that a call to @code{ev} (with argument) pushes the previously 11140active environment onto a stack. If, say, environments @samp{foo}, 11141@samp{bar}, and @samp{zap} are called (in that order), the first 11142@code{ev} request without parameter switches back to environment 11143@samp{bar} (which is popped off the stack), and a second call 11144switches back to environment @samp{foo}. 11145 11146Here is an example: 11147 11148@Example 11149.ev footnote-env 11150.fam N 11151.ps 6 11152.vs 8 11153.ll -.5i 11154.ev 11155 11156... 11157 11158.ev footnote-env 11159\(dg Note the large, friendly letters. 11160.ev 11161@endExample 11162@endDefreq 11163 11164@Defreq {evc, env} 11165@cindex copying environment (@code{evc}) 11166@cindex environment, copying (@code{evc}) 11167Copy the environment @var{env} into the current environment. 11168 11169The following environment data is not copied: 11170 11171@itemize @bullet 11172@item 11173Partially filled lines. 11174 11175@item 11176The status whether the previous line was interrupted. 11177 11178@item 11179The number of lines still to center, or to right-justify, or to underline 11180(with or without underlined spaces); they are set to zero. 11181 11182@item 11183The status whether a temporary indent is active. 11184 11185@item 11186Input traps and its associated data. 11187 11188@item 11189Line numbering mode is disabled; it can be reactivated with 11190@w{@samp{.nm +0}}. 11191 11192@item 11193The number of consecutive hyphenated lines (set to zero). 11194@end itemize 11195@endDefreq 11196 11197@DefregList {.cht} 11198@DefregItem {.cdp} 11199@DefregListEnd {.csk} 11200@cindex environment, last glyph 11201The @code{\n[.cht]} register contains the 11202maximum extent (above the baseline) 11203of the last glyph added to the current environment. 11204 11205The @code{\n[.cdp]} register contains the 11206maximum extent (below the baseline) 11207of the last glyph added to the current environment. 11208 11209The @code{\n[.csk]} register contains the 11210@dfn{skew} (how far to the right of the glyph's center 11211that @code{gtroff} shold place an accent) 11212of the last glyph added to the current environment. 11213@endDefreg 11214 11215 11216@c ===================================================================== 11217 11218@node Suppressing output, Colors, Environments, gtroff Reference 11219@section Suppressing output 11220 11221@Defesc {\\O, , num, } 11222@cindex suppressing output (@code{\O}) 11223@cindex output, suppressing (@code{\O}) 11224Disable or enable output depending on the value of @var{num}: 11225 11226@table @samp 11227@item \O0 11228Disable any glyphs from being emitted to the device driver, provided that 11229the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}). 11230Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}. 11231 11232@item \O1 11233Enable output of glyphs, provided that the escape occurs at the outer 11234level. 11235@end table 11236 11237@vindex opminx 11238@vindex opminy 11239@vindex opmaxx 11240@vindex opmaxy 11241@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 11242@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 11243@xref{Register Index}. These four registers mark the top left and 11244bottom right hand corners of a box which encompasses all written glyphs. 11245 11246For example the input text: 11247 11248@Example 11249Hello \O[0]world \O[1]this is a test. 11250@endExample 11251 11252@noindent 11253produces the following output: 11254 11255@Example 11256Hello this is a test. 11257@endExample 11258 11259@table @samp 11260@item \O2 11261Provided that the escape occurs at the outer level, enable output of 11262glyphs and also write out to @code{stderr} the page number and four 11263registers encompassing the glyphs previously written since the last call 11264to @code{\O}. 11265 11266@item \O3 11267Begin a nesting level. At start-up, @code{gtroff} is at outer level. 11268 11269@item \O4 11270End a nesting level. 11271 11272@item \O[5@var{P}@var{filename}] 11273This escape is @code{grohtml} specific. Provided that this escape 11274occurs at the outer nesting level write the @code{filename} to 11275@code{stderr}. The position of the image, @var{P}, must be specified 11276and must be one of @code{l}, @code{r}, @code{c}, or@w{ }@code{i} (left, 11277right, centered, inline). @var{filename} will be associated with the 11278production of the next inline image. 11279@end table 11280@endDefesc 11281 11282@c ===================================================================== 11283 11284@node Colors, I/O, Suppressing output, gtroff Reference 11285@section Colors 11286@cindex colors 11287 11288@DefreqList {color, [@Var{n}]} 11289@DefregListEnd {.color} 11290If @var{n} is missing or non-zero, activate colors (this is the default); 11291otherwise, turn it off. 11292 11293The read-only number register @code{.color} is@w{ }1 if colors are active, 112940@w{ }otherwise. 11295 11296Internally, @code{color} sets a global flag; it does not produce a token. 11297Similar to the @code{cp} request, you should use it at the beginning of 11298your document to control color output. 11299 11300Colors can be also turned off with the @option{-c} command line option. 11301@endDefreq 11302 11303@Defreq {defcolor, ident scheme color_components} 11304Define color with name @var{ident}. @var{scheme} can be one of the 11305following values: @code{rgb} (three components), @code{cym} (three 11306components), @code{cmyk} (four components), and @code{gray} or 11307@code{grey} (one component). 11308 11309@cindex default color 11310@cindex color, default 11311Color components can be given either as a hexadecimal string or as 11312positive decimal integers in the range 0--65535. A hexadecimal string 11313contains all color components concatenated. It must start with either 11314@code{#} or @code{##}; the former specifies hex values in the range 113150--255 (which are internally multiplied by@w{ }257), the latter in the 11316range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff} 11317(magenta). The default color name @c{default} can't be redefined; its 11318value is device-specific (usually black). It is possible that the 11319default color for @code{\m} and @code{\M} is not identical. 11320 11321@cindex @code{f} unit, and colors 11322@cindex unit, @code{f}, and colors 11323A new scaling indicator@w{ }@code{f} has been introduced which multiplies 11324its value by 65536; this makes it convenient to specify color components 11325as fractions in the range 0 to@w{ }1 (1f equals 65536u). Example: 11326 11327@Example 11328.defcolor darkgreen rgb 0.1f 0.5f 0.2f 11329@endExample 11330 11331Note that @code{f} is the default scaling indicator for the 11332@code{defcolor} request, thus the above statement is equivalent to 11333 11334@Example 11335.defcolor darkgreen rgb 0.1 0.5 0.2 11336@endExample 11337@endDefreq 11338 11339@DefescList {\\m, , c, } 11340@DefescItem {\\m, @lparen{}, co, } 11341@DefescListEnd {\\m, @lbrack{}, color, @rbrack} 11342Set drawing color. The following example shows how to turn the next four 11343words red. 11344 11345@Example 11346\m[red]these are in red\m[] and these words are in black. 11347@endExample 11348 11349The escape @code{\m[]} returns to the previous color. 11350 11351The drawing color is associated with the current environment 11352(@pxref{Environments}). 11353 11354Note that @code{\m} doesn't produce an input token in @code{gtroff}. 11355As a consequence, it can be used in requests like @code{mc} (which 11356expects a single character as an argument) to change the color on 11357the fly: 11358 11359@Example 11360.mc \m[red]x\m[] 11361@endExample 11362@endDefesc 11363 11364@DefescList {\\M, , c, } 11365@DefescItem {\\M, @lparen{}, co, } 11366@DefescListEnd {\\M, @lbrack{}, color, @rbrack} 11367Set background color for filled objects drawn with the 11368@code{\D'@dots{}'} commands. 11369 11370A red ellipse can be created with the following code: 11371 11372@Example 11373\M[red]\h'0.5i'\D'E 2i 1i'\M[] 11374@endExample 11375 11376The escape @code{\M[]} returns to the previous fill color. 11377 11378The fill color is associated with the current environment 11379(@pxref{Environments}). 11380 11381Note that @code{\M} doesn't produce an input token in @code{gtroff}. 11382@endDefesc 11383 11384 11385@c ===================================================================== 11386 11387@node I/O, Postprocessor Access, Colors, gtroff Reference 11388@section I/O 11389@cindex i/o 11390@cindex input and output requests 11391@cindex requests for input and output 11392@cindex output and input requests 11393 11394@code{gtroff} has several requests for including files: 11395 11396@Defreq {so, file} 11397@cindex including a file (@code{so}) 11398@cindex file, inclusion (@code{so}) 11399Read in the specified @var{file} and 11400includes it in place of the @code{so} request. This is quite useful for 11401large documents, e.g.@: keeping each chapter in a separate file. 11402@xref{gsoelim}, for more information. 11403 11404Since @code{gtroff} replaces the @code{so} request with the contents 11405of @code{file}, it makes a difference whether the data is terminated with 11406a newline or not: Assuming that file @file{xxx} contains the word 11407@samp{foo} without a final newline, this 11408 11409@Example 11410This is 11411.so xxx 11412bar 11413@endExample 11414 11415@noindent 11416yields @samp{This is foobar}. 11417@endDefreq 11418 11419@Defreq {pso, command} 11420Read the standard output from the specified @var{command} 11421and includes it in place of the @code{pso} request. 11422 11423@cindex safer mode 11424@cindex mode, safer 11425@cindex unsafe mode 11426@cindex mode, unsafe 11427This request causes an error if used in safer mode (which is the default). 11428Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 11429mode. 11430 11431The comment regarding a final newline for the @code{so} request is valid 11432for @code{pso} also. 11433@endDefreq 11434 11435@Defreq {mso, file} 11436Identical to the @code{so} request except that @code{gtroff} searches for 11437the specified @var{file} in the same directories as macro files for the 11438the @option{-m} command line option. If the file name to be included 11439has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 11440to include @file{tmac.@var{name}} and vice versa. 11441@endDefreq 11442 11443@DefreqList {trf, file} 11444@DefreqListEnd {cf, file} 11445@cindex transparent output (@code{cf}, @code{trf}) 11446@cindex output, transparent (@code{cf}, @code{trf}) 11447Transparently output the contents of @var{file}. Each line is output 11448as if it were preceded by @code{\!}; however, the lines are not subject 11449to copy mode interpretation. If the file does not end with a newline, 11450then a newline is added (@code{trf} only). For example, to define a 11451macro@w{ }@code{x} containing the contents of file@w{ }@file{f}, use 11452 11453@Example 11454.di x 11455.trf f 11456.di 11457@endExample 11458 11459Both @code{trf} and @code{cf}, when used in a diversion, 11460embeds an object in the diversion which, when reread, causes the 11461contents of @var{file} to be transparently copied through to the 11462output. In @acronym{UNIX} @code{troff}, the contents of @var{file} 11463is immediately copied through to the output regardless of whether there 11464is a current diversion; this behaviour is so anomalous that it must be 11465considered a bug. 11466 11467@cindex @code{trf} request, and invalid characters 11468@cindex characters, invalid for @code{trf} request 11469@cindex invalid characters for @code{trf} request 11470While @code{cf} copies the contents of @var{file} completely unprocessed, 11471@code{trf} disallows characters such as NUL that are not valid 11472@code{gtroff} input characters (@pxref{Identifiers}). 11473 11474Both requests cause a line break. 11475@endDefreq 11476 11477@Defreq {nx, [@Var{file}]} 11478@cindex processing next file (@code{nx}) 11479@cindex file, processing next (@code{nx}) 11480@cindex next file, processing (@code{nx}) 11481Force @code{gtroff} to continue processing of 11482the file specified as an argument. If no argument is given, immediately 11483jump to the end of file. 11484@endDefreq 11485 11486@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]} 11487@cindex reading from standard input (@code{rd}) 11488@cindex standard input, reading from (@code{rd}) 11489@cindex input, standard, reading from (@code{rd}) 11490Read from standard input, and include what is read as though it 11491were part of the input file. Text is read until a blank line 11492is encountered. 11493 11494If standard input is a TTY input device (keyboard), write @var{prompt} 11495to standard error, followed by a colon (or send BEL for a beep if no 11496argument is given). 11497 11498Arguments after @var{prompt} are available for the input. For example, 11499the line 11500 11501@Example 11502.rd data foo bar 11503@endExample 11504 11505with the input @w{@samp{This is \$2.}} prints 11506 11507@Example 11508This is bar. 11509@endExample 11510@endDefreq 11511 11512@cindex form letters 11513@cindex letters, form 11514Using the @code{nx} and @code{rd} requests, 11515it is easy to set up form letters. The form 11516letter template is constructed like this, putting the following lines 11517into a file called @file{repeat.let}: 11518 11519@Example 11520.ce 11521\*(td 11522.sp 2 11523.nf 11524.rd 11525.sp 11526.rd 11527.fi 11528Body of letter. 11529.bp 11530.nx repeat.let 11531@endExample 11532 11533@cindex @code{ex} request, used with @code{nx} and @code{rd} 11534@noindent 11535When this is run, a file containing the following lines should be 11536redirected in. Note that requests included in this file are executed 11537as though they were part of the form letter. The last block of input 11538is the @code{ex} request which tells @code{groff} to stop processing. If 11539this was not there, @code{groff} would not know when to stop. 11540 11541@Example 11542Trent A. Fisher 11543708 NW 19th Av., #202 11544Portland, OR 97209 11545 11546Dear Trent, 11547 11548Len Adollar 115494315 Sierra Vista 11550San Diego, CA 92103 11551 11552Dear Mr. Adollar, 11553 11554.ex 11555@endExample 11556 11557@Defreq {pi, pipe} 11558Pipe the output of @code{gtroff} to the shell command(s) 11559specified by @var{pipe}. This request must occur before 11560@code{gtroff} has a chance to print anything. 11561 11562@cindex safer mode 11563@cindex mode, safer 11564@cindex unsafe mode 11565@cindex mode, unsafe 11566@code{pi} causes an error if used in safer mode (which is the default). 11567Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 11568mode. 11569 11570Multiple calls to @code{pi} are allowed, acting as a chain. For example, 11571 11572@Example 11573.pi foo 11574.pi bar 11575... 11576@endExample 11577 11578is the same as @w{@samp{.pi foo | bar}}. 11579 11580@cindex @code{groff}, and @code{pi} request 11581@cindex @code{pi} request, and @code{groff} 11582Note that the intermediate output format of @code{gtroff} is piped to 11583the specified commands. Consequently, calling @code{groff} without the 11584@option{-Z} option normally causes a fatal error. 11585@endDefreq 11586 11587@DefreqList {sy, cmds} 11588@DefregListEnd {systat} 11589Execute the shell command(s) specified by @var{cmds}. The output is not 11590saved anyplace, so it is up to the user to do so. 11591 11592@cindex safer mode 11593@cindex mode, safer 11594@cindex unsafe mode 11595@cindex mode, unsafe 11596This request causes an error if used in safer mode (which is the default). 11597Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 11598mode. 11599 11600For example, the following code fragment introduces the current time into a 11601document: 11602 11603@cindex time, current 11604@cindex current time 11605@pindex perl 11606@Example 11607.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 11608 (localtime(time))[2,1,0]' > /tmp/x\n[$$] 11609.so /tmp/x\n[$$] 11610.sy rm /tmp/x\n[$$] 11611\nH:\nM:\nS 11612@endExample 11613 11614@noindent 11615Note that this works by having the @code{perl} script (run by @code{sy}) 11616print out the @code{nr} requests which set the number registers 11617@code{H}, @code{M}, and @code{S}, and then reads those commands in with 11618the @code{so} request. 11619 11620For most practical purposes, the number registers @code{seconds}, 11621@code{minutes}, and @code{hours} which are initialized at start-up of 11622@code{gtroff} should be sufficient. Use the @code{af} request to get a 11623formatted output: 11624 11625@Example 11626.af hours 00 11627.af minutes 00 11628.af seconds 00 11629\n[hours]:\n[minutes]:\n[seconds] 11630@endExample 11631 11632@cindex @code{system()} return value register (@code{systat}) 11633The @code{systat} read-write number register contains the return value 11634of the @code{system()} function executed by the last @code{sy} request. 11635@endDefreq 11636 11637@DefreqList {open, stream file} 11638@DefreqListEnd {opena, stream file} 11639@cindex opening file (@code{open}) 11640@cindex file, opening (@code{open}) 11641@cindex appending to a file (@code{opena}) 11642@cindex file, appending to (@code{opena}) 11643Open the specified @var{file} for writing and 11644associates the specified @var{stream} with it. 11645 11646The @code{opena} request is like @code{open}, but if the file exists, 11647append to it instead of truncating it. 11648 11649@cindex safer mode 11650@cindex mode, safer 11651@cindex unsafe mode 11652@cindex mode, unsafe 11653Both @code{open} and @code{opena} cause an error if used in safer mode 11654(which is the default). Use @code{groff}'s or @code{troff}'s @option{-U} 11655option to activate unsafe mode. 11656@endDefreq 11657 11658@DefreqList {write, stream data} 11659@DefreqListEnd {writec, stream data} 11660@cindex copy-in mode, and @code{write} requests 11661@cindex mode, copy-in, and @code{write} requests 11662@cindex writing to file (@code{write}) 11663@cindex file, writing to (@code{write}) 11664Write to the file associated with the specified @var{stream}. 11665The stream must previously have 11666been the subject of an open request. The remainder of the line is 11667interpreted as the @code{ds} request reads its second argument: A 11668leading @samp{"} is stripped, and it is read in copy-in mode. 11669 11670The @code{writec} request is like @code{write}, but only 11671@code{write} appends a newline to the data. 11672@endDefreq 11673 11674@Defreq {writem, stream xx} 11675@cindex @code{asciify} request, and @code{writem} 11676Write the contents of the macro or string @var{xx} 11677to the file associated with the specified @var{stream}. 11678 11679@var{xx} is read in copy mode, i.e., already formatted elements are 11680ignored. Consequently, diversions must be unformatted with the 11681@code{asciify} request before calling @code{writem}. Usually, this 11682means a loss of information. 11683@endDefreq 11684 11685@Defreq {close, stream} 11686@cindex closing file (@code{close}) 11687@cindex file, closing (@code{close}) 11688Close the specified @var{stream}; 11689the stream is no longer an acceptable argument to the 11690@code{write} request. 11691 11692Here a simple macro to write an index entry. 11693 11694@Example 11695.open idx test.idx 11696. 11697.de IX 11698. write idx \\n[%] \\$* 11699.. 11700. 11701.IX test entry 11702. 11703.close idx 11704@endExample 11705@endDefreq 11706 11707@DefescList {\\V, , e, } 11708@DefescItem {\\V, @lparen{}, ev, } 11709@DefescListEnd {\\V, @lbrack{}, env, @rbrack} 11710Interpolate the contents of the specified environment variable 11711@var{env} (one-character name@w{ }@var{e}, two-character name @var{ev}) 11712as returned by the function @code{getenv}. @code{\V} is interpreted 11713in copy-in mode. 11714@endDefesc 11715 11716 11717@c ===================================================================== 11718 11719@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 11720@section Postprocessor Access 11721@cindex postprocessor access 11722@cindex access of postprocessor 11723 11724There are two escapes which give information directly to the 11725postprocessor. This is particularly useful for embedding 11726@sc{PostScript} into the final document. 11727 11728@Defesc {\\X, ', xxx, '} 11729Embeds its argument into the @code{gtroff} 11730output preceded with @w{@samp{x X}}. 11731 11732@cindex @code{\&}, in @code{\X} 11733@cindex @code{\)}, in @code{\X} 11734@cindex @code{\%}, in @code{\X} 11735@ifnotinfo 11736@cindex @code{\:}, in @code{\X} 11737@end ifnotinfo 11738@ifinfo 11739@cindex @code{\@r{<colon>}}, in @code{\X} 11740@end ifinfo 11741The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored 11742within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single 11743space characters. All other escapes (except @code{\\} which produces a 11744backslash) cause an error. 11745 11746@kindex use_charnames_in_special 11747@pindex DESC@r{, and @code{use_charnames_in_special}} 11748@cindex @code{\X}, and special characters 11749If the @samp{use_charnames_in_special} keyword is set in the @file{DESC} 11750file, special characters no longer cause an error; the name @var{xx} is 11751represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command. 11752Additionally, the backslash is represented as @code{\\}. 11753 11754@samp{use_charnames_in_special} is currently used by @code{grohtml} only. 11755@endDefesc 11756 11757@DefescList {\\Y, , n, } 11758@DefescItem {\\Y, @lparen{}, nm, } 11759@DefescListEnd {\\Y, @lbrack{}, name, @rbrack} 11760This is approximately equivalent to @samp{\X'\*[@var{name}]'} 11761(one-character name@w{ }@var{n}, two-character name @var{nm}). 11762However, the contents of the string or macro @var{name} are not 11763interpreted; also it is permitted for @var{name} to have been defined 11764as a macro and thus contain newlines (it is not permitted for the 11765argument to @code{\X} to contain newlines). The inclusion of 11766newlines requires an extension to the @acronym{UNIX} @code{troff} 11767output format, and confuses drivers that do not know about this 11768extension (@pxref{Device Control Commands}). 11769@endDefesc 11770 11771@xref{Output Devices}. 11772 11773 11774@c ===================================================================== 11775 11776@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 11777@section Miscellaneous 11778 11779This section documents parts of @code{gtroff} which cannot (yet) be 11780categorized elsewhere in this manual. 11781 11782@Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]} 11783@cindex printing line numbers (@code{nm}) 11784@cindex line numbers, printing (@code{nm}) 11785@cindex numbers, line, printing (@code{nm}) 11786Print line numbers. 11787@var{start} is the line number of the @emph{next} 11788output line. @var{inc} indicates which line numbers are printed. 11789For example, the value@w{ }5 means to emit only line numbers which 11790are multiples of@w{ }5; this defaults to@w{ }1. @var{space} is the 11791space to be left between the number and the text; this defaults to 11792one digit space. The fourth argument is the indentation of the line 11793numbers, defaulting to zero. Both @var{space} and @var{indent} are 11794given as multiples of digit spaces; they can be negative also. 11795Without any arguments, line numbers are turned off. 11796 11797@code{gtroff} reserves three digit spaces for the line number (which is 11798printed right-justified) plus the amount given by @var{indent}; the 11799output lines are concatenated to the line numbers, separated by 11800@var{space}, and @emph{without} reducing the line length. Depending 11801on the value of the horizontal page offset (as set with the 11802@code{po} request), line numbers which are longer than the reserved 11803space stick out to the left, or the whole line is moved to the right. 11804 11805Parameters corresponding to missing arguments are not changed; any 11806non-digit argument (to be more precise, any argument starting with a 11807character valid as a delimiter for identifiers) is also treated as 11808missing. 11809 11810If line numbering has been disabled with a call to @code{nm} without 11811an argument, it can be reactivated with @samp{.nm +0}, using the 11812previously active line numbering parameters. 11813 11814The parameters of @code{nm} are associated with the current environment 11815(@pxref{Environments}). The current output line number is available 11816in the number register @code{ln}. 11817 11818@Example 11819.po 1m 11820.ll 2i 11821This test shows how line numbering works with groff. 11822.nm 999 11823This test shows how line numbering works with groff. 11824.br 11825.nm xxx 3 2 11826.ll -\w'0'u 11827This test shows how line numbering works with groff. 11828.nn 2 11829This test shows how line numbering works with groff. 11830@endExample 11831 11832@noindent 11833And here the result: 11834 11835@Example 11836 This test shows how 11837 line numbering works 11838 999 with groff. This 118391000 test shows how line 118401001 numbering works with 118411002 groff. 11842 This test shows how 11843 line numbering 11844 works with groff. 11845 This test shows how 118461005 line numbering 11847 works with groff. 11848@endExample 11849@endDefreq 11850 11851@Defreq {nn, [@Var{skip}]} 11852Temporarily turn off line numbering. The argument is the number 11853of lines not to be numbered; this defaults to@w{ }1. 11854@endDefreq 11855 11856@Defreq {mc, glyph [@Var{dist}]} 11857@cindex margin glyph (@code{mc}) 11858@cindex glyph, for margins (@code{mc}) 11859Print a @dfn{margin character} to the right of the 11860text.@footnote{@dfn{Margin character} is a misnomer since it is an 11861output glyph.} The first argument is the glyph to be 11862printed. The second argument is the distance away from the right 11863margin. If missing, the previously set value is used; default is 1186410@dmn{pt}). For text lines that are too long (that is, longer than 11865the text length plus @var{dist}), the margin character is directly 11866appended to the lines. 11867 11868With no arguments the margin character is turned off. 11869If this occurs before a break, no margin character is printed. 11870 11871@cindex @code{tl} request, and @code{mc} 11872For empty lines and lines produced by the @code{tl} request no margin 11873character is emitted. 11874 11875The margin character is associated with the current environment 11876(@pxref{Environments}). 11877 11878@pindex nrchbar 11879@pindex changebar 11880This is quite useful for indicating text that has changed, and, in fact, 11881there are programs available for doing this (they are called 11882@code{nrchbar} and @code{changebar} and can be found in any 11883@samp{comp.sources.unix} archive. 11884 11885@Example 11886.ll 3i 11887.mc | 11888This paragraph is highlighted with a margin 11889character. 11890.sp 11891Note that vertical space isn't marked. 11892.br 11893\& 11894.br 11895But we can fake it with `\&'. 11896@endExample 11897 11898Result: 11899 11900@Example 11901This paragraph is highlighted | 11902with a margin character. | 11903 11904Note that vertical space isn't | 11905marked. | 11906 | 11907But we can fake it with `\&'. | 11908@endExample 11909@endDefreq 11910 11911@DefreqList {psbb, filename} 11912@DefregItem {llx} 11913@DefregItem {lly} 11914@DefregItem {urx} 11915@DefregListEnd {ury} 11916@cindex PostScript, bounding box 11917@cindex bounding box 11918Retrieve the bounding box of the PostScript image 11919found in @var{filename}. 11920The file must conform to 11921Adobe's @dfn{Document Structuring Conventions} (DSC); 11922the command searches for a @code{%%BoundingBox} comment 11923and extracts the bounding box values into the number registers 11924@code{llx}, @code{lly}, @code{urx}, and @code{ury}. 11925If an error occurs (for example, @code{psbb} cannot find 11926the @code{%%BoundingBox} comment), 11927it sets the four number registers to zero. 11928@endDefreq 11929 11930 11931@c ===================================================================== 11932 11933@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 11934@section @code{gtroff} Internals 11935 11936@cindex input token 11937@cindex token, input 11938@cindex output node 11939@cindex node, output 11940@code{gtroff} processes input in three steps. One or more input 11941characters are converted to an @dfn{input token}.@footnote{Except the 11942escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R}, 11943@code{\s}, and @code{\S} which are processed immediately if not in 11944copy-in mode.} Then, one or more input tokens are converted to an 11945@dfn{output node}. Finally, output nodes are converted to the 11946intermediate output language understood by all output devices. 11947 11948Actually, before step one happens, @code{gtroff} converts certain 11949escape sequences into reserved input characters (not accessible by 11950the user); such reserved characters are used for other internal 11951processing also -- this is the very reason why not all characters 11952are valid input. @xref{Identifiers}, for more on this topic. 11953 11954For example, the input string @samp{fi\[:u]} is converted into a 11955character token @samp{f}, a character token @samp{i}, and a special 11956token @samp{:u} (representing u@w{ }umlaut). Later on, the character 11957tokens @samp{f} and @samp{i} are merged to a single output node 11958representing the ligature glyph @samp{fi} (provided the current font 11959has a glyph for this ligature); the same happens with @samp{:u}. All 11960output glyph nodes are `processed' which means that they are invariably 11961associated with a given font, font size, advance width, etc. During 11962the formatting process, @code{gtroff} itself adds various nodes to 11963control the data flow. 11964 11965Macros, diversions, and strings collect elements in two chained lists: 11966a list of input tokens which have been passed unprocessed, and a list 11967of output nodes. Consider the following the diversion. 11968 11969@Example 11970.di xxx 11971a 11972\!b 11973c 11974.br 11975.di 11976@endExample 11977 11978@noindent 11979It contains these elements. 11980 11981@multitable {@i{vertical size node}} {token list} {element number} 11982@item node list @tab token list @tab element number 11983 11984@item @i{line start node} @tab --- @tab 1 11985@item @i{glyph node @code{a}} @tab --- @tab 2 11986@item @i{word space node} @tab --- @tab 3 11987@item --- @tab @code{b} @tab 4 11988@item --- @tab @code{\n} @tab 5 11989@item @i{glyph node @code{c}} @tab --- @tab 6 11990@item @i{vertical size node} @tab --- @tab 7 11991@item @i{vertical size node} @tab --- @tab 8 11992@item --- @tab @code{\n} @tab 9 11993@end multitable 11994 11995@cindex @code{\v}, internal representation 11996@noindent 11997Elements 1, 7, and@w{ }8 are inserted by @code{gtroff}; the latter two 11998(which are always present) specify the vertical extent of the last 11999line, possibly modified by @code{\x}. The @code{br} request finishes 12000the current partial line, inserting a newline input token which is 12001subsequently converted to a space when the diversion is reread. Note 12002that the word space node has a fixed width which isn't stretchable 12003anymore. To convert horizontal space nodes back to input tokens, use 12004the @code{unformat} request. 12005 12006Macros only contain elements in the token list (and the node list is 12007empty); diversions and strings can contain elements in both lists. 12008 12009Note that the @code{chop} request simply reduces the number of elements in a 12010macro, string, or diversion by one. Exceptions are @dfn{compatibility save} 12011and @dfn{compatibility ignore} input tokens which are ignored. The 12012@code{substring} request also ignores those input tokens. 12013 12014Some requests like @code{tr} or @code{cflags} work on glyph 12015identifiers only; this means that the associated glyph can be changed 12016without destroying this association. This can be very helpful for 12017substituting glyphs. In the following example, we assume that 12018glyph @samp{foo} isn't available by default, so we provide a 12019substitution using the @code{fchar} request and map it to input 12020character @samp{x}. 12021 12022@Example 12023.fchar \[foo] foo 12024.tr x \[foo] 12025@endExample 12026 12027@noindent 12028Now let us assume that we install an additional special font 12029@samp{bar} which has glyph @samp{foo}. 12030 12031@Example 12032.special bar 12033.rchar \[foo] 12034@endExample 12035 12036@noindent 12037Since glyphs defined with @code{fchar} are searched before glyphs 12038in special fonts, we must call @code{rchar} to remove the definition 12039of the fallback glyph. Anyway, the translation is still active; 12040@samp{x} now maps to the real glyph @samp{foo}. 12041 12042 12043@c ===================================================================== 12044 12045@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 12046@section Debugging 12047@cindex debugging 12048 12049@code{gtroff} is not easy to debug, but there are some useful features 12050and strategies for debugging. 12051 12052@Defreq {lf, line filename} 12053@pindex soelim 12054@cindex multi-file documents 12055@cindex documents, multi-file 12056@cindex setting input line number (@code{lf}) 12057@cindex input line number, setting (@code{lf}) 12058@cindex number, input line, setting (@code{lf}) 12059Change the line number and the file name @code{gtroff} shall use for 12060error and warning messages. @var{line} is the input line number of the 12061@emph{next} line. 12062 12063Without argument, the request is ignored. 12064 12065This is a debugging aid for documents which are split into many files, 12066then put together with @code{soelim} and other preprocessors. Usually, 12067it isn't invoked manually. 12068@endDefreq 12069 12070@DefreqList {tm, string} 12071@DefreqItem {tm1, string} 12072@DefreqListEnd {tmc, string} 12073@cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc}) 12074@cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc}) 12075Send @var{string} to the standard error output; 12076this is very useful for printing debugging messages among other things. 12077 12078@var{string} is read in copy mode. 12079 12080The @code{tm} request ignores leading spaces of @var{string}; @code{tm1} 12081handles its argument similar to the @code{ds} request: a leading double 12082quote in @var{string} is stripped to allow initial blanks. 12083 12084The @code{tmc} request is similar to @code{tm1} but does 12085not append a newline (as is done in @code{tm} and @code{tm1}). 12086@endDefreq 12087 12088@Defreq {ab, [@Var{string}]} 12089@cindex aborting (@code{ab}) 12090Similar to the @code{tm} request, except that 12091it causes @code{gtroff} to stop processing. With no argument it 12092prints @samp{User Abort.} to standard error. 12093@endDefreq 12094 12095@Defreq {ex, } 12096@cindex @code{ex} request, use in debugging 12097@cindex exiting (@code{ex}) 12098The @code{ex} request also causes @code{gtroff} to stop processing; 12099see also @ref{I/O}. 12100@endDefreq 12101 12102When doing something involved it is useful to leave the debugging 12103statements in the code and have them turned on by a command line flag. 12104 12105@Example 12106.if \n(DB .tm debugging output 12107@endExample 12108 12109@noindent 12110To activate these statements say 12111 12112@Example 12113groff -rDB=1 file 12114@endExample 12115 12116If it is known in advance that there will be many errors and no useful 12117output, @code{gtroff} can be forced to suppress formatted output with 12118the @option{-z} flag. 12119 12120@Defreq {pm, } 12121@cindex dumping symbol table (@code{pm}) 12122@cindex symbol table, dumping (@code{pm}) 12123Print the entire symbol table on @code{stderr}. Names of all defined 12124macros, strings, and diversions are print together with their size in 12125bytes. Since @code{gtroff} sometimes adds nodes by itself, the 12126returned size can be larger than expected. 12127 12128This request differs from @acronym{UNIX} @code{troff}: @code{gtroff} 12129reports the sizes of diversions, ignores an additional argument to 12130print only the total of the sizes, and the size isn't returned in 12131blocks of 128 characters. 12132@endDefreq 12133 12134@Defreq {pnr, } 12135@cindex dumping number registers (@code{pnr}) 12136@cindex number registers, dumping (@code{pnr}) 12137Print the names and contents of all 12138currently defined number registers on @code{stderr}. 12139@endDefreq 12140 12141@Defreq {ptr, } 12142@cindex dumping traps (@code{ptr}) 12143@cindex traps, dumping (@code{ptr}) 12144Print the names and positions of all traps 12145(not including input line traps and diversion traps) on @code{stderr}. 12146Empty slots in the page trap list are printed as well, because they can 12147affect the priority of subsequently planted traps. 12148@endDefreq 12149 12150@Defreq {fl, } 12151@cindex flush output (@code{fl}) 12152@cindex output, flush (@code{fl}) 12153@cindex interactive use of @code{gtroff} 12154@cindex @code{gtroff}, interactive use 12155Instruct @code{gtroff} to flush its output immediately. The intent 12156is for interactive use, but this behaviour is currently not 12157implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff}, 12158TTY output is sent to a device driver also (@code{grotty}), making it 12159non-trivial to communicate interactively. 12160 12161This request causes a line break. 12162@endDefreq 12163 12164@Defreq {backtrace, } 12165@cindex backtrace of input stack (@code{backtrace}) 12166@cindex input stack, backtrace (@code{backtrace}) 12167Print a backtrace of the input stack to the standard error stream. 12168 12169Consider the following in file @file{test}: 12170 12171@Example 12172.de xxx 12173. backtrace 12174.. 12175.de yyy 12176. xxx 12177.. 12178. 12179.yyy 12180@endExample 12181 12182@noindent 12183On execution, @code{gtroff} prints the following: 12184 12185@Example 12186test:2: backtrace: macro `xxx' 12187test:5: backtrace: macro `yyy' 12188test:8: backtrace: file `test' 12189@endExample 12190 12191The option @option{-b} of @code{gtroff} internally calls a variant of 12192this request on each error and warning. 12193@endDefreq 12194 12195@Defreg {slimit} 12196@cindex input stack, setting limit 12197Use the @code{slimit} number register 12198to set the maximum number of objects on the input stack. 12199If @code{slimit} is less than or equal to@w{ }0, 12200there is no limit set. 12201With no limit, a buggy recursive macro can exhaust virtual memory. 12202 12203The default value is 1000; this is a compile-time constant. 12204@endDefreg 12205 12206@Defreq {warnscale, si} 12207Set the scaling indicator used in warnings to @var{si}. Valid values for 12208@var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At 12209startup, it is set to @samp{i}. 12210@endDefreq 12211 12212@Defreq {spreadwarn, [@Var{limit}]} 12213Make @code{gtroff} emit a warning if the additional space inserted for 12214each space between words in an output line is larger or equal to 12215@var{limit}. A negative value is changed to zero; no argument toggles the 12216warning on and off without changing @var{limit}. The default scaling 12217indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and 12218@var{limit} is set to 3@dmn{m}. 12219 12220For example, 12221 12222@Example 12223.spreadwarn 0.2m 12224@endExample 12225 12226@noindent 12227will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each 12228interword space in a line. 12229 12230This request is active only if text is justified to both margins (using 12231@w{@samp{.ad b}}). 12232@endDefreq 12233 12234@cindex warnings 12235@code{gtroff} has command line options for printing out more warnings 12236(@option{-w}) and for printing backtraces (@option{-b}) when a warning 12237or an error occurs. The most verbose level of warnings is @option{-ww}. 12238 12239@DefreqList {warn, [@Var{flags}]} 12240@DefregListEnd {.warn} 12241@cindex level of warnings (@code{warn}) 12242@cindex warnings, level (@code{warn}) 12243Control the level of warnings checked for. The @var{flags} are the sum 12244of the numbers associated with each warning that is to be enabled; all 12245other warnings are disabled. The number associated with each warning is 12246listed below. For example, @w{@code{.warn 0}} disables all warnings, 12247and @w{@code{.warn 1}} disables all warnings except that about missing 12248glyphs. If no argument is given, all warnings are enabled. 12249 12250The read-only number register @code{.warn} contains the current warning 12251level. 12252@endDefreq 12253 12254@menu 12255* Warnings:: 12256@end menu 12257 12258@c --------------------------------------------------------------------- 12259 12260@node Warnings, , Debugging, Debugging 12261@subsection Warnings 12262@cindex warnings 12263 12264The warnings that can be given to @code{gtroff} are divided into the 12265following categories. The name associated with each warning is used by 12266the @option{-w} and @option{-W} options; the number is used by the 12267@code{warn} request and by the @code{.warn} register. 12268 12269@table @samp 12270@item char 12271@itemx 1 12272Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports 12273missing glyphs -- there aren't missing input characters, only invalid 12274ones.} This is enabled by default. 12275 12276@item number 12277@itemx 2 12278Invalid numeric expressions. This is enabled by default. 12279@xref{Expressions}. 12280 12281@item break 12282@itemx 4 12283@cindex fill mode 12284@cindex mode, fill 12285In fill mode, lines which could not be broken so that their length was 12286less than the line length. This is enabled by default. 12287 12288@item delim 12289@itemx 8 12290Missing or mismatched closing delimiters. 12291 12292@item el 12293@itemx 16 12294@cindex @code{ie} request, and warnings 12295@cindex @code{el} request, and warnings 12296Use of the @code{el} request with no matching @code{ie} request. 12297@xref{if-else}. 12298 12299@item scale 12300@itemx 32 12301Meaningless scaling indicators. 12302 12303@item range 12304@itemx 64 12305Out of range arguments. 12306 12307@item syntax 12308@itemx 128 12309Dubious syntax in numeric expressions. 12310 12311@item di 12312@itemx 256 12313@cindex @code{di} request, and warnings 12314@cindex @code{da} request, and warnings 12315Use of @code{di} or @code{da} without an argument when there is no 12316current diversion. 12317 12318@item mac 12319@itemx 512 12320@cindex @code{de}, @code{de1}, @code{dei} requests, and warnings 12321@cindex @code{am}, @code{am1}, @code{ami} requests, and warnings 12322@cindex @code{ds}, @code{ds1} requests, and warnings 12323@cindex @code{as}, @code{as1} requests, and warnings 12324@cindex @code{di} request, and warnings 12325@cindex @code{da} request, and warnings 12326@cindex @code{box}, @code{boxa} requests, and warnings 12327@cindex @code{\*}, and warnings 12328Use of undefined strings, macros and diversions. When an undefined 12329string, macro, or diversion is used, that string is automatically 12330defined as empty. So, in most cases, at most one warning is given 12331for each name. 12332 12333@item reg 12334@itemx 1024 12335@cindex @code{nr} request, and warnings 12336@cindex @code{\R}, and warnings 12337@cindex @code{\n}, and warnings 12338Use of undefined number registers. When an undefined number register is 12339used, that register is automatically defined to have a value of@w{ }0. 12340So, in most cases, at most one warning is given for use of a particular 12341name. 12342 12343@item tab 12344@itemx 2048 12345@cindex @code{\t}, and warnings 12346Use of a tab character where a number was expected. 12347 12348@item right-brace 12349@itemx 4096 12350@cindex @code{\@}}, and warnings 12351Use of @code{\@}} where a number was expected. 12352 12353@item missing 12354@itemx 8192 12355Requests that are missing non-optional arguments. 12356 12357@item input 12358@itemx 16384 12359Invalid input characters. 12360 12361@item escape 12362@itemx 32768 12363Unrecognized escape sequences. When an unrecognized escape sequence 12364@code{\@var{X}} is encountered, the escape character is ignored, and 12365@var{X} is printed. 12366 12367@item space 12368@itemx 65536 12369@cindex compatibility mode 12370Missing space between a request or macro and its argument. This warning 12371is given when an undefined name longer than two characters is 12372encountered, and the first two characters of the name make a defined 12373name. The request or macro is not invoked. When this warning is 12374given, no macro is automatically defined. This is enabled by default. 12375This warning never occurs in compatibility mode. 12376 12377@item font 12378@itemx 131072 12379Non-existent fonts. This is enabled by default. 12380 12381@item ig 12382@itemx 262144 12383Invalid escapes in text ignored with the @code{ig} request. These are 12384conditions that are errors when they do not occur in ignored text. 12385 12386@item color 12387@itemx 524288 12388Color related warnings. 12389 12390@item all 12391All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 12392intended that this covers all warnings that are useful with traditional 12393macro packages. 12394 12395@item w 12396All warnings. 12397@end table 12398 12399 12400@c ===================================================================== 12401 12402@node Implementation Differences, , Debugging, gtroff Reference 12403@section Implementation Differences 12404@cindex implementation differences 12405@cindex differences in implementation 12406@cindex incompatibilities with @acronym{AT&T} @code{troff} 12407@cindex compatibility mode 12408@cindex mode, compatibility 12409 12410GNU @code{troff} has a number of features which cause incompatibilities 12411with documents written with old versions of @code{troff}. 12412 12413@cindex long names 12414@cindex names, long 12415Long names cause some incompatibilities. @acronym{UNIX} @code{troff} 12416interprets 12417 12418@Example 12419.dsabcd 12420@endExample 12421 12422@cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff} 12423@cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff} 12424@noindent 12425as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 12426@code{troff} interprets this as a call of a macro named 12427@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 12428@code{\*[} or @code{\n[} as references to a string or number register 12429called @samp{[}. In GNU @code{troff}, however, this is normally 12430interpreted as the start of a long name. In compatibility mode GNU 12431@code{troff} interprets long names in the traditional way 12432(which means that they are not recognized as names). 12433 12434@DefreqList {cp, [@Var{n}]} 12435@DefreqItem {do, cmd} 12436@DefregListEnd {.C} 12437If @var{n} is missing or non-zero, turn on compatibility mode; 12438otherwise, turn it off. 12439 12440The read-only number register @code{.C} is@w{ }1 if compatibility mode is 12441on, 0@w{ }otherwise. 12442 12443Compatibility mode can be also turned on with the @option{-C} command line 12444option. 12445 12446The @code{do} request turns off compatibility mode 12447while executing its arguments as a @code{gtroff} command. 12448 12449@Example 12450.do fam T 12451@endExample 12452 12453@noindent 12454executes the @code{fam} request when compatibility mode 12455is enabled. 12456 12457@code{gtroff} restores the previous compatibility setting 12458before interpreting any files sourced by the @var{cmd}. 12459@endDefreq 12460 12461@cindex input level in delimited arguments 12462@cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff} 12463Two other features are controlled by @option{-C}. If not in 12464compatibility mode, GNU @code{troff} preserves the input level in 12465delimited arguments: 12466 12467@Example 12468.ds xx ' 12469\w'abc\*(xxdef' 12470@endExample 12471 12472@noindent 12473In compatibility mode, the string @samp{72def'} is returned; without 12474@option{-C} the resulting string is @samp{168} (assuming a TTY output 12475device). 12476 12477@cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff} 12478@cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff} 12479@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff} 12480@cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff} 12481Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M}, 12482@code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the 12483beginning of a line only in compatibility mode (this is a rather obscure 12484feature). For example, the code 12485 12486@Example 12487.de xx 12488Hallo! 12489.. 12490\fB.xx\fP 12491@endExample 12492 12493prints @samp{Hallo!} in bold face if in compatibility mode, and 12494@samp{.xx} in bold face otherwise. 12495 12496@cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff} 12497@cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff} 12498@cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff} 12499@cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff} 12500@cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff} 12501@cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff} 12502@cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff} 12503@cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff} 12504@cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff} 12505@cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff} 12506@cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff} 12507@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 12508@cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff} 12509@cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff} 12510GNU @code{troff} does not allow the use of the escape sequences 12511@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 12512@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 12513@code{\%}, and @code{\c} in names of strings, macros, diversions, number 12514registers, fonts or environments; @acronym{UNIX} @code{troff} does. The 12515@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 12516avoiding use of these escape sequences in names. 12517 12518@cindex fractional point sizes 12519@cindex fractional type sizes 12520@cindex point sizes, fractional 12521@cindex type sizes, fractional 12522@cindex sizes, fractional 12523@cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff} 12524Fractional point sizes cause one noteworthy incompatibility. In 12525@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 12526indicators and thus 12527 12528@Example 12529.ps 10u 12530@endExample 12531 12532@noindent 12533sets the point size to 10@w{ }points, whereas in GNU @code{troff} it 12534sets the point size to 10@w{ }scaled points. @xref{Fractional Type 12535Sizes}, for more information. 12536 12537@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff} 12538@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff} 12539@cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff} 12540@cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff} 12541@cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff} 12542@cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff} 12543@cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff} 12544@cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff} 12545In GNU @code{troff} there is a fundamental difference between 12546(unformatted) input characters and (formatted) output glyphs. 12547Everything that affects how a glyph is output is stored 12548with the glyph node; once a glyph node has been constructed it is 12549unaffected by any subsequent requests that are executed, including 12550@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 12551Normally glyphs are constructed from input characters at the 12552moment immediately before the glyph is added to the current output 12553line. Macros, diversions and strings are all, in fact, the same type of 12554object; they contain lists of input characters and glyph nodes in 12555any combination. A glyph node does not behave like an input 12556character for the purposes of macro processing; it does not inherit any 12557of the special properties that the input character from which it was 12558constructed might have had. For example, 12559 12560@Example 12561.di x 12562\\\\ 12563.br 12564.di 12565.x 12566@endExample 12567 12568@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 12569@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 12570@cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff} 12571@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 12572@cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff} 12573@cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff} 12574@cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff} 12575@noindent 12576prints @samp{\\} in GNU @code{troff}; each pair of input backslashes 12577is turned into one output backslash and the resulting output backslashes 12578are not interpreted as escape characters when they are reread. 12579@acronym{UNIX} @code{troff} would interpret them as escape characters 12580when they were reread and would end up printing one @samp{\}. The 12581correct way to obtain a printable backslash is to use the @code{\e} 12582escape sequence: This always prints a single instance of the current 12583escape character, regardless of whether or not it is used in a 12584diversion; it also works in both GNU @code{troff} and @acronym{UNIX} 12585@code{troff}.@footnote{To be completely independent of the current 12586escape character, use @code{\(rs} which represents a reverse solidus 12587(backslash) glyph.} To store, for some reason, an escape sequence in a 12588diversion that will be interpreted when the diversion is reread, either 12589use the traditional @code{\!} transparent output facility, or, if this 12590is unsuitable, the new @code{\?} escape sequence. 12591 12592@xref{Diversions}, and @ref{Gtroff Internals}, for more information. 12593 12594 12595 12596@c ===================================================================== 12597@c ===================================================================== 12598 12599@node Preprocessors, Output Devices, gtroff Reference, Top 12600@chapter Preprocessors 12601@cindex preprocessors 12602 12603This chapter describes all preprocessors that come with @code{groff} or 12604which are freely available. 12605 12606@menu 12607* geqn:: 12608* gtbl:: 12609* gpic:: 12610* ggrn:: 12611* grap:: 12612* grefer:: 12613* gsoelim:: 12614@end menu 12615 12616 12617@c ===================================================================== 12618 12619@node geqn, gtbl, Preprocessors, Preprocessors 12620@section @code{geqn} 12621@cindex @code{eqn}, the program 12622@cindex @code{geqn}, the program 12623 12624@c XXX 12625 12626@menu 12627* Invoking geqn:: 12628@end menu 12629 12630@c --------------------------------------------------------------------- 12631 12632@node Invoking geqn, , geqn, geqn 12633@subsection Invoking @code{geqn} 12634@cindex invoking @code{geqn} 12635@cindex @code{geqn}, invoking 12636 12637@c XXX 12638 12639 12640@c ===================================================================== 12641 12642@node gtbl, gpic, geqn, Preprocessors 12643@section @code{gtbl} 12644@cindex @code{tbl}, the program 12645@cindex @code{gtbl}, the program 12646 12647@c XXX 12648 12649@menu 12650* Invoking gtbl:: 12651@end menu 12652 12653@c --------------------------------------------------------------------- 12654 12655@node Invoking gtbl, , gtbl, gtbl 12656@subsection Invoking @code{gtbl} 12657@cindex invoking @code{gtbl} 12658@cindex @code{gtbl}, invoking 12659 12660@c XXX 12661 12662 12663@c ===================================================================== 12664 12665@node gpic, ggrn, gtbl, Preprocessors 12666@section @code{gpic} 12667@cindex @code{pic}, the program 12668@cindex @code{gpic}, the program 12669 12670@c XXX 12671 12672@menu 12673* Invoking gpic:: 12674@end menu 12675 12676@c --------------------------------------------------------------------- 12677 12678@node Invoking gpic, , gpic, gpic 12679@subsection Invoking @code{gpic} 12680@cindex invoking @code{gpic} 12681@cindex @code{gpic}, invoking 12682 12683@c XXX 12684 12685 12686@c ===================================================================== 12687 12688@node ggrn, grap, gpic, Preprocessors 12689@section @code{ggrn} 12690@cindex @code{grn}, the program 12691@cindex @code{ggrn}, the program 12692 12693@c XXX 12694 12695@menu 12696* Invoking ggrn:: 12697@end menu 12698 12699@c --------------------------------------------------------------------- 12700 12701@node Invoking ggrn, , ggrn, ggrn 12702@subsection Invoking @code{ggrn} 12703@cindex invoking @code{ggrn} 12704@cindex @code{ggrn}, invoking 12705 12706@c XXX 12707 12708 12709@c ===================================================================== 12710 12711@node grap, grefer, ggrn, Preprocessors 12712@section @code{grap} 12713@cindex @code{grap}, the program 12714 12715A free implementation of @code{grap}, written by Ted Faber, 12716is available as an extra package from the following address: 12717 12718@display 12719@url{http://www.lunabase.org/~faber/Vault/software/grap/} 12720@end display 12721 12722 12723@c ===================================================================== 12724 12725@node grefer, gsoelim, grap, Preprocessors 12726@section @code{grefer} 12727@cindex @code{refer}, the program 12728@cindex @code{grefer}, the program 12729 12730@c XXX 12731 12732@menu 12733* Invoking grefer:: 12734@end menu 12735 12736@c --------------------------------------------------------------------- 12737 12738@node Invoking grefer, , grefer, grefer 12739@subsection Invoking @code{grefer} 12740@cindex invoking @code{grefer} 12741@cindex @code{grefer}, invoking 12742 12743@c XXX 12744 12745 12746@c ===================================================================== 12747 12748@node gsoelim, , grefer, Preprocessors 12749@section @code{gsoelim} 12750@cindex @code{soelim}, the program 12751@cindex @code{gsoelim}, the program 12752 12753@c XXX 12754 12755@menu 12756* Invoking gsoelim:: 12757@end menu 12758 12759@c --------------------------------------------------------------------- 12760 12761@node Invoking gsoelim, , gsoelim, gsoelim 12762@subsection Invoking @code{gsoelim} 12763@cindex invoking @code{gsoelim} 12764@cindex @code{gsoelim}, invoking 12765 12766@c XXX 12767 12768 12769 12770@c ===================================================================== 12771@c ===================================================================== 12772 12773@node Output Devices, File formats, Preprocessors, Top 12774@chapter Output Devices 12775@cindex output devices 12776@cindex devices for output 12777 12778@c XXX 12779 12780@menu 12781* Special Characters:: 12782* grotty:: 12783* grops:: 12784* grodvi:: 12785* grolj4:: 12786* grolbp:: 12787* grohtml:: 12788* gxditview:: 12789@end menu 12790 12791 12792@c ===================================================================== 12793 12794@node Special Characters, grotty, Output Devices, Output Devices 12795@section Special Characters 12796@cindex special characters 12797@cindex characters, special 12798 12799@c XXX 12800 12801@xref{Font Files}. 12802 12803 12804@c ===================================================================== 12805 12806@node grotty, grops, Special Characters, Output Devices 12807@section @code{grotty} 12808@cindex @code{grotty}, the program 12809 12810@c XXX 12811 12812@menu 12813* Invoking grotty:: 12814@end menu 12815 12816@c --------------------------------------------------------------------- 12817 12818@node Invoking grotty, , grotty, grotty 12819@subsection Invoking @code{grotty} 12820@cindex invoking @code{grotty} 12821@cindex @code{grotty}, invoking 12822 12823@c XXX 12824 12825@c The following is no longer true; fix and extend it. 12826 12827@c @pindex less 12828@c @cindex Teletype 12829@c @cindex ISO 6249 SGR 12830@c @cindex terminal control sequences 12831@c @cindex control sequences, for terminals 12832@c For TTY output devices, underlining is done by emitting sequences of 12833@c @samp{_} and @samp{\b} (the backspace character) before the actual 12834@c character. Literally, this is printing an underline character, then 12835@c moving back one character position, and printing the actual character 12836@c at the same position as the underline character (similar to a 12837@c typewriter). Usually, a modern terminal can't interpret this (and the 12838@c original Teletype machines for which this sequence was appropriate are 12839@c no longer in use). You need a pager program like @code{less} which 12840@c translates this into ISO 6429 SGR sequences to control terminals. 12841 12842 12843@c ===================================================================== 12844 12845@node grops, grodvi, grotty, Output Devices 12846@section @code{grops} 12847@cindex @code{grops}, the program 12848 12849@c XXX 12850 12851@menu 12852* Invoking grops:: 12853* Embedding PostScript:: 12854@end menu 12855 12856@c --------------------------------------------------------------------- 12857 12858@node Invoking grops, Embedding PostScript, grops, grops 12859@subsection Invoking @code{grops} 12860@cindex invoking @code{grops} 12861@cindex @code{grops}, invoking 12862 12863@c XXX 12864 12865@c --------------------------------------------------------------------- 12866 12867@node Embedding PostScript, , Invoking grops, grops 12868@subsection Embedding @sc{PostScript} 12869@cindex embedding PostScript 12870@cindex PostScript, embedding 12871 12872@c XXX 12873 12874 12875@c ===================================================================== 12876 12877@node grodvi, grolj4, grops, Output Devices 12878@section @code{grodvi} 12879@cindex @code{grodvi}, the program 12880 12881@c XXX 12882 12883@menu 12884* Invoking grodvi:: 12885@end menu 12886 12887@c --------------------------------------------------------------------- 12888 12889@node Invoking grodvi, , grodvi, grodvi 12890@subsection Invoking @code{grodvi} 12891@cindex invoking @code{grodvi} 12892@cindex @code{grodvi}, invoking 12893 12894@c XXX 12895 12896 12897@c ===================================================================== 12898 12899@node grolj4, grolbp, grodvi, Output Devices 12900@section @code{grolj4} 12901@cindex @code{grolj4}, the program 12902 12903@c XXX 12904 12905@menu 12906* Invoking grolj4:: 12907@end menu 12908 12909@c --------------------------------------------------------------------- 12910 12911@node Invoking grolj4, , grolj4, grolj4 12912@subsection Invoking @code{grolj4} 12913@cindex invoking @code{grolj4} 12914@cindex @code{grolj4}, invoking 12915 12916@c XXX 12917 12918 12919@c ===================================================================== 12920 12921@node grolbp, grohtml, grolj4, Output Devices 12922@section @code{grolbp} 12923@cindex @code{grolbp}, the program 12924 12925@c XXX 12926 12927@menu 12928* Invoking grolbp:: 12929@end menu 12930 12931@c --------------------------------------------------------------------- 12932 12933@node Invoking grolbp, , grolbp, grolbp 12934@subsection Invoking @code{grolbp} 12935@cindex invoking @code{grolbp} 12936@cindex @code{grolbp}, invoking 12937 12938@c XXX 12939 12940 12941@c ===================================================================== 12942 12943@node grohtml, gxditview, grolbp, Output Devices 12944@section @code{grohtml} 12945@cindex @code{grohtml}, the program 12946 12947@c XXX 12948 12949@menu 12950* Invoking grohtml:: 12951* grohtml specific registers and strings:: 12952@end menu 12953 12954@c --------------------------------------------------------------------- 12955 12956@node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml 12957@subsection Invoking @code{grohtml} 12958@cindex invoking @code{grohtml} 12959@cindex @code{grohtml}, invoking 12960 12961@c XXX 12962 12963@c --------------------------------------------------------------------- 12964 12965@node grohtml specific registers and strings, , Invoking grohtml, grohtml 12966@subsection @code{grohtml} specific registers and strings 12967@cindex registers specific to @code{grohtml} 12968@cindex strings specific to @code{grohtml} 12969@cindex @code{grohtml}, registers and strings 12970 12971@DefmpregList {ps4html, grohtml} 12972@DefstrListEnd {www-image-template, grohtml} 12973The registers @code{ps4html} and @code{www-image-template} are defined 12974by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in 12975the @code{troff} input, marks up the inline equations and passes the 12976result firstly to 12977 12978@Example 12979troff -Tps -rps4html=1 -dwww-image-template=@var{template} 12980@endExample 12981 12982@noindent 12983and secondly to 12984 12985@Example 12986troff -Thtml 12987@endExample 12988 12989The PostScript device is used to create all the image files, and the 12990register @code{ps4html} enables the macro sets to ignore floating 12991keeps, footers, and headings. 12992 12993The register @code{www-image-template} is set to the user specified 12994template name or the default name. 12995@endDefmpreg 12996 12997 12998@c ===================================================================== 12999 13000@node gxditview, , grohtml, Output Devices 13001@section @code{gxditview} 13002@cindex @code{gxditview}, the program 13003 13004@c XXX 13005 13006@menu 13007* Invoking gxditview:: 13008@end menu 13009 13010@c --------------------------------------------------------------------- 13011 13012@node Invoking gxditview, , gxditview, gxditview 13013@subsection Invoking @code{gxditview} 13014@cindex invoking @code{gxditview} 13015@cindex @code{gxditview}, invoking 13016 13017@c XXX 13018@c X11's xditview 13019 13020 13021 13022@c ===================================================================== 13023@c ===================================================================== 13024 13025@node File formats, Installation, Output Devices, Top 13026@chapter File formats 13027@cindex file formats 13028@cindex formats, file 13029 13030All files read and written by @code{gtroff} are text files. The 13031following two sections describe their format. 13032 13033@menu 13034* gtroff Output:: 13035* Font Files:: 13036@end menu 13037 13038 13039@c ===================================================================== 13040 13041@node gtroff Output, Font Files, File formats, File formats 13042@section @code{gtroff} Output 13043@cindex @code{gtroff}, output 13044@cindex output, @code{gtroff} 13045 13046This section describes the intermediate output format of GNU 13047@code{troff}. This output is produced by a run of @code{gtroff} 13048before it is fed into a device postprocessor program. 13049 13050As @code{groff} is a wrapper program around @code{gtroff} that 13051automatically calls a postprocessor, this output does not show up 13052normally. This is why it is called @dfn{intermediate}. 13053@code{groff} provides the option @option{-Z} to inhibit postprocessing, 13054such that the produced intermediate output is sent to standard output 13055just like calling @code{gtroff} manually. 13056 13057@cindex troff output 13058@cindex output, troff 13059@cindex intermediate output 13060@cindex output, intermediate 13061Here, the term @dfn{troff output} describes what is output by 13062@code{gtroff}, while @dfn{intermediate output} refers to the language 13063that is accepted by the parser that prepares this output for the 13064postprocessors. This parser is smarter on whitespace and implements 13065obsolete elements for compatibility, otherwise both formats are the 13066same.@footnote{The parser and postprocessor for intermediate output 13067can be found in the file@* 13068@file{@var{groff-source-dir}/src/libs/libdriver/input.cc}.} 13069 13070The main purpose of the intermediate output concept is to facilitate 13071the development of postprocessors by providing a common programming 13072interface for all devices. It has a language of its own that is 13073completely different from the @code{gtroff} language. While the 13074@code{gtroff} language is a high-level programming language for text 13075processing, the intermediate output language is a kind of low-level 13076assembler language by specifying all positions on the page for writing 13077and drawing. 13078 13079The intermediate output produced by @code{gtroff} is fairly readable, 13080while output from @acronym{AT&T} @code{troff} is rather hard to 13081understand because of strange habits that are still supported, but not 13082used any longer by @code{gtroff}. 13083 13084@menu 13085* Language Concepts:: 13086* Command Reference:: 13087* Intermediate Output Examples:: 13088* Output Language Compatibility:: 13089@end menu 13090 13091@c --------------------------------------------------------------------- 13092 13093@node Language Concepts, Command Reference, gtroff Output, gtroff Output 13094@subsection Language Concepts 13095 13096During the run of @code{gtroff}, the input data is cracked down to the 13097information on what has to be printed at what position on the intended 13098device. So the language of the intermediate output format can be quite 13099small. Its only elements are commands with and without arguments. 13100In this section, the term @dfn{command} always refers to the intermediate 13101output language, and never to the @code{gtroff} language used for document 13102formatting. There are commands for positioning and text writing, for drawing, and 13103for device controlling. 13104 13105@menu 13106* Separation:: 13107* Argument Units:: 13108* Document Parts:: 13109@end menu 13110 13111@node Separation, Argument Units, Language Concepts, Language Concepts 13112@subsubsection Separation 13113 13114@acronym{AT&T} @code{troff} output has strange requirements on whitespace. 13115The @code{gtroff} output parser, however, is smart about whitespace by 13116making it maximally optional. The whitespace characters, i.e., the 13117tab, space, and newline characters, always have a syntactical meaning. 13118They are never printable because spacing within the output is always 13119done by positioning commands. 13120 13121Any sequence of space or tab characters is treated as a single 13122@dfn{syntactical space}. It separates commands and arguments, but is 13123only required when there would occur a clashing between the command code 13124and the arguments without the space. Most often, this happens when 13125variable-length command names, arguments, argument lists, or command 13126clusters meet. Commands and arguments with a known, fixed length need 13127not be separated by syntactical space. 13128 13129A line break is a syntactical element, too. Every command argument can be 13130followed by whitespace, a comment, or a newline character. Thus a 13131@dfn{syntactical line break} is defined to consist of optional 13132syntactical space that is optionally followed by a comment, and a 13133newline character. 13134 13135The normal commands, those for positioning and text, consist of a 13136single letter taking a fixed number of arguments. For historical reasons, 13137the parser allows to stack such commands on the same line, but 13138fortunately, in @code{gtroff}'s intermediate output, every command with 13139at least one argument is followed by a line break, thus providing 13140excellent readability. 13141 13142The other commands -- those for drawing and device controlling -- 13143have a more complicated structure; some recognize long command names, 13144and some take a variable number of arguments. So all @samp{D} and 13145@samp{x} commands were designed to request a syntactical line break 13146after their last argument. Only one command, @w{@samp{x X}}, 13147has an argument that can stretch over several lines; all other 13148commands must have all of their arguments on the same line as the 13149command, i.e., the arguments may not be splitted by a line break. 13150 13151Empty lines (these are lines containing only space and/or a comment), can 13152occur everywhere. They are just ignored. 13153 13154@node Argument Units, Document Parts, Separation, Language Concepts 13155@subsubsection Argument Units 13156 13157Some commands take integer arguments that are assumed to represent 13158values in a measurement unit, but the letter for the corresponding 13159scale indicator is not written with the output command arguments. 13160Most commands assume the scale indicator @samp{u}, the basic unit of 13161the device, some use @samp{z}, the scaled point unit of the device, 13162while others, such as the color commands, expect plain integers. 13163 13164Note that single characters can have the eighth bit set, as can the 13165names of fonts and special characters. The names of characters and 13166fonts can be of arbitrary length. A character that is to be printed 13167will always be in the current font. 13168 13169A string argument is always terminated by the next whitespace 13170character (space, tab, or newline); an embedded @samp{#} character is 13171regarded as part of the argument, not as the beginning of a comment 13172command. An integer argument is already terminated by the next 13173non-digit character, which then is regarded as the first character of 13174the next argument or command. 13175 13176@node Document Parts, , Argument Units, Language Concepts 13177@subsubsection Document Parts 13178 13179A correct intermediate output document consists of two parts, the 13180@dfn{prologue} and the @dfn{body}. 13181 13182The task of the prologue is to set the general device parameters 13183using three exactly specified commands. @code{gtroff}'s prologue 13184is guaranteed to consist of the following three lines (in that order): 13185 13186@Example 13187x T @var{device} 13188x res @var{n} @var{h} @var{v} 13189x init 13190@endExample 13191 13192@noindent 13193with the arguments set as outlined in @ref{Device Control Commands}. 13194Note that the parser for the intermediate output format is able to 13195swallow additional whitespace and comments as well even in the 13196prologue. 13197 13198The body is the main section for processing the document data. 13199Syntactically, it is a sequence of any commands different from the 13200ones used in the prologue. Processing is terminated as soon as the 13201first @w{@samp{x stop}} command is encountered; the last line of any 13202@code{gtroff} intermediate output always contains such a command. 13203 13204Semantically, the body is page oriented. A new page is started by a 13205@samp{p} command. Positioning, writing, and drawing commands are 13206always done within the current page, so they cannot occur before the 13207first @samp{p} command. Absolute positioning (by the @samp{H} and 13208@samp{V} commands) is done relative to the current page; all other 13209positioning is done relative to the current location within this page. 13210 13211@c --------------------------------------------------------------------- 13212 13213@node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output 13214@subsection Command Reference 13215 13216This section describes all intermediate output commands, both from 13217@acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions. 13218 13219@menu 13220* Comment Command:: 13221* Simple Commands:: 13222* Graphics Commands:: 13223* Device Control Commands:: 13224* Obsolete Command:: 13225@end menu 13226 13227@node Comment Command, Simple Commands, Command Reference, Command Reference 13228@subsubsection Comment Command 13229 13230@table @code 13231@item #@var{anything}@angles{end of line} 13232A comment. Ignore any characters from the @samp{#} character up to 13233the next newline character. 13234 13235This command is the only possibility for commenting in the intermediate 13236output. Each comment can be preceded by arbitrary syntactical space; 13237every command can be terminated by a comment. 13238@end table 13239 13240@node Simple Commands, Graphics Commands, Comment Command, Command Reference 13241@subsubsection Simple Commands 13242 13243The commands in this subsection have a command code consisting of a 13244single character, taking a fixed number of arguments. Most of them 13245are commands for positioning and text writing. These commands are 13246smart about whitespace. Optionally, syntactical space can be inserted 13247before, after, and between the command letter and its arguments. 13248All of these commands are stackable, i.e., they can be preceded by 13249other simple commands or followed by arbitrary other commands on the 13250same line. A separating syntactical space is only necessary when two 13251integer arguments would clash or if the preceding argument ends with a 13252string argument. 13253 13254@table @code 13255@ignore 13256.if (\n[@USE_ENV_STACK] == 1) \{\ 13257.command { 13258Open a new environment by copying the actual device configuration data 13259to the environment stack. 13260. 13261The current environment is setup by the device specification and 13262manipulated by the setting commands. 13263. 13264. 13265.command } 13266Close the actual environment (opened by a preceding 13267.BR { \~command) 13268and restore the previous environment from the environment 13269stack as the actual device configuration data. 13270. 13271\} \" endif @USE_ENV_STACK 13272@end ignore 13273 13274@item C @var{xxx}@angles{whitespace} 13275Print a special character named @var{xxx}. The trailing 13276syntactical space or line break is necessary to allow glyph names 13277of arbitrary length. The glyph is printed at the current print 13278position; the glyph's size is read from the font file. The print 13279position is not changed. 13280 13281@item c @var{g} 13282Print glyph@w{ }@var{g} at the current print position;@footnote{@samp{c} 13283is actually a misnomer since it outputs a glyph.} the glyph's size is 13284read from the font file. The print position is not changed. 13285 13286@item f @var{n} 13287Set font to font number@w{ }@var{n} (a non-negative integer). 13288 13289@item H @var{n} 13290Move right to the absolute vertical position@w{ }@var{n} (a 13291non-negative integer in basic units @samp{u} relative to left edge 13292of current page. 13293 13294@item h @var{n} 13295Move @var{n} (a non-negative integer) basic units @samp{u} horizontally 13296to the right. The original @acronym{UNIX} troff manual allows negative 13297values for @var{n} also, but @code{gtroff} doesn't use this. 13298 13299@item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]} 13300Set the color for text (glyphs), line drawing, and the outline of 13301graphic objects using different color schemes; the analoguous command 13302for the filling color of graphic objects is @samp{DF}. The color 13303components are specified as integer arguments between 0 and 65536. 13304The number of color components and their meaning vary for the 13305different color schemes. These commands are generated by 13306@code{gtroff}'s escape sequence @code{\m}. No position changing. 13307These commands are a @code{gtroff} extension. 13308 13309@table @code 13310@item mc @var{cyan} @var{magenta} @var{yellow} 13311Set color using the CMY color scheme, having the 3@w{ }color components 13312@var{cyan}, @var{magenta}, and @var{yellow}. 13313 13314@item md 13315Set color to the default color value (black in most cases). 13316No component arguments. 13317 13318@item mg @var{gray} 13319Set color to the shade of gray given by the argument, an integer 13320between 0 (black) and 65536 (white). 13321 13322@item mk @var{cyan} @var{magenta} @var{yellow} @var{black} 13323Set color using the CMYK color scheme, having the 4@w{ }color components 13324@var{cyan}, @var{magenta}, @var{yellow}, and @var{black}. 13325 13326@item mr @var{red} @var{green} @var{blue} 13327Set color using the RGB color scheme, having the 3@w{ }color components 13328@var{red}, @var{green}, and @var{blue}. 13329 13330@end table 13331 13332@item N @var{n} 13333Print glyph with index@w{ }@var{n} (a non-negative integer) of the 13334current font. This command is a @code{gtroff} extension. 13335 13336@item n @var{b} @var{a} 13337Inform the device about a line break, but no positioning is done by 13338this command. In @acronym{AT&T} @code{troff}, the integer arguments 13339@var{b} and@w{ }@var{a} informed about the space before and after the 13340current line to make the intermediate output more human readable 13341without performing any action. In @code{groff}, they are just ignored, but 13342they must be provided for compatibility reasons. 13343 13344@item p @var{n} 13345Begin a new page in the outprint. The page number is set 13346to@w{ }@var{n}. This page is completely independent of pages formerly 13347processed even if those have the same page number. The vertical 13348position on the outprint is automatically set to@w{ }0. All 13349positioning, writing, and drawing is always done relative to a page, 13350so a @samp{p} command must be issued before any of these commands. 13351 13352@item s @var{n} 13353Set point size to @var{n}@w{ }scaled points (this is unit @samp{z}). 13354@acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead. 13355@xref{Output Language Compatibility}. 13356 13357@item t @var{xxx}@angles{whitespace} 13358@itemx t @var{xxx} @var{dummy-arg}@angles{whitespace} 13359Print a word, i.e., a sequence of characters @var{xxx} representing 13360output glyphs which names are single characters, terminated by 13361a space character or a line break; an optional second integer argument 13362is ignored (this allows the formatter to generate an even number of 13363arguments). The first glyph should be printed at the current 13364position, the current horizontal position should then be increased by 13365the width of the first glyph, and so on for each glyph. 13366The widths of the glyphs are read from the font file, scaled for the 13367current point size, and rounded to a multiple of the horizontal 13368resolution. Special characters cannot be printed using this command 13369(use the @samp{C} command for special characters). This command is a 13370@code{gtroff} extension; it is only used for devices whose @file{DESC} 13371file contains the @code{tcommand} keyword (@pxref{DESC File Format}). 13372 13373@item u @var{n} @var{xxx}@angles{whitespace} 13374Print word with track kerning. This is the same as the @samp{t} 13375command except that after printing each glyph, the current 13376horizontal position is increased by the sum of the width of that 13377glyph and@w{ }@var{n} (an integer in basic units @samp{u}). 13378This command is a @code{gtroff} extension; it is only used for devices 13379whose @file{DESC} file contains the @code{tcommand} keyword 13380(@pxref{DESC File Format}). 13381 13382@item V @var{n} 13383Move down to the absolute vertical position@w{ }@var{n} (a 13384non-negative integer in basic units @samp{u}) relative to upper edge 13385of current page. 13386 13387@item v @var{n} 13388Move @var{n}@w{ }basic units @samp{u} down (@var{n} is a non-negative 13389integer). The original @acronym{UNIX} troff manual allows negative 13390values for @var{n} also, but @code{gtroff} doesn't use this. 13391 13392@item w 13393Informs about a paddable white space to increase readability. 13394The spacing itself must be performed explicitly by a move command. 13395 13396@end table 13397 13398@node Graphics Commands, Device Control Commands, Simple Commands, Command Reference 13399@subsubsection Graphics Commands 13400 13401Each graphics or drawing command in the intermediate output starts 13402with the letter @samp{D}, followed by one or two characters that 13403specify a subcommand; this is followed by a fixed or variable number 13404of integer arguments that are separated by a single space character. 13405A @samp{D} command may not be followed by another command on the same line 13406(apart from a comment), so each @samp{D} command is terminated by a 13407syntactical line break. 13408 13409@code{gtroff} output follows the classical spacing rules (no space 13410between command and subcommand, all arguments are preceded by a 13411single space character), but the parser allows optional space between 13412the command letters and makes the space before the first argument 13413optional. As usual, each space can be any sequence of tab and space 13414characters. 13415 13416Some graphics commands can take a variable number of arguments. 13417In this case, they are integers representing a size measured in basic 13418units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{}, 13419@var{hn} stand for horizontal distances where positive means right, 13420negative left. The arguments called @var{v1}, @var{v2}, @dots{}, 13421@var{vn} stand for vertical distances where positive means down, 13422negative up. All these distances are offsets relative to the current 13423location. 13424 13425Unless indicated otherwise, each graphics command directly corresponds 13426to a similar @code{gtroff} @code{\D} escape sequence. @xref{Drawing 13427Requests}. 13428 13429Unknown @samp{D} commands are assumed to be device-specific. 13430Its arguments are parsed as strings; the whole information is then 13431sent to the postprocessor. 13432 13433In the following command reference, the syntax element 13434@angles{line break} means a syntactical line break as defined above. 13435 13436@table @code 13437@item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 13438Draw B-spline from current position to offset (@var{h1},@var{v1}), 13439then to offset (@var{h2},@var{v2}), if given, etc.@: up to 13440(@var{hn},@var{vn}). This command takes a variable number of argument 13441pairs; the current position is moved to the terminal point of the drawn 13442curve. 13443 13444@item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break} 13445Draw arc from current position to 13446(@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at 13447(@var{h1},@var{v1}); then move the current position to the final point 13448of the arc. 13449 13450@item DC @var{d}@angles{line break} 13451@itemx DC @var{d} @var{dummy-arg}@angles{line break} 13452Draw a solid circle using the current fill color with 13453diameter@w{ }@var{d} (integer in basic units @samp{u}) with leftmost 13454point at the current position; then move the current position to the 13455rightmost point of the circle. An optional second integer argument is 13456ignored (this allows the formatter to generate an even number of 13457arguments). This command is a @code{gtroff} extension. 13458 13459@item Dc @var{d}@angles{line break} 13460Draw circle line with diameter@w{ }@var{d} (integer in basic units 13461@samp{u}) with leftmost point at the current position; then move the 13462current position to the rightmost point of the circle. 13463 13464@item DE @var{h} @var{v}@angles{line break} 13465Draw a solid ellipse in the current fill color with a horizontal 13466diameter of@w{ }@var{h} and a vertical diameter of@w{ }@var{v} (both 13467integers in basic units @samp{u}) with the leftmost point at the 13468current position; then move to the rightmost point of the ellipse. 13469This command is a @code{gtroff} extension. 13470 13471@item De @var{h} @var{v}@angles{line break} 13472Draw an outlined ellipse with a horizontal diameter of@w{ }@var{h} 13473and a vertical diameter of@w{ }@var{v} (both integers in basic units 13474@samp{u}) with the leftmost point at current position; then move to 13475the rightmost point of the ellipse. 13476 13477@item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break} 13478Set fill color for solid drawing objects using different color 13479schemes; the analoguous command for setting the color of text, line 13480graphics, and the outline of graphic objects is @samp{m}. 13481The color components are specified as integer arguments between 0 and 1348265536. The number of color components and their meaning vary for the 13483different color schemes. These commands are generated by @code{gtroff}'s 13484escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other 13485corresponding graphics commands). No position changing. This command 13486is a @code{gtroff} extension. 13487 13488@table @code 13489@item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break} 13490Set fill color for solid drawing objects using the CMY color scheme, 13491having the 3@w{ }color components @var{cyan}, @var{magenta}, and 13492@var{yellow}. 13493 13494@item DFd@angles{line break} 13495Set fill color for solid drawing objects to the default fill color value 13496(black in most cases). No component arguments. 13497 13498@item DFg @var{gray}@angles{line break} 13499Set fill color for solid drawing objects to the shade of gray given by 13500the argument, an integer between 0 (black) and 65536 (white). 13501 13502@item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break} 13503Set fill color for solid drawing objects using the CMYK color scheme, 13504having the 4@w{ }color components @var{cyan}, @var{magenta}, @var{yellow}, 13505and @var{black}. 13506 13507@item DFr @var{red} @var{green} @var{blue}@angles{line break} 13508Set fill color for solid drawing objects using the RGB color scheme, 13509having the 3@w{ }color components @var{red}, @var{green}, and @var{blue}. 13510 13511@end table 13512 13513@item Df @var{n}@angles{line break} 13514The argument@w{ }@var{n} must be an integer in the range @math{-32767} 13515to 32767. 13516 13517@table @asis 13518@item @math{0 @LE @var{n} @LE 1000} 13519Set the color for filling solid drawing objects to a shade of gray, 13520where 0 corresponds to solid white, 1000 (the default) to solid black, 13521and values in between to intermediate shades of gray; this is 13522obsoleted by command @samp{DFg}. 13523 13524@item @math{@var{n} @LT 0} or @math{@var{n} @LT 1000} 13525Set the filling color to the color that is currently being used for 13526the text and the outline, see command @samp{m}. For example, the 13527command sequence 13528 13529@Example 13530mg 0 0 65536 13531Df -1 13532@endExample 13533 13534@noindent 13535sets all colors to blue. 13536 13537@end table 13538 13539@noindent 13540No position changing. This command is a @code{gtroff} extension. 13541 13542@item Dl @var{h} @var{v}@angles{line break} 13543Draw line from current position to offset (@var{h},@var{v}) (integers 13544in basic units @samp{u}); then set current position to the end of the 13545drawn line. 13546 13547@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 13548Draw a polygon line from current position to offset (@var{h1},@var{v1}), 13549from there to offset (@var{h2},@var{v2}), etc.@: up to offset 13550(@var{hn},@var{vn}), and from there back to the starting position. 13551For historical reasons, the position is changed by adding the sum of 13552all arguments with odd index to the actual horizontal position and the 13553even ones to the vertical position. Although this doesn't make sense 13554it is kept for compatibility. 13555@ignore 13556As the polygon is closed, the end of drawing is the starting point, so 13557the position doesn't change. 13558@end ignore 13559This command is a @code{gtroff} extension. 13560 13561@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 13562Draw a solid polygon in the current fill color rather than an outlined 13563polygon, using the same arguments and positioning as the corresponding 13564@samp{Dp} command. 13565@ignore 13566No position changing. 13567@end ignore 13568This command is a @code{gtroff} extension. 13569 13570@item Dt @var{n}@angles{line break} 13571Set the current line thickness to@w{ }@var{n} (an integer in basic 13572units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the 13573smallest available line thickness; if @math{@var{n}<0} set the line 13574thickness proportional to the point size (this is the default before 13575the first @samp{Dt} command was specified). For historical reasons, 13576the horizontal position is changed by adding the argument to the actual 13577horizontal position, while the vertical position is not changed. 13578Although this doesn't make sense it is kept for compatibility. 13579@ignore 13580No position changing. 13581@end ignore 13582This command is a @code{gtroff} extension. 13583 13584@end table 13585 13586@node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference 13587@subsubsection Device Control Commands 13588 13589Each device control command starts with the letter @samp{x}, 13590followed by a space character (optional or arbitrary space or tab in 13591@code{gtroff}) and a subcommand letter or word; each argument (if any) 13592must be preceded by a syntactical space. All @samp{x} commands are 13593terminated by a syntactical line break; no device control command can 13594be followed by another command on the same line (except a comment). 13595 13596The subcommand is basically a single letter, but to increase 13597readability, it can be written as a word, i.e., an arbitrary sequence 13598of characters terminated by the next tab, space, or newline character. 13599All characters of the subcommand word but the first are simply ignored. 13600For example, @code{gtroff} outputs the initialization command 13601@w{@samp{x i}} as @w{@samp{x init}} and the resolution command 13602@w{@samp{x r}} as @w{@samp{x res}}. 13603 13604In the following, the syntax element @angles{line break} means a 13605syntactical line break (@pxref{Separation}). 13606 13607@table @code 13608@item xF @var{name}@angles{line break} 13609The @samp{F} stands for @var{Filename}. 13610 13611Use @var{name} as the intended name for the current file in error 13612reports. This is useful for remembering the original file name when 13613@code{gtroff} uses an internal piping mechanism. The input file is 13614not changed by this command. This command is a @code{gtroff} extension. 13615 13616@item xf @var{n} @var{s}@angles{line break} 13617The @samp{f} stands for @var{font}. 13618 13619Mount font position@w{ }@var{n} (a non-negative integer) with font 13620named@w{ }@var{s} (a text word). @xref{Font Positions}. 13621 13622@item xH @var{n}@angles{line break} 13623The @samp{H} stands for @var{Height}. 13624 13625Set glyph height to@w{ }@var{n} (a positive integer in scaled 13626points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points 13627(@samp{p}) instead. @xref{Output Language Compatibility}. 13628 13629@item xi@angles{line break} 13630The @samp{i} stands for @var{init}. 13631 13632Initialize device. This is the third command of the prologue. 13633 13634@item xp@angles{line break} 13635The @samp{p} stands for @var{pause}. 13636 13637Parsed but ignored. The original @acronym{UNIX} troff manual writes 13638 13639@display 13640pause device, can be restarted 13641@end display 13642 13643@item xr @var{n} @var{h} @var{v}@angles{line break} 13644The @samp{r} stands for @var{resolution}. 13645 13646Resolution is@w{ }@var{n}, while @var{h} is the minimal horizontal 13647motion, and @var{v} the minimal vertical motion possible with this 13648device; all arguments are positive integers in basic units @samp{u} 13649per inch. This is the second command of the prologue. 13650 13651@item xS @var{n}@angles{line break} 13652The @samp{S} stands for @var{Slant}. 13653 13654Set slant to@w{ }@var{n} (an integer in basic units @samp{u}). 13655 13656@item xs@angles{line break} 13657The @samp{s} stands for @var{stop}. 13658 13659Terminates the processing of the current file; issued as the last 13660command of any intermediate troff output. 13661 13662@item xt@angles{line break} 13663The @samp{t} stands for @var{trailer}. 13664 13665Generate trailer information, if any. In @var{gtroff}, this is 13666actually just ignored. 13667 13668@item xT @var{xxx}@angles{line break} 13669The @samp{T} stands for @var{Typesetter}. 13670 13671Set name of device to word @var{xxx}, a sequence of characters ended 13672by the next white space character. The possible device names coincide 13673with those from the @code{groff} @option{-T} option. This is the first 13674command of the prologue. 13675 13676@item xu @var{n}@angles{line break} 13677The @samp{u} stands for @var{underline}. 13678 13679Configure underlining of spaces. If @var{n} is@w{ }1, start 13680underlining of spaces; if @var{n} is@w{ }0, stop underlining of spaces. 13681This is needed for the @code{cu} request in nroff mode and is ignored 13682otherwise. This command is a @code{gtroff} extension. 13683 13684@item xX @var{anything}@angles{line break} 13685The @samp{x} stands for @var{X-escape}. 13686 13687Send string @var{anything} uninterpreted to the device. If the line 13688following this command starts with a @samp{+} character this line is 13689interpreted as a continuation line in the following sense. The 13690@samp{+} is ignored, but a newline character is sent instead to the 13691device, the rest of the line is sent uninterpreted. The same applies 13692to all following lines until the first character of a line is not a 13693@samp{+} character. This command is generated by the @code{gtroff} 13694escape sequence @code{\X}. The line-continuing feature is a 13695@code{gtroff} extension. 13696 13697@end table 13698 13699@node Obsolete Command, , Device Control Commands, Command Reference 13700@subsubsection Obsolete Command 13701In @acronym{AT&T} @code{troff} output, the writing of a single 13702glyph is mostly done by a very strange command that combines a 13703horizontal move and a single character giving the glyph name. It 13704doesn't have a command code, but is represented by a 3-character 13705argument consisting of exactly 2@w{ }digits and a character. 13706 13707@table @asis 13708@item @var{dd}@var{g} 13709Move right @var{dd} (exactly two decimal digits) basic units @samp{u}, 13710then print glyph@w{ }@var{g} (represented as a single character). 13711 13712In @code{gtroff}, arbitrary syntactical space around and within this 13713command is allowed to be added. Only when a preceding command on the 13714same line ends with an argument of variable length a separating space 13715is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these 13716and other commands are used, mostly without spaces; this made such output 13717almost unreadable. 13718 13719@end table 13720 13721For modern high-resolution devices, this command does not make sense 13722because the width of the glyphs can become much larger than two 13723decimal digits. In @code{gtroff}, this is only used for the devices 13724@code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other 13725devices, the commands @samp{t} and @samp{u} provide a better 13726functionality. 13727 13728@c --------------------------------------------------------------------- 13729 13730@node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output 13731@subsection Intermediate Output Examples 13732 13733This section presents the intermediate output generated from the same 13734input for three different devices. The input is the sentence 13735@samp{hell world} fed into @code{gtroff} on the command line. 13736 13737@table @asis 13738@item High-resolution device @code{ps} 13739 13740This is the standard output of @code{gtroff} if no @option{-T} option 13741is given. 13742 13743@example 13744@group 13745shell> echo "hell world" | groff -Z -T ps 13746 13747x T ps 13748x res 72000 1 1 13749x init 13750@end group 13751p1 13752x font 5 TR 13753f5 13754s10000 13755V12000 13756H72000 13757thell 13758wh2500 13759tw 13760H96620 13761torld 13762n12000 0 13763@group 13764x trailer 13765V792000 13766x stop 13767@end group 13768@end example 13769 13770@noindent 13771This output can be fed into @code{grops} to get its representation as 13772a PostScript file. 13773 13774@item Low-resolution device @code{latin1} 13775 13776This is similar to the high-resolution device except that the 13777positioning is done at a minor scale. Some comments (lines starting 13778with @samp{#}) were added for clarification; they were not generated 13779by the formatter. 13780 13781@example 13782@group 13783shell> echo "hell world" | groff -Z -T latin1 13784 13785# prologue 13786x T latin1 13787x res 240 24 40 13788x init 13789@end group 13790# begin a new page 13791p1 13792# font setup 13793x font 1 R 13794f1 13795s10 13796# initial positioning on the page 13797V40 13798H0 13799# write text `hell' 13800thell 13801# inform about space, and issue a horizontal jump 13802wh24 13803# write text `world' 13804tworld 13805# announce line break, but do nothing because ... 13806n40 0 13807@group 13808# ... the end of the document has been reached 13809x trailer 13810V2640 13811x stop 13812@end group 13813@end example 13814 13815@noindent 13816This output can be fed into @code{grotty} to get a formatted text 13817document. 13818 13819@item @acronym{AT&T} @code{troff} output 13820Since a computer monitor has a very low resolution compared to modern 13821printers the intermediate output for the X@w{ }Window devices can use 13822the jump-and-write command with its 2-digit displacements. 13823 13824@example 13825@group 13826shell> echo "hell world" | groff -Z -T X100 13827 13828x T X100 13829x res 100 1 1 13830x init 13831@end group 13832p1 13833x font 5 TR 13834f5 13835s10 13836V16 13837H100 13838# write text with jump-and-write commands 13839ch07e07l03lw06w11o07r05l03dh7 13840n16 0 13841@group 13842x trailer 13843V1100 13844x stop 13845@end group 13846@end example 13847 13848@noindent 13849This output can be fed into @code{xditview} or @code{gxditview} 13850for displaying in@w{ }X. 13851 13852Due to the obsolete jump-and-write command, the text clusters in the 13853@acronym{AT&T} @code{troff} output are almost unreadable. 13854 13855@end table 13856 13857@c --------------------------------------------------------------------- 13858 13859@node Output Language Compatibility, , Intermediate Output Examples, gtroff Output 13860@subsection Output Language Compatibility 13861 13862The intermediate output language of @acronym{AT&T} @code{troff} 13863was first documented in the @acronym{UNIX} troff manual, with later 13864additions documented in @cite{A Typesetter-indenpendent TROFF}, 13865written by Brian Kernighan. 13866 13867The @code{gtroff} intermediate output format is compatible with this 13868specification except for the following features. 13869 13870@itemize @bullet 13871@item 13872The classical quasi device independence is not yet implemented. 13873 13874@item 13875The old hardware was very different from what we use today. So the 13876@code{groff} devices are also fundamentally different from the ones in 13877@acronym{AT&T} @code{troff}. For example, the @acronym{AT&T} 13878PostScript device is called @code{post} and has a resolution of only 13879720 units per inch, suitable for printers 20 years ago, while 13880@code{groff}'s @code{ps} device has a resolution of 1388172000 units per inch. Maybe, by implementing some rescaling 13882mechanism similar to the classical quasi device independence, 13883@code{groff} could emulate @acronym{AT&T}'s @code{post} device. 13884 13885@item 13886The B-spline command @samp{D~} is correctly handled by the 13887intermediate output parser, but the drawing routines aren't 13888implemented in some of the postprocessor programs. 13889 13890@item 13891The argument of the commands @samp{s} and @w{@samp{x H}} has the 13892implicit unit scaled point @samp{z} in @code{gtroff}, while 13893@acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an 13894incompatibility but a compatible extension, for both units coincide 13895for all devices without a @code{sizescale} parameter in the @file{DESC} 13896file, including all postprocessors from @acronym{AT&T} and 13897@code{groff}'s text devices. The few @code{groff} devices with 13898a @code{sizescale} parameter either do not exist for @acronym{AT&T} 13899@code{troff}, have a different name, or seem to have a different 13900resolution. So conflicts are very unlikely. 13901 13902@item 13903The position changing after the commands @samp{Dp}, @samp{DP}, and 13904@samp{Dt} is illogical, but as old versions of @code{gtroff} used this 13905feature it is kept for compatibility reasons. 13906 13907@ignore 13908Temporarily, there existed some confusion on the positioning after the 13909@samp{D} commands that are groff extensions. This has been clarified 13910by establishing the classical rule for all @code{groff} drawing commands: 13911 13912@itemize 13913@item 13914The position after a graphic object has been drawn is at its end; 13915for circles and ellipses, the `end' is at the right side. 13916 13917@item 13918From this, the positionings specified for the drawing commands above 13919follow quite naturally. 13920@end itemize 13921@end ignore 13922 13923@end itemize 13924 13925 13926@c ===================================================================== 13927 13928@node Font Files, , gtroff Output, File formats 13929@section Font Files 13930@cindex font files 13931@cindex files, font 13932 13933The @code{gtroff} font format is roughly a superset of the 13934@code{ditroff} font format (as used in later versions of @acronym{AT&T} 13935@code{troff} and its descendants). Unlike the @code{ditroff} font 13936format, there is no associated binary format; all files are text 13937files.@footnote{Plan@w{ }9 @code{troff} has also abandoned the binary 13938format.} The font files for device @var{name} are stored in a directory 13939@file{dev@var{name}}. There are two types of file: a device description 13940file called @file{DESC} and for each font@w{ }@var{f} a font file 13941called@w{ }@file{@var{f}}. 13942 13943@menu 13944* DESC File Format:: 13945* Font File Format:: 13946@end menu 13947 13948@c --------------------------------------------------------------------- 13949 13950@node DESC File Format, Font File Format, Font Files, Font Files 13951@subsection @file{DESC} File Format 13952@cindex @file{DESC} file, format 13953@cindex font description file, format 13954@cindex format of font description file 13955@pindex DESC@r{ file format} 13956 13957The @file{DESC} file can contain the following types of line. Except 13958for the @code{charset} keyword which must comes last (if at all), the 13959order of the lines is not important. 13960 13961@table @code 13962@item res @var{n} 13963@kindex res 13964There are @var{n}@w{ }machine units per inch. 13965 13966@item hor @var{n} 13967@kindex hor 13968The horizontal resolution is @var{n}@w{ }machine units. 13969 13970@item vert @var{n} 13971@kindex vert 13972The vertical resolution is @var{n}@w{ }machine units. 13973 13974@item sizescale @var{n} 13975@kindex sizescale 13976The scale factor for point sizes. By default this has a value of@w{ }1. 13977One scaled point is equal to one point/@var{n}. The arguments to the 13978@code{unitwidth} and @code{sizes} commands are given in scaled points. 13979@xref{Fractional Type Sizes}, for more information. 13980 13981@item unitwidth @var{n} 13982@kindex unitwidth 13983Quantities in the font files are given in machine units for fonts whose 13984point size is @var{n}@w{ }scaled points. 13985 13986@item prepro @var{program} 13987@kindex prepro 13988Call @var{program} as a preprocessor. Currently, this keyword is used 13989by @code{groff} with option @option{-Thtml} only. 13990 13991@item postpro @var{program} 13992@kindex postpro 13993Call @var{program} as a postprocessor. For example, the line 13994 13995@Example 13996postpro grodvi 13997@endExample 13998 13999@noindent 14000in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi} 14001if option @option{-Tdvi} is given (and @option{-Z} isn't used). 14002 14003@item tcommand 14004@kindex tcommand 14005This means that the postprocessor can handle the @samp{t} and @samp{u} 14006intermediate output commands. 14007 14008@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 14009@kindex sizes 14010This means that the device has fonts at @var{s1}, @var{s2}, @dots{} 14011@var{sn} scaled points. The list of sizes must be terminated by@w{ }0 14012(this is digit zero). Each @var{si} can also be a range of sizes 14013@var{m}-@var{n}. The list can extend over more than one line. 14014 14015@item styles @var{S1} @var{S2} @dots{} @var{Sm} 14016@kindex styles 14017The first @var{m}@w{ }font positions are associated with styles 14018@var{S1} @dots{} @var{Sm}. 14019 14020@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 14021@kindex fonts 14022Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 14023@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 14024styles. This command may extend over more than one line. A font name 14025of@w{ }0 means no font is mounted on the corresponding font position. 14026 14027@item family @var{fam} 14028@kindex family 14029The default font family is @var{fam}. 14030 14031@item use_charnames_in_special 14032@kindex use_charnames_in_special 14033This command indicates that @code{gtroff} should encode special 14034characters inside special commands. Currently, this is only used 14035by the @acronym{HTML} output device. @xref{Postprocessor Access}. 14036 14037@item papersize @var{string} @dots{} 14038@kindex papersize 14039Select a paper size. Valid values for @var{string} are the ISO paper 14040types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7}, 14041@code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter}, 14042@code{legal}, @code{tabloid}, @code{ledger}, @code{statement}, 14043@code{executive}, @code{com10}, and @code{monarch}. Case is not significant 14044for @var{string} if it holds predefined paper types. Alternatively, 14045@var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file 14046can be opened, @code{groff} reads the first line and tests for the above 14047paper sizes. Finally, @var{string} can be a custom paper size in the format 14048@code{@var{length},@var{width}} (no spaces before and after the comma). 14049Both @var{length} and @var{width} must have a unit appended; valid values 14050are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and 14051@samp{P} for picas. Example: @code{12c,235p}. An argument which starts 14052with a digit is always treated as a custom paper format. @code{papersize} 14053sets both the vertical and horizontal dimension of the output medium. 14054 14055More than one argument can be specified; @code{groff} scans from left to 14056right and uses the first valid paper specification. 14057 14058@item pass_filenames 14059@kindex pass_filenames 14060Tell @code{gtroff} to emit the name of the source file currently 14061being processed. This is achieved by the intermediate output command 14062@samp{F}. Currently, this is only used by the @acronym{HTML} output 14063device. 14064 14065@item print @var{program} 14066@kindex print 14067Use @var{program} as a spooler program for printing. If omitted, 14068the @option{-l} and @option{-L} options of @code{groff} are ignored. 14069 14070@item charset 14071@kindex charset 14072This line and everything following in the file are ignored. It is 14073allowed for the sake of backwards compatibility. 14074@end table 14075 14076The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines 14077are mandatory. Other commands are ignored by @code{gtroff} but may be 14078used by postprocessors to store arbitrary information about the device 14079in the @file{DESC} file. 14080 14081@kindex spare1 14082@kindex spare2 14083@kindex biggestfont 14084Here a list of obsolete keywords which are recognized by @code{groff} 14085but completely ignored: @code{spare1}, @code{spare2}, 14086@code{biggestfont}. 14087 14088 14089@c --------------------------------------------------------------------- 14090 14091@node Font File Format, , DESC File Format, Font Files 14092@subsection Font File Format 14093@cindex font file, format 14094@cindex font description file, format 14095@cindex format of font files 14096@cindex format of font description files 14097 14098A @dfn{font file}, also (and probably better) called a @dfn{font 14099description file}, has two sections. The first section is a sequence 14100of lines each containing a sequence of blank delimited words; the first 14101word in the line is a key, and subsequent words give a value for that 14102key. 14103 14104@table @code 14105@item name @var{f} 14106@kindex name 14107The name of the font is@w{ }@var{f}. 14108 14109@item spacewidth @var{n} 14110@kindex spacewidth 14111The normal width of a space is@w{ }@var{n}. 14112 14113@item slant @var{n} 14114@kindex slant 14115The glyphs of the font have a slant of @var{n}@w{ }degrees. 14116(Positive means forward.) 14117 14118@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 14119@kindex ligatures 14120Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 14121possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 14122@samp{ffl}. For backwards compatibility, the list of ligatures may be 14123terminated with a@w{ }0. The list of ligatures may not extend over more 14124than one line. 14125 14126@item special 14127@cindex special fonts 14128@kindex special 14129The font is @dfn{special}; this means that when a glyph is requested 14130that is not present in the current font, it is searched for in any 14131special fonts that are mounted. 14132@end table 14133 14134Other commands are ignored by @code{gtroff} but may be used by 14135postprocessors to store arbitrary information about the font in the font 14136file. 14137 14138@cindex comments in font files 14139@cindex font files, comments 14140@kindex # 14141The first section can contain comments which start with the @samp{#} 14142character and extend to the end of a line. 14143 14144The second section contains one or two subsections. It must contain a 14145@code{charset} subsection and it may also contain a @code{kernpairs} 14146subsection. These subsections can appear in any order. Each 14147subsection starts with a word on a line by itself. 14148 14149@kindex charset 14150The word @code{charset} starts the character set 14151subsection.@footnote{This keyword is misnamed since it starts a list 14152of ordered glyphs, not characters.} The @code{charset} line is 14153followed by a sequence of lines. Each line gives information for one 14154glyph. A line comprises a number of fields separated by blanks or 14155tabs. The format is 14156 14157@quotation 14158@var{name} @var{metrics} @var{type} @var{code} 14159[@var{entity-name}] [@code{--} @var{comment}] 14160@end quotation 14161 14162@cindex 8-bit input 14163@cindex input, 8-bit 14164@cindex accessing unnamed glyphs with @code{\N} 14165@cindex unnamed glyphs, accessing with @code{\N} 14166@cindex characters, unnamed, accessing with @code{\N} 14167@cindex glyphs, unnamed, accessing with @code{\N} 14168@kindex --- 14169@noindent 14170@var{name} identifies the glyph name@footnote{The distinction between 14171input, characters, and output, glyphs, is not clearly separated in the 14172terminology of @code{groff}; for example, the @code{char} request 14173should be called @code{glyph} since it defines an output entity.}: 14174If @var{name} is a single character@w{ }@var{c} then it corresponds 14175to the @code{gtroff} input character@w{ }@var{c}; if it is of the form 14176@samp{\@var{c}} where @var{c} is a single character, then it 14177corresponds to the special character @code{\[@var{c}]}; otherwise it 14178corresponds to the special character @samp{\[@var{name}]}. If it 14179is exactly two characters @var{xx} it can be entered as 14180@samp{\(@var{xx}}. Note that single-letter special characters can't 14181be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which 14182is identical to @code{\[-]}. 14183 14184@code{gtroff} supports 8-bit input characters; however some utilities 14185have difficulties with eight-bit characters. For this reason, there is 14186a convention that the entity name @samp{char@var{n}} is equivalent to 14187the single input character whose code is@w{ }@var{n}. For example, 14188@samp{char163} would be equivalent to the character with code@w{ }163 14189which is the pounds sterling sign in the @w{ISO Latin-1} character set. 14190You shouldn't use @samp{char@var{n}} entities in font description files 14191since they are related to input, not output. Otherwise, you get 14192hard-coded connections between input and output encoding which 14193prevents use of different (input) character sets. 14194 14195The name @samp{---} is special and indicates that the glyph is 14196unnamed; such glyphs can only be used by means of the @code{\N} 14197escape sequence in @code{gtroff}. 14198 14199The @var{type} field gives the glyph type: 14200 14201@table @code 14202@item 1 14203the glyph has a descender, for example, @samp{p}; 14204 14205@item 2 14206the glyph has an ascender, for example, @samp{b}; 14207 14208@item 3 14209the glyph has both an ascender and a descender, for example, @samp{(}. 14210@end table 14211 14212The @var{code} field gives the code which the postprocessor uses to 14213print the glyph. The glyph can also be input to @code{gtroff} 14214using this code by means of the @code{\N} escape sequence. @var{code} 14215can be any integer. If it starts with @samp{0} it is interpreted as 14216octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 14217hexadecimal. Note, however, that the @code{\N} escape sequence only 14218accepts a decimal integer. 14219 14220The @var{entity-name} field gives an @acronym{ASCII} string 14221identifying the glyph which the postprocessor uses to print the 14222@code{gtroff} glyph @var{name}. This field is optional and has been 14223introduced so that the @acronym{HTML} device driver can encode its 14224character set. For example, the glyph @samp{\[Po]} is 14225represented as @samp{£} in @acronym{HTML} 4.0. 14226 14227Anything on the line after the @var{entity-name} field resp.@: after 14228@samp{--} will be ignored. 14229 14230The @var{metrics} field has the form: 14231 14232@display 14233@group 14234@var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction} 14235 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]] 14236@end group 14237@end display 14238 14239@noindent 14240There must not be any spaces between these subfields (it has been split 14241here into two lines for better legibility only). Missing subfields are 14242assumed to be@w{ }0. The subfields are all decimal integers. Since 14243there is no associated binary format, these values are not required to 14244fit into a variable of type @samp{char} as they are in @code{ditroff}. 14245The @var{width} subfield gives the width of the glyph. The @var{height} 14246subfield gives the height of the glyph (upwards is positive); if a 14247glyph does not extend above the baseline, it should be given a zero 14248height, rather than a negative height. The @var{depth} subfield gives 14249the depth of the glyph, that is, the distance from the baseline to the 14250lowest point below the baseline to which the glyph extends (downwards is 14251positive); if a glyph does not extend below the baseline, it should be 14252given a zero depth, rather than a negative depth. The 14253@var{italic-correction} subfield gives the amount of space that should 14254be added after the glyph when it is immediately to be followed by a 14255glyph from a roman font. The @var{left-italic-correction} subfield 14256gives the amount of space that should be added before the glyph when it 14257is immediately to be preceded by a glyph from a roman font. The 14258@var{subscript-correction} gives the amount of space that should be 14259added after a glyph before adding a subscript. This should be less 14260than the italic correction. 14261 14262A line in the @code{charset} section can also have the format 14263 14264@Example 14265@var{name} " 14266@endExample 14267 14268@noindent 14269This indicates that @var{name} is just another name for the glyph 14270mentioned in the preceding line. 14271 14272@kindex kernpairs 14273The word @code{kernpairs} starts the kernpairs section. This contains a 14274sequence of lines of the form: 14275 14276@Example 14277@var{c1} @var{c2} @var{n} 14278@endExample 14279 14280@noindent 14281This means that when glyph @var{c1} appears next to glyph @var{c2} 14282the space between them should be increased by@w{ }@var{n}. Most 14283entries in the kernpairs section have a negative value for@w{ }@var{n}. 14284 14285 14286 14287@c ===================================================================== 14288@c ===================================================================== 14289 14290@node Installation, Copying This Manual, File formats, Top 14291@chapter Installation 14292@cindex installation 14293 14294@c XXX 14295 14296 14297 14298@c ===================================================================== 14299@c ===================================================================== 14300 14301@node Copying This Manual, Request Index, Installation, Top 14302@appendix Copying This Manual 14303 14304@menu 14305* GNU Free Documentation License:: License for copying this manual. 14306@end menu 14307 14308@include fdl.texi 14309 14310 14311 14312@c ===================================================================== 14313@c ===================================================================== 14314 14315@node Request Index, Escape Index, Copying This Manual, Top 14316@appendix Request Index 14317 14318Requests appear without the leading control character (normally either 14319@samp{.} or @samp{'}). 14320 14321@printindex rq 14322 14323 14324 14325@c ===================================================================== 14326@c ===================================================================== 14327 14328@node Escape Index, Operator Index, Request Index, Top 14329@appendix Escape Index 14330 14331Any escape sequence @code{\@var{X}} with @var{X} not in the list below 14332emits a warning, printing glyph @var{X}. 14333 14334@printindex es 14335 14336 14337 14338@c ===================================================================== 14339@c ===================================================================== 14340 14341@node Operator Index, Register Index, Escape Index, Top 14342@appendix Operator Index 14343 14344@printindex op 14345 14346 14347 14348@c ===================================================================== 14349@c ===================================================================== 14350 14351@node Register Index, Macro Index, Operator Index, Top 14352@appendix Register Index 14353 14354The macro package or program a specific register belongs to is appended in 14355brackets. 14356 14357A register name@w{ }@code{x} consisting of exactly one character can be 14358accessed as @samp{\nx}. A register name @code{xx} consisting of exactly 14359two characters can be accessed as @samp{\n(xx}. Register names @code{xxx} 14360of any length can be accessed as @samp{\n[xxx]}. 14361 14362@printindex vr 14363 14364 14365 14366@c ===================================================================== 14367@c ===================================================================== 14368 14369@node Macro Index, String Index, Register Index, Top 14370@appendix Macro Index 14371 14372The macro package a specific macro belongs to is appended in brackets. 14373They appear without the leading control character (normally @samp{.}). 14374 14375@printindex ma 14376 14377 14378 14379@c ===================================================================== 14380@c ===================================================================== 14381 14382@node String Index, Glyph Name Index, Macro Index, Top 14383@appendix String Index 14384 14385The macro package or program a specific string belongs to is appended in 14386brackets. 14387 14388A string name@w{ }@code{x} consisting of exactly one character can be 14389accessed as @samp{\*x}. A string name @code{xx} consisting of exactly 14390two characters can be accessed as @samp{\*(xx}. String names @code{xxx} 14391of any length can be accessed as @samp{\*[xxx]}. 14392 14393 14394@printindex st 14395 14396 14397 14398@c ===================================================================== 14399@c ===================================================================== 14400 14401@node Glyph Name Index, Font File Keyword Index, String Index, Top 14402@appendix Glyph Name Index 14403 14404A glyph name @code{xx} consisting of exactly two characters can be 14405accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 14406accessed as @samp{\[xxx]}. 14407 14408@c XXX 14409 14410 14411 14412@c ===================================================================== 14413@c ===================================================================== 14414 14415@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 14416@appendix Font File Keyword Index 14417 14418@printindex ky 14419 14420 14421 14422@c ===================================================================== 14423@c ===================================================================== 14424 14425@node Program and File Index, Concept Index, Font File Keyword Index, Top 14426@appendix Program and File Index 14427 14428@printindex pg 14429 14430 14431 14432@c ===================================================================== 14433@c ===================================================================== 14434 14435@node Concept Index, , Program and File Index, Top 14436@appendix Concept Index 14437 14438@printindex cp 14439 14440 14441@bye 14442