groff.texinfo revision 114402
1\input texinfo @c -*-texinfo-*- 2 3@c 4@c Please convert this manual with `texi2dvi -e groff.texinfo' due to 5@c problems in texinfo regarding expansion of user-defined macros. 6@c 7@c You need texinfo 4.3 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.19. 25 26Copyright @copyright{} 1994-2000, 2001, 2002, 2003 27Free Software Foundation, Inc. 28 29@quotation 30Permission is granted to copy, distribute and/or modify this document 31under the terms of the GNU Free Documentation License, Version 1.1 or 32any later version published by the Free Software Foundation; with no 33Invariant Sections, with the Front-Cover texts being `A GNU Manual,'' 34and with the Back-Cover Texts as in (a) below. A copy of the 35license is included in the section entitled `GNU Free Documentation 36License.'' 37 38(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify 39this GNU Manual, like GNU software. Copies published by the Free 40Software Foundation raise funds for GNU development.'' 41@end quotation 42@end copying 43 44 45@c We use the following indices: 46@c 47@c cindex: concepts 48@c rqindex: requests 49@c esindex: escapes 50@c vindex: registers 51@c kindex: commands in font files 52@c pindex: programs and files 53@c tindex: environment variables 54@c maindex: macros 55@c stindex: strings 56@c opindex: operators 57@c 58@c tindex and cindex are merged. 59 60@defcodeindex rq 61@defcodeindex es 62@defcodeindex ma 63@defcodeindex st 64@defcodeindex op 65@syncodeindex tp cp 66 67 68@c To avoid uppercasing in @deffn while converting to info, we define 69@c our special @Var{}. 70@c 71@c Due to a (not officially documented) `feature' in makeinfo 4.0, 72@c macros are not expanded in @deffn (but the macro definition is 73@c properly removed), so we have to define @Var{} directly in TeX also. 74 75@macro Var{arg} 76\arg\ 77@end macro 78@tex 79\gdef\Var#1{\var{#1}} 80@end tex 81 82 83@c To assure correct HTML translation, some ugly hacks are necessary. 84@c While processing a @def... request, the HTML translator looks at the 85@c next line to decide whether it should start indentation or not. If 86@c it is something starting with @def... (e.g. @deffnx), it doesn't. 87@c So we must assure during macro expansion that a @def... is seen. 88@c 89@c The following macros have to be used: 90@c 91@c One item: 92@c 93@c @Def... 94@c 95@c Two items: 96@c 97@c @Def...List 98@c @Def...ListEnd 99@c 100@c More than two: 101@c 102@c @Def...List 103@c @Def...Item 104@c @Def...Item 105@c ... 106@c @Def...ListEnd 107@c 108@c The definition block must end with 109@c 110@c @endDef... 111@c 112@c The above is valid for texinfo 4.0f and above. 113 114 115@c a dummy macro to assure the `@def...' 116 117@macro defdummy 118@end macro 119 120 121@c definition of requests 122 123@macro Defreq{name, arg} 124@deffn Request @t{.\name\} \arg\ 125@rqindex \name\ 126@end macro 127 128@macro DefreqList{name, arg} 129@deffn Request @t{.\name\} \arg\ 130@defdummy 131@rqindex \name\ 132@end macro 133 134@macro DefreqItem{name, arg} 135@deffnx Request @t{.\name\} \arg\ 136@defdummy 137@rqindex \name\ 138@end macro 139 140@macro DefreqListEnd{name, arg} 141@deffnx Request @t{.\name\} \arg\ 142@rqindex \name\ 143@end macro 144 145@macro endDefreq 146@end deffn 147@end macro 148 149 150@c definition of escapes 151 152@macro Defesc{name, delimI, arg, delimII} 153@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 154@esindex \name\ 155@end macro 156 157@macro DefescList{name, delimI, arg, delimII} 158@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 159@defdummy 160@esindex \name\ 161@end macro 162 163@macro DefescItem{name, delimI, arg, delimII} 164@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 165@defdummy 166@esindex \name\ 167@end macro 168 169@macro DefescListEnd{name, delimI, arg, delimII} 170@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 171@esindex \name\ 172@end macro 173 174@macro endDefesc 175@end deffn 176@end macro 177 178 179@c definition of registers 180 181@macro Defreg{name} 182@deffn Register @t{\\n[\name\]} 183@vindex \name\ 184@end macro 185 186@macro DefregList{name} 187@deffn Register @t{\\n[\name\]} 188@defdummy 189@vindex \name\ 190@end macro 191 192@macro DefregItem{name} 193@deffnx Register @t{\\n[\name\]} 194@defdummy 195@vindex \name\ 196@end macro 197 198@macro DefregListEnd{name} 199@deffnx Register @t{\\n[\name\]} 200@vindex \name\ 201@end macro 202 203@macro endDefreg 204@end deffn 205@end macro 206 207 208@c definition of registers specific to macro packages, preprocessors, etc. 209 210@macro Defmpreg{name, package} 211@deffn Register @t{\\n[\name\]} 212@vindex \name\ @r{[}\package\@r{]} 213@end macro 214 215@macro DefmpregList{name, package} 216@deffn Register @t{\\n[\name\]} 217@defdummy 218@vindex \name\ @r{[}\package\@r{]} 219@end macro 220 221@macro DefmpregItem{name, package} 222@deffnx Register @t{\\n[\name\]} 223@defdummy 224@vindex \name\ @r{[}\package\@r{]} 225@end macro 226 227@macro DefmpregListEnd{name, package} 228@deffnx Register @t{\\n[\name\]} 229@vindex \name\ @r{[}\package\@r{]} 230@end macro 231 232@macro endDefmpreg 233@end deffn 234@end macro 235 236 237@c definition of macros 238 239@macro Defmac{name, arg, package} 240@defmac @t{.\name\} \arg\ 241@maindex \name\ @r{[}\package\@r{]} 242@end macro 243 244@macro DefmacList{name, arg, package} 245@defmac @t{.\name\} \arg\ 246@defdummy 247@maindex \name\ @r{[}\package\@r{]} 248@end macro 249 250@macro DefmacItem{name, arg, package} 251@defmacx @t{.\name\} \arg\ 252@defdummy 253@maindex \name\ @r{[}\package\@r{]} 254@end macro 255 256@macro DefmacListEnd{name, arg, package} 257@defmacx @t{.\name\} \arg\ 258@maindex \name\ @r{[}\package\@r{]} 259@end macro 260 261@macro endDefmac 262@end defmac 263@end macro 264 265 266@c definition of strings 267 268@macro Defstr{name, package} 269@deffn String @t{\\*[\name\]} 270@stindex \name\ @r{[}\package\@r{]} 271@end macro 272 273@macro DefstrList{name, package} 274@deffn String @t{\\*[\name\]} 275@defdummy 276@stindex \name\ @r{[}\package\@r{]} 277@end macro 278 279@macro DefstrItem{name, package} 280@deffnx String @t{\\*[\name\]} 281@defdummy 282@stindex \name\ @r{[}\package\@r{]} 283@end macro 284 285@macro DefstrListEnd{name, package} 286@deffnx String @t{\\*[\name\]} 287@stindex \name\ @r{[}\package\@r{]} 288@end macro 289 290@macro endDefstr 291@end deffn 292@end macro 293 294 295@c our example macro 296 297@macro Example 298@example 299@group 300@end macro 301 302@macro endExample 303@end group 304@end example 305@end macro 306 307 308@c <text> 309 310@tex 311\gdef\angles#1{\angleleft{}\r{#1}\angleright{}} 312@end tex 313 314@macro angles{text} 315<\text\> 316@end macro 317 318 319@c a <= sign 320 321@tex 322\gdef\LE{\le} 323@end tex 324 325@macro LE 326<= 327@end macro 328 329 330@c We need special parentheses and brackets: 331@c 332@c . Real parentheses in @deffn produce an error while compiling with 333@c TeX. 334@c . Real brackets use the wrong font in @deffn, overriding @t{}. 335@c 336@c Since macros aren't expanded in @deffn during -E, the following 337@c definitions are for non-TeX only. 338@c 339@c This is true for texinfo 4.0. 340 341@macro lparen 342( 343@end macro 344@macro rparen 345) 346@end macro 347@macro lbrack 348[ 349@end macro 350@macro rbrack 351] 352@end macro 353 354 355@tex 356\gdef\gobblefirst#1#2{#2} 357\gdef\putwordAppendix{\gobblefirst} 358@end tex 359 360 361@c Note: We say `Roman numerals' but `roman font'. 362 363 364@dircategory Typesetting 365@direntry 366* Groff: (groff). The GNU troff document formatting system. 367@end direntry 368 369 370@titlepage 371@title groff 372@subtitle The GNU implementation of @code{troff} 373@subtitle Edition 1.19 374@subtitle Spring 2003 375@author by Trent A.@tie{}Fisher 376@author and Werner Lemberg (@email{bug-groff@@gnu.org}) 377 378@page 379@vskip 0pt plus 1filll 380@insertcopying 381@end titlepage 382 383 384@contents 385 386@ifinfo 387@node Top, Introduction, (dir), (dir) 388@top GNU troff 389 390@insertcopying 391@end ifinfo 392 393@ifhtml 394@node Top, Introduction, (dir), (dir) 395@top GNU troff 396 397@insertcopying 398@end ifhtml 399 400@menu 401* Introduction:: 402* Invoking groff:: 403* Tutorial for Macro Users:: 404* Macro Packages:: 405* gtroff Reference:: 406* Preprocessors:: 407* Output Devices:: 408* File formats:: 409* Installation:: 410* Copying This Manual:: 411* Request Index:: 412* Escape Index:: 413* Operator Index:: 414* Register Index:: 415* Macro Index:: 416* String Index:: 417* Glyph Name Index:: 418* Font File Keyword Index:: 419* Program and File Index:: 420* Concept Index:: 421@end menu 422 423 424 425@c ===================================================================== 426@c ===================================================================== 427 428@node Introduction, Invoking groff, Top, Top 429@chapter Introduction 430@cindex introduction 431 432GNU @code{troff} (or @code{groff}) is a system for typesetting 433documents. @code{troff} is very flexible and has been in existence (and 434use) for about 3@tie{}decades. It is quite widespread and firmly 435entrenched in the @acronym{UNIX} community. 436 437@menu 438* What Is groff?:: 439* History:: 440* groff Capabilities:: 441* Macro Package Intro:: 442* Preprocessor Intro:: 443* Output device intro:: 444* Credits:: 445@end menu 446 447 448@c ===================================================================== 449 450@node What Is groff?, History, Introduction, Introduction 451@section What Is @code{groff}? 452@cindex what is @code{groff}? 453@cindex @code{groff} -- what is it? 454 455@code{groff} belongs to an older generation of document preparation 456systems, which operate more like compilers than the more recent 457interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 458systems. @code{groff} and its contemporary counterpart, @TeX{}, both 459work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 460normal text files with embedded formatting commands. These files can 461then be processed by @code{groff} to produce a typeset document on a 462variety of devices. 463 464Likewise, @code{groff} should not be confused with a @dfn{word 465processor}, since that term connotes an integrated system that includes 466an editor and a text formatter. Also, many word processors follow the 467@acronym{WYSIWYG} paradigm discussed earlier. 468 469Although @acronym{WYSIWYG} systems may be easier to use, they have a 470number of disadvantages compared to @code{troff}: 471 472@itemize @bullet 473@item 474They must be used on a graphics display to work on a document. 475 476@item 477Most of the @acronym{WYSIWYG} systems are either non-free or are not 478very portable. 479 480@item 481@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 482 483@item 484It is difficult to have a wide range of capabilities available within 485the confines of a GUI/window system. 486 487@item 488It is more difficult to make global changes to a document. 489@end itemize 490 491@quotation 492``GUIs normally make it simple to accomplish simple actions and 493impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 494@code{comp.unix.wizards}) 495@end quotation 496 497 498@c ===================================================================== 499 500@node History, groff Capabilities, What Is groff?, Introduction 501@section History 502@cindex history 503 504@cindex @code{runoff}, the program 505@cindex @code{rf}, the program 506@code{troff} can trace its origins back to a formatting program called 507@code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS 508operating system in the mid-sixties. This name came from the common 509phrase of the time ``I'll run off a document.'' Bob Morris ported it to 510the 635 architecture and called the program @code{roff} (an abbreviation 511of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 512(before having @acronym{UNIX}), and at the same time (1969), Doug 513McIllroy rewrote an extended and simplified version of @code{roff} in 514the @acronym{BCPL} programming language. 515 516@cindex @code{roff}, the program 517The first version of @acronym{UNIX} was developed on a @w{PDP-7} which 518was sitting around Bell Labs. In 1971 the developers wanted to get a 519@w{PDP-11} for further work on the operating system. In order to 520justify the cost for this system, they proposed that they would 521implement a document formatting system for the @acronym{AT&T} patents 522division. This first formatting program was a reimplementation of 523McIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna. 524 525@cindex @code{nroff}, the program 526When they needed a more flexible language, a new version of @code{roff} 527called @code{nroff} (``Newer @code{roff}'') was written. It had a much 528more complicated syntax, but provided the basis for all future versions. 529When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 530version of @code{nroff} that would drive it. It was dubbed 531@code{troff}, for ``typesetter @code{roff}'', although many people have 532speculated that it actually means ``Times @code{roff}'' because of the 533use of the Times font family in @code{troff} by default. As such, the 534name @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 535 536With @code{troff} came @code{nroff} (they were actually the same program 537except for some @samp{#ifdef}s), which was for producing output for line 538printers and character terminals. It understood everything @code{troff} 539did, and ignored the commands which were not applicable (e.g.@: font 540changes). 541 542Since there are several things which cannot be done easily in 543@code{troff}, work on several preprocessors began. These programs would 544transform certain parts of a document into @code{troff}, which made a 545very natural use of pipes in @acronym{UNIX}. 546 547The @code{eqn} preprocessor allowed mathematical formul@ae{} to be 548specified in a much simpler and more intuitive manner. @code{tbl} is a 549preprocessor for formatting tables. The @code{refer} preprocessor (and 550the similar program, @code{bib}) processes citations in a document 551according to a bibliographic database. 552 553Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 554language and produced output specifically for the CAT phototypesetter. 555He rewrote it in C, although it was now 7000@tie{}lines of uncommented 556code and still dependent on the CAT. As the CAT became less common, and 557was no longer supported by the manufacturer, the need to make it support 558other devices became a priority. However, before this could be done, 559Ossanna was killed in a car accident. 560 561@pindex ditroff 562@cindex @code{ditroff}, the program 563So, Brian Kernighan took on the task of rewriting @code{troff}. The 564newly rewritten version produced device independent code which was 565very easy for postprocessors to read and translate to the appropriate 566printer codes. Also, this new version of @code{troff} (called 567@code{ditroff} for ``device independent @code{troff}'') had several 568extensions, which included drawing functions. 569 570Due to the additional abilities of the new version of @code{troff}, 571several new preprocessors appeared. The @code{pic} preprocessor 572provides a wide range of drawing functions. Likewise the @code{ideal} 573preprocessor did the same, although via a much different paradigm. The 574@code{grap} preprocessor took specifications for graphs, but, unlike 575other preprocessors, produced @code{pic} code. 576 577James Clark began work on a GNU implementation of @code{ditroff} in 578early@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released 579June@tie{}1990. @code{groff} included: 580 581@itemize @bullet 582@item 583A replacement for @code{ditroff} with many extensions. 584 585@item 586The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 587 588@item 589Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 590X@tie{}Windows. GNU @code{troff} also eliminated the need for a 591separate @code{nroff} program with a postprocessor which would produce 592@acronym{ASCII} output. 593 594@item 595A version of the @file{me} macros and an implementation of the 596@file{man} macros. 597@end itemize 598 599Also, a front-end was included which could construct the, sometimes 600painfully long, pipelines required for all the post- and preprocessors. 601 602Development of GNU @code{troff} progressed rapidly, and saw the 603additions of a replacement for @code{refer}, an implementation of the 604@file{ms} and @file{mm} macros, and a program to deduce how to format a 605document (@code{grog}). 606 607It was declared a stable (i.e.@: non-beta) package with the release of 608version@tie{}1.04 around November@tie{}1991. 609 610Beginning in@tie{}1999, @code{groff} has new maintainers (the package was 611an orphan for a few years). As a result, new features and programs like 612@code{grn}, a preprocessor for gremlin images, and an output device to 613produce @acronym{HTML} output have been added. 614 615 616@c ===================================================================== 617 618@node groff Capabilities, Macro Package Intro, History, Introduction 619@section @code{groff} Capabilities 620@cindex @code{groff} capabilities 621@cindex capabilities of @code{groff} 622 623So what exactly is @code{groff} capable of doing? @code{groff} provides 624a wide range of low-level text formatting operations. Using these, it 625is possible to perform a wide range of formatting tasks, such as 626footnotes, table of contents, multiple columns, etc. Here's a list of 627the most important operations supported by @code{groff}: 628 629@itemize @bullet 630@item 631text filling, adjusting, and centering 632 633@item 634hyphenation 635 636@item 637page control 638 639@item 640font and glyph size control 641 642@item 643vertical spacing (e.g.@: double-spacing) 644 645@item 646line length and indenting 647 648@item 649macros, strings, diversions, and traps 650 651@item 652number registers 653 654@item 655tabs, leaders, and fields 656 657@item 658input and output conventions and character translation 659 660@item 661overstrike, bracket, line drawing, and zero-width functions 662 663@item 664local horizontal and vertical motions and the width function 665 666@item 667three-part titles 668 669@item 670output line numbering 671 672@item 673conditional acceptance of input 674 675@item 676environment switching 677 678@item 679insertions from the standard input 680 681@item 682input/output file switching 683 684@item 685output and error messages 686@end itemize 687 688 689@c ===================================================================== 690 691@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 692@section Macro Packages 693@cindex macro packages 694 695Since @code{groff} provides such low-level facilities, it can be quite 696difficult to use by itself. However, @code{groff} provides a 697@dfn{macro} facility to specify how certain routine operations 698(e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@: 699should be done. These macros can be collected together into a @dfn{macro 700package}. There are a number of macro packages available; the most 701common (and the ones described in this manual) are @file{man}, 702@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 703 704 705@c ===================================================================== 706 707@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 708@section Preprocessors 709@cindex preprocessors 710 711Although @code{groff} provides most functions needed to format a 712document, some operations would be unwieldy (e.g.@: to draw pictures). 713Therefore, programs called @dfn{preprocessors} were written which 714understand their own language and produce the necessary @code{groff} 715operations. These preprocessors are able to differentiate their own 716input from the rest of the document via markers. 717 718To use a preprocessor, @acronym{UNIX} pipes are used to feed the output 719from the preprocessor into @code{groff}. Any number of preprocessors 720may be used on a given document; in this case, the preprocessors are 721linked together into one pipeline. However, with @code{groff}, the user 722does not need to construct the pipe, but only tell @code{groff} what 723preprocessors to use. 724 725@code{groff} currently has preprocessors for producing tables 726(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 727(@code{pic} and @code{grn}), and for processing bibliographies 728(@code{refer}). An associated program which is useful when dealing with 729preprocessors is @code{soelim}. 730 731A free implementation of @code{grap}, a preprocessor for drawing graphs, 732can be obtained as an extra package; @code{groff} can use @code{grap} 733also. 734 735There are other preprocessors in existence, but, unfortunately, no free 736implementations are available. Among them are preprocessors for drawing 737mathematical pictures (@code{ideal}) and chemical structures 738(@code{chem}). 739 740 741@c ===================================================================== 742 743@node Output device intro, Credits, Preprocessor Intro, Introduction 744@section Output Devices 745@cindex postprocessors 746@cindex output devices 747@cindex devices for output 748 749@code{groff} actually produces device independent code which may be 750fed into a postprocessor to produce output for a particular device. 751Currently, @code{groff} has postprocessors for @sc{PostScript} 752devices, character terminals, X@tie{}Windows (for previewing), @TeX{} 753DVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use 754@acronym{CAPSL}), and @acronym{HTML}. 755 756 757@c ===================================================================== 758 759@node Credits, , Output device intro, Introduction 760@section Credits 761@cindex credits 762 763Large portions of this manual were taken from existing documents, most 764notably, the manual pages for the @code{groff} package by James Clark, 765and Eric Allman's papers on the @file{me} macro package. 766 767The section on the @file{man} macro package is partly based on 768Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the 769Debian GNU/Linux system. 770 771Larry Kollar contributed the section in the @file{ms} macro package. 772 773 774 775@c ===================================================================== 776@c ===================================================================== 777 778@node Invoking groff, Tutorial for Macro Users, Introduction, Top 779@chapter Invoking @code{groff} 780@cindex invoking @code{groff} 781@cindex @code{groff} invocation 782 783This section focuses on how to invoke the @code{groff} front end. This 784front end takes care of the details of constructing the pipeline among 785the preprocessors, @code{gtroff} and the postprocessor. 786 787It has become a tradition that GNU programs get the prefix @samp{g} to 788distinguish it from its original counterparts provided by the host (see 789@ref{Environment}, for more details). Thus, for example, @code{geqn} is 790GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which 791don't contain proprietary versions of @code{troff}, and on 792MS-DOS/MS-Windows, where @code{troff} and associated programs are not 793available at all, this prefix is omitted since GNU @code{troff} is the 794only used incarnation of @code{troff}. Exception: @samp{groff} is never 795replaced by @samp{roff}. 796 797In this document, we consequently say @samp{gtroff} when talking about 798the GNU @code{troff} program. All other implementations of @code{troff} 799are called @acronym{AT&T} @code{troff} which is the common origin of 800all @code{troff} derivates (with more or less compatible changes). 801Similarly, we say @samp{gpic}, @samp{geqn}, etc. 802 803@menu 804* Groff Options:: 805* Environment:: 806* Macro Directories:: 807* Font Directories:: 808* Paper Size:: 809* Invocation Examples:: 810@end menu 811 812 813@c ===================================================================== 814 815@node Groff Options, Environment, Invoking groff, Invoking groff 816@section Options 817@cindex options 818 819@pindex groff 820@pindex gtroff 821@pindex gpic 822@pindex geqn 823@pindex ggrn 824@pindex grap 825@pindex gtbl 826@pindex grefer 827@pindex gsoelim 828@code{groff} normally runs the @code{gtroff} program and a postprocessor 829appropriate for the selected device. The default device is @samp{ps} 830(but it can be changed when @code{groff} is configured and built). It 831can optionally preprocess with any of @code{gpic}, @code{geqn}, 832@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 833 834This section only documents options to the @code{groff} front end. Many 835of the arguments to @code{groff} are passed on to @code{gtroff}, 836therefore those are also included. Arguments to pre- or postprocessors 837can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 838gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 839gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 840grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 841grolbp}, and @ref{Invoking gxditview}. 842 843The command line format for @code{groff} is: 844 845@Example 846groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 847 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 848 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 849 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 850 [ @var{files}@dots{} ] 851@endExample 852 853The command line format for @code{gtroff} is as follows. 854 855@Example 856gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 857 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 858 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 859 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 860@endExample 861 862@noindent 863Obviously, many of the options to @code{groff} are actually passed on to 864@code{gtroff}. 865 866Options without an argument can be grouped behind a single@tie{}@option{-}. 867A filename of@tie{}@file{-} denotes the standard input. It is possible to 868have whitespace between an option and its parameter. 869 870The @code{grog} command can be used to guess the correct @code{groff} 871command to format a file. 872 873Here's the description of the command-line options: 874 875@cindex command-line options 876@table @samp 877@item -h 878Print a help message. 879 880@item -e 881Preprocess with @code{geqn}. 882 883@item -t 884Preprocess with @code{gtbl}. 885 886@item -g 887Preprocess with @code{ggrn}. 888 889@item -G 890Preprocess with @code{grap}. 891 892@item -p 893Preprocess with @code{gpic}. 894 895@item -s 896Preprocess with @code{gsoelim}. 897 898@item -c 899Suppress color output. 900 901@item -R 902Preprocess with @code{grefer}. No mechanism is provided for passing 903arguments to @code{grefer} because most @code{grefer} options have 904equivalent commands which can be included in the file. @xref{grefer}, 905for more details. 906 907@pindex troffrc 908@pindex troffrc-end 909Note that @code{gtroff} also accepts a @option{-R} option, which is not 910accessible via @code{groff}. This option prevents the loading of the 911@file{troffrc} and @file{troffrc-end} files. 912 913@item -v 914Make programs run by @code{groff} print out their version number. 915 916@item -V 917Print the pipeline on @code{stdout} instead of executing it. 918 919@item -z 920Suppress output from @code{gtroff}. Only error messages are printed. 921 922@item -Z 923Do not postprocess the output of @code{gtroff}. Normally @code{groff} 924automatically runs the appropriate postprocessor. 925 926@item -P@var{arg} 927Pass @var{arg} to the postprocessor. Each argument should be passed 928with a separate @option{-P} option. Note that @code{groff} does not 929prepend @samp{-} to @var{arg} before passing it to the postprocessor. 930 931@item -l 932Send the output to a spooler for printing. The command used for this is 933specified by the @code{print} command in the device description file 934(see @ref{Font Files}, for more info). If not present, @option{-l} is 935ignored. 936 937@item -L@var{arg} 938Pass @var{arg} to the spooler. Each argument should be passed with a 939separate @option{-L} option. Note that @code{groff} does not prepend 940a @samp{-} to @var{arg} before passing it to the postprocessor. 941If the @code{print} keyword in the device description file is missing, 942@option{-L} is ignored. 943 944@item -T@var{dev} 945Prepare output for device @var{dev}. The default device is @samp{ps}, 946unless changed when @code{groff} was configured and built. The 947following are the output devices currently available: 948 949@table @code 950@item ps 951For @sc{PostScript} printers and previewers. 952 953@item dvi 954For @TeX{} DVI format. 955 956@item X75 957For a 75@dmn{dpi} X11 previewer. 958 959@item X75-12 960For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 961document. 962 963@item X100 964For a 100@dmn{dpi} X11 previewer. 965 966@item X100-12 967For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 968document. 969 970@item ascii 971@cindex encoding, output, @acronym{ASCII} 972@cindex @acronym{ASCII}, output encoding 973@cindex output encoding, @acronym{ASCII} 974For typewriter-like devices using the (7-bit) @acronym{ASCII} 975character set. 976 977@item latin1 978@cindex encoding, output, @w{latin-1} (ISO @w{8859-1}) 979@cindex @w{latin-1} (ISO @w{8859-1}), output encoding 980@cindex ISO @w{8859-1} (@w{latin-1}), output encoding 981@cindex output encoding, @w{latin-1} (ISO @w{8859-1}) 982For typewriter-like devices that support the @w{Latin-1} 983(ISO@tie{}@w{8859-1}) character set. 984 985@item utf8 986@cindex encoding, output, @w{utf-8} 987@cindex @w{utf-8}, output encoding 988@cindex output encoding, @w{utf-8} 989For typewriter-like devices which use the Unicode (ISO@tie{}10646) 990character set with @w{UTF-8} encoding. 991 992@item cp1047 993@cindex encoding, output, @acronym{EBCDIC} 994@cindex @acronym{EBCDIC}, output encoding 995@cindex output encoding, @acronym{EBCDIC} 996@cindex encoding, output, cp1047 997@cindex cp1047, output encoding 998@cindex output encoding, cp1047 999@cindex IBM cp1047 output encoding 1000For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 1001cp1047. 1002 1003@item lj4 1004For HP LaserJet4-compatible (or other PCL5-compatible) printers. 1005 1006@item lbp 1007For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 1008printers). 1009 1010@pindex pre-grohtml 1011@pindex post-grohtml 1012@cindex @code{grohtml}, the program 1013@item html 1014To produce @acronym{HTML} output. Note that the @acronym{HTML} driver 1015consists of two parts, a preprocessor (@code{pre-grohtml}) and a 1016postprocessor (@code{post-grohtml}). 1017@end table 1018 1019@cindex output device name string register (@code{.T}) 1020@cindex output device usage number register (@code{.T}) 1021The predefined @code{gtroff} string register @code{.T} contains the 1022current output device; the read-only number register @code{.T} is set 1023to@tie{}1 if this option is used (which is always true if @code{groff} is 1024used to call @code{gtroff}). @xref{Built-in Registers}. 1025 1026The postprocessor to be used for a device is specified by the 1027@code{postpro} command in the device description file. (@xref{Font 1028Files}, for more info.) This can be overridden with the @option{-X} 1029option. 1030 1031@item -X 1032Preview with @code{gxditview} instead of using the usual postprocessor. 1033This is unlikely to produce good results except with @option{-Tps}. 1034 1035Note that this is not the same as using @option{-TX75} or 1036@option{-TX100} to view a document with @code{gxditview}: The former 1037uses the metrics of the specified device, whereas the latter uses 1038X-specific fonts and metrics. 1039 1040@item -N 1041Don't allow newlines with @code{eqn} delimiters. This is the same as 1042the @option{-N} option in @code{geqn}. 1043 1044@item -S 1045@cindex @code{open} request, and safer mode 1046@cindex @code{opena} request, and safer mode 1047@cindex @code{pso} request, and safer mode 1048@cindex @code{sy} request, and safer mode 1049@cindex @code{pi} request, and safer mode 1050@cindex safer mode 1051@cindex mode, safer 1052Safer mode. Pass the @option{-S} option to @code{gpic} and disable the 1053@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 1054requests. For security reasons, this is enabled by default. 1055 1056@item -U 1057@cindex mode, unsafe 1058@cindex unsafe mode 1059Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso}, 1060@code{sy}, and @code{pi} requests. 1061 1062@item -a 1063@cindex @acronym{ASCII} approximation output register (@code{.A}) 1064Generate an @acronym{ASCII} approximation of the typeset output. The 1065read-only register @code{.A} is then set to@tie{}1. @xref{Built-in 1066Registers}. A typical example is 1067 1068@Example 1069groff -a -man -Tdvi troff.man | less 1070@endExample 1071 1072@noindent 1073which shows how lines are broken for the DVI device. Note that this 1074option is rather useless today since graphic output devices are 1075available virtually everywhere. 1076 1077@item -b 1078Print a backtrace with each warning or error message. This backtrace 1079should help track down the cause of the error. The line numbers given 1080in the backtrace may not always be correct: @code{gtroff} can get 1081confused by @code{as} or @code{am} requests while counting line numbers. 1082 1083@item -i 1084Read the standard input after all the named input files have been 1085processed. 1086 1087@item -w@var{name} 1088Enable warning @var{name}. Available warnings are described in 1089@ref{Debugging}. Multiple @option{-w} options are allowed. 1090 1091@item -W@var{name} 1092Inhibit warning @var{name}. Multiple @option{-W} options are allowed. 1093 1094@item -E 1095Inhibit all error messages. 1096 1097@item -C 1098Enable compatibility mode. @xref{Implementation Differences}, for the 1099list of incompatibilities between @code{groff} and @acronym{AT&T} 1100@code{troff}. 1101 1102@item -d@var{c}@var{s} 1103@itemx -d@var{name}=@var{s} 1104Define @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must 1105be a one-letter name; @var{name} can be of arbitrary length. All string 1106assignments happen before loading any macro file (including the start-up 1107file). 1108 1109@item -f@var{fam} 1110Use @var{fam} as the default font family. @xref{Font Families}. 1111 1112@item -m@var{name} 1113Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches 1114for this in its macro directories. If it isn't found, it tries 1115@file{tmac.@var{name}} (searching in the same directories). 1116 1117@item -n@var{num} 1118Number the first page @var{num}. 1119 1120@item -o@var{list} 1121@cindex print current page register (@code{.P}) 1122Output only pages in @var{list}, which is a comma-separated list of page 1123ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}} 1124means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}} 1125means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every 1126page beginning with@tie{}@var{n}. @code{gtroff} exits after printing the 1127last page in the list. All the ranges are inclusive on both ends. 1128 1129Within @code{gtroff}, this information can be extracted with the 1130@samp{.P} register. @xref{Built-in Registers}. 1131 1132If your document restarts page numbering at the beginning of each 1133chapter, then @code{gtroff} prints the specified page range for each 1134chapter. 1135 1136@item -r@var{c}@var{n} 1137@itemx -r@var{name}=@var{n} 1138Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}. 1139@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary 1140length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All 1141register assignments happen before loading any macro file (including 1142the start-up file). 1143 1144@item -F@var{dir} 1145Search @file{@var{dir}} for subdirectories @file{dev@var{name}} 1146(@var{name} is the name of the device), for the @file{DESC} file, and 1147for font files before looking in the standard directories (@pxref{Font 1148Directories}). This option is passed to all pre- and postprocessors 1149using the @env{GROFF_FONT_PATH} environment variable. 1150 1151@item -M@var{dir} 1152Search directory @file{@var{dir}} for macro files before the standard 1153directories (@pxref{Macro Directories}). 1154 1155@item -I@var{dir} 1156This option is as described in @ref{gsoelim}. It implies the 1157@option{-s} option. 1158@end table 1159 1160 1161@c ===================================================================== 1162 1163@node Environment, Macro Directories, Groff Options, Invoking groff 1164@section Environment 1165@cindex environment variables 1166@cindex variables in environment 1167 1168There are also several environment variables (of the operating system, 1169not within @code{gtroff}) which can modify the behavior of @code{groff}. 1170 1171@table @code 1172@item GROFF_COMMAND_PREFIX 1173@tindex GROFF_COMMAND_PREFIX@r{, environment variable} 1174@cindex command prefix 1175@cindex prefix, for commands 1176If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff} 1177instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 1178@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 1179apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 1180@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 1181 1182The default command prefix is determined during the installation process. 1183If a non-GNU troff system is found, prefix @samp{g} is used, none 1184otherwise. 1185 1186@item GROFF_TMAC_PATH 1187@tindex GROFF_TMAC_PATH@r{, environment variable} 1188A colon-separated list of directories in which to search for macro files 1189(before the default directories are tried). @xref{Macro Directories}. 1190 1191@item GROFF_TYPESETTER 1192@tindex GROFF_TYPESETTER@r{, environment variable} 1193The default output device. 1194 1195@item GROFF_FONT_PATH 1196@tindex GROFF_FONT_PATH@r{, environment variable} 1197A colon-separated list of directories in which to search for the 1198@code{dev}@var{name} directory (before the default directories are 1199tried). @xref{Font Directories}. 1200 1201@item GROFF_BIN_PATH 1202@tindex GROFF_BIN_PATH@r{, environment variable} 1203This search path, followed by @code{PATH}, is used for commands executed 1204by @code{groff}. 1205 1206@item GROFF_TMPDIR 1207@tindex GROFF_TMPDIR@r{, environment variable} 1208@tindex TMPDIR@r{, environment variable} 1209The directory in which @code{groff} creates temporary files. If this is 1210not set and @env{TMPDIR} is set, temporary files are created in that 1211directory. Otherwise temporary files are created in a system-dependent 1212default directory (on Unix and GNU/Linux systems, this is usually 1213@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 1214@code{post-grohtml} can create temporary files in this directory. 1215@end table 1216 1217Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 1218rather than colons, to separate the directories in the lists described 1219above. 1220 1221 1222@c ===================================================================== 1223 1224@node Macro Directories, Font Directories, Environment, Invoking groff 1225@section Macro Directories 1226@cindex macro directories 1227@cindex directories for macros 1228@cindex searching macros 1229@cindex macros, searching 1230 1231All macro file names must be named @code{@var{name}.tmac} or 1232@code{tmac.@var{name}} to make the @option{-m@var{name}} command line 1233option work. The @code{mso} request doesn't have this restriction; any 1234file name can be used, and @code{gtroff} won't try to append or prepend 1235the @samp{tmac} string. 1236 1237@cindex tmac, directory 1238@cindex directory, for tmac files 1239@cindex tmac, path 1240@cindex path, for tmac files 1241@cindex searching macro files 1242@cindex macro files, searching 1243@cindex files, macro, searching 1244Macro files are kept in the @dfn{tmac directories}, all of which 1245constitute the @dfn{tmac path}. The elements of the search path for 1246macro files are (in that order): 1247 1248@itemize @bullet 1249@item 1250The directories specified with @code{gtroff}'s or @code{groff}'s 1251@option{-M} command line option. 1252 1253@item 1254@tindex GROFF_TMAC_PATH@r{, environment variable} 1255The directories given in the @env{GROFF_TMAC_PATH} environment 1256variable. 1257 1258@item 1259@cindex safer mode 1260@cindex mode, safer 1261@cindex unsafe mode 1262@cindex mode, unsafe 1263@cindex current directory 1264@cindex directory, current 1265The current directory (only if in unsafe mode using the @option{-U} 1266command line switch). 1267 1268@item 1269@cindex home directory 1270@cindex directory, home 1271The home directory. 1272 1273@item 1274@cindex site-specific directory 1275@cindex directory, site-specific 1276@cindex platform-specific directory 1277@cindex directory, platform-specific 1278A platform-dependent directory, a site-specific (platform-independent) 1279directory, and the main tmac directory; the default locations are 1280 1281@Example 1282/usr/local/lib/groff/site-tmac 1283/usr/local/share/groff/site-tmac 1284/usr/local/share/groff/1.18.2/tmac 1285@endExample 1286 1287@noindent 1288assuming that the version of @code{groff} is 1.18.2, and the installation 1289prefix was @file{/usr/local}. It is possible to fine-tune those 1290directories during the installation process. 1291@end itemize 1292 1293 1294@c ===================================================================== 1295 1296@node Font Directories, Paper Size, Macro Directories, Invoking groff 1297@section Font Directories 1298@cindex font directories 1299@cindex directories for fonts 1300@cindex searching fonts 1301@cindex fonts, searching 1302 1303Basically, there is no restriction how font files for @code{groff} are 1304named and how long font names are; however, to make the font family 1305mechanism work (@pxref{Font Families}), fonts within a family should 1306start with the family name, followed by the shape. For example, the 1307Times family uses @samp{T} for the family name and @samp{R}, @samp{B}, 1308@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold', 1309`italic', and `bold italic', respectively. Thus the final font names 1310are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}. 1311 1312@cindex font path 1313@cindex path, for font files 1314All font files are kept in the @dfn{font directories} which constitute 1315the @dfn{font path}. The file search functions will always append the 1316directory @code{dev}@var{name}, where @var{name} is the name of the 1317output device. Assuming, say, DVI output, and @file{/foo/bar} as a 1318font directory, the font files for @code{grodvi} must be in 1319@file{/foo/bar/devdvi}. 1320 1321The elements of the search path for font files are (in that order): 1322 1323@itemize @bullet 1324@item 1325The directories specified with @code{gtroff}'s or @code{groff}'s 1326@option{-F} command line option. All device drivers and some 1327preprocessors also have this option. 1328 1329@item 1330@tindex GROFF_FONT_PATH@r{, environment variable} 1331The directories given in the @env{GROFF_FONT_PATH} environment 1332variable. 1333 1334@item 1335@cindex site-specific directory 1336@cindex directory, site-specific 1337A site-specific directory and the main font directory; the default 1338locations are 1339 1340@Example 1341/usr/local/share/groff/site-font 1342/usr/local/share/groff/1.18.2/font 1343@endExample 1344 1345@noindent 1346assuming that the version of @code{groff} is 1.18.2, and the installation 1347prefix was @file{/usr/local}. It is possible to fine-tune those 1348directories during the installation process. 1349@end itemize 1350 1351 1352@c ===================================================================== 1353 1354@node Paper Size, Invocation Examples, Font Directories, Invoking groff 1355@section Paper Size 1356@cindex paper size 1357@cindex size, paper 1358@cindex landscape page orientation 1359@cindex orientation, landscape 1360@cindex page orientation, landscape 1361 1362In groff, the page size for @code{gtroff} and for output devices are 1363handled separately. @xref{Page Layout}, for vertical manipulation of 1364the page size. @xref{Line Layout}, for horizontal changes. 1365 1366A default paper size can be set in the device's @file{DESC} file. Most 1367output devices also have a command line option @option{-p} to override 1368the default paper size and option @option{-l} to use landscape 1369orientation. @xref{DESC File Format}, for a description of the 1370@code{papersize} keyword which takes the same argument as @option{-p}. 1371 1372@pindex papersize.tmac 1373@pindex troffrc 1374A convenient shorthand to set a particular paper size for @code{gtroff} 1375is command line option @option{-dpaper=@var{size}}. This defines string 1376@code{paper} which is processed in file @file{papersize.tmac} (loaded in 1377the start-up file @file{troffrc} by default). Possible values for 1378@var{size} are the same as the predefined values for the 1379@code{papersize} keyword (but only in lowercase) except 1380@code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes 1381landscape orientation. 1382 1383For example, use the following for PS output on A4 paper in landscape 1384orientation: 1385 1386@Example 1387groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps 1388@endExample 1389 1390Note that it is up to the particular macro package to respect default 1391page dimensions set in this way (most do). 1392 1393 1394@c ===================================================================== 1395 1396@node Invocation Examples, , Paper Size, Invoking groff 1397@section Invocation Examples 1398@cindex invocation examples 1399@cindex examples of invocation 1400 1401This section lists several common uses of @code{groff} and the 1402corresponding command lines. 1403 1404@Example 1405groff file 1406@endExample 1407 1408@noindent 1409This command processes @file{file} without a macro package or a 1410preprocessor. The output device is the default, @samp{ps}, and the 1411output is sent to @code{stdout}. 1412 1413@Example 1414groff -t -mandoc -Tascii file | less 1415@endExample 1416 1417@noindent 1418This is basically what a call to the @code{man} program does. 1419@code{gtroff} processes the manual page @file{file} with the 1420@file{mandoc} macro file (which in turn either calls the @file{man} or 1421the @file{mdoc} macro package), using the @code{tbl} preprocessor and 1422the @acronym{ASCII} output device. Finally, the @code{less} pager 1423displays the result. 1424 1425@Example 1426groff -X -m me file 1427@endExample 1428 1429@noindent 1430Preview @file{file} with @code{gxditview}, using the @file{me} macro 1431package. Since no @option{-T} option is specified, use the default 1432device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 1433@w{@samp{-me}}; the latter is an anachronism from the early days of 1434@acronym{UNIX}.@footnote{The same is true for the other main macro 1435packages that come with @code{groff}: @file{man}, @file{mdoc}, 1436@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 1437for example, to load @file{trace.tmac}, either @samp{-mtrace} or 1438@w{@samp{-m trace}} must be used.} 1439 1440@Example 1441groff -man -rD1 -z file 1442@endExample 1443 1444@noindent 1445Check @file{file} with the @file{man} macro package, forcing 1446double-sided printing -- don't produce any output. 1447 1448@menu 1449* grog:: 1450@end menu 1451 1452@c --------------------------------------------------------------------- 1453 1454@node grog, , Invocation Examples, Invocation Examples 1455@subsection @code{grog} 1456 1457@pindex grog 1458@code{grog} reads files, guesses which of the @code{groff} preprocessors 1459and/or macro packages are required for formatting them, and prints the 1460@code{groff} command including those options on the standard output. It 1461generates one or more of the options @option{-e}, @option{-man}, 1462@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc}, 1463@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 1464@option{-s}, and @option{-t}. 1465 1466A special file name@tie{}@file{-} refers to the standard input. Specifying 1467no files also means to read the standard input. Any specified options 1468are included in the printed command. No space is allowed between 1469options and their arguments. The only options recognized are 1470@option{-C} (which is also passed on) to enable compatibility mode, and 1471@option{-v} to print the version number and exit. 1472 1473For example, 1474 1475@Example 1476grog -Tdvi paper.ms 1477@endExample 1478 1479@noindent 1480guesses the appropriate command to print @file{paper.ms} and then prints 1481it to the command line after adding the @option{-Tdvi} option. For 1482direct execution, enclose the call to @code{grog} in backquotes at the 1483@acronym{UNIX} shell prompt: 1484 1485@Example 1486`grog -Tdvi paper.ms` > paper.dvi 1487@endExample 1488 1489@noindent 1490As seen in the example, it is still necessary to redirect the output to 1491something meaningful (i.e.@: either a file or a pager program like 1492@code{less}). 1493 1494 1495 1496@c ===================================================================== 1497@c ===================================================================== 1498 1499@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 1500@chapter Tutorial for Macro Users 1501@cindex tutorial for macro users 1502@cindex macros, tutorial for users 1503@cindex user's tutorial for macros 1504@cindex user's macro tutorial 1505 1506Most users tend to use a macro package to format their papers. This 1507means that the whole breadth of @code{groff} is not necessary for most 1508people. This chapter covers the material needed to efficiently use a 1509macro package. 1510 1511@menu 1512* Basics:: 1513* Common Features:: 1514@end menu 1515 1516 1517@c ===================================================================== 1518 1519@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 1520@section Basics 1521@cindex basics of macros 1522@cindex macro basics 1523 1524This section covers some of the basic concepts necessary to understand 1525how to use a macro package.@footnote{This section is derived from 1526@cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.} 1527References are made throughout to more detailed information, if desired. 1528 1529@code{gtroff} reads an input file prepared by the user and outputs a 1530formatted document suitable for publication or framing. The input 1531consists of text, or words to be printed, and embedded commands 1532(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 1533format the output. For more detail on this, see @ref{Embedded 1534Commands}. 1535 1536The word @dfn{argument} is used in this chapter to mean a word or number 1537which appears on the same line as a request, and which modifies the 1538meaning of that request. For example, the request 1539 1540@Example 1541.sp 1542@endExample 1543 1544@noindent 1545spaces one line, but 1546 1547@Example 1548.sp 4 1549@endExample 1550 1551@noindent 1552spaces four lines. The number@tie{}4 is an argument to the @code{sp} 1553request which says to space four lines instead of one. Arguments are 1554separated from the request and from each other by spaces (@emph{no} 1555tabs). More details on this can be found in @ref{Request and Macro 1556Arguments}. 1557 1558The primary function of @code{gtroff} is to collect words from input 1559lines, fill output lines with those words, justify the right-hand margin 1560by inserting extra spaces in the line, and output the result. For 1561example, the input: 1562 1563@Example 1564Now is the time 1565for all good men 1566to come to the aid 1567of their party. 1568Four score and seven 1569years ago, etc. 1570@endExample 1571 1572@noindent 1573is read, packed onto output lines, and justified to produce: 1574 1575@quotation 1576Now is the time for all good men to come to the aid of their party. 1577Four score and seven years ago, etc. 1578@end quotation 1579 1580@cindex break 1581@cindex line break 1582Sometimes a new output line should be started even though the current 1583line is not yet full; for example, at the end of a paragraph. To do 1584this it is possible to cause a @dfn{break}, which starts a new output 1585line. Some requests cause a break automatically, as normally do blank 1586input lines and input lines beginning with a space. 1587 1588Not all input lines are text to be formatted. Some input lines are 1589requests which describe how to format the text. Requests always have a 1590period (@samp{.}) or an apostrophe (@samp{'}) as the first character of 1591the input line. 1592 1593The text formatter also does more complex things, such as automatically 1594numbering pages, skipping over page boundaries, putting footnotes in the 1595correct place, and so forth. 1596 1597Here are a few hints for preparing text for input to @code{gtroff}. 1598 1599@itemize @bullet 1600@item 1601First, keep the input lines short. Short input lines are easier to 1602edit, and @code{gtroff} packs words onto longer lines anyhow. 1603 1604@item 1605In keeping with this, it is helpful to begin a new line after every 1606comma or phrase, since common corrections are to add or delete sentences 1607or phrases. 1608 1609@item 1610End each sentence with two spaces -- or better, start each sentence on a 1611new line. @code{gtroff} recognizes characters that usually end a 1612sentence, and inserts sentence space accordingly. 1613 1614@item 1615Do not hyphenate words at the end of lines -- @code{gtroff} is smart 1616enough to hyphenate words as needed, but is not smart enough to take 1617hyphens out and join a word back together. Also, words such as 1618``mother-in-law'' should not be broken over a line, since then a space 1619can occur where not wanted, such as ``@w{mother- in}-law''. 1620@end itemize 1621 1622@cindex double-spacing (@code{ls}) 1623@cindex spacing 1624@code{gtroff} double-spaces output text automatically if you use the 1625request @w{@samp{.ls 2}}. Reactivate single-spaced mode by typing 1626@w{@samp{.ls 1}}.@footnote{If you need finer granularity of the 1627vertical space, use the @code{pvs} request (@pxref{Changing Type 1628Sizes}).} 1629 1630A number of requests allow to change the way the output looks, 1631sometimes called the @dfn{layout} of the output page. Most of these 1632requests adjust the placing of @dfn{whitespace} (blank lines or 1633spaces). 1634 1635@cindex new page (@code{bp}) 1636The @code{bp} request starts a new page, causing a line break. 1637 1638@cindex blank line (@code{sp}) 1639@cindex empty line (@code{sp}) 1640@cindex line, empty (@code{sp}) 1641The request @w{@samp{.sp @var{N}}} leaves @var{N}@tie{}lines of blank 1642space. @var{N}@tie{}can be omitted (meaning skip a single line) or can 1643be of the form @var{N}i (for @var{N}@tie{}inches) or @var{N}c (for 1644@var{N}@tie{}centimeters). For example, the input: 1645 1646@Example 1647.sp 1.5i 1648My thoughts on the subject 1649.sp 1650@endExample 1651 1652@noindent 1653leaves one and a half inches of space, followed by the line ``My 1654thoughts on the subject'', followed by a single blank line (more 1655measurement units are available, see @ref{Measurements}). 1656 1657@cindex centering lines (@code{ce}) 1658@cindex lines, centering (@code{ce}) 1659Text lines can be centered by using the @code{ce} request. The line 1660after @code{ce} is centered (horizontally) on the page. To center more 1661than one line, use @w{@samp{.ce @var{N}}} (where @var{N} is the number 1662of lines to center), followed by the @var{N}@tie{}lines. To center many 1663lines without counting them, type: 1664 1665@Example 1666.ce 1000 1667lines to center 1668.ce 0 1669@endExample 1670 1671@noindent 1672The @w{@samp{.ce 0}} request tells @code{groff} to center zero more 1673lines, in other words, stop centering. 1674 1675@cindex line break (@code{br}) 1676@cindex break (@code{br}) 1677All of these requests cause a break; that is, they always start a new 1678line. To start a new line without performing any other action, use 1679@code{br}. 1680 1681 1682@c ===================================================================== 1683 1684@node Common Features, , Basics, Tutorial for Macro Users 1685@section Common Features 1686@cindex common features 1687@cindex features, common 1688 1689@code{gtroff} provides very low-level operations for formatting a 1690document. There are many common routine operations which are done in 1691all documents. These common operations are written into @dfn{macros} 1692and collected into a @dfn{macro package}. 1693 1694All macro packages provide certain common capabilities which fall into 1695the following categories. 1696 1697@menu 1698* Paragraphs:: 1699* Sections and Chapters:: 1700* Headers and Footers:: 1701* Page Layout Adjustment:: 1702* Displays:: 1703* Footnotes and Annotations:: 1704* Table of Contents:: 1705* Indices:: 1706* Paper Formats:: 1707* Multiple Columns:: 1708* Font and Size Changes:: 1709* Predefined Strings:: 1710* Preprocessor Support:: 1711* Configuration and Customization:: 1712@end menu 1713 1714@c --------------------------------------------------------------------- 1715 1716@node Paragraphs, Sections and Chapters, Common Features, Common Features 1717@subsection Paragraphs 1718@cindex paragraphs 1719 1720One of the most common and most used capability is starting a 1721paragraph. There are a number of different types of paragraphs, any 1722of which can be initiated with macros supplied by the macro package. 1723Normally, paragraphs start with a blank line and the first line 1724indented, like the text in this manual. There are also block style 1725paragraphs, which omit the indentation: 1726 1727@Example 1728Some men look at constitutions with sanctimonious 1729reverence, and deem them like the ark of the covenant, too 1730sacred to be touched. 1731@endExample 1732 1733@noindent 1734And there are also indented paragraphs which begin with a tag or label 1735at the margin and the remaining text indented. 1736 1737@Example 1738one This is the first paragraph. Notice how the first 1739 line of the resulting paragraph lines up with the 1740 other lines in the paragraph. 1741@endExample 1742@Example 1743longlabel 1744 This paragraph had a long label. The first 1745 character of text on the first line does not line up 1746 with the text on second and subsequent lines, 1747 although they line up with each other. 1748@endExample 1749 1750A variation of this is a bulleted list. 1751 1752@Example 1753. Bulleted lists start with a bullet. It is possible 1754 to use other glyphs instead of the bullet. In nroff 1755 mode using the ASCII character set for output, a dot 1756 is used instead of a real bullet. 1757@endExample 1758 1759@c --------------------------------------------------------------------- 1760 1761@node Sections and Chapters, Headers and Footers, Paragraphs, Common Features 1762@subsection Sections and Chapters 1763 1764Most macro packages supply some form of section headers. The simplest 1765kind is simply the heading on a line by itself in bold type. Others 1766supply automatically numbered section heading or different heading 1767styles at different levels. Some, more sophisticated, macro packages 1768supply macros for starting chapters and appendices. 1769 1770@c --------------------------------------------------------------------- 1771 1772@node Headers and Footers, Page Layout Adjustment, Sections and Chapters, Common Features 1773@subsection Headers and Footers 1774 1775Every macro package gives some way to manipulate the @dfn{headers} and 1776@dfn{footers} (also called @dfn{titles}) on each page. This is text 1777put at the top and bottom of each page, respectively, which contain 1778data like the current page number, the current chapter title, and so 1779on. Its appearance is not affected by the running text. Some packages 1780allow for different ones on the even and odd pages (for material printed 1781in a book form). 1782 1783The titles are called @dfn{three-part titles}, that is, there is a 1784left-justified part, a centered part, and a right-justified part. An 1785automatically generated page number may be put in any of these fields 1786with the @samp{%} character (see @ref{Page Layout}, for more details). 1787 1788@c --------------------------------------------------------------------- 1789 1790@node Page Layout Adjustment, Displays, Headers and Footers, Common Features 1791@subsection Page Layout 1792 1793Most macro packages let the user specify top and bottom margins and 1794other details about the appearance of the printed pages. 1795 1796@c --------------------------------------------------------------------- 1797 1798@node Displays, Footnotes and Annotations, Page Layout Adjustment, Common Features 1799@subsection Displays 1800@cindex displays 1801 1802@dfn{Displays} are sections of text to be set off from the body of 1803the paper. Major quotes, tables, and figures are types of displays, as 1804are all the examples used in this document. 1805 1806@cindex quotes, major 1807@cindex major quotes 1808@dfn{Major quotes} are quotes which are several lines long, and hence 1809are set in from the rest of the text without quote marks around them. 1810 1811@cindex list 1812A @dfn{list} is an indented, single-spaced, unfilled display. Lists 1813should be used when the material to be printed should not be filled and 1814justified like normal text, such as columns of figures or the examples 1815used in this paper. 1816 1817@cindex keep 1818A @dfn{keep} is a display of lines which are kept on a single page if 1819possible. An example for a keep might be a diagram. Keeps differ from 1820lists in that lists may be broken over a page boundary whereas keeps are 1821not. 1822 1823@cindex keep, floating 1824@cindex floating keep 1825@dfn{Floating keeps} move relative to the text. Hence, they are good for 1826things which are referred to by name, such as ``See figure@tie{}3''. A 1827floating keep appears at the bottom of the current page if it fits; 1828otherwise, it appears at the top of the next page. Meanwhile, the 1829surrounding text `flows' around the keep, thus leaving no blank areas. 1830 1831@c --------------------------------------------------------------------- 1832 1833@node Footnotes and Annotations, Table of Contents, Displays, Common Features 1834@subsection Footnotes and Annotations 1835@cindex footnotes 1836@cindex annotations 1837 1838There are a number of requests to save text for later printing. 1839 1840@dfn{Footnotes} are printed at the bottom of the current page. 1841 1842@cindex delayed text 1843@dfn{Delayed text} is very similar to a footnote except that it is 1844printed when called for explicitly. This allows a list of references to 1845appear (for example) at the end of each chapter, as is the convention in 1846some disciplines. 1847 1848Most macro packages which supply this functionality also supply a means 1849of automatically numbering either type of annotation. 1850 1851@c --------------------------------------------------------------------- 1852 1853@node Table of Contents, Indices, Footnotes and Annotations, Common Features 1854@subsection Table of Contents 1855@cindex table of contents 1856@cindex contents, table of 1857 1858@dfn{Tables of contents} are a type of delayed text having a tag 1859(usually the page number) attached to each entry after a row of dots. 1860The table accumulates throughout the paper until printed, usually after 1861the paper has ended. Many macro packages provide the ability to have 1862several tables of contents (e.g.@: a standard table of contents, a list 1863of tables, etc). 1864 1865@c --------------------------------------------------------------------- 1866 1867@node Indices, Paper Formats, Table of Contents, Common Features 1868@subsection Indices 1869@cindex index, in macro package 1870 1871While some macro packages use the term @dfn{index}, none actually 1872provide that functionality. The facilities they call indices are 1873actually more appropriate for tables of contents. 1874 1875@pindex makeindex 1876To produce a real index in a document, external tools like the 1877@code{makeindex} program are necessary. 1878 1879@c --------------------------------------------------------------------- 1880 1881@node Paper Formats, Multiple Columns, Indices, Common Features 1882@subsection Paper Formats 1883@cindex paper formats 1884 1885Some macro packages provide stock formats for various kinds of 1886documents. Many of them provide a common format for the title and 1887opening pages of a technical paper. The @file{mm} macros in particular 1888provide formats for letters and memoranda. 1889 1890@c --------------------------------------------------------------------- 1891 1892@node Multiple Columns, Font and Size Changes, Paper Formats, Common Features 1893@subsection Multiple Columns 1894 1895Some macro packages (but not @file{man}) provide the ability to have two 1896or more columns on a page. 1897 1898@c --------------------------------------------------------------------- 1899 1900@node Font and Size Changes, Predefined Strings, Multiple Columns, Common Features 1901@subsection Font and Size Changes 1902 1903The built-in font and size functions are not always intuitive, so all 1904macro packages provide macros to make these operations simpler. 1905 1906@c --------------------------------------------------------------------- 1907 1908@node Predefined Strings, Preprocessor Support, Font and Size Changes, Common Features 1909@subsection Predefined Strings 1910 1911Most macro packages provide various predefined strings for a variety of 1912uses; examples are sub- and superscripts, printable dates, quotes and 1913various special characters. 1914 1915@c --------------------------------------------------------------------- 1916 1917@node Preprocessor Support, Configuration and Customization, Predefined Strings, Common Features 1918@subsection Preprocessor Support 1919 1920All macro packages provide support for various preprocessors and may 1921extend their functionality. 1922 1923For example, all macro packages mark tables (which are processed with 1924@code{gtbl}) by placing them between @code{TS} and @code{TE} macros. 1925The @file{ms} macro package has an option, @samp{.TS@tie{}H}, that prints 1926a caption at the top of a new page (when the table is too long to fit on 1927a single page). 1928 1929@c --------------------------------------------------------------------- 1930 1931@node Configuration and Customization, , Preprocessor Support, Common Features 1932@subsection Configuration and Customization 1933 1934Some macro packages provide means of customizing many of the details of 1935how the package behaves. This ranges from setting the default type size 1936to changing the appearance of section headers. 1937 1938 1939 1940@c ===================================================================== 1941@c ===================================================================== 1942 1943@node Macro Packages, gtroff Reference, Tutorial for Macro Users, Top 1944@chapter Macro Packages 1945@cindex macro packages 1946@cindex packages, macros 1947 1948This chapter documents the main macro packages that come with 1949@code{groff}. 1950 1951Different main macro packages can't be used at the same time; for example 1952 1953@Example 1954groff -m man foo.man -m ms bar.doc 1955@endExample 1956 1957@noindent 1958doesn't work. Note that option arguments are processed before non-option 1959arguments; the above (failing) sample is thus reordered to 1960 1961@Example 1962groff -m man -m ms foo.man bar.doc 1963@endExample 1964 1965@menu 1966* man:: 1967* mdoc:: 1968* ms:: 1969* me:: 1970* mm:: 1971@end menu 1972 1973 1974@c ===================================================================== 1975 1976@node man, mdoc, Macro Packages, Macro Packages 1977@section @file{man} 1978@cindex manual pages 1979@cindex man pages 1980@pindex an.tmac 1981@pindex man.tmac 1982@pindex man-old.tmac 1983 1984This is the most popular and probably the most important macro package 1985of @code{groff}. It is easy to use, and a vast majority of manual pages 1986are based on it. 1987 1988@menu 1989* Man options:: 1990* Man usage:: 1991* Man font macros:: 1992* Miscellaneous man macros:: 1993* Predefined man strings:: 1994* Preprocessors in man pages:: 1995* Optional man extensions:: 1996@end menu 1997 1998@c --------------------------------------------------------------------- 1999 2000@node Man options, Man usage, man, man 2001@subsection Options 2002 2003The command line format for using the @file{man} macros with 2004@code{groff} is: 2005 2006@Example 2007groff -m man [ -rLL=@var{length} ] [ -rLT=@var{length} ] [ -rFT=@var{dist} ] 2008 [ -rcR=1 ] [ -rC1 ] [ -rD1 ] [-rHY=@var{flags} ] 2009 [ -rP@var{nnn} ] [ -rS@var{xx} ] [ -rX@var{nnn} ] 2010 [ -rIN=@var{length} ] [ -rSN=@var{length} ] [ @var{files}@dots{} ] 2011@endExample 2012 2013@noindent 2014It is possible to use @samp{-man} instead of @w{@samp{-m man}}. 2015 2016@table @code 2017@item -rcR=1 2018This option (the default if a TTY output device is used) creates a 2019single, very long page instead of multiple pages. Use @code{-rcR=0} 2020to disable it. 2021 2022@item -rC1 2023If more than one manual page is given on the command line, number the 2024pages continuously, rather than starting each at@tie{}1. 2025 2026@item -rD1 2027Double-sided printing. Footers for even and odd pages are formatted 2028differently. 2029 2030@item -rFT=@var{dist} 2031Set the position of the footer text to @var{dist}. If positive, the 2032distance is measured relative to the top of the page, otherwise it is 2033relative to the bottom. The default is @minus{}0.5@dmn{i}. 2034 2035@item -rHY=@var{flags} 2036Set hyphenation flags. Possible values are 1@tie{}to hyphenate without 2037restrictions, 2@tie{} to not hyphenate the last word on a page, 20384@tie{}to not hyphenate the last two characters of a word, and 20398@tie{}to not hyphenate the first two characters of a word. These 2040values are additive; the default is@tie{}14. 2041 2042@item -rIN=@var{length} 2043Set the body text indent to @var{length}. 2044If not specified, the indent defaults to 7@dmn{n} 2045(7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise. 2046For nroff, this value should always be an integer multiple of unit @samp{n} 2047to get consistent indentation. 2048 2049@item -rLL=@var{length} 2050Set line length to @var{length}. If not specified, the line length 2051defaults to 78@tie{}en in nroff mode (this is 78@tie{}characters per 2052line) and 6.5@tie{}inch otherwise. 2053 2054@item -rLT=@var{length} 2055Set title length to @var{length}. If not specified, the title length 2056defaults to the line length. 2057 2058@item -rP@var{nnn} 2059Page numbering starts with @var{nnn} rather than with@tie{}1. 2060 2061@item -rS@var{xx} 2062Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base 2063document font size instead of the default value of@tie{}10@dmn{pt}. 2064 2065@item -rSN=@var{length} 2066Set the indent for sub-subheadings to @var{length}. 2067If not specified, the indent defaults to 3@dmn{n}. 2068 2069@item -rX@var{nnn} 2070After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, 2071@var{nnn}c, etc. For example, the option @option{-rX2} produces the 2072following page numbers: 1, 2, 2a, 2b, 2c, etc. 2073@end table 2074 2075@c --------------------------------------------------------------------- 2076 2077@node Man usage, Man font macros, Man options, man 2078@subsection Usage 2079@cindex @code{man} macros 2080@cindex macros for manual pages [@code{man}] 2081 2082@pindex man.local 2083This section describes the available macros for manual pages. For 2084further customization, put additional macros and requests into the file 2085@file{man.local} which is loaded immediately after the @file{man} 2086package. 2087 2088@Defmac {TH, title section [@Var{extra1} [@Var{extra2} [@Var{extra3}]]], man} 2089Set the title of the man page to @var{title} and the section to 2090@var{section}, which must have a value between 1 and@tie{}8. The value 2091of @var{section} may also have a string appended, e.g.@: @samp{.pm}, 2092to indicate a specific subsection of the man pages. 2093 2094Both @var{title} and @var{section} are positioned at the left and right 2095in the header line (with @var{section} in parentheses immediately 2096appended to @var{title}. @var{extra1} is positioned in the middle of 2097the footer line. @var{extra2} is positioned at the left in the footer 2098line (or at the left on even pages and at the right on odd pages if 2099double-sided printing is active). @var{extra3} is centered in the 2100header line. 2101 2102For @acronym{HTML} output, headers and footers are completely suppressed. 2103 2104Additionally, this macro starts a new page; the new line number is@tie{}1 2105again (except if the @option{-rC1} option is given on the command line) 2106-- this feature is intended only for formatting multiple man pages; a 2107single man page should contain exactly one @code{TH} macro at the 2108beginning of the file. 2109@endDefmac 2110 2111@Defmac {SH, [@Var{heading}], man} 2112Set up an unnumbered section heading sticking out to the left. Prints 2113out all the text following @code{SH} up to the end of the line (or the 2114text in the next line if there is no argument to @code{SH}) in bold 2115face (or the font specified by the string @code{HF}), one size larger than 2116the base document size. Additionally, the left margin and the indentation 2117for the following text is reset to its default value. 2118@endDefmac 2119 2120@Defmac {SS, [@Var{heading}], man} 2121Set up an unnumbered (sub)section heading. Prints out all the text 2122following @code{SS} up to the end of the line (or the text in the next 2123line if there is no argument to @code{SS}) in bold face (or the font 2124specified by the string @code{HF}), at the same size as the base document 2125size. Additionally, the left margin and the indentation for the 2126following text is reset to its default value. 2127@endDefmac 2128 2129@Defmac {TP, [@Var{nnn}], man} 2130Set up an indented paragraph with label. The indentation is set to 2131@var{nnn} if that argument is supplied (the default unit is @samp{n} 2132if omitted), otherwise it is set to the previous indentation value 2133specified with @code{TP}, @code{IP}, or @code{HP} (or to the default 2134value if none of them have been used yet). 2135 2136The first line of text following this macro is interpreted as a string 2137to be printed flush-left, as it is appropriate for a label. It is not 2138interpreted as part of a paragraph, so there is no attempt to fill the 2139first line with text from the following input lines. Nevertheless, if 2140the label is not as wide as the indentation the paragraph starts 2141at the same line (but indented), continuing on the following lines. 2142If the label is wider than the indentation the descriptive part 2143of the paragraph begins on the line following the label, entirely 2144indented. Note that neither font shape nor font size of the label is 2145set to a default value; on the other hand, the rest of the text has 2146default font settings. 2147@endDefmac 2148 2149@DefmacList {LP, , man} 2150@DefmacItem {PP, , man} 2151@DefmacListEnd {P, , man} 2152These macros are mutual aliases. Any of them causes a line break at 2153the current position, followed by a vertical space downwards by the 2154amount specified by the @code{PD} macro. The font size and shape are 2155reset to the default value (10@dmn{pt} roman if no @option{-rS} option 2156is given on the command line). Finally, the current left margin and the 2157indentation is restored. 2158@endDefmac 2159 2160@Defmac {IP, [@Var{designator} [@Var{nnn}]], man} 2161Set up an indented paragraph, using @var{designator} as a tag to mark 2162its beginning. The indentation is set to @var{nnn} if that argument 2163is supplied (default unit is @samp{n}), otherwise it is set to the 2164previous indentation value specified with @code{TP}, @code{IP}, or 2165@code{HP} (or the default value if none of them have been used yet). 2166Font size and face of the paragraph (but not the designator) are reset 2167to their default values. 2168 2169To start an indented paragraph with a particular indentation but without 2170a designator, use @samp{""} (two double quotes) as the first argument of 2171@code{IP}. 2172 2173For example, to start a paragraph with bullets as the designator and 21744@tie{}en indentation, write 2175 2176@Example 2177.IP \(bu 4 2178@endExample 2179@endDefmac 2180 2181@Defmac {HP, [@Var{nnn}], man} 2182@cindex hanging indentation [@code{man}] 2183@cindex @code{man} macros, hanging indentation 2184Set up a paragraph with hanging left indentation. The indentation is 2185set to @var{nnn} if that argument is supplied (default unit is 2186@samp{n}), otherwise it is set to the previous indentation value 2187specified with @code{TP}, @code{IP}, or @code{HP} (or the default 2188value if non of them have been used yet). Font size and face are reset 2189to their default values. 2190@endDefmac 2191 2192@Defmac {RS, [@Var{nnn}], man} 2193@cindex left margin, how to move [@code{man}] 2194@cindex @code{man} macros, moving left margin 2195Move the left margin to the right by the value @var{nnn} if specified 2196(default unit is @samp{n}); otherwise it is set to the previous 2197indentation value specified with @code{TP}, @code{IP}, or @code{HP} 2198(or to the default value if none of them have been used yet). The 2199indentation value is then set to the default. 2200 2201Calls to the @code{RS} macro can be nested. 2202@endDefmac 2203 2204@Defmac {RE, [@Var{nnn}], man} 2205Move the left margin back to level @var{nnn}, restoring the previous left 2206margin. If no argument is given, it moves one level back. The first 2207level (i.e., no call to @code{RS} yet) has number@tie{}1, and each call 2208to @code{RS} increases the level by@tie{}1. 2209@endDefmac 2210 2211@cindex line breaks, with vertical space [@code{man}] 2212@cindex @code{man} macros, line breaks with vertical space 2213To summarize, the following macros cause a line break with the insertion 2214of vertical space (which amount can be changed with the @code{PD} 2215macro): @code{SH}, @code{SS}, @code{TP}, @code{LP} (@code{PP}, 2216@code{P}), @code{IP}, and @code{HP}. 2217 2218@cindex line breaks, without vertical space [@code{man}] 2219@cindex @code{man} macros, line breaks without vertical space 2220The macros @code{RS} and @code{RE} also cause a break but do not insert 2221vertical space. 2222 2223@cindex default indentation, resetting [@code{man}] 2224@cindex indentaion, resetting to default [@code{man}] 2225@cindex @code{man} macros, resetting default indentation 2226Finally, the macros @code{SH}, @code{SS}, @code{LP} (@code{PP}, @code{P}), 2227and @code{RS} reset the indentation to its default value. 2228 2229@c --------------------------------------------------------------------- 2230 2231@node Man font macros, Miscellaneous man macros, Man usage, man 2232@subsection Macros to set fonts 2233@cindex font selection [@code{man}] 2234@cindex @code{man} macros, how to set fonts 2235 2236The standard font is roman; the default text size is 10@tie{}point. 2237If command line option @option{-rS=@var{n}} is given, use 2238@var{n}@dmn{pt} as the default text size. 2239 2240@Defmac {SM, [@Var{text}], man} 2241Set the text on the same line or the text on the next line in a font 2242that is one point size smaller than the default font. 2243@endDefmac 2244 2245@Defmac {SB, [@Var{text}], man} 2246@cindex bold face [@code{man}] 2247@cindex @code{man} macros, bold face 2248Set the text on the same line or the text on the next line in bold face 2249font, one point size smaller than the default font. 2250@endDefmac 2251 2252@Defmac {BI, text, man} 2253Set its arguments alternately in bold face and italic, without a space 2254between the arguments. Thus, 2255 2256@Example 2257.BI this "word and" that 2258@endExample 2259 2260@noindent 2261produces ``thisword andthat'' with ``this'' and ``that'' in bold face, 2262and ``word and'' in italics. 2263@endDefmac 2264 2265@Defmac {IB, text, man} 2266Set its arguments alternately in italic and bold face, without a space 2267between the arguments. 2268@endDefmac 2269 2270@Defmac {RI, text, man} 2271Set its arguments alternately in roman and italic, without a space between 2272the arguments. 2273@endDefmac 2274 2275@Defmac {IR, text, man} 2276Set its arguments alternately in italic and roman, without a space between 2277the arguments. 2278@endDefmac 2279 2280@Defmac {BR, text, man} 2281Set its arguments alternately in bold face and roman, without a space 2282between the arguments. 2283@endDefmac 2284 2285@Defmac {RB, text, man} 2286Set its arguments alternately in roman and bold face, without a space 2287between the arguments. 2288@endDefmac 2289 2290@Defmac {B, [@Var{text}], man} 2291Set @var{text} in bold face. If no text is present on the line where 2292the macro is called, then the text of the next line appears in bold 2293face. 2294@endDefmac 2295 2296@Defmac {I, [@Var{text}], man} 2297@cindex italic fonts [@code{man}] 2298@cindex @code{man} macros, italic fonts 2299Set @var{text} in italic. If no text is present on the line where the 2300macro is called, then the text of the next line appears in italic. 2301@endDefmac 2302 2303@c --------------------------------------------------------------------- 2304 2305@node Miscellaneous man macros, Predefined man strings, Man font macros, man 2306@subsection Miscellaneous macros 2307 2308@pindex grohtml 2309@cindex @code{man} macros, default indentation 2310@cindex default indentation [@code{man}] 2311The default indentation is 7.2@dmn{n} in troff mode and 7@dmn{n} in 2312nroff mode except for @code{grohtml} which ignores indentation. 2313 2314@Defmac {DT, , man} 2315@cindex tab stops [@code{man}] 2316@cindex @code{man} macros, tab stops 2317Set tabs every 0.5@tie{}inches. Since this macro is always executed 2318during a call to the @code{TH} macro, it makes sense to call it only if 2319the tab positions have been changed. 2320@endDefmac 2321 2322@Defmac {PD, [@Var{nnn}], man} 2323@cindex empty space before a paragraph [@code{man}] 2324@cindex @code{man} macros, empty space before a paragraph 2325Adjust the empty space before a new paragraph (or section). The 2326optional argument gives the amount of space (default unit is 2327@samp{v}); without parameter, the value is reset to its default value 2328(1@tie{}line in nroff mode, 0.4@dmn{v}@tie{}otherwise). 2329 2330This affects the macros @code{SH}, @code{SS}, @code{TP}, @code{LP} (as 2331well as @code{PP} and @code{P}), @code{IP}, and @code{HP}. 2332@endDefmac 2333 2334The following two macros are included for 2335BSD compatibility. 2336 2337@Defmac {AT, [@Var{system} [@Var{release}]], man} 2338@cindex @code{man}macros, BSD compatibility 2339Alter the footer for use with @acronym{AT&T} manpages. 2340This command exists only for compatibility; don't use it. 2341The first argument @var{system} can be: 2342 2343@table @code 2344@item 3 23457th Edition (the default) 2346 2347@item 4 2348System III 2349 2350@item 5 2351System V 2352@end table 2353 2354An optional second argument @var{release} to @code{AT} specifies the 2355release number (such as ``System V Release 3''). 2356@endDefmac 2357 2358@Defmac {UC, [@Var{version}], man} 2359@cindex @code{man}macros, BSD compatibility 2360Alters the footer for use with @acronym{BSD} manpages. 2361This command exists only for compatibility; don't use it. 2362The argument can be: 2363 2364@table @code 2365@item 3 23663rd Berkeley Distribution (the default) 2367 2368@item 4 23694th Berkeley Distribution 2370 2371@item 5 23724.2 Berkeley Distribution 2373 2374@item 6 23754.3 Berkeley Distribution 2376 2377@item 7 23784.4 Berkeley Distribution 2379@end table 2380@endDefmac 2381 2382@c --------------------------------------------------------------------- 2383 2384@node Predefined man strings, Preprocessors in man pages, Miscellaneous man macros, man 2385@subsection Predefined strings 2386 2387The following strings are defined: 2388 2389@Defstr {S, man} 2390Switch back to the default font size. 2391@endDefstr 2392 2393@Defstr {HF, man} 2394The typeface used for headings. 2395The default is @samp{B}. 2396@endDefstr 2397 2398@Defstr {R, man} 2399The `registered' sign. 2400@endDefstr 2401 2402@Defstr {Tm, man} 2403The `trademark' sign. 2404@endDefstr 2405 2406@DefstrList {lq, man} 2407@DefstrListEnd {rq, man} 2408@cindex @code{lq} glyph, and @code{lq} string [@code{man}] 2409@cindex @code{rq} glyph, and @code{rq} string [@code{man}] 2410Left and right quote. This is equal to @code{\(lq} and @code{\(rq}, 2411respectively. 2412@endDefstr 2413 2414@c --------------------------------------------------------------------- 2415 2416@node Preprocessors in man pages, Optional man extensions, Predefined man strings, man 2417@subsection Preprocessors in @file{man} pages 2418 2419@cindex preprocessor, calling convention 2420@cindex calling convention of preprocessors 2421If a preprocessor like @code{gtbl} or @code{geqn} is needed, it has 2422become common usage to make the first line of the man page look like 2423this: 2424 2425@Example 2426'\" @var{word} 2427@endExample 2428 2429@pindex geqn@r{, invocation in manual pages} 2430@pindex grefer@r{, invocation in manual pages} 2431@pindex gtbl@r{, invocation in manual pages} 2432@pindex man@r{, invocation of preprocessors} 2433@noindent 2434Note the single space character after the double quote. @var{word} 2435consists of letters for the needed preprocessors: @samp{e} for 2436@code{geqn}, @samp{r} for @code{grefer}, @samp{t} for @code{gtbl}. 2437Modern implementations of the @code{man} program read this first line 2438and automatically call the right preprocessor(s). 2439 2440@c --------------------------------------------------------------------- 2441 2442@node Optional man extensions, , Preprocessors in man pages, man 2443@subsection Optional @file{man} extensions 2444 2445@pindex man.local 2446Use the file @file{man.local} for local extensions 2447to the @code{man} macros or for style changes. 2448 2449@unnumberedsubsubsec Custom headers and footers 2450@cindex @code{man} macros, custom headers and footers 2451 2452In groff versions 1.18.2 and later, you can specify custom 2453headers and footers by redefining the following macros in 2454@file{man.local}. 2455 2456@Defmac {PT, , man} 2457Control the content of the headers. 2458Normally, the header prints the command name 2459and section number on either side, and the 2460optional fifth argument to @code{TH} in the center. 2461@endDefmac 2462 2463@Defmac {BT, , man} 2464Control the content of the footers. 2465Normally, the footer prints the page number 2466and the third and fourth arguments to @code{TH}. 2467 2468Use the @code{FT} number register to specify the 2469footer position. 2470The default is @minus{}0.5@dmn{i}. 2471@endDefmac 2472 2473@unnumberedsubsubsec Ultrix-specific man macros 2474@cindex Ultrix-specific @code{man} macros 2475@cindex @code{man} macros, Ultrix-specific 2476 2477@pindex man.ultrix 2478The @code{groff} source distribution includes 2479a file named @file{man.ultrix}, containing 2480macros compatible with the Ultrix variant of 2481@code{man}. 2482Copy this file into @file{man.local} (or use the @code{mso} request to 2483load it) to enable the following macros. 2484 2485@Defmac {CT, @Var{key}, man} 2486Print @samp{<CTRL/@var{key}>}. 2487@endDefmac 2488 2489@Defmac {CW, , man} 2490Print subsequent text using the constant width (Courier) typeface. 2491@endDefmac 2492 2493@Defmac {Ds, , man} 2494Begin a non-filled display. 2495@endDefmac 2496 2497@Defmac {De, , man} 2498End a non-filled display started with @code{Ds}. 2499@endDefmac 2500 2501@Defmac {EX, [@Var{indent}], man} 2502Begins a non-filled display 2503using the constant width (Courier) typeface. 2504Use the optional @var{indent} argument to 2505indent the display. 2506@endDefmac 2507 2508@Defmac {EE, , man} 2509End a non-filled display started with @code{EX}. 2510@endDefmac 2511 2512@Defmac {G, [@Var{text}], man} 2513Sets @var{text} in Helvetica. 2514If no text is present on the line where 2515the macro is called, then the text of the 2516next line appears in Helvetica. 2517@endDefmac 2518 2519@Defmac {GL, [@Var{text}], man} 2520Sets @var{text} in Helvetica Oblique. 2521If no text is present on the line where 2522the macro is called, then the text of the 2523next line appears in Helvetica Oblique. 2524@endDefmac 2525 2526@Defmac {HB, [@Var{text}], man} 2527Sets @var{text} in Helvetica Bold. 2528If no text is present on the line where 2529the macro is called, then all text up to 2530the next @code{HB} appears in Helvetica Bold. 2531@endDefmac 2532 2533@Defmac {TB, [@Var{text}], man} 2534Identical to @code{HB}. 2535@endDefmac 2536 2537@Defmac {MS, @Var{title} @Var{sect} [@Var{punct}], man} 2538Set a manpage reference in Ultrix format. 2539The @var{title} is in Courier instead of italic. 2540Optional punctuation follows the section number without 2541an intervening space. 2542@endDefmac 2543 2544@Defmac {NT, [@code{C}] [@Var{title}], man} 2545Begin a note. 2546Print the optional @Var{title}, or the word ``Note'', 2547centered on the page. 2548Text following the macro makes up the body of the note, 2549and is indented on both sides. 2550If the first argument is @code{C}, the body of the 2551note is printed centered (the second argument replaces 2552the word ``Note'' if specified). 2553@endDefmac 2554 2555@Defmac {NE, , man} 2556End a note begun with @code{NT}. 2557@endDefmac 2558 2559@Defmac {PN, @Var{path} [@Var{punct}], man} 2560Set the path name in constant width (Courier), 2561followed by optional punctuation. 2562@endDefmac 2563 2564@Defmac {Pn, [@Var{punct}] @Var{path} [@Var{punct}], man} 2565When called with two arguments, identical to @code{PN}. 2566When called with three arguments, 2567set the second argument in constant width (Courier), 2568bracketed by the first and third arguments in the current font. 2569@endDefmac 2570 2571@Defmac {R, , man} 2572Switch to roman font and turn off any underlining in effect. 2573@endDefmac 2574 2575@Defmac {RN, , man} 2576Print the string @samp{<RETURN>}. 2577@endDefmac 2578 2579@Defmac {VS, [@code{4}], man} 2580Start printing a change bar in the margin if 2581the number @code{4} is specified. 2582Otherwise, this macro does nothing. 2583@endDefmac 2584 2585@Defmac {VE, , man} 2586End printing the change bar begun by @code{VS}. 2587@endDefmac 2588 2589@unnumberedsubsubsec Simple example 2590 2591The following example @file{man.local} file 2592alters the @code{SH} macro to add some extra 2593vertical space before printing the heading. 2594Headings are printed in Helvetica Bold. 2595 2596@Example 2597.\" Make the heading fonts Helvetica 2598.ds HF HB 2599. 2600.\" Put more whitespace in front of headings. 2601.rn SH SH-orig 2602.de SH 2603. if t .sp (u;\\n[PD]*2) 2604. SH-orig \\$* 2605.. 2606@endExample 2607 2608@c ===================================================================== 2609 2610@node mdoc, ms, man, Macro Packages 2611@section @file{mdoc} 2612@cindex @code{mdoc} macros 2613 2614@c XXX documentation 2615@c XXX this is a placeholder until we get stuff knocked into shape 2616See the @cite{groff_mdoc(7)} man page (type @command{man groff_mdoc} 2617at the command line). 2618 2619 2620@c ===================================================================== 2621 2622@node ms, me, mdoc, Macro Packages 2623@section @file{ms} 2624@cindex @code{ms} macros 2625 2626The @file{-ms} 2627macros are suitable for reports, letters, books, 2628user manuals, and so forth. 2629The package provides macros for cover pages, section headings, 2630paragraphs, lists, footnotes, pagination, 2631and a table of contents. 2632 2633@menu 2634* ms Intro:: 2635* General ms Structure:: 2636* ms Document Control Registers:: 2637* ms Cover Page Macros:: 2638* ms Body Text:: 2639* ms Page Layout:: 2640* Differences from AT&T ms:: 2641@end menu 2642 2643@c --------------------------------------------------------------------- 2644 2645@node ms Intro, General ms Structure, ms, ms 2646@subsection Introduction to @file{ms} 2647 2648The original @file{-ms} macros were included with 2649@acronym{AT&T} @code{troff} as well as the 2650@file{man} macros. 2651While the @file{man} package is intended for brief documents 2652that can be read on-line as well as printed, the @file{ms} 2653macros are suitable for longer documents that are meant to be 2654printed rather than read on-line. 2655 2656The @file{ms} macro package included with @code{groff} 2657is a complete, bottom-up re-implementation. 2658Several macros (specific to @acronym{AT&T} 2659or Berkeley) are not included, while several new commands are. 2660@xref{Differences from AT&T ms}, for more information. 2661 2662@c --------------------------------------------------------------------- 2663 2664@node General ms Structure, ms Document Control Registers, ms Intro, ms 2665@subsection General structure of an @file{ms} document 2666@cindex @code{ms} macros, general structure 2667 2668The @file{ms} macro package expects a certain amount of structure, 2669but not as much as packages such as @file{man} or @file{mdoc}. 2670 2671The simplest documents can begin with a paragraph macro 2672(such as @code{LP} or @code{PP}), 2673and consist of text separated by paragraph macros 2674or even blank lines. 2675Longer documents have a structure as follows: 2676 2677@table @strong 2678@item Document type 2679If you invoke the @code{RP} 2680(report) macro on the first line of the document, 2681@code{groff} prints the cover page information on its own page; 2682otherwise it prints the information on the 2683first page with your document text immediately following. 2684Other document formats found in @acronym{AT&T} @code{troff} 2685are specific to @acronym{AT&T} or Berkeley, and are not supported in 2686@code{groff}. 2687 2688@item Format and layout 2689By setting number registers, 2690you can change your document's type (font and size), 2691margins, spacing, headers and footers, and footnotes. 2692@xref{ms Document Control Registers}, for more details. 2693 2694@item Cover page 2695A cover page consists of a title, the author's name and institution, 2696an abstract, and the date. 2697@footnote{Actually, only the title is required.} 2698@xref{ms Cover Page Macros}, for more details. 2699 2700@item Body 2701Following the cover page is your document. 2702You can use the @file{ms} 2703macros to write reports, letters, books, and so forth. 2704The package is designed for structured documents, 2705consisting of paragraphs interspersed with headings 2706and augmented by lists, footnotes, tables, and other 2707common constructs. 2708@xref{ms Body Text}, for more details. 2709 2710@item Table of contents 2711Longer documents usually include a table of contents, 2712which you can invoke by placing the 2713@code{TC} 2714macro at the end of your document. 2715The @file{ms} 2716macros have minimal indexing facilities, consisting of the 2717@code{IX} macro, which prints an entry on standard error. 2718Printing the table of contents at the end is necessary since 2719@code{groff} is a single-pass text formatter, 2720thus it cannot determine the page number of each section 2721until that section has actually been set and printed. 2722Since @file{ms} output is intended for hardcopy, 2723you can manually relocate the pages containing 2724the table of contents between the cover page and the 2725body text after printing. 2726@end table 2727 2728@c --------------------------------------------------------------------- 2729 2730@node ms Document Control Registers, ms Cover Page Macros, General ms Structure, ms 2731@subsection Document control registers 2732@cindex @code{ms} macros, document control registers 2733 2734The following is a list of document control number registers. 2735For the sake of consistency, 2736set registers related to margins at the beginning of your document, 2737or just after the @code{RP} macro. 2738You can set other registers later in your document, 2739but you should keep them together at the beginning 2740to make them easy to find and edit as necessary. 2741 2742@unnumberedsubsubsec Margin Settings 2743 2744@Defmpreg {PO, ms} 2745Defines the page offset (i.e.@: the left margin). 2746There is no explicit right margin setting; the combination of 2747the @code{PO} and @code{LL} registers implicitly define the 2748right margin width. 2749 2750Effective: next page. 2751 2752Default value: 1@dmn{i}. 2753@endDefmpreg 2754 2755@Defmpreg {LL, ms} 2756Defines the line length (i.e.@: the width of the body text). 2757 2758Effective: next paragraph. 2759 2760Default: 6@dmn{i}. 2761@endDefmpreg 2762 2763@Defmpreg {LT, ms} 2764Defines the title length (i.e.@: the header and footer width). 2765This is usually the same as @code{LL}, but not necessarily. 2766 2767Effective: next paragraph. 2768 2769Default: 6@dmn{i}. 2770@endDefmpreg 2771 2772@Defmpreg {HM, ms} 2773Defines the header margin height at the top of the page. 2774 2775Effective: next page. 2776 2777Default: 1@dmn{i}. 2778@endDefmpreg 2779 2780@Defmpreg {FM, ms} 2781Defines the footer margin height at the bottom of the page. 2782 2783Effective: next page. 2784 2785Default: 1@dmn{i}. 2786@endDefmpreg 2787 2788@unnumberedsubsubsec Text Settings 2789 2790@Defmpreg {PS, ms} 2791Defines the point size of the body text. 2792 2793Effective: next paragraph. 2794 2795Default: 10@dmn{p}. 2796@endDefmpreg 2797 2798@Defmpreg {VS, ms} 2799Defines the space between lines (line height plus leading). 2800 2801Effective: next paragraph. 2802 2803Default: 12@dmn{p}. 2804@endDefmpreg 2805 2806@unnumberedsubsubsec Paragraph Settings 2807 2808@Defmpreg {PI, ms} 2809Defines the initial indent of a @code{.PP} paragraph. 2810 2811Effective: next paragraph. 2812 2813Default: 5@dmn{n}. 2814@endDefmpreg 2815 2816@Defmpreg {PD, ms} 2817Defines the space between paragraphs. 2818 2819Effective: next paragraph. 2820 2821Default: 0.3@dmn{v}. 2822@endDefmpreg 2823 2824@Defmpreg {QI, ms} 2825Defines the indent on both sides of a quoted (@code{.QP}) paragraph. 2826 2827Effective: next paragraph. 2828 2829Default: 5@dmn{n}. 2830@endDefmpreg 2831 2832@unnumberedsubsubsec Footnote Settings 2833 2834@Defmpreg {FL, ms} 2835Defines the length of a footnote. 2836 2837Effective: next footnote. 2838 2839Default: @math{@code{@\n[LL]} * 5 / 6}. 2840@endDefmpreg 2841 2842@Defmpreg {FI, ms} 2843Defines the footnote indent. 2844 2845Effective: next footnote. 2846 2847Default: 2@dmn{n}. 2848@endDefmpreg 2849 2850@Defmpreg {FF, ms} 2851The footnote format: 2852@table @code 2853@item 0 2854Prints the footnote number as a superscript; indents the footnote (default). 2855 2856@item 1 2857Prints the number followed by a period (like 1.) 2858and indents the footnote. 2859 2860@item 2 2861Like 1, without an indent. 2862 2863@item 3 2864Like 1, but prints the footnote number as a hanging paragraph. 2865@end table 2866 2867Effective: next footnote. 2868 2869Default: 0. 2870@endDefmpreg 2871 2872@unnumberedsubsubsec Miscellaneous Number Registers 2873 2874@Defmpreg {MINGW, ms} 2875Defines the minimum width between columns in a multi-column document. 2876 2877Effective: next page. 2878 2879Default: 2@dmn{n}. 2880@endDefmpreg 2881 2882@c --------------------------------------------------------------------- 2883 2884@node ms Cover Page Macros, ms Body Text, ms Document Control Registers, ms 2885@subsection Cover page macros 2886@cindex @code{ms} macros, cover page 2887@cindex cover page macros, [@code{ms}] 2888 2889Use the following macros to create a cover page for your document 2890in the order shown. 2891 2892@Defmac {RP, [@code{no}], ms} 2893Specifies the report format for your document. 2894The report format creates a separate cover page. 2895The default action (no @code{.RP} 2896macro) is to print a subset of the 2897cover page on page 1 of your document. 2898 2899If you use the word @code{no} as an optional argument, 2900@code{groff} prints a title page but 2901does not repeat any of the title page information 2902(title, author, abstract, etc.) 2903on page 1 of the document. 2904@endDefmac 2905 2906@Defmac {DA, [@dots{}], ms} 2907(optional) Print the current date, or the arguments to the macro if any, 2908on the title page (if specified) and in the footers. 2909This is the default for @code{nroff}. 2910@endDefmac 2911 2912@Defmac {ND, [@dots{}], ms} 2913(optional) Print the current date, or the arguments to the macro if any, 2914on the title page (if specified) but not in the footers. 2915This is the default for @code{troff}. 2916@endDefmac 2917 2918@Defmac {TL, , ms} 2919Specifies the document title. 2920@code{groff} collects text following the @code{.TL} 2921macro into the title, until reaching the author name or abstract. 2922@endDefmac 2923 2924@Defmac {AU, , ms} 2925Specifies the author's name, which appears on the 2926line (or lines) immediately following. 2927You can specify multiple authors as follows: 2928 2929@Example 2930.AU 2931John Doe 2932.AI 2933University of West Bumblefuzz 2934.AU 2935Martha Buck 2936.AI 2937Monolithic Corporation 2938 2939... 2940@endExample 2941@endDefmac 2942 2943@Defmac {AI, , ms} 2944Specifies the author's institution. 2945You can specify multiple institutions in the same way 2946that you specify multiple authors. 2947@endDefmac 2948 2949@Defmac {AB, [@code{no}], ms} 2950Begins the abstract. 2951The default is to print the word @acronym{ABSTRACT}, 2952centered and in italics, above the text of the abstract. 2953The word @code{no} as an optional argument suppresses this heading. 2954@endDefmac 2955 2956@Defmac {AE, , ms} 2957End the abstract. 2958@endDefmac 2959 2960The following is example mark-up for a title page. 2961@cindex title page, example markup 2962@cindex example markup, title page 2963 2964@Example 2965@cartouche 2966.RP 2967.TL 2968The Inevitability of Code Bloat 2969in Commercial and Free Software 2970.AU 2971J. Random Luser 2972.AI 2973University of West Bumblefuzz 2974.AB 2975This report examines the long-term growth 2976of the code bases in two large, popular software 2977packages; the free Emacs and the commercial 2978Microsoft Word. 2979While differences appear in the type or order 2980of features added, due to the different 2981methodologies used, the results are the same 2982in the end. 2983.PP 2984The free software approach is shown to be 2985superior in that while free software can 2986become as bloated as commercial offerings, 2987free software tends to have fewer serious 2988bugs and the added features are in line with 2989user demand. 2990.AE 2991 2992... the rest of the paper follows ... 2993@end cartouche 2994@endExample 2995 2996@c --------------------------------------------------------------------- 2997 2998@node ms Body Text, ms Page Layout, ms Cover Page Macros, ms 2999@subsection Body text 3000@cindex @code{ms} macros, body text 3001 3002This section describes macros used to mark up the body of your document. 3003Examples include paragraphs, sections, and other groups. 3004 3005@menu 3006* Paragraphs in ms:: 3007* Headings in ms:: 3008* Highlighting in ms:: 3009* Lists in ms:: 3010* Indents in ms:: 3011* Tabstops in ms:: 3012* ms Displays and Keeps:: 3013* ms Insertions:: 3014* Example multi-page table:: 3015* ms Footnotes:: 3016@end menu 3017 3018@c --------------------------------------------------------------------- 3019 3020@node Paragraphs in ms, Headings in ms, ms Body Text, ms Body Text 3021@subsubsection Paragraphs 3022@cindex @code{ms} macros, paragraph handling 3023 3024The following paragraph types are available. 3025 3026@Defmac {PP, , ms} 3027Sets a paragraph with an initial indent. 3028@endDefmac 3029 3030@Defmac {LP, , ms} 3031Sets a paragraph with no initial indent. 3032@endDefmac 3033 3034@Defmac {QP, , ms} 3035Sets a paragraph that is indented at both left and right margins. 3036The effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} element. 3037The next paragraph or heading returns margins to normal. 3038@endDefmac 3039 3040@Defmac {XP, , ms} 3041Sets a paragraph whose lines are indented, 3042except for the first line. 3043This is a Berkeley extension. 3044@endDefmac 3045 3046The following markup uses all four paragraph macros. 3047 3048@Example 3049@cartouche 3050.NH 2 3051Cases used in the study 3052.LP 3053The following software and versions were 3054considered for this report. 3055.PP 3056For commercial software, we chose 3057.B "Microsoft Word for Windows" , 3058starting with version 1.0 through the 3059current version (Word 2000). 3060.PP 3061For free software, we chose 3062.B Emacs , 3063from its first appearance as a standalone 3064editor through the current version (v20). 3065See [Bloggs 2002] for details. 3066.QP 3067Franklin's Law applied to software: 3068software expands to outgrow both 3069RAM and disk space over time. 3070.LP 3071Bibliography: 3072.XP 3073Bloggs, Joseph R., 3074.I "Everyone's a Critic" , 3075Underground Press, March 2002. 3076A definitive work that answers all questions 3077and criticisms about the quality and usability of 3078free software. 3079 3080@end cartouche 3081@endExample 3082 3083@c --------------------------------------------------------------------- 3084 3085@node Headings in ms, Highlighting in ms, Paragraphs in ms, ms Body Text 3086@subsubsection Headings 3087@cindex @code{ms} macros, headings 3088 3089Use headings to create a hierarchical structure for your document. 3090The @file{ms} macros print headings in @strong{bold}, 3091using the same font family and point size as the body text. 3092 3093The following describes the heading macros: 3094 3095@DefmacList {NH, @Var{curr-level}, ms} 3096@DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms} 3097Numbered heading. 3098The argument is either a numeric argument to indicate the 3099level of the heading, or the letter@tie{}@code{S} followed by numeric 3100arguments to set the heading level explicitly. 3101 3102If you specify heading levels out of sequence, such as invoking 3103@samp{.NH 3} after @samp{.NH 1}, @code{groff} 3104prints a warning on standard error. 3105@endDefmac 3106 3107@Defmac {SH, , ms} 3108Unnumbered subheading. 3109@endDefmac 3110 3111@c --------------------------------------------------------------------- 3112 3113@node Highlighting in ms, Lists in ms, Headings in ms, ms Body Text 3114@subsubsection Highlighting 3115@cindex @code{ms} macros, highlighting 3116 3117The @file{ms} macros provide a variety of methods to highlight 3118or emphasize text: 3119 3120@Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3121Sets its first argument in @strong{bold type}. 3122If you specify a second argument, @code{groff} prints it in the 3123previous font after the bold text, with no intervening space 3124(this allows you to set punctuation after the highlighted text 3125without highlighting the punctuation). 3126Similarly, it prints the third argument (if any) in the previous 3127font @strong{before} the first argument. 3128For example, 3129 3130@Example 3131.B foo ) ( 3132@endExample 3133 3134prints (@strong{foo}). 3135 3136If you give this macro no arguments, @code{groff} 3137prints all text following in bold until 3138the next highlighting, paragraph, or heading macro. 3139@endDefmac 3140 3141@Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3142Sets its first argument in roman (or regular) type. 3143It operates similarly to the @code{B}@tie{}macro otherwise. 3144@endDefmac 3145 3146@Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3147Sets its first argument in @emph{italic type}. 3148It operates similarly to the @code{B}@tie{}macro otherwise. 3149@endDefmac 3150 3151@Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3152Sets its first argument in a @code{constant width face}. 3153It operates similarly to the @code{B}@tie{}macro otherwise. 3154@endDefmac 3155 3156@Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} 3157Sets its first argument in bold italic type. 3158It operates similarly to the @code{B}@tie{}macro otherwise. 3159@endDefmac 3160 3161@Defmac {BX, [@Var{txt}], ms} 3162Prints its argument and draws a box around it. 3163If you want to box a string that contains spaces, 3164use a digit-width space (@code{\0}). 3165@endDefmac 3166 3167@Defmac {UL, [@Var{txt} [@Var{post}]], ms} 3168Prints its first argument with an underline. 3169If you specify a second argument, @code{groff} 3170prints it in the previous font after 3171the underlined text, with no intervening space. 3172@endDefmac 3173 3174@Defmac {LG, , ms} 3175Prints all text following in larger type 3176(two points larger than the current point size) until 3177the next font size, highlighting, paragraph, or heading macro. 3178You can specify this macro multiple times 3179to enlarge the point size as needed. 3180@endDefmac 3181 3182@Defmac {SM, , ms} 3183Prints all text following in smaller type 3184(two points smaller than the current point size) until 3185the next type size, highlighting, paragraph, or heading macro. 3186You can specify this macro multiple times 3187to reduce the point size as needed. 3188@endDefmac 3189 3190@Defmac {NL, , ms} 3191Prints all text following in the normal point size 3192(that is, the value of the @code{PS} register). 3193@endDefmac 3194 3195@c --------------------------------------------------------------------- 3196 3197@node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text 3198@subsubsection Lists 3199@cindex @code{ms} macros, lists 3200 3201The @code{.IP} macro handles duties for all lists. 3202 3203@Defmac {IP, [@Var{marker} [@Var{width}]], ms} 3204The @var{marker} is usually a bullet glyph (@code{\[bu]}) 3205for unordered lists, a number (or auto-incrementing number 3206register) for numbered lists, or a word or phrase for indented 3207(glossary-style) lists. 3208 3209The @var{width} specifies the indent for the body of each list item; 3210its default unit is @samp{n}. 3211Once specified, the indent remains the same for all 3212list items in the document until specified again. 3213@endDefmac 3214 3215The following is an example of a bulleted list. 3216@cindex example markup, bulleted list [@code{ms}] 3217@cindex bulleted list, example markup [@code{ms}] 3218 3219@Example 3220A bulleted list: 3221.IP \[bu] 2 3222lawyers 3223.IP \[bu] 3224guns 3225.IP \[bu] 3226money 3227@endExample 3228 3229Produces: 3230 3231@Example 3232A bulleted list: 3233 3234o lawyers 3235 3236o guns 3237 3238o money 3239@endExample 3240 3241@sp 1 3242 3243The following is an example of a numbered list. 3244@cindex example markup, numbered list [@code{ms}] 3245@cindex numbered list, example markup [@code{ms}] 3246 3247@Example 3248.nr step 1 1 3249A numbered list: 3250.IP \n[step] 3 3251lawyers 3252.IP \n+[step] 3253guns 3254.IP \n+[step] 3255money 3256@endExample 3257 3258Produces: 3259 3260@Example 3261A numbered list: 3262 32631. lawyers 3264 32652. guns 3266 32673. money 3268@endExample 3269 3270Note the use of the auto-incrementing number 3271register in this example. 3272 3273@sp 1 3274The following is an example of a glossary-style list. 3275@cindex example markup, glossary-style list [@code{ms}] 3276@cindex glossary-style list, example markup [@code{ms}] 3277 3278@Example 3279A glossary-style list: 3280.IP lawyers 0.4i 3281Two or more attorneys. 3282.IP guns 3283Firearms, preferably 3284large-caliber. 3285.IP money 3286Gotta pay for those 3287lawyers and guns! 3288@endExample 3289 3290Produces: 3291 3292@Example 3293A glossary-style list: 3294 3295lawyers 3296 Two or more attorneys. 3297 3298guns Firearms, preferably large-caliber. 3299 3300money 3301 Gotta pay for those lawyers and guns! 3302@endExample 3303 3304In the last example, the @code{IP} macro places the definition 3305on the same line as the term if it has enough space; otherwise, 3306it breaks to the next line and starts the definition below the 3307term. 3308This may or may not be the effect you want, especially if some 3309of the definitions break and some do not. 3310The following examples show two possible ways to force a break. 3311 3312The first workaround uses the @code{br} 3313request to force a break after printing the term or label. 3314 3315@Example 3316@cartouche 3317A glossary-style list: 3318.IP lawyers 0.4i 3319Two or more attorneys. 3320.IP guns 3321.br 3322Firearms, preferably large-caliber. 3323.IP money 3324Gotta pay for those lawyers and guns! 3325@end cartouche 3326@endExample 3327 3328@sp 1 3329The second workaround uses the @code{\p} escape to force the break. 3330Note the space following the escape; this is important. 3331If you omit the space, @code{groff} prints the first word on 3332the same line as the term or label (if it fits) @strong{then} 3333breaks the line. 3334 3335@Example 3336@cartouche 3337A glossary-style list: 3338.IP lawyers 0.4i 3339Two or more attorneys. 3340.IP guns 3341\p Firearms, preferably large-caliber. 3342.IP money 3343Gotta pay for those lawyers and guns! 3344@end cartouche 3345@endExample 3346 3347@sp 1 3348To set nested lists, use the @code{RS} and @code{RE} macros. 3349@xref{Indents in ms}, for more information. 3350@cindex @code{ms} macros, nested lists 3351@cindex nested lists [@code{ms}] 3352 3353For example: 3354 3355@Example 3356@cartouche 3357.IP \[bu] 2 3358Lawyers: 3359.RS 3360.IP \[bu] 3361Dewey, 3362.IP \[bu] 3363Cheatham, 3364.IP \[bu] 3365and Howe. 3366.RE 3367.IP \[bu] 3368Guns 3369@end cartouche 3370@endExample 3371 3372Produces: 3373 3374@Example 3375o Lawyers: 3376 3377 o Dewey, 3378 3379 o Cheatham, 3380 3381 o and Howe. 3382 3383o Guns 3384@endExample 3385 3386@c --------------------------------------------------------------------- 3387 3388@node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text 3389@subsubsection Indents 3390 3391In many situations, 3392you may need to indent a section of text 3393while still wrapping and filling. 3394@xref{Lists in ms}, 3395for an example of nested lists. 3396 3397@DefmacList {RS, , ms} 3398@DefmacListEnd {RE, , ms} 3399These macros begin and end an indented section. 3400The @code{PI} register controls the amount of indent, 3401allowing the indented text to line up under hanging 3402and indented paragraphs. 3403@endDefmac 3404 3405@xref{ms Displays and Keeps}, 3406for macros to indent and turn off filling. 3407 3408@c --------------------------------------------------------------------- 3409 3410@node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text 3411@subsubsection Tab Stops 3412 3413Use the @code{ta} request to define tab stops as needed. 3414@xref{Tabs and Fields}. 3415 3416@Defmac{TA, , ms} 3417Use this macro to reset the tab stops to the default for @file{ms} 3418(every 5n). 3419You can redefine the @code{TA} macro to create a different set 3420of default tab stops. 3421@endDefmac 3422 3423@c --------------------------------------------------------------------- 3424 3425@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text 3426@subsubsection Displays and keeps 3427@cindex @code{ms} macros, displays 3428@cindex @code{ms} macros, keeps 3429@cindex keeps [@code{ms}] 3430@cindex displays [@code{ms}] 3431 3432Use displays to show text-based examples or figures 3433(such as code listings). 3434 3435Displays turn off filling, so lines of code are displayed 3436as-is without inserting @code{br} requests in between each line. 3437Displays can be @dfn{kept} on a single page, or allowed 3438to break across pages. 3439 3440@DefmacList {DS, @t{L}, ms} 3441@DefmacItem {LD, , ms} 3442@DefmacListEnd {DE, , ms} 3443Left-justified display. 3444The @samp{.DS L} call generates a page break, if necessary, 3445to keep the entire display on one page. 3446The @code{LD} macro allows the display to break across pages. 3447The @code{DE} macro ends the display. 3448@endDefmac 3449 3450@DefmacList {DS, @t{I}, ms} 3451@DefmacItem {ID, , ms} 3452@DefmacListEnd {DE, , ms} 3453Indents the display as defined by the @code{DI} register. 3454The @samp{.DS I} call generates a page break, if necessary, 3455to keep the entire display on one page. 3456The @code{ID} macro allows the display to break across pages. 3457The @code{DE} macro ends the display. 3458@endDefmac 3459 3460@DefmacList {DS, @t{B}, ms} 3461@DefmacItem {BD, , ms} 3462@DefmacListEnd {DE, , ms} 3463Sets a block-centered display: the entire display is left-justified, 3464but indented so that the longest line in the display is centered 3465on the page. 3466The @samp{.DS B} call generates a page break, if necessary, 3467to keep the entire display on one page. 3468The @code{BD} macro allows the display to break across pages. 3469The @code{DE} macro ends the display. 3470@endDefmac 3471 3472@DefmacList {DS, @t{C}, ms} 3473@DefmacItem {CD, , ms} 3474@DefmacListEnd {DE, , ms} 3475Sets a centered display: each line in the display is centered. 3476The @samp{.DS C} call generates a page break, if necessary, 3477to keep the entire display on one page. 3478The @code{CD} macro allows the display to break across pages. 3479The @code{DE} macro ends the display. 3480@endDefmac 3481 3482@DefmacList {DS, @t{R}, ms} 3483@DefmacItem {RD, , ms} 3484@DefmacListEnd {DE, , ms} 3485Right-justifies each line in the display. 3486The @samp{.DS R} call generates a page break, if necessary, 3487to keep the entire display on one page. 3488The @code{RD} macro allows the display to break across pages. 3489The @code{DE} macro ends the display. 3490@endDefmac 3491 3492@sp 1 3493On occasion, you may want to @dfn{keep} other text together on a page. 3494For example, you may want to keep two paragraphs together, or 3495a paragraph that refers to a table (or list, or other item) 3496immediately following. 3497The @file{ms} macros provide the @code{KS} and @code{KE} 3498macros for this purpose. 3499 3500@DefmacList {KS, , ms} 3501@DefmacListEnd {KE, , ms} 3502The @code{KS} macro begins a block of text to be kept on a 3503single page, and the @code{KE} macro ends the block. 3504@endDefmac 3505 3506@DefmacList {KF, , ms} 3507@DefmacListEnd {KE, , ms} 3508Specifies a @dfn{floating keep}; 3509if the keep cannot fit on the current page, @code{groff} 3510holds the contents of the keep and allows text following 3511the keep (in the source file) to fill in the remainder of 3512the current page. 3513When the page breaks, whether by an explicit @code{bp} 3514request or by reaching the end of the page, @code{groff} 3515prints the floating keep at the top of the new page. 3516This is useful for printing large graphics or tables 3517that do not need to appear exactly where specified. 3518@endDefmac 3519 3520You can also use the @code{ne} request to force a page break if 3521there is not enough vertical space remaining on the page. 3522 3523@sp 1 3524Use the following macros to draw a box around a section of 3525text (such as a display). 3526 3527@DefmacList {B1, , ms} 3528@DefmacListEnd {B2, , ms} 3529Marks the beginning and ending of text that is to have a 3530box drawn around it. 3531The @code{B1} macro begins the box; the @code{B2} macro ends it. 3532Text in the box is automatically placed in a diversion (keep). 3533@endDefmac 3534 3535@c --------------------------------------------------------------------- 3536 3537@node ms Insertions, Example multi-page table, ms Displays and Keeps, ms Body Text 3538@subsubsection Tables, figures, equations, and references 3539@cindex @code{ms} macros, tables 3540@cindex @code{ms} macros, figures 3541@cindex @code{ms} macros, equations 3542@cindex @code{ms} macros, references 3543@cindex tables [@code{ms}] 3544@cindex figures [@code{ms}] 3545@cindex equations [@code{ms}] 3546@cindex references [@code{ms}] 3547 3548The @file{ms} macros support the standard 3549@code{groff} preprocessors: 3550@code{tbl}, @code{pic}, @code{eqn}, and @code{refer}. 3551@pindex tbl 3552@pindex pic 3553@pindex eqn 3554@pindex refer 3555You mark text meant for preprocessors by enclosing it 3556in pairs of tags as follows. 3557 3558@DefmacList {TS, [@code{H}], ms} 3559@DefmacListEnd {TE, , ms} 3560Denotes a table, to be processed by the @code{tbl} preprocessor. 3561The optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} 3562to create a running header with the information 3563up to the @code{TH} macro. 3564@code{groff} prints the header at the beginning of the 3565table; if the table runs onto another page, @code{groff} 3566prints the header on the next page as well. 3567@endDefmac 3568 3569@DefmacList {PS, , ms} 3570@DefmacListEnd {PE, , ms} 3571Denotes a graphic, to be processed by the @code{pic} preprocessor. 3572You can create a @code{pic} file by hand, using the @acronym{AT&T} 3573@code{pic} manual available on the Web as a reference, or by using 3574a graphics program such as @code{xfig}. 3575@endDefmac 3576 3577@DefmacList {EQ, [@Var{align}], ms} 3578@DefmacListEnd {EN, , ms} 3579Denotes an equation, to be processed by the @code{eqn} preprocessor. 3580The optional @var{align} argument can be @code{C}, @code{L}, 3581or@tie{}@code{I} to center (the default), left-justify, or indent the 3582equation. 3583@endDefmac 3584 3585@DefmacList {[, , ms} 3586@DefmacListEnd {], , ms} 3587Denotes a reference, to be processed by the @code{refer} preprocessor. 3588The @acronym{GNU} @cite{refer(1)} man page provides a comprehensive 3589reference to the preprocessor and the format of the bibliographic 3590database. 3591@endDefmac 3592 3593@menu 3594* Example multi-page table:: 3595@end menu 3596 3597@c --------------------------------------------------------------------- 3598 3599@node Example multi-page table, ms Footnotes, ms Insertions, ms Body Text 3600@subsubsection An example multi-page table 3601@cindex example markup, multi-page table [@code{ms}] 3602@cindex multi-page table, example markup [@code{ms}] 3603 3604The following is an example of how to set up a 3605table that may print across two or more pages. 3606 3607@Example 3608@cartouche 3609.TS H 3610allbox expand; 3611cb | cb . 3612Text ...of heading... 3613_ 3614.TH 3615.T& 3616l | l . 3617... the rest of the table follows... 3618.CW 3619.TE 3620@end cartouche 3621@endExample 3622 3623@c --------------------------------------------------------------------- 3624 3625@node ms Footnotes, , Example multi-page table, ms Body Text 3626@subsubsection Footnotes 3627@cindex @code{ms} macros, footnotes 3628@cindex footnotes [@code{ms}] 3629 3630The @file{ms} macro package has a flexible footnote system. 3631You can specify either numbered footnotes or symbolic footnotes 3632(that is, using a marker such as a dagger symbol). 3633 3634@Defstr {*, ms} 3635Specifies the location of a numbered footnote marker in the text. 3636@endDefesc 3637 3638@DefmacList {FS, , ms} 3639@DefmacListEnd {FE, , ms} 3640Specifies the text of the footnote. 3641The default action is to create a numbered footnote; 3642you can create a symbolic footnote by specifying 3643a @dfn{mark} glyph 3644(such as @code{\[dg]} for the dagger glyph) 3645in the body text and as an argument to the @code{FS} macro, 3646followed by the text of the footnote 3647and the @code{FE} macro. 3648@endDefmac 3649 3650You can control how @code{groff} 3651prints footnote numbers by changing the value of the 3652@code{FF} register. @xref{ms Document Control Registers}. 3653 3654@c --------------------------------------------------------------------- 3655 3656@node ms Page Layout, Differences from AT&T ms, ms Body Text, ms 3657@subsection Page layout 3658@cindex @code{ms} macros, page layout 3659@cindex page layout [@code{ms}] 3660 3661The default output from the @file{ms} 3662macros provides a minimalist page layout: 3663it prints a single column, with the page number centered at the top 3664of each page. 3665It prints no footers. 3666 3667You can change the layout by setting 3668the proper number registers and strings. 3669 3670@menu 3671* ms Headers and Footers:: 3672* ms Margins:: 3673* ms Multiple Columns:: 3674* ms TOC:: 3675* ms Strings and Special Characters:: 3676@end menu 3677 3678@c --------------------------------------------------------------------- 3679 3680@node ms Headers and Footers, ms Margins, ms Page Layout, ms Page Layout 3681@subsubsection Headers and footers 3682@cindex @code{ms} macros, headers 3683@cindex @code{ms} macros, footers 3684@cindex headers [@code{ms}] 3685@cindex footers [@code{ms}] 3686 3687For documents that do not distinguish between odd and even pages, 3688set the following strings: 3689 3690@DefstrList {LH, ms} 3691@DefstrItem {CH, ms} 3692@DefstrListEnd {RH, ms} 3693Sets the left, center, and right headers. 3694@endDefstr 3695 3696@DefstrList {LF, ms} 3697@DefstrItem {CF, ms} 3698@DefstrListEnd {RF, ms} 3699Sets the left, center, and right footers. 3700@endDefstr 3701 3702@sp 1 3703For documents that need different information printed in the 3704even and odd pages, use the following macros: 3705 3706@DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3707@DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3708@DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3709@DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} 3710The @code{OH} and @code{EH} macros define headers for the odd and even pages; 3711the @code{OF} and @code{EF} macros define footers for the odd and even pages. 3712This is more flexible than defining the individual strings. 3713 3714You can replace the quote (@code{'}) marks with any character not 3715appearing in the header or footer text. 3716@endDefmac 3717 3718@c --------------------------------------------------------------------- 3719 3720@node ms Margins, ms Multiple Columns, ms Headers and Footers, ms Page Layout 3721@subsubsection Margins 3722@cindex @code{ms} macros, margins 3723 3724You control margins using a set of number registers. 3725@xref{ms Document Control Registers}, for details. 3726 3727@c --------------------------------------------------------------------- 3728 3729@node ms Multiple Columns, ms TOC, ms Margins, ms Page Layout 3730@subsubsection Multiple columns 3731@cindex @code{ms} macros, multiple columns 3732@cindex multiple columns [@code{ms}] 3733 3734The @file{ms} macros can set text in as many columns as will 3735reasonably fit on the page. 3736The following macros are available; 3737all of them force a page break if a multi-column mode is already set. 3738However, if the current mode is single-column, starting a multi-column 3739mode does @strong{not} force a page break. 3740 3741@Defmac {1C, , ms} 3742Single-column mode. 3743@endDefmac 3744 3745@Defmac {2C, , ms} 3746Two-column mode. 3747@endDefmac 3748 3749@Defmac {MC, [@Var{width} [@Var{gutter}]], ms} 3750Multi-column mode. 3751If you specify no arguments, it is equivalent to the 3752@code{2C} macro. 3753Otherwise, @var{width} is the width of each column and 3754@var{gutter} is the space between columns. 3755The @code{MINGW} number register controls the default gutter width. 3756@endDefmac 3757 3758@c --------------------------------------------------------------------- 3759 3760@node ms TOC, ms Strings and Special Characters, ms Multiple Columns, ms Page Layout 3761@subsubsection Creating a table of contents 3762@cindex @code{ms} macros, creating table of contents 3763@cindex table of contents, creating [@code{ms}] 3764 3765The facilities in the @file{ms} macro package for creating 3766a table of contents are semi-automated at best. 3767Assuming that you want the table of contents to consist of 3768the document's headings, you need to repeat those headings 3769wrapped in @code{XS} and @code{XE} macros. 3770 3771@DefmacList {XS, [@Var{page}], ms} 3772@DefmacItem {XA, [@Var{page}], ms} 3773@DefmacListEnd {XE, , ms} 3774These macros define a table of contents 3775or an individual entry in the table of contents, 3776depending on their use. 3777The macros are very simple; they cannot indent a heading based on its level. 3778The easiest way to work around this is to add tabs 3779to the table of contents string. 3780The following is an example: 3781 3782@Example 3783@cartouche 3784.NH 1 3785Introduction 3786.XS 3787Introduction 3788.XE 3789.LP 3790... 3791.CW 3792.NH 2 3793Methodology 3794.XS 3795Methodology 3796.XE 3797.LP 3798... 3799@end cartouche 3800@endExample 3801 3802You can manually create a table of contents 3803by beginning with the @code{XS} macro for the first entry, 3804specifying the page number for that entry as the argument to @code{XS}. 3805Add subsequent entries using the @code{XA} macro, 3806specifying the page number for that entry as the argument to @code{XA}. 3807The following is an example: 3808 3809@Example 3810@cartouche 3811.XS 1 3812Introduction 3813.XA 2 3814A Brief History of the Universe 3815.XA 729 3816Details of Galactic Formation 3817... 3818.XE 3819@end cartouche 3820@endExample 3821@endDefmac 3822 3823@Defmac {TC, [@code{no}], ms} 3824Prints the table of contents on a new page, 3825setting the page number to@tie{}@strong{i} (Roman numeral one). 3826You should usually place this macro at the end of the 3827file, since @code{groff} is a single-pass formatter and 3828can only print what has been collected up to the point 3829that the @code{TC} macro appears. 3830 3831The optional argument @code{no} suppresses printing 3832the title specified by the string register @code{TOC}. 3833@endDefmac 3834 3835@Defmac{PX, [@code{no}], ms} 3836Prints the table of contents on a new page, 3837using the current page numbering sequence. 3838Use this macro to print a manually-generated table of contents 3839at the beginning of your document. 3840 3841The optional argument @code{no} suppresses printing 3842the title specified by the string register @code{TOC}. 3843@endDefmac 3844 3845The @cite{Groff and Friends HOWTO} 3846includes a @code{sed} script that automatically inserts 3847@code{XS} and @code{XE} macro entries after each heading in a document. 3848 3849Altering the @code{NH} macro to automatically build the table 3850of contents is perhaps initially more difficult, but would save 3851a great deal of time in the long run if you use @file{ms} regularly. 3852 3853@c --------------------------------------------------------------------- 3854 3855@node ms Strings and Special Characters, , ms TOC, ms Page Layout 3856@subsubsection Strings and Special Characters 3857@cindex @code{ms} macros, strings 3858@cindex @code{ms} macros, special characters 3859@cindex @code{ms} macros, accent marks 3860@cindex accent marks [@code{ms}] 3861@cindex special characters [@code{ms}] 3862@cindex strings [@code{ms}] 3863 3864The @file{ms} macros provide the following predefined strings. 3865You can change the string definitions to help in creating 3866documents in languages other than English. 3867 3868@Defstr {REFERENCES, ms} 3869Contains the string printed at the beginning of the 3870references (bibliography) page. 3871The default is @samp{References}. 3872@endDefstr 3873 3874@Defstr {ABSTRACT, ms} 3875Contains the string printed at the beginning of the abstract. 3876The default is @samp{ABSTRACT}. 3877@endDefstr 3878 3879@Defstr {TOC, ms} 3880Contains the string printed at the beginning of the table of contents. 3881@endDefstr 3882 3883@DefstrList {MONTH1, ms} 3884@DefstrItem {MONTH2, ms} 3885@DefstrItem {MONTH3, ms} 3886@DefstrItem {MONTH4, ms} 3887@DefstrItem {MONTH5, ms} 3888@DefstrItem {MONTH6, ms} 3889@DefstrItem {MONTH7, ms} 3890@DefstrItem {MONTH8, ms} 3891@DefstrItem {MONTH9, ms} 3892@DefstrItem {MONTH10, ms} 3893@DefstrItem {MONTH11, ms} 3894@DefstrListEnd {MONTH12, ms} 3895Prints the full name of the month in dates. 3896The default is @samp{January}, @samp{February}, etc. 3897@endDefstr 3898 3899The following special characters are available@footnote{For an 3900explanation what special characters are see @ref{Special Characters}.}: 3901 3902@Defstr {-, ms} 3903Prints an em dash. 3904@endDefstr 3905 3906@DefstrList {*Q, ms} 3907@DefstrListEnd {*U, ms} 3908Prints typographer's quotes in troff, 3909plain quotes in nroff. 3910@code{*Q} is the left quote and @code{*U} is the right quote. 3911@endDefstr 3912 3913Improved accent marks are available in the @file{ms} macros. 3914 3915@Defmac {AM, , ms} 3916Specify this macro at the beginning of your document 3917to enable extended accent marks and special characters. 3918This is a Berkeley extension. 3919 3920To use the accent marks, place them @strong{after} 3921the character being accented. 3922@endDefmac 3923 3924The following accent marks are available 3925after invoking the @code{AM} macro: 3926 3927@Defstr {\', ms} 3928Acute accent. 3929@endDefstr 3930 3931@Defstr {\`, ms} 3932Grave accent. 3933@endDefstr 3934 3935@Defstr {^, ms} 3936Circumflex. 3937@endDefstr 3938 3939@Defstr {\,, ms} 3940Cedilla. 3941@endDefstr 3942 3943@Defstr {~, ms} 3944Tilde. 3945@endDefstr 3946 3947@deffn String @t{\*[:]} 3948@ifnotinfo 3949@stindex : @r{[}ms@r{]} 3950@end ifnotinfo 3951@ifinfo 3952@stindex \*[@r{<colon>}] @r{[}ms@r{]} 3953@end ifinfo 3954Umlaut. 3955@end deffn 3956 3957@Defstr {v, ms} 3958Hacek. 3959@endDefstr 3960 3961@Defstr {_, ms} 3962Macron (overbar). 3963@endDefstr 3964 3965@Defstr {., ms} 3966Underdot. 3967@endDefstr 3968 3969@Defstr {o, ms} 3970Ring above. 3971@endDefstr 3972 3973The following are standalone characters 3974available after invoking the @code{AM} macro: 3975 3976@Defstr {?, ms} 3977Upside-down question mark. 3978@endDefstr 3979 3980@Defstr {!, ms} 3981Upside-down exclamation point. 3982@endDefstr 3983 3984@Defstr {8, ms} 3985German @ss{} ligature. 3986@endDefstr 3987 3988@Defstr {3, ms} 3989Yogh. 3990@endDefstr 3991 3992@Defstr {Th, ms} 3993Uppercase thorn. 3994@endDefstr 3995 3996@Defstr {th, ms} 3997Lowercase thorn. 3998@endDefstr 3999 4000@Defstr {D-, ms} 4001Uppercase eth. 4002@endDefstr 4003 4004@Defstr {d-, ms} 4005Lowercase eth. 4006@endDefstr 4007 4008@Defstr {q, ms} 4009Hooked o. 4010@endDefstr 4011 4012@Defstr {ae, ms} 4013Lowercase @ae{} ligature. 4014@endDefstr 4015 4016@Defstr {Ae, ms} 4017Uppercase @AE{} ligature. 4018@endDefstr 4019 4020@c --------------------------------------------------------------------- 4021 4022@node Differences from AT&T ms, , ms Page Layout, ms 4023@subsection Differences from @acronym{AT&T} @file{ms} 4024@cindex @code{ms} macros, differences from @acronym{AT&T} 4025@cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences 4026 4027This section lists the (minor) differences between the 4028@code{groff -ms} macros and @acronym{AT&T} 4029@code{troff -ms} macros. 4030 4031@menu 4032* Missing ms Macros:: 4033* Additional ms Macros:: 4034@end menu 4035 4036@c --------------------------------------------------------------------- 4037 4038@node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms 4039@subsubsection @code{troff} macros not appearing in @code{groff} 4040 4041Macros missing from @code{groff -ms} 4042are cover page macros specific to Bell Labs. 4043The macros known to be missing are: 4044 4045@table @code 4046@item .TM 4047Technical memorandum; a cover sheet style 4048 4049@item .IM 4050Internal memorandum; a cover sheet style 4051 4052@item .MR 4053Memo for record; a cover sheet style 4054 4055@item .MF 4056Memo for file; a cover sheet style 4057 4058@item .EG 4059Engineer's notes; a cover sheet style 4060 4061@item .TR 4062Computing Science Tech Report; a cover sheet style 4063 4064@item .OK 4065Other keywords 4066 4067@item .CS 4068Cover sheet information 4069 4070@item .MH 4071A cover sheet macro 4072@end table 4073 4074@c --------------------------------------------------------------------- 4075 4076@node Additional ms Macros, , Missing ms Macros, Differences from AT&T ms 4077@subsubsection @code{groff} macros not appearing in @acronym{AT&T} @code{troff} 4078 4079The @code{groff -ms} macros have a few minor extensions 4080compared to the @acronym{AT&T} @code{troff -ms} macros. 4081 4082@Defmac {AM, , ms} 4083Improved accent marks. 4084@xref{ms Strings and Special Characters}, for details. 4085@endDefmac 4086 4087@Defmac {DS, @t{I}, ms} 4088Indented display. 4089The default behavior of @acronym{AT&T} @code{troff -ms} 4090was to indent; the @code{groff} default prints displays 4091flush left with the body text. 4092@endDefmac 4093 4094@Defmac {CW, , ms} 4095Print text in @code{constant width} (Courier) font. 4096@endDefmac 4097 4098@Defmac {IX, , ms} 4099Indexing term (printed on standard error). 4100You can write a script to capture and process an index 4101generated in this manner. 4102@endDefmac 4103 4104@sp 1 4105The following additional number registers 4106appear in @code{groff -ms}: 4107 4108@Defmpreg {MINGW, ms} 4109Specifies a minimum space 4110between columns (for multi-column output); this takes the 4111place of the @code{GW} register that was documented but apparently 4112not implemented in @acronym{AT&T} @code{troff}. 4113@endDefmpreg 4114 4115@sp 1 4116Several new string registers are available as well. 4117You can change these to handle (for example) the local language. 4118@xref{ms Strings and Special Characters}, for details. 4119 4120 4121@c ===================================================================== 4122 4123@node me, mm, ms, Macro Packages 4124@section @file{me} 4125@cindex @code{me} macro package 4126 4127@c XXX documentation 4128@c XXX this is a placeholder until we get stuff knocked into shape 4129See the @file{meintro.me} and @file{meref.me} documents in 4130groff's @file{doc} directory. 4131 4132 4133@c ===================================================================== 4134 4135@node mm, , me, Macro Packages 4136@section @file{mm} 4137@cindex @code{mm} macro package 4138 4139@c XXX documentation 4140@c XXX this is a placeholder until we get stuff knocked into shape 4141See the @cite{groff_mm(7)} man page (type @command{man groff_mm} at 4142the command line). 4143 4144 4145@c ===================================================================== 4146@c ===================================================================== 4147 4148@node gtroff Reference, Preprocessors, Macro Packages, Top 4149@chapter @code{gtroff} Reference 4150@cindex reference, @code{gtroff} 4151@cindex @code{gtroff}, reference 4152 4153This chapter covers @strong{all} of the facilities of @code{gtroff}. 4154Users of macro packages may skip it if not interested in details. 4155 4156 4157@menu 4158* Text:: 4159* Measurements:: 4160* Expressions:: 4161* Identifiers:: 4162* Embedded Commands:: 4163* Registers:: 4164* Manipulating Filling and Adjusting:: 4165* Manipulating Hyphenation:: 4166* Manipulating Spacing:: 4167* Tabs and Fields:: 4168* Character Translations:: 4169* Troff and Nroff Mode:: 4170* Line Layout:: 4171* Line Control:: 4172* Page Layout:: 4173* Page Control:: 4174* Fonts and Symbols:: 4175* Sizes:: 4176* Strings:: 4177* Conditionals and Loops:: 4178* Writing Macros:: 4179* Page Motions:: 4180* Drawing Requests:: 4181* Traps:: 4182* Diversions:: 4183* Environments:: 4184* Suppressing output:: 4185* Colors:: 4186* I/O:: 4187* Postprocessor Access:: 4188* Miscellaneous:: 4189* Gtroff Internals:: 4190* Debugging:: 4191* Implementation Differences:: 4192@end menu 4193 4194 4195@c ===================================================================== 4196 4197@node Text, Measurements, gtroff Reference, gtroff Reference 4198@section Text 4199@cindex text, @code{gtroff} processing 4200 4201@code{gtroff} input files contain text with control commands 4202interspersed throughout. But, even without control codes, @code{gtroff} 4203still does several things with the input text: 4204 4205@itemize @bullet 4206@item 4207filling and adjusting 4208 4209@item 4210adding additional space after sentences 4211 4212@item 4213hyphenating 4214 4215@item 4216inserting implicit line breaks 4217@end itemize 4218 4219@menu 4220* Filling and Adjusting:: 4221* Hyphenation:: 4222* Sentences:: 4223* Tab Stops:: 4224* Implicit Line Breaks:: 4225* Input Conventions:: 4226* Input Encodings:: 4227@end menu 4228 4229@c --------------------------------------------------------------------- 4230 4231@node Filling and Adjusting, Hyphenation, Text, Text 4232@subsection Filling and Adjusting 4233@cindex filling 4234@cindex adjusting 4235 4236When @code{gtroff} reads text, it collects words from the input and fits 4237as many of them together on one output line as it can. This is known as 4238@dfn{filling}. 4239 4240@cindex leading spaces 4241@cindex spaces, leading and trailing 4242@cindex extra spaces 4243@cindex trailing spaces 4244Once @code{gtroff} has a @dfn{filled} line, it tries to @dfn{adjust} 4245it. This means it widens the spacing between words until the text 4246reaches the right margin (in the default adjustment mode). Extra spaces 4247between words are preserved, but spaces at the end of lines are ignored. 4248Spaces at the front of a line cause a @dfn{break} (breaks are 4249explained in @ref{Implicit Line Breaks}). 4250 4251@xref{Manipulating Filling and Adjusting}. 4252 4253@c --------------------------------------------------------------------- 4254 4255@node Hyphenation, Sentences, Filling and Adjusting, Text 4256@subsection Hyphenation 4257@cindex hyphenation 4258 4259Since the odds are not great for finding a set of words, for every 4260output line, which fit nicely on a line without inserting excessive 4261amounts of space between words, @code{gtroff} hyphenates words so 4262that it can justify lines without inserting too much space between 4263words. It uses an internal hyphenation algorithm (a simplified version 4264of the algorithm used within @TeX{}) to indicate which words can be 4265hyphenated and how to do so. When a word is hyphenated, the first part 4266of the word is added to the current filled line being output (with 4267an attached hyphen), and the other portion is added to the next 4268line to be filled. 4269 4270@xref{Manipulating Hyphenation}. 4271 4272@c --------------------------------------------------------------------- 4273 4274@node Sentences, Tab Stops, Hyphenation, Text 4275@subsection Sentences 4276@cindex sentences 4277 4278Although it is often debated, some typesetting rules say there should be 4279different amounts of space after various punctuation marks. For 4280example, the @cite{Chicago typsetting manual} says that a period at the 4281end of a sentence should have twice as much space following it as would 4282a comma or a period as part of an abbreviation. 4283 4284@c XXX exact citation of Chicago manual 4285 4286@cindex sentence space 4287@cindex space between sentences 4288@cindex french-spacing 4289@code{gtroff} does this by flagging certain characters (normally 4290@samp{!}, @samp{?}, and @samp{.}) as @dfn{end-of-sentence} characters. 4291When @code{gtroff} encounters one of these characters at the end of a 4292line, it appends a normal space followed by a @dfn{sentence space} in 4293the formatted output. (This justifies one of the conventions mentioned 4294in @ref{Input Conventions}.) 4295 4296@cindex transparent characters 4297@cindex character, transparent 4298@cindex @code{dg} glyph, at end of sentence 4299@cindex @code{rq} glyph, at end of sentence 4300@cindex @code{"}, at end of sentence 4301@cindex @code{'}, at end of sentence 4302@cindex @code{)}, at end of sentence 4303@cindex @code{]}, at end of sentence 4304@cindex @code{*}, at end of sentence 4305In addition, the following characters and symbols are treated 4306transparently while handling end-of-sentence characters: @samp{"}, 4307@samp{'}, @samp{)}, @samp{]}, @samp{*}, @code{\[dg]}, and @code{\[rq]}. 4308 4309See the @code{cflags} request in @ref{Using Symbols}, for more details. 4310 4311@cindex @code{\&}, at end of sentence 4312To prevent the insertion of extra space after an end-of-sentence 4313character (at the end of a line), append @code{\&}. 4314 4315@c --------------------------------------------------------------------- 4316 4317@node Tab Stops, Implicit Line Breaks, Sentences, Text 4318@subsection Tab Stops 4319@cindex tab stops 4320@cindex stops, tabulator 4321@cindex tab character 4322@cindex character, tabulator 4323 4324@cindex @acronym{EBCDIC} encoding 4325@cindex encoding, @acronym{EBCDIC} 4326@code{gtroff} translates @dfn{tabulator characters}, also called 4327@dfn{tabs} (normally code point @acronym{ASCII} @code{0x09} or 4328@acronym{EBCDIC} @code{0x05}), in the input into movements to the next 4329tabulator stop. These tab stops are initially located every half inch 4330across the page. Using this, simple tables can be made easily. 4331However, it can often be deceptive as the appearance (and width) of the 4332text on a terminal and the results from @code{gtroff} can vary greatly. 4333 4334Also, a possible sticking point is that lines beginning with tab 4335characters are still filled, again producing unexpected results. 4336For example, the following input 4337 4338@multitable {12345678} {12345678} {12345678} {12345678} 4339@item 4340@tab 1 @tab 2 @tab 3 4341@item 4342@tab @tab 4 @tab 5 4343@end multitable 4344 4345@noindent 4346produces 4347 4348@multitable {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} {12345678} 4349@item 4350@tab 1 @tab 2 @tab 3 @tab @tab 4 @tab 5 4351@end multitable 4352 4353@xref{Tabs and Fields}. 4354 4355@c --------------------------------------------------------------------- 4356 4357@node Implicit Line Breaks, Input Conventions, Tab Stops, Text 4358@subsection Implicit Line Breaks 4359@cindex implicit line breaks 4360@cindex implicit breaks of lines 4361@cindex line, implicit breaks 4362@cindex break, implicit 4363@cindex line break 4364 4365An important concept in @code{gtroff} is the @dfn{break}. When a break 4366occurs, @code{gtroff} outputs the partially filled line 4367(unjustified), and resumes collecting and filling text on the next output 4368line. 4369 4370@cindex blank line 4371@cindex empty line 4372@cindex line, blank 4373@cindex blank line macro (@code{blm}) 4374There are several ways to cause a break in @code{gtroff}. A blank 4375line not only causes a break, but it also outputs a one-line vertical 4376space (effectively a blank line). Note that this behaviour can be 4377modified with the blank line macro request @code{blm}. 4378@xref{Blank Line Traps}. 4379 4380@cindex fill mode 4381@cindex mode, fill 4382A line that begins with a space causes a break and the space is 4383output at the beginning of the next line. Note that this space isn't 4384adjusted, even in fill mode. 4385 4386The end of file also causes a break -- otherwise the last line of 4387the document may vanish! 4388 4389Certain requests also cause breaks, implicitly or explicitly. This is 4390discussed in @ref{Manipulating Filling and Adjusting}. 4391 4392@c --------------------------------------------------------------------- 4393 4394@node Input Conventions, Input Encodings, Implicit Line Breaks, Text 4395@subsection Input Conventions 4396@cindex input conventions 4397@cindex conventions for input 4398 4399Since @code{gtroff} does filling automatically, it is traditional in 4400@code{groff} not to try and type things in as nicely formatted 4401paragraphs. These are some conventions commonly used when typing 4402@code{gtroff} text: 4403 4404@itemize @bullet 4405@item 4406Break lines after punctuation, particularly at the end of a sentence 4407and in other logical places. Keep separate phrases on lines by 4408themselves, as entire phrases are often added or deleted when editing. 4409 4410@item 4411Try to keep lines less than 40-60@tie{}characters, to allow space for 4412inserting more text. 4413 4414@item 4415Do not try to do any formatting in a @acronym{WYSIWYG} manner (i.e., 4416don't try using spaces to get proper indentation). 4417@end itemize 4418 4419@c --------------------------------------------------------------------- 4420 4421@node Input Encodings, , Input Conventions, Text 4422@subsection Input Encodings 4423 4424Currently, the following input encodings are available. 4425 4426@table @asis 4427@item cp1047 4428@cindex encoding, input, @acronym{EBCDIC} 4429@cindex @acronym{EBCDIC}, input encoding 4430@cindex input encoding, @acronym{EBCDIC} 4431@cindex encoding, input, cp1047 4432@cindex cp1047, input encoding 4433@cindex input encoding, cp1047 4434@cindex IBM cp1047 input encoding 4435@pindex cp1047.tmac 4436This input encoding works only on @acronym{EBCDIC} platforms (and vice 4437versa, the other input encodings don't work with @acronym{EBCDIC}); the 4438file @file{cp1047.tmac} is by default loaded at start-up. 4439 4440@item latin-1 4441@cindex encoding, input, @w{latin-1} (ISO @w{8859-1}) 4442@cindex @w{latin-1} (ISO @w{8859-1}), input encoding 4443@cindex ISO @w{8859-1} (@w{latin-1}), input encoding 4444@cindex input encoding, @w{latin-1} (ISO @w{8859-1}) 4445@pindex latin1.tmac 4446This is the default input encoding on non-@acronym{EBCDIC} platforms; 4447the file @file{latin1.tmac} is loaded at start-up. 4448 4449@item latin-2 4450@cindex encoding, input, @w{latin-2} (ISO @w{8859-2}) 4451@cindex @w{latin-2} (ISO @w{8859-2}), input encoding 4452@cindex ISO @w{8859-2} (@w{latin-2}), input encoding 4453@cindex input encoding, @w{latin-2} (ISO @w{8859-2}) 4454@pindex latin2.tmac 4455To use this encoding, either say @w{@samp{.mso latin2.tmac}} at the very 4456beginning of your document or use @samp{-mlatin2} as a command line 4457argument for @code{groff}. 4458 4459@item latin-9 (latin-0) 4460@cindex encoding, input, @w{latin-9} (@w{latin-0}, ISO @w{8859-15}) 4461@cindex @w{latin-9} (@w{latin-0}, ISO @w{8859-15}), input encoding 4462@cindex ISO @w{8859-15} (@w{latin-9}, @w{latin-0}), input encoding 4463@cindex input encoding, @w{latin-9} (@w{latin-9}, ISO @w{8859-15}) 4464@pindex latin9.tmac 4465This encoding is intended (at least in Europe) to replace @w{latin-1} 4466encoding. The main difference to @w{latin-1} is that @w{latin-9} 4467contains the Euro character. To use this encoding, either say 4468@w{@samp{.mso latin9.tmac}} at the very beginning of your document or 4469use @samp{-mlatin9} as a command line argument for @code{groff}. 4470@end table 4471 4472Note that it can happen that some input encoding characters are not 4473available for a particular output device. For example, saying 4474 4475@Example 4476groff -Tlatin1 -mlatin9 ... 4477@endExample 4478 4479@noindent 4480will fail if you use the Euro character in the input. Usually, this 4481limitation is present only for devices which have a limited set of 4482output glyphs (e.g.@: @option{-Tascii} and @option{-Tlatin1}); for other 4483devices it is usually sufficient to install proper fonts which contain 4484the necessary glyphs. 4485 4486@pindex freeeuro.pfa 4487@pindex ec.tmac 4488Due to the importance of the Euro glyph in Europe, the groff package now 4489comes with a @sc{PostScript} font called @file{freeeuro.pfa} which 4490provides various glyph shapes for the Euro. With other words, 4491@w{latin-9} encoding is supported for the @option{-Tps} device out of 4492the box (@w{latin-2} isn't). 4493 4494By its very nature, @option{-Tutf8} supports all input encodings; 4495@option{-Tdvi} has support for both @w{latin-2} and @w{latin-9} if the 4496command line @option{-mec} is used also to load the file @file{ec.tmac} 4497(which flips to the EC fonts). 4498 4499 4500@c ===================================================================== 4501 4502@node Measurements, Expressions, Text, gtroff Reference 4503@section Measurements 4504@cindex measurements 4505 4506@cindex units of measurement 4507@cindex basic unit (@code{u}) 4508@cindex machine unit (@code{u}) 4509@cindex measurement unit 4510@cindex @code{u} unit 4511@cindex unit, @code{u} 4512@code{gtroff} (like many other programs) requires numeric parameters to 4513specify various measurements. Most numeric parameters@footnote{those 4514that specify vertical or horizontal motion or a type size} may have a 4515@dfn{measurement unit} attached. These units are specified as a single 4516character which immediately follows the number or expression. Each of 4517these units are understood, by @code{gtroff}, to be a multiple of its 4518@dfn{basic unit}. So, whenever a different measurement unit is 4519specified @code{gtroff} converts this into its @dfn{basic units}. This 4520basic unit, represented by a @samp{u}, is a device dependent measurement 4521which is quite small, ranging from 1/75@dmn{th} to 1/72000@dmn{th} of an 4522inch. The values may be given as fractional numbers; however, 4523fractional basic units are always rounded to integers. 4524 4525Some of the measurement units are completely independent of any of the 4526current settings (e.g.@: type size) of @code{gtroff}. 4527 4528@table @code 4529@item i 4530@cindex inch unit (@code{i}) 4531@cindex @code{i} unit 4532@cindex unit, @code{i} 4533Inches. An antiquated measurement unit still in use in certain 4534backwards countries with incredibly low-cost computer equipment. One 4535inch is equal to@tie{}2.54@dmn{cm}. 4536 4537@item c 4538@cindex centimeter unit (@code{c}) 4539@cindex @code{c} unit 4540@cindex unit, @code{c} 4541Centimeters. One centimeter is equal to@tie{}0.3937@dmn{in}. 4542 4543@item p 4544@cindex point unit (@code{p}) 4545@cindex @code{p} unit 4546@cindex unit, @code{p} 4547Points. This is a typesetter's measurement used for measure type size. 4548It is 72@tie{}points to an inch. 4549 4550@item P 4551@cindex pica unit (@code{P}) 4552@cindex @code{P} unit 4553@cindex unit, @code{P} 4554Pica. Another typesetting measurement. 6@tie{}Picas to an inch (and 455512@tie{}points to a pica). 4556 4557@item s 4558@itemx z 4559@cindex @code{s} unit 4560@cindex unit, @code{s} 4561@cindex @code{z} unit 4562@cindex unit, @code{z} 4563@xref{Fractional Type Sizes}, for a discussion of these units. 4564 4565@item f 4566@cindex @code{f} unit 4567@cindex unit, @code{f} 4568Fractions. Value is 65536. 4569@xref{Colors}, for usage. 4570@end table 4571 4572The other measurements understood by @code{gtroff} depend on 4573settings currently in effect in @code{gtroff}. These are very useful 4574for specifying measurements which should look proper with any size of 4575text. 4576 4577@table @code 4578@item m 4579@cindex em unit (@code{m}) 4580@cindex @code{m} unit 4581@cindex unit, @code{m} 4582Ems. This unit is equal to the current font size in points. So called 4583because it is @emph{approximately} the width of the letter@tie{}@samp{m} 4584in the current font. 4585 4586@item n 4587@cindex en unit (@code{n}) 4588@cindex @code{n} unit 4589@cindex unit, @code{n} 4590Ens. In @code{groff}, this is half of an em. 4591 4592@item v 4593@cindex vertical space unit (@code{v}) 4594@cindex space, vertical, unit (@code{v}) 4595@cindex @code{v} unit 4596@cindex unit, @code{v} 4597Vertical space. This is equivalent to the current line spacing. 4598@xref{Sizes}, for more information about this. 4599 4600@item M 4601@cindex @code{M} unit 4602@cindex unit, @code{M} 4603100ths of an em. 4604@end table 4605 4606@menu 4607* Default Units:: 4608@end menu 4609 4610@c --------------------------------------------------------------------- 4611 4612@node Default Units, , Measurements, Measurements 4613@subsection Default Units 4614@cindex default units 4615@cindex units, default 4616 4617Many requests take a default unit. While this can be helpful at times, 4618it can cause strange errors in some expressions. For example, the line 4619length request expects em units. Here are several attempts to get a 4620line length of 3.5@tie{}inches and their results: 4621 4622@Example 46233.5i @result{} 3.5i 46247/2 @result{} 0i 46257/2i @result{} 0i 4626(7 / 2)u @result{} 0i 46277i/2 @result{} 0.1i 46287i/2u @result{} 3.5i 4629@endExample 4630 4631@noindent 4632Everything is converted to basic units first. In the above example it 4633is assumed that 1@dmn{i} equals@tie{}240@dmn{u}, and 1@dmn{m} 4634equals@tie{}10@dmn{p} (thus 1@dmn{m} equals@tie{}33@dmn{u}). The value 46357@dmn{i}/2 is first handled as 7@dmn{i}/2@dmn{m}, then converted to 46361680@dmn{u}/66@dmn{u} which is 25@dmn{u}, and this is approximately 46370.1@dmn{i}. As can be seen, a scaling indicator after a closing 4638parenthesis is simply ignored. 4639 4640@cindex measurements, specifying safely 4641Thus, the safest way to specify measurements is to always 4642attach a scaling indicator. If you want to multiply or divide by a 4643certain scalar value, use @samp{u} as the unit for that value. 4644 4645 4646@c ===================================================================== 4647 4648@node Expressions, Identifiers, Measurements, gtroff Reference 4649@section Expressions 4650@cindex expressions 4651 4652@code{gtroff} has most arithmetic operators common to other languages: 4653 4654@itemize @bullet 4655@item 4656@cindex arithmetic operators 4657@cindex operators, arithmetic 4658@opindex + 4659@opindex - 4660@opindex / 4661@opindex * 4662@opindex % 4663Arithmetic: @samp{+} (addition), @samp{-} (subtraction), @samp{/} 4664(division), @samp{*} (multiplication), @samp{%} (modulo). 4665 4666@code{gtroff} only provides integer arithmetic. The internal type used 4667for computing results is @samp{int}, which is usually a 32@dmn{bit} 4668signed integer. 4669 4670@item 4671@cindex comparison operators 4672@cindex operators, comparison 4673@opindex < 4674@opindex > 4675@opindex >= 4676@opindex <= 4677@opindex = 4678@opindex == 4679Comparison: @samp{<} (less than), @samp{>} (greater than), @samp{<=} 4680(less than or equal), @samp{>=} (greater than or equal), @samp{=} 4681(equal), @samp{==} (the same as @samp{=}). 4682 4683@item 4684@cindex logical operators 4685@cindex operators, logical 4686@opindex & 4687@ifnotinfo 4688@opindex : 4689@end ifnotinfo 4690@ifinfo 4691@opindex @r{<colon>} 4692@end ifinfo 4693Logical: @samp{&} (logical and), @samp{:} (logical or). 4694 4695@item 4696@cindex unary operators 4697@cindex operators, unary 4698@opindex - 4699@opindex + 4700@opindex ! 4701@cindex @code{if} request, and the @samp{!} operator 4702@cindex @code{while} request, and the @samp{!} operator 4703Unary operators: @samp{-} (negating, i.e.@: changing the sign), @samp{+} 4704(just for completeness; does nothing in expressions), @samp{!} (logical 4705not; this works only within @code{if} and @code{while} requests). See 4706below for the use of unary operators in motion requests. 4707 4708@item 4709@cindex extremum operators (@code{>?}, @code{<?}) 4710@cindex operators, extremum (@code{>?}, @code{<?}) 4711@opindex >? 4712@opindex <? 4713Extrema: @samp{>?} (maximum), @samp{<?} (minimum). 4714 4715Example: 4716 4717@Example 4718.nr x 5 4719.nr y 3 4720.nr z (\n[x] >? \n[y]) 4721@endExample 4722 4723@noindent 4724The register@tie{}@code{z} now contains@tie{}5. 4725 4726@item 4727@cindex scaling operator 4728@cindex operator, scaling 4729Scaling: @code{(@var{c};@var{e})}. Evaluate@tie{}@var{e} using@tie{}@var{c} 4730as the default scaling indicator. If @var{c} is missing, ignore scaling 4731indicators in the evaluation of@tie{}@var{e}. 4732@end itemize 4733 4734@cindex parentheses 4735@cindex order of evaluation in expressions 4736@cindex expression, order of evaluation 4737@opindex ( 4738@opindex ) 4739Parentheses may be used as in any other language. However, in 4740@code{gtroff} they are necessary to ensure order of evaluation. 4741@code{gtroff} has no operator precedence; expressions are evaluated left 4742to right. This means that @code{gtroff} evaluates @samp{3+5*4} as if it were 4743parenthesized like @samp{(3+5)*4}, not as @samp{3+(5*4)}, as might be 4744expected. 4745 4746@cindex @code{+}, and page motion 4747@cindex @code{-}, and page motion 4748@cindex motion operators 4749@cindex operators, motion 4750For many requests which cause a motion on the page, the unary operators 4751@samp{+} and @samp{-} work differently if leading an expression. They 4752then indicate a motion relative to the current position (down or up, 4753respectively). 4754 4755@cindex @code{|}, and page motion 4756@cindex absolute position operator (@code{|}) 4757@cindex position, absolute, operator (@code{|}) 4758Similarly, a leading @samp{|} operator indicates an absolute position. 4759For vertical movements, it specifies the distance from the top of the 4760page; for horizontal movements, it gives the distance from the beginning 4761of the @emph{input} line. 4762 4763@cindex @code{bp} request, using @code{+} and@tie{}@code{-} 4764@cindex @code{in} request, using @code{+} and@tie{}@code{-} 4765@cindex @code{ll} request, using @code{+} and@tie{}@code{-} 4766@cindex @code{lt} request, using @code{+} and@tie{}@code{-} 4767@cindex @code{nm} request, using @code{+} and@tie{}@code{-} 4768@cindex @code{nr} request, using @code{+} and@tie{}@code{-} 4769@cindex @code{pl} request, using @code{+} and@tie{}@code{-} 4770@cindex @code{pn} request, using @code{+} and@tie{}@code{-} 4771@cindex @code{po} request, using @code{+} and@tie{}@code{-} 4772@cindex @code{ps} request, using @code{+} and@tie{}@code{-} 4773@cindex @code{pvs} request, using @code{+} and@tie{}@code{-} 4774@cindex @code{rt} request, using @code{+} and@tie{}@code{-} 4775@cindex @code{ti} request, using @code{+} and@tie{}@code{-} 4776@cindex @code{\H}, using @code{+} and@tie{}@code{-} 4777@cindex @code{\R}, using @code{+} and@tie{}@code{-} 4778@cindex @code{\s}, using @code{+} and@tie{}@code{-} 4779@samp{+} and @samp{-} are also treated differently by the following 4780requests and escapes: @code{bp}, @code{in}, @code{ll}, @code{lt}, 4781@code{nm}, @code{nr}, @code{pl}, @code{pn}, @code{po}, @code{ps}, 4782@code{pvs}, @code{rt}, @code{ti}, @code{\H}, @code{\R}, and @code{\s}. 4783Here, leading plus and minus signs indicate increments and decrements. 4784 4785@xref{Setting Registers}, for some examples. 4786 4787@Defesc {\\B, ', anything, '} 4788@cindex numeric expression, valid 4789@cindex valid numeric expression 4790Return@tie{}1 if @var{anything} is a valid numeric expression; 4791or@tie{}0 if @var{anything} is empty or not a valid numeric expression. 4792@endDefesc 4793 4794@cindex space characters, in expressions 4795@cindex expressions, and space characters 4796Due to the way arguments are parsed, spaces are not allowed in 4797expressions, unless the entire expression is surrounded by parentheses. 4798 4799@xref{Request and Macro Arguments}, and @ref{Conditionals and Loops}. 4800 4801 4802@c ===================================================================== 4803 4804@node Identifiers, Embedded Commands, Expressions, gtroff Reference 4805@section Identifiers 4806@cindex identifiers 4807 4808Like any other language, @code{gtroff} has rules for properly formed 4809@dfn{identifiers}. In @code{gtroff}, an identifier can be made up of 4810almost any printable character, with the exception of the following 4811characters: 4812 4813@itemize @bullet 4814@item 4815@cindex whitespace characters 4816@cindex newline character 4817@cindex character, whitespace 4818Whitespace characters (spaces, tabs, and newlines). 4819 4820@item 4821@cindex character, backspace 4822@cindex backspace character 4823@cindex @acronym{EBCDIC} encoding of backspace 4824Backspace (@acronym{ASCII}@tie{}@code{0x08} or 4825@acronym{EBCDIC}@tie{}@code{0x16}) and character code @code{0x01}. 4826 4827@item 4828@cindex invalid input characters 4829@cindex input characters, invalid 4830@cindex characters, invalid input 4831@cindex Unicode 4832The following input characters are invalid and are ignored if 4833@code{groff} runs on a machine based on @acronym{ASCII}, causing a 4834warning message of type @samp{input} (see @ref{Debugging}, for more 4835details): @code{0x00}, @code{0x0B}, @code{0x0D}-@code{0x1F}, 4836@code{0x80}-@code{0x9F}. 4837 4838And here are the invalid input characters if @code{groff} runs on an 4839@acronym{EBCDIC} host: @code{0x00}, @code{0x08}, @code{0x09}, 4840@code{0x0B}, @code{0x0D}-@code{0x14}, @code{0x17}-@code{0x1F}, 4841@code{0x30}-@code{0x3F}. 4842 4843Currently, some of these reserved codepoints are used internally, thus 4844making it non-trivial to extend @code{gtroff} to cover Unicode or other 4845character sets and encodings which use characters of these ranges. 4846 4847Note that invalid characters are removed before parsing; an 4848identifier @code{foo}, followed by an invalid character, followed by 4849@code{bar} is treated as @code{foobar}. 4850@end itemize 4851 4852For example, any of the following is valid. 4853 4854@Example 4855br 4856PP 4857(l 4858end-list 4859@@_ 4860@endExample 4861 4862@cindex @code{]}, as part of an identifier 4863@noindent 4864Note that identifiers longer than two characters with a closing bracket 4865(@samp{]}) in its name can't be accessed with escape sequences which 4866expect an identifier as a parameter. For example, @samp{\[foo]]} 4867accesses the glyph @samp{foo}, followed by @samp{]}, whereas 4868@samp{\C'foo]'} really asks for glyph @samp{foo]}. 4869 4870@cindex @code{refer}, and macro names starting with @code{[} or @code{]} 4871@cindex @code{[}, macro names starting with, and @code{refer} 4872@cindex @code{]}, macro names starting with, and @code{refer} 4873@cindex macro names, starting with @code{[} or @code{]}, and @code{refer} 4874To avoid problems with the @code{refer} preprocessor, macro names 4875should not start with @samp{[} or @samp{]}. Due to backwards 4876compatibility, everything after @samp{.[} and @samp{.]} is handled as 4877a special argument to @code{refer}. For example, @samp{.[foo} makes 4878@code{refer} to start a reference, using @samp{foo} as a parameter. 4879 4880@Defesc {\\A, ', ident, '} 4881Test whether an identifier @var{ident} is valid in @code{gtroff}. It 4882expands to the character@tie{}1 or@tie{}0 according to whether its 4883argument (usually delimited by quotes) is or is not acceptable as the 4884name of a string, macro, diversion, number register, environment, or 4885font. It returns@tie{}0 if no argument is given. This is useful for 4886looking up user input in some sort of associative table. 4887 4888@Example 4889\A'end-list' 4890 @result{} 1 4891@endExample 4892@endDefesc 4893 4894@xref{Escapes}, for details on parameter delimiting characters. 4895 4896Identifiers in @code{gtroff} can be any length, but, in some contexts, 4897@code{gtroff} needs to be told where identifiers end and text begins 4898(and in different ways depending on their length): 4899 4900@itemize @bullet 4901@item 4902Single character. 4903 4904@cindex @code{(}, starting a two-character identifier 4905@item 4906Two characters. Must be prefixed with @samp{(} in some situations. 4907 4908@cindex @code{[}, starting an identifier 4909@cindex @code{]}, ending an identifier 4910@item 4911Arbitrary length (@code{gtroff} only). Must be bracketed with @samp{[} 4912and@tie{}@samp{]} in some situations. Any length identifier can be put 4913in brackets. 4914@end itemize 4915 4916@cindex undefined identifiers 4917@cindex identifiers, undefined 4918Unlike many other programming languages, undefined identifiers are 4919silently ignored or expanded to nothing. 4920When @code{gtroff} finds an undefined identifier, it emits a 4921warning, doing the following: 4922 4923@itemize @bullet 4924@item 4925If the identifier is a string, macro, or diversion, 4926@code{gtroff} defines it as empty. 4927 4928@item 4929If the identifier is a number register, @code{gtroff} 4930defines it with a value of@tie{}0. 4931@end itemize 4932 4933@xref{Warnings}., @ref{Interpolating Registers}, and @ref{Strings}. 4934 4935Note that macros, strings, and diversions share the same name space. 4936 4937@Example 4938.de xxx 4939. nop foo 4940.. 4941. 4942.di xxx 4943bar 4944.br 4945.di 4946. 4947.xxx 4948 @result{} bar 4949@endExample 4950 4951@noindent 4952As can be seen in the previous example, @code{gtroff} reuses the 4953identifier @samp{xxx}, changing it from a macro to a diversion. 4954No warning is emitted! The contents of the first macro definition is 4955lost. 4956 4957@xref{Interpolating Registers}, and @ref{Strings}. 4958 4959 4960@c ===================================================================== 4961 4962@node Embedded Commands, Registers, Identifiers, gtroff Reference 4963@section Embedded Commands 4964@cindex embedded commands 4965@cindex commands, embedded 4966 4967Most documents need more functionality beyond filling, adjusting and 4968implicit line breaking. In order to gain further functionality, 4969@code{gtroff} allows commands to be embedded into the text, in two ways. 4970 4971The first is a @dfn{request} which takes up an entire line, and does 4972some large-scale operation (e.g.@: break lines, start new pages). 4973 4974The other is an @dfn{escape} which can be usually embedded anywhere 4975in the text; most requests can accept it even as an argument. 4976Escapes generally do more minor operations like sub- and superscripts, 4977print a symbol, etc. 4978 4979@menu 4980* Requests:: 4981* Macros:: 4982* Escapes:: 4983@end menu 4984 4985@c --------------------------------------------------------------------- 4986 4987@node Requests, Macros, Embedded Commands, Embedded Commands 4988@subsection Requests 4989@cindex requests 4990 4991@cindex control character (@code{.}) 4992@cindex character, control (@code{.}) 4993@cindex no-break control character (@code{'}) 4994@cindex character, no-break control (@code{'}) 4995@cindex control character, no-break (@code{'}) 4996A request line begins with a control character, which is either a single 4997quote (@samp{'}, the @dfn{no-break control character}) or a period 4998(@samp{.}, the normal @dfn{control character}). These can be changed; 4999see @ref{Character Translations}, for details. After this there may be 5000optional tabs or spaces followed by an identifier which is the name of 5001the request. This may be followed by any number of space-separated 5002arguments (@emph{no} tabs here). 5003 5004@cindex structuring source code of documents or macro packages 5005@cindex documents, structuring the source code 5006@cindex macro packages, structuring the source code 5007Since a control character followed by whitespace only is ignored, it 5008is common practice to use this feature for structuring the source code 5009of documents or macro packages. 5010 5011@Example 5012.de foo 5013. tm This is foo. 5014.. 5015. 5016. 5017.de bar 5018. tm This is bar. 5019.. 5020@endExample 5021 5022@cindex blank line 5023@cindex blank line macro (@code{blm}) 5024Another possibility is to use the blank line macro request @code{blm} 5025by assigning an empty macro to it. 5026 5027@Example 5028.de do-nothing 5029.. 5030.blm do-nothing \" activate blank line macro 5031 5032.de foo 5033. tm This is foo. 5034.. 5035 5036 5037.de bar 5038. tm This is bar. 5039.. 5040 5041.blm \" deactivate blank line macro 5042@endExample 5043 5044@xref{Blank Line Traps}. 5045 5046@cindex zero width space character (@code{\&}) 5047@cindex character, zero width space (@code{\&}) 5048@cindex space character, zero width (@code{\&}) 5049@cindex @code{\&}, escaping control characters 5050To begin a line with a control character without it being interpreted, 5051precede it with @code{\&}. This represents a zero width space, which 5052means it does not affect the output. 5053 5054In most cases the period is used as a control character. Several 5055requests cause a break implicitly; using the single quote control 5056character prevents this. 5057 5058@menu 5059* Request and Macro Arguments:: 5060@end menu 5061 5062@node Request and Macro Arguments, , Requests, Requests 5063@subsubsection Request and Macro Arguments 5064@cindex request arguments 5065@cindex macro arguments 5066@cindex arguments to requests and macros 5067 5068Arguments to requests and macros are processed much like the shell: 5069The line is split into arguments according to 5070spaces.@footnote{Plan@tie{}9's @code{troff} implementation also allows 5071tabs for argument separation -- @code{gtroff} intentionally doesn't 5072support this.} 5073 5074@cindex spaces, in a macro argument 5075An argument to a macro which is intended to contain spaces can either be 5076enclosed in double quotes, or have the spaces @dfn{escaped} with 5077backslashes. This is @emph{not} true for requests. 5078 5079Here are a few examples for a hypothetical macro @code{uh}: 5080 5081@Example 5082.uh The Mouse Problem 5083.uh "The Mouse Problem" 5084.uh The\ Mouse\ Problem 5085@endExample 5086 5087@cindex @code{\~}, difference to @code{\@key{SP}} 5088@cindex @code{\@key{SP}}, difference to @code{\~} 5089@noindent 5090The first line is the @code{uh} macro being called with 3 arguments, 5091@samp{The}, @samp{Mouse}, and @samp{Problem}. The latter two have the 5092same effect of calling the @code{uh} macro with one argument, @samp{The 5093Mouse Problem}.@footnote{The last solution, i.e., using escaped spaces, 5094is ``classical'' in the sense that it can be found in most @code{troff} 5095documents. Nevertheless, it is not optimal in all situations, since 5096@w{@samp{\ }} inserts a fixed-width, non-breaking space character which 5097can't stretch. @code{gtroff} provides a different command @code{\~} to 5098insert a stretchable, non-breaking space.} 5099 5100@cindex @code{"}, in a macro argument 5101@cindex double quote, in a macro argument 5102A double quote which isn't preceded by a space doesn't start a macro 5103argument. If not closing a string, it is printed literally. 5104 5105For example, 5106 5107@Example 5108.xxx a" "b c" "de"fg" 5109@endExample 5110 5111@noindent 5112has the arguments @samp{a"}, @w{@samp{b c}}, @samp{de}, and @samp{fg"}. 5113Don't rely on this obscure behaviour! 5114 5115There are two possibilities to get a double quote reliably. 5116 5117@itemize @bullet 5118@item 5119Enclose the whole argument with double quotes and use two consecutive double 5120quotes to represent a single one. This traditional solution has the 5121disadvantage that double quotes don't survive argument expansion again if 5122called in compatibility mode (using the @option{-C} option of @code{groff}): 5123 5124@Example 5125.de xx 5126. tm xx: `\\$1' `\\$2' `\\$3' 5127. 5128. yy "\\$1" "\\$2" "\\$3" 5129.. 5130.de yy 5131. tm yy: `\\$1' `\\$2' `\\$3' 5132.. 5133.xx A "test with ""quotes""" . 5134 @result{} xx: `A' `test with "quotes"' `.' 5135 @result{} yy: `A' `test with ' `quotes""' 5136@endExample 5137 5138@noindent 5139If not in compatibility mode, you get the expected result 5140 5141@Example 5142xx: `A' `test with "quotes"' `.' 5143yy: `A' `test with "quotes"' `.' 5144@endExample 5145 5146@noindent 5147since @code{gtroff} preserves the input level. 5148 5149@item 5150Use the double quote glyph @code{\(dq}. This works with and without 5151compatibility mode enabled since @code{gtroff} doesn't convert @code{\(dq} 5152back to a double quote input character. 5153 5154Not that this method won't work with @acronym{UNIX} @code{troff} in general 5155since the glyph `dq' isn't defined normally. 5156@end itemize 5157 5158@cindex @code{ds} request, and double quotes 5159Double quotes in the @code{ds} request are handled differently. 5160@xref{Strings}, for more details. 5161 5162@c --------------------------------------------------------------------- 5163 5164@node Macros, Escapes, Requests, Embedded Commands 5165@subsection Macros 5166@cindex macros 5167 5168@code{gtroff} has a @dfn{macro} facility for defining a series of lines 5169which can be invoked by name. They are called in the same manner as 5170requests -- arguments also may be passed basically in the same manner. 5171 5172@xref{Writing Macros}, and @ref{Request and Macro Arguments}. 5173 5174@c --------------------------------------------------------------------- 5175 5176@node Escapes, , Macros, Embedded Commands 5177@subsection Escapes 5178@cindex escapes 5179 5180Escapes may occur anywhere in the input to @code{gtroff}. They usually 5181begin with a backslash and are followed by a single character which 5182indicates the function to be performed. The escape character can be 5183changed; see @ref{Character Translations}. 5184 5185Escape sequences which require an identifier as a parameter accept three 5186possible syntax forms. 5187 5188@itemize @bullet 5189@item 5190The next single character is the identifier. 5191 5192@cindex @code{(}, starting a two-character identifier 5193@item 5194If this single character is an opening parenthesis, take the following 5195two characters as the identifier. Note that there is no closing 5196parenthesis after the identifier. 5197 5198@cindex @code{[}, starting an identifier 5199@cindex @code{]}, ending an identifier 5200@item 5201If this single character is an opening bracket, take all characters 5202until a closing bracket as the identifier. 5203@end itemize 5204 5205@noindent 5206Examples: 5207 5208@Example 5209\fB 5210\n(XX 5211\*[TeX] 5212@endExample 5213 5214@cindex @code{'}, delimiting arguments 5215@cindex argument delimiting characters 5216@cindex characters, argument delimiting 5217@cindex delimiting characters for arguments 5218Other escapes may require several arguments and/or some special format. 5219In such cases the argument is traditionally enclosed in single quotes 5220(and quotes are always used in this manual for the definitions of escape 5221sequences). The enclosed text is then processed according to what that 5222escape expects. Example: 5223 5224@Example 5225\l'1.5i\(bu' 5226@endExample 5227 5228@cindex @code{\o}, possible quote characters 5229@cindex @code{\b}, possible quote characters 5230@cindex @code{\X}, possible quote characters 5231Note that the quote character can be replaced with any other character 5232which does not occur in the argument (even a newline or a space 5233character) in the following escapes: @code{\o}, @code{\b}, and 5234@code{\X}. This makes e.g. 5235 5236@Example 5237A caf 5238\o 5239e\' 5240 5241 5242in Paris 5243 @result{} A caf@'e in Paris 5244@endExample 5245 5246@noindent 5247possible, but it is better not to use this feature to avoid confusion. 5248 5249@cindex @code{\%}, used as delimiter 5250@cindex @code{\@key{SP}}, used as delimiter 5251@cindex @code{\|}, used as delimiter 5252@cindex @code{\^}, used as delimiter 5253@cindex @code{\@{}, used as delimiter 5254@cindex @code{\@}}, used as delimiter 5255@cindex @code{\'}, used as delimiter 5256@cindex @code{\`}, used as delimiter 5257@cindex @code{\-}, used as delimiter 5258@cindex @code{\_}, used as delimiter 5259@cindex @code{\!}, used as delimiter 5260@cindex @code{\?}, used as delimiter 5261@cindex @code{\@@}, used as delimiter 5262@cindex @code{\)}, used as delimiter 5263@cindex @code{\/}, used as delimiter 5264@cindex @code{\,}, used as delimiter 5265@cindex @code{\&}, used as delimiter 5266@ifnotinfo 5267@cindex @code{\:}, used as delimiter 5268@end ifnotinfo 5269@ifinfo 5270@cindex @code{\@r{<colon>}}, used as delimiter 5271@end ifinfo 5272@cindex @code{\~}, used as delimiter 5273@cindex @code{\0}, used as delimiter 5274@cindex @code{\a}, used as delimiter 5275@cindex @code{\c}, used as delimiter 5276@cindex @code{\d}, used as delimiter 5277@cindex @code{\e}, used as delimiter 5278@cindex @code{\E}, used as delimiter 5279@cindex @code{\p}, used as delimiter 5280@cindex @code{\r}, used as delimiter 5281@cindex @code{\t}, used as delimiter 5282@cindex @code{\u}, used as delimiter 5283The following escapes sequences (which are handled similarly to 5284characters since they don't take a parameter) are also allowed as 5285delimiters: @code{\%}, @w{@samp{\ }}, @code{\|}, @code{\^}, @code{\@{}, 5286@code{\@}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 5287@code{\?}, @code{\@@}, @code{\)}, @code{\/}, @code{\,}, @code{\&}, 5288@code{\:}, @code{\~}, @code{\0}, @code{\a}, @code{\c}, @code{\d}, 5289@code{\e}, @code{\E}, @code{\p}, @code{\r}, @code{\t}, and @code{\u}. 5290Again, don't use these if possible. 5291 5292@cindex @code{\A}, allowed delimiters 5293@cindex @code{\B}, allowed delimiters 5294@cindex @code{\Z}, allowed delimiters 5295@cindex @code{\C}, allowed delimiters 5296@cindex @code{\w}, allowed delimiters 5297No newline characters as delimiters are allowed in the following 5298escapes: @code{\A}, @code{\B}, @code{\Z}, @code{\C}, and @code{\w}. 5299 5300@cindex @code{\D}, allowed delimiters 5301@cindex @code{\h}, allowed delimiters 5302@cindex @code{\H}, allowed delimiters 5303@cindex @code{\l}, allowed delimiters 5304@cindex @code{\L}, allowed delimiters 5305@cindex @code{\N}, allowed delimiters 5306@cindex @code{\R}, allowed delimiters 5307@cindex @code{\s}, allowed delimiters 5308@cindex @code{\S}, allowed delimiters 5309@cindex @code{\v}, allowed delimiters 5310@cindex @code{\x}, allowed delimiters 5311Finally, the escapes @code{\D}, @code{\h}, @code{\H}, @code{\l}, 5312@code{\L}, @code{\N}, @code{\R}, @code{\s}, @code{\S}, @code{\v}, 5313and @code{\x} can't use the following characters as delimiters: 5314 5315@itemize @bullet 5316@item 5317@cindex numbers, and delimiters 5318@cindex digits, and delimiters 5319The digits @code{0}-@code{9}. 5320 5321@item 5322@cindex operators, as delimiters 5323@cindex @code{+}, as delimiter 5324@cindex @code{-}, as delimiter 5325@cindex @code{/}, as delimiter 5326@cindex @code{*}, as delimiter 5327@cindex @code{%}, as delimiter 5328@cindex @code{<}, as delimiter 5329@cindex @code{>}, as delimiter 5330@cindex @code{=}, as delimiter 5331@cindex @code{&}, as delimiter 5332@ifnotinfo 5333@cindex @code{:}, as delimiter 5334@end ifnotinfo 5335@ifinfo 5336@cindex <colon>, as delimiter 5337@end ifinfo 5338@cindex @code{(}, as delimiter 5339@cindex @code{)}, as delimiter 5340@cindex @code{.}, as delimiter 5341The (single-character) operators @samp{+-/*%<>=&:().}. 5342 5343@item 5344@cindex space character 5345@cindex character, space 5346@cindex tab character 5347@cindex character, tab 5348@cindex newline character 5349@cindex character, newline 5350The space, tab, and newline characters. 5351 5352@item 5353@cindex @code{\%}, used as delimiter 5354@ifnotinfo 5355@cindex @code{\:}, used as delimiter 5356@end ifnotinfo 5357@ifinfo 5358@cindex @code{\@r{<colon>}}, used as delimiter 5359@end ifinfo 5360@cindex @code{\@{}, used as delimiter 5361@cindex @code{\@}}, used as delimiter 5362@cindex @code{\'}, used as delimiter 5363@cindex @code{\`}, used as delimiter 5364@cindex @code{\-}, used as delimiter 5365@cindex @code{\_}, used as delimiter 5366@cindex @code{\!}, used as delimiter 5367@cindex @code{\@@}, used as delimiter 5368@cindex @code{\/}, used as delimiter 5369@cindex @code{\c}, used as delimiter 5370@cindex @code{\e}, used as delimiter 5371@cindex @code{\p}, used as delimiter 5372All escape sequences except @code{\%}, @code{\:}, @code{\@{}, @code{\@}}, 5373@code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, @code{\@@}, 5374@code{\/}, @code{\c}, @code{\e}, and @code{\p}. 5375@end itemize 5376 5377@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 5378@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 5379To have a backslash (actually, the current escape character) appear in the 5380output several escapes are defined: @code{\\}, @code{\e} or @code{\E}. 5381These are very similar, and only differ with respect to being used in 5382macros or diversions. @xref{Character Translations}, for an exact 5383description of those escapes. 5384 5385@xref{Implementation Differences}, @ref{Copy-in Mode}, and @ref{Diversions}, 5386@ref{Identifiers}, for more information. 5387 5388@menu 5389* Comments:: 5390@end menu 5391 5392@node Comments, , Escapes, Escapes 5393@subsubsection Comments 5394@cindex comments 5395 5396Probably one of the most@footnote{Unfortunately, this is a lie. But 5397hopefully future @code{gtroff} hackers will believe it @code{:-)}} 5398common forms of escapes is the comment. 5399 5400@Defesc {\\", , , } 5401Start a comment. Everything to the end of the input line is ignored. 5402 5403This may sound simple, but it can be tricky to keep the comments from 5404interfering with the appearance of the final output. 5405 5406@cindex @code{ds}, @code{ds1} requests, and comments 5407@cindex @code{as}, @code{as1} requests, and comments 5408If the escape is to the right of some text or a request, that portion 5409of the line is ignored, but the space leading up to it is noticed by 5410@code{gtroff}. This only affects the @code{ds} and @code{as} 5411request and its variants. 5412 5413@cindex tabs, before comments 5414@cindex comments, lining up with tabs 5415One possibly irritating idiosyncracy is that tabs must not be used to 5416line up comments. Tabs are not treated as whitespace between the 5417request and macro arguments. 5418 5419@cindex undefined request 5420@cindex request, undefined 5421A comment on a line by itself is treated as a blank line, because 5422after eliminating the comment, that is all that remains: 5423 5424@Example 5425Test 5426\" comment 5427Test 5428@endExample 5429 5430@noindent 5431produces 5432 5433@Example 5434Test 5435 5436Test 5437@endExample 5438 5439To avoid this, it is common to start the line with @code{.\"} which 5440causes the line to be treated as an undefined request and thus ignored 5441completely. 5442 5443@cindex @code{'}, as a comment 5444Another commenting scheme seen sometimes is three consecutive single 5445quotes (@code{'''}) at the beginning of a line. This works, but 5446@code{gtroff} gives a warning about an undefined macro (namely 5447@code{''}), which is harmless, but irritating. 5448@endDefesc 5449 5450@Defesc {\\#, , , } 5451To avoid all this, @code{gtroff} has a new comment mechanism using the 5452@code{\#} escape. This escape works the same as @code{\"} except that 5453the newline is also ignored: 5454 5455@Example 5456Test 5457\# comment 5458Test 5459@endExample 5460 5461@noindent 5462produces 5463 5464@Example 5465Test Test 5466@endExample 5467 5468@noindent 5469as expected. 5470@endDefesc 5471 5472@Defreq {ig, [@Var{end}]} 5473Ignore all input until @code{gtroff} encounters the macro named 5474@code{.}@var{end} on a line by itself (or @code{..} if @var{end} is not 5475specified). This is useful for commenting out large blocks of text: 5476 5477@Example 5478text text text... 5479.ig 5480This is part of a large block 5481of text that has been 5482temporarily(?) commented out. 5483 5484We can restore it simply by removing 5485the .ig request and the ".." at the 5486end of the block. 5487.. 5488More text text text... 5489@endExample 5490 5491@noindent 5492produces 5493 5494@Example 5495text text text@dots{} More text text text@dots{} 5496@endExample 5497 5498@noindent 5499Note that the commented-out block of text does not 5500cause a break. 5501 5502The input is read in copy-mode; auto-incremented registers @emph{are} 5503affected (@pxref{Auto-increment}). 5504@endDefreq 5505 5506 5507@c ===================================================================== 5508 5509@node Registers, Manipulating Filling and Adjusting, Embedded Commands, gtroff Reference 5510@section Registers 5511@cindex registers 5512 5513Numeric variables in @code{gtroff} are called @dfn{registers}. There 5514are a number of built-in registers, supplying anything from the date to 5515details of formatting parameters. 5516 5517@xref{Identifiers}, for details on register identifiers. 5518 5519@menu 5520* Setting Registers:: 5521* Interpolating Registers:: 5522* Auto-increment:: 5523* Assigning Formats:: 5524* Built-in Registers:: 5525@end menu 5526 5527@c --------------------------------------------------------------------- 5528 5529@node Setting Registers, Interpolating Registers, Registers, Registers 5530@subsection Setting Registers 5531@cindex setting registers (@code{nr}, @code{\R}) 5532@cindex registers, setting (@code{nr}, @code{\R}) 5533 5534Define or set registers using the @code{nr} request or the 5535@code{\R} escape. 5536 5537@DefreqList {nr, ident value} 5538@DefescListEnd {\\R, ', ident value, '} 5539Set number register @var{ident} to @var{value}. If @var{ident} 5540doesn't exist, @code{gtroff} creates it. 5541 5542The argument to @code{\R} usually has to be enclosed in quotes. 5543@xref{Escapes}, for details on parameter delimiting characters. 5544 5545The @code{\R} escape doesn't produce an input token in @code{gtroff}; 5546with other words, it vanishes completely after @code{gtroff} has 5547processed it. 5548@endDefreq 5549 5550For example, the following two lines are equivalent: 5551 5552@Example 5553.nr a (((17 + (3 * 4))) % 4) 5554\R'a (((17 + (3 * 4))) % 4)' 5555 @result{} 1 5556@endExample 5557 5558Both @code{nr} and @code{\R} have two additional special forms to 5559increment or decrement a register. 5560 5561@DefreqList {nr, ident @t{+}@Var{value}} 5562@DefreqItem {nr, ident @t{-}@Var{value}} 5563@DefescItem {\\R, ', ident @t{+}value, '} 5564@DefescListEnd {\\R, ', ident @t{-}value, '} 5565Increment (decrement) register @var{ident} by @var{value}. 5566 5567@Example 5568.nr a 1 5569.nr a +1 5570\na 5571 @result{} 2 5572@endExample 5573 5574@cindex negating register values 5575To assign the negated value of a register to another register, some care 5576must be taken to get the desired result: 5577 5578@Example 5579.nr a 7 5580.nr b 3 5581.nr a -\nb 5582\na 5583 @result{} 4 5584.nr a (-\nb) 5585\na 5586 @result{} -3 5587@endExample 5588 5589@noindent 5590The surrounding parentheses prevent the interpretation of the minus sign 5591as a decrementing operator. An alternative is to start the assignment 5592with a @samp{0}: 5593 5594@Example 5595.nr a 7 5596.nr b -3 5597.nr a \nb 5598\na 5599 @result{} 4 5600.nr a 0\nb 5601\na 5602 @result{} -3 5603@endExample 5604@endDefreq 5605 5606@Defreq {rr, ident} 5607@cindex removing number register (@code{rr}) 5608@cindex number register, removing (@code{rr}) 5609@cindex register, removing (@code{rr}) 5610Remove number register @var{ident}. If @var{ident} doesn't exist, the 5611request is ignored. 5612@endDefreq 5613 5614@Defreq {rnn, ident1 ident2} 5615@cindex renaming number register (@code{rnn}) 5616@cindex number register, renaming (@code{rnn}) 5617@cindex register, renaming (@code{rnn}) 5618Rename number register @var{ident1} to @var{ident2}. If either 5619@var{ident1} or @var{ident2} doesn't exist, the request is ignored. 5620@endDefreq 5621 5622@Defreq {aln, ident1 ident2} 5623@cindex alias, number register, creating (@code{aln}) 5624@cindex creating alias, for number register (@code{aln}) 5625@cindex number register, creating alias (@code{aln}) 5626@cindex register, creating alias (@code{aln}) 5627Create an alias @var{ident1} for a number register @var{ident2}. The 5628new name and the old name are exactly equivalent. If @var{ident1} is 5629undefined, a warning of type @samp{reg} is generated, and the request 5630is ignored. @xref{Debugging}, for information about warnings. 5631@endDefreq 5632 5633@c --------------------------------------------------------------------- 5634 5635@node Interpolating Registers, Auto-increment, Setting Registers, Registers 5636@subsection Interpolating Registers 5637@cindex interpolating registers (@code{\n}) 5638@cindex registers, interpolating (@code{\n}) 5639 5640Numeric registers can be accessed via the @code{\n} escape. 5641 5642@DefescList {\\n, , i, } 5643@DefescItem {\\n, @lparen{}, id, } 5644@DefescListEnd {\\n, @lbrack{}, ident, @rbrack} 5645@cindex nested assignments 5646@cindex assignments, nested 5647@cindex indirect assignments 5648@cindex assignments, indirect 5649Interpolate number register with name @var{ident} (one-character 5650name@tie{}@var{i}, two-character name @var{id}). This means that the value 5651of the register is expanded in-place while @code{gtroff} is parsing the 5652input line. Nested assignments (also called indirect assignments) are 5653possible. 5654 5655@Example 5656.nr a 5 5657.nr as \na+\na 5658\n(as 5659 @result{} 10 5660@endExample 5661 5662@Example 5663.nr a1 5 5664.nr ab 6 5665.ds str b 5666.ds num 1 5667\n[a\n[num]] 5668 @result{} 5 5669\n[a\*[str]] 5670 @result{} 6 5671@endExample 5672@endDefesc 5673 5674@c --------------------------------------------------------------------- 5675 5676@node Auto-increment, Assigning Formats, Interpolating Registers, Registers 5677@subsection Auto-increment 5678@cindex auto-increment 5679@cindex increment, automatic 5680 5681Number registers can also be auto-incremented and auto-decremented. 5682The increment or decrement value can be specified with a third 5683argument to the @code{nr} request or @code{\R} escape. 5684 5685@Defreq {nr, ident value incr} 5686@cindex @code{\R}, difference to @code{nr} 5687Set number register @var{ident} to @var{value}; the increment for 5688auto-incrementing is set to @var{incr}. Note that the @code{\R} 5689escape doesn't support this notation. 5690@endDefreq 5691 5692To activate auto-incrementing, the escape @code{\n} has a special 5693syntax form. 5694 5695@DefescList {\\n, +, i, } 5696@DefescItem {\\n, -, i, } 5697@DefescItem {\\n, @lparen{}+, id, } 5698@DefescItem {\\n, @lparen{}-, id, } 5699@DefescItem {\\n, +@lparen{}, id, } 5700@DefescItem {\\n, -@lparen{}, id, } 5701@DefescItem {\\n, @lbrack{}+, ident, @rbrack{}} 5702@DefescItem {\\n, @lbrack{}-, ident, @rbrack{}} 5703@DefescItem {\\n, +@lbrack{}, ident, @rbrack{}} 5704@DefescListEnd {\\n, -@lbrack{}, ident, @rbrack{}} 5705Before interpolating, increment or decrement @var{ident} 5706(one-character name@tie{}@var{i}, two-character name @var{id}) by the 5707auto-increment value as specified with the @code{nr} request (or the 5708@code{\R} escape). If no auto-increment value has been specified, 5709these syntax forms are identical to @code{\n}. 5710@endDefesc 5711 5712For example, 5713 5714@Example 5715.nr a 0 1 5716.nr xx 0 5 5717.nr foo 0 -2 5718\n+a, \n+a, \n+a, \n+a, \n+a 5719.br 5720\n-(xx, \n-(xx, \n-(xx, \n-(xx, \n-(xx 5721.br 5722\n+[foo], \n+[foo], \n+[foo], \n+[foo], \n+[foo] 5723@endExample 5724 5725@noindent 5726produces 5727 5728@Example 57291, 2, 3, 4, 5 5730-5, -10, -15, -20, -25 5731-2, -4, -6, -8, -10 5732@endExample 5733 5734@cindex increment value without changing the register 5735@cindex value, incrementing without changing the register 5736To change the increment value without changing the value of a register 5737(@var{a} in the example), the following can be used: 5738 5739@Example 5740.nr a \na 10 5741@endExample 5742 5743@c --------------------------------------------------------------------- 5744 5745@node Assigning Formats, Built-in Registers, Auto-increment, Registers 5746@subsection Assigning Formats 5747@cindex assigning formats (@code{af}) 5748@cindex formats, assigning (@code{af}) 5749 5750When a register is used in the text of an input file (as opposed to 5751part of an expression), it is textually replaced (or interpolated) 5752with a representation of that number. This output format can be 5753changed to a variety of formats (numbers, Roman numerals, etc.). This 5754is done using the @code{af} request. 5755 5756@Defreq {af, ident format} 5757Change the output format of a number register. The first argument 5758@var{ident} is the name of the number register to be changed, and the 5759second argument @var{format} is the output format. The following 5760output formats are available: 5761 5762@table @code 5763@item 1 5764Decimal arabic numbers. This is the default format: 0, 1, 2, 57653,@tie{}@enddots{} 5766 5767@item 0@dots{}0 5768Decimal numbers with as many digits as specified. So, @samp{00} would 5769result in printing numbers as 01, 02, 03,@tie{}@enddots{} 5770 5771In fact, any digit instead of zero will do; @code{gtroff} only counts 5772how many digits are specified. As a consequence, @code{af}'s default 5773format @samp{1} could be specified as @samp{0} also (and exactly this is 5774returned by the @code{\g} escape, see below). 5775 5776@item I 5777@cindex Roman numerals 5778@cindex numerals, Roman 5779Upper-case Roman numerals: 0, I, II, III, IV,@tie{}@enddots{} 5780 5781@item i 5782Lower-case Roman numerals: 0, i, ii, iii, iv,@tie{}@enddots{} 5783 5784@item A 5785Upper-case letters: 0, A, B, C, @dots{},@tie{}Z, AA, AB,@tie{}@enddots{} 5786 5787@item a 5788Lower-case letters: 0, a, b, c, @dots{},@tie{}z, aa, ab,@tie{}@enddots{} 5789@end table 5790 5791Omitting the number register format causes a warning of type 5792@samp{missing}. @xref{Debugging}, for more details. Specifying a 5793nonexistent format causes an error. 5794 5795The following example produces @samp{10, X, j, 010}: 5796 5797@Example 5798.nr a 10 5799.af a 1 \" the default format 5800\na, 5801.af a I 5802\na, 5803.af a a 5804\na, 5805.af a 001 5806\na 5807@endExample 5808 5809@cindex Roman numerals, maximum and minimum 5810@cindex maximum values of Roman numerals 5811@cindex minimum values of Roman numerals 5812The largest number representable for the @samp{i} and @samp{I} formats 5813is 39999 (or @minus{}39999); @acronym{UNIX} @code{troff} uses @samp{z} 5814and @samp{w} to represent 10000 and 5000 in Roman numerals, and so does 5815@code{gtroff}. Currently, the correct glyphs of Roman numeral five 5816thousand and Roman numeral ten thousand (Unicode code points 5817@code{U+2182} and @code{U+2181}, respectively) are not available. 5818 5819If @var{ident} doesn't exist, it is created. 5820 5821@cindex read-only register, changing format 5822@cindex changing format, and read-only registers 5823Changing the output format of a read-only register causes an error. It 5824is necessary to first copy the register's value to a writeable register, 5825then apply the @code{af} request to this other register. 5826@endDefreq 5827 5828@DefescList {\\g, , i, } 5829@DefescItem {\\g, @lparen{}, id, } 5830@DefescListEnd {\\g, @lbrack{}, ident, @rbrack{}} 5831@cindex format of register (@code{\g}) 5832@cindex register, format (@code{\g}) 5833Return the current format of the specified register @var{ident} 5834(one-character name@tie{}@var{i}, two-character name @var{id}). For 5835example, @samp{\ga} after the previous example would produce the 5836string @samp{000}. If the register hasn't been defined yet, nothing 5837is returned. 5838@endDefesc 5839 5840@c --------------------------------------------------------------------- 5841 5842@node Built-in Registers, , Assigning Formats, Registers 5843@subsection Built-in Registers 5844@cindex built-in registers 5845@cindex registers, built-in 5846 5847The following lists some built-in registers which are not described 5848elsewhere in this manual. Any register which begins with a @samp{.} is 5849read-only. A complete listing of all built-in registers can be found in 5850appendix@tie{}@ref{Register Index}. 5851 5852@table @code 5853@item .F 5854@cindex current input file name register (@code{.F}) 5855@cindex input file name, current, register (@code{.F}) 5856@vindex .F 5857This string-valued register returns the current input file name. 5858 5859@item .H 5860@cindex horizontal resolution register (@code{.H}) 5861@cindex resolution, horizontal, register (@code{.H}) 5862@vindex .H 5863Horizontal resolution in basic units. 5864 5865@item .V 5866@cindex vertical resolution register (@code{.V}) 5867@cindex resolution, vertical, register (@code{.V}) 5868@vindex .V 5869Vertical resolution in basic units. 5870 5871@item seconds 5872@cindex seconds, current time (@code{seconds}) 5873@cindex time, current, seconds (@code{seconds}) 5874@cindex current time, seconds (@code{seconds}) 5875@vindex seconds 5876The number of seconds after the minute, normally in the range@tie{}0 5877to@tie{}59, but can be up to@tie{}61 to allow for leap seconds. Initialized 5878at start-up of @code{gtroff}. 5879 5880@item minutes 5881@cindex minutes, current time (@code{minutes}) 5882@cindex time, current, minutes (@code{minutes}) 5883@cindex current time, minutes (@code{minutes}) 5884@vindex minutes 5885The number of minutes after the hour, in the range@tie{}0 to@tie{}59. 5886Initialized at start-up of @code{gtroff}. 5887 5888@item hours 5889@cindex hours, current time (@code{hours}) 5890@cindex time, current, hours (@code{hours}) 5891@cindex current time, hours (@code{hours}) 5892@vindex hours 5893The number of hours past midnight, in the range@tie{}0 to@tie{}23. 5894Initialized at start-up of @code{gtroff}. 5895 5896@item dw 5897@cindex day of the week register (@code{dw}) 5898@cindex date, day of the week register (@code{dw}) 5899@vindex dw 5900Day of the week (1-7). 5901 5902@item dy 5903@cindex day of the month register (@code{dy}) 5904@cindex date, day of the month register (@code{dy}) 5905@vindex dy 5906Day of the month (1-31). 5907 5908@item mo 5909@cindex month of the year register (@code{mo}) 5910@cindex date, month of the year register (@code{mo}) 5911@vindex mo 5912Current month (1-12). 5913 5914@item year 5915@cindex date, year register (@code{year}, @code{yr}) 5916@cindex year, current, register (@code{year}, @code{yr}) 5917@vindex year 5918The current year. 5919 5920@item yr 5921@vindex yr 5922The current year minus@tie{}1900. Unfortunately, the documentation of 5923@acronym{UNIX} Version@tie{}7's @code{troff} had a year@tie{}2000 bug: It 5924incorrectly claimed that @code{yr} contains the last two digits of the 5925year. That claim has never been true of either @acronym{AT&T} 5926@code{troff} or GNU @code{troff}. Old @code{troff} input that looks 5927like this: 5928 5929@Example 5930'\" The following line stopped working after 1999 5931This document was formatted in 19\n(yr. 5932@endExample 5933 5934@noindent 5935can be corrected as follows: 5936 5937@Example 5938This document was formatted in \n[year]. 5939@endExample 5940 5941@noindent 5942or, to be portable to older @code{troff} versions, as follows: 5943 5944@Example 5945.nr y4 1900+\n(yr 5946This document was formatted in \n(y4. 5947@endExample 5948 5949@item .c 5950@vindex .c 5951@itemx c. 5952@vindex c. 5953@cindex input line number register (@code{.c}, @code{c.}) 5954@cindex line number, input, register (@code{.c}, @code{c.}) 5955The current @emph{input} line number. Register @samp{.c} is read-only, 5956whereas @samp{c.} (a @code{gtroff} extension) is writable also, 5957affecting both @samp{.c} and @samp{c.}. 5958 5959@item ln 5960@vindex ln 5961@cindex output line number register (@code{ln}) 5962@cindex line number, output, register (@code{ln}) 5963The current @emph{output} line number after a call to the @code{nm} 5964request to activate line numbering. 5965 5966@xref{Miscellaneous}, for more information about line numbering. 5967 5968@item .x 5969@vindex .x 5970@cindex major version number register (@code{.x}) 5971@cindex version number, major, register (@code{.x}) 5972The major version number. For example, if the version number 5973is 1.03 then @code{.x} contains@tie{}@samp{1}. 5974 5975@item .y 5976@vindex .y 5977@cindex minor version number register (@code{.y}) 5978@cindex version number, minor, register (@code{.y}) 5979The minor version number. For example, if the version number 5980is 1.03 then @code{.y} contains@tie{}@samp{03}. 5981 5982@item .Y 5983@vindex .Y 5984@cindex revision number register (@code{.Y}) 5985The revision number of @code{groff}. 5986 5987@item $$ 5988@vindex $$ 5989@cindex process ID of @code{gtroff} register (@code{$$}) 5990@cindex @code{gtroff}, process ID register (@code{$$}) 5991The process ID of @code{gtroff}. 5992 5993@item .g 5994@vindex .g 5995@cindex @code{gtroff}, identification register (@code{.g}) 5996@cindex GNU-specific register (@code{.g}) 5997Always@tie{}1. Macros should use this to determine whether they are 5998running under GNU @code{troff}. 5999 6000@item .A 6001@vindex .A 6002@cindex @acronym{ASCII} approximation output register (@code{.A}) 6003If the command line option @option{-a} is used to produce an 6004@acronym{ASCII} approximation of the output, this is set to@tie{}1, zero 6005otherwise. @xref{Groff Options}. 6006 6007@item .P 6008@vindex .P 6009This register is set to@tie{}1 (and to@tie{}0 otherwise) if the current 6010page is actually being printed, i.e., if the @option{-o} option is being 6011used to only print selected pages. @xref{Groff Options}, for more 6012information. 6013 6014@item .T 6015@vindex .T 6016If @code{gtroff} is called with the @option{-T} command line option, the 6017number register @code{.T} is set to@tie{}1, and zero otherwise. 6018@xref{Groff Options}. 6019 6020@stindex .T 6021@cindex output device name string register (@code{.T}) 6022Additionally, @code{gtroff} predefines a single read-write string 6023register @code{.T} which contains the current output device (for 6024example, @samp{latin1} or @samp{ps}). 6025@end table 6026 6027 6028@c ===================================================================== 6029 6030@node Manipulating Filling and Adjusting, Manipulating Hyphenation, Registers, gtroff Reference 6031@section Manipulating Filling and Adjusting 6032@cindex manipulating filling and adjusting 6033@cindex filling and adjusting, manipulating 6034@cindex adjusting and filling, manipulating 6035@cindex justifying text 6036@cindex text, justifying 6037 6038@cindex break 6039@cindex line break 6040@cindex @code{bp} request, causing implicit linebreak 6041@cindex @code{ce} request, causing implicit linebreak 6042@cindex @code{cf} request, causing implicit linebreak 6043@cindex @code{fi} request, causing implicit linebreak 6044@cindex @code{fl} request, causing implicit linebreak 6045@cindex @code{in} request, causing implicit linebreak 6046@cindex @code{nf} request, causing implicit linebreak 6047@cindex @code{rj} request, causing implicit linebreak 6048@cindex @code{sp} request, causing implicit linebreak 6049@cindex @code{ti} request, causing implicit linebreak 6050@cindex @code{trf} request, causing implicit linebreak 6051Various ways of causing @dfn{breaks} were given in @ref{Implicit Line 6052Breaks}. The @code{br} request likewise causes a break. Several 6053other requests also cause breaks, but implicitly. These are 6054@code{bp}, @code{ce}, @code{cf}, @code{fi}, @code{fl}, @code{in}, 6055@code{nf}, @code{rj}, @code{sp}, @code{ti}, and @code{trf}. 6056 6057@Defreq {br, } 6058Break the current line, i.e., the input collected so far is emitted 6059without adjustment. 6060 6061If the no-break control character is used, @code{gtroff} suppresses 6062the break: 6063 6064@Example 6065a 6066'br 6067b 6068 @result{} a b 6069@endExample 6070@endDefreq 6071 6072Initially, @code{gtroff} fills and adjusts text to both margins. 6073Filling can be disabled via the @code{nf} request and re-enabled with 6074the @code{fi} request. 6075 6076@DefreqList {fi, } 6077@DefregListEnd {.u} 6078@cindex fill mode (@code{fi}) 6079@cindex mode, fill (@code{fi}) 6080Activate fill mode (which is the default). This request implicitly 6081enables adjusting; it also inserts a break in the text currently being 6082filled. The read-only number register @code{.u} is set to@tie{}1. 6083 6084The fill mode status is associated with the current environment 6085(@pxref{Environments}). 6086 6087See @ref{Line Control}, for interaction with the @code{\c} escape. 6088@endDefreq 6089 6090@Defreq {nf, } 6091@cindex no-fill mode (@code{nf}) 6092@cindex mode, no-fill (@code{nf}) 6093Activate no-fill mode. Input lines are output as-is, retaining line 6094breaks and ignoring the current line length. This command implicitly 6095disables adjusting; it also causes a break. The number register 6096@code{.u} is set to@tie{}0. 6097 6098The fill mode status is associated with the current environment 6099(@pxref{Environments}). 6100 6101See @ref{Line Control}, for interaction with the @code{\c} escape. 6102@endDefreq 6103 6104@DefreqList {ad, [@Var{mode}]} 6105@DefregListEnd {.j} 6106Set adjusting mode. 6107 6108Activation and deactivation of adjusting is done implicitly with 6109calls to the @code{fi} or @code{nf} requests. 6110 6111@var{mode} can have one of the following values: 6112 6113@table @code 6114@item l 6115@cindex ragged-right 6116Adjust text to the left margin. This produces what is traditionally 6117called ragged-right text. 6118 6119@item r 6120@cindex ragged-left 6121Adjust text to the right margin, producing ragged-left text. 6122 6123@item c 6124@cindex centered text 6125@cindex @code{ce} request, difference to @samp{.ad@tie{}c} 6126Center filled text. This is different to the @code{ce} request which 6127only centers text without filling. 6128 6129@item b 6130@itemx n 6131Justify to both margins. This is the default used by @code{gtroff}. 6132@end table 6133 6134Finally, @var{mode} can be the numeric argument returned by the @code{.j} 6135register. 6136 6137With no argument, @code{gtroff} adjusts lines in the same way it did 6138before adjusting was deactivated (with a call to @code{na}, for 6139example). 6140 6141@Example 6142text 6143.ad r 6144.nr ad \n[.j] 6145text 6146.ad c 6147text 6148.na 6149text 6150.ad \" back to centering 6151text 6152.ad \n[ad] \" back to right justifying 6153@endExample 6154 6155@cindex adjustment mode register (@code{.j}) 6156The current adjustment mode is available in the read-only number 6157register @code{.j}; it can be stored and subsequently used to set 6158adjustment. 6159 6160The adjustment mode status is associated with the current environment 6161(@pxref{Environments}). 6162@endDefreq 6163 6164@Defreq {na, } 6165Disable adjusting. This request won't change the current adjustment 6166mode: A subsequent call to @code{ad} uses the previous adjustment 6167setting. 6168 6169The adjustment mode status is associated with the current environment 6170(@pxref{Environments}). 6171@endDefreq 6172 6173@DefreqList {brp, } 6174@DefescListEnd {\\p, , , } 6175Adjust the current line and cause a break. 6176 6177In most cases this produces very ugly results since @code{gtroff} 6178doesn't have a sophisticated paragraph building algorithm (as @TeX{} 6179have, for example); instead, @code{gtroff} fills and adjusts a paragraph 6180line by line: 6181 6182@Example 6183 This is an uninteresting sentence. 6184 This is an uninteresting sentence.\p 6185 This is an uninteresting sentence. 6186@endExample 6187 6188@noindent 6189is formatted as 6190 6191@Example 6192 This is an uninteresting sentence. This is an 6193 uninteresting sentence. 6194 This is an uninteresting sentence. 6195@endExample 6196@endDefreq 6197 6198@DefreqList {ss, word_space_size [@Var{sentence_space_size}]} 6199@DefregItem {.ss} 6200@DefregListEnd {.sss} 6201@cindex word space size register (@code{.ss}) 6202@cindex size of word space register (@code{.ss}) 6203@cindex space between words register (@code{.ss}) 6204@cindex sentence space size register (@code{.sss}) 6205@cindex size of sentence space register (@code{.sss}) 6206@cindex space between sentences register (@code{.sss}) 6207Change the size of a space between words. It takes its units as one 6208twelfth of the space width parameter for the current font. 6209Initially both the @var{word_space_size} and @var{sentence_space_size} 6210are@tie{}12. In fill mode, the values specify the minimum distance. 6211 6212@cindex fill mode 6213@cindex mode, fill 6214If two arguments are given to the @code{ss} request, the second 6215argument sets the sentence space size. If the second argument is not 6216given, sentence space size is set to @var{word_space_size}. The 6217sentence space size is used in two circumstances: If the end of a 6218sentence occurs at the end of a line in fill mode, then both an 6219inter-word space and a sentence space are added; if two spaces follow 6220the end of a sentence in the middle of a line, then the second space 6221is a sentence space. If a second argument is never given to the 6222@code{ss} request, the behaviour of @acronym{UNIX} @code{troff} is the 6223same as that exhibited by GNU @code{troff}. In GNU @code{troff}, as 6224in @acronym{UNIX} @code{troff}, a sentence should always be followed 6225by either a newline or two spaces. 6226 6227The read-only number registers @code{.ss} and @code{.sss} hold the 6228values of the parameters set by the first and second arguments of the 6229@code{ss} request. 6230 6231The word space and sentence space values are associated with the current 6232environment (@pxref{Environments}). 6233 6234Contrary to @acronym{AT&T} @code{troff}, this request is @emph{not} 6235ignored if a TTY output device is used; the given values are then 6236rounded down to a multiple of@tie{}12 (@pxref{Implementation Differences}). 6237 6238The request is ignored if there is no parameter. 6239 6240@cindex discardable horizontal space 6241@cindex space, discardable, horizontal 6242@cindex horizontal discardable space 6243Another useful application of the @code{ss} request is to insert 6244discardable horizontal space, i.e., space which is discarded at a line 6245break. For example, paragraph-style footnotes could be separated this 6246way: 6247 6248@Example 6249.ll 4.5i 62501.\ This is the first footnote.\c 6251.ss 48 6252.nop 6253.ss 12 62542.\ This is the second footnote. 6255@endExample 6256 6257@noindent 6258The result: 6259 6260@Example 62611. This is the first footnote. 2. This 6262is the second footnote. 6263@endExample 6264 6265@noindent 6266Note that the @code{\h} escape produces unbreakable space. 6267@endDefreq 6268 6269@DefreqList {ce, [@Var{nnn}]} 6270@DefregListEnd {.ce} 6271@cindex centering lines (@code{ce}) 6272@cindex lines, centering (@code{ce}) 6273Center text. While the @w{@samp{.ad c}} request also centers text, 6274it fills the text as well. @code{ce} does not fill the 6275text it affects. This request causes a break. The number of lines 6276still to be centered is associated with the current environment 6277(@pxref{Environments}). 6278 6279The following example demonstrates the differences. 6280Here the input: 6281 6282@Example 6283.ll 4i 6284.ce 1000 6285This is a small text fragment which shows the differences 6286between the `.ce' and the `.ad c' request. 6287.ce 0 6288 6289.ad c 6290This is a small text fragment which shows the differences 6291between the `.ce' and the `.ad c' request. 6292@endExample 6293 6294@noindent 6295And here the result: 6296 6297@Example 6298 This is a small text fragment which 6299 shows the differences 6300between the `.ce' and the `.ad c' request. 6301 6302 This is a small text fragment which 6303shows the differences between the `.ce' 6304 and the `.ad c' request. 6305@endExample 6306 6307With no arguments, @code{ce} centers the next line of text. @var{nnn} 6308specifies the number of lines to be centered. If the argument is zero 6309or negative, centering is disabled. 6310 6311The basic length for centering text is the line length (as set with the 6312@code{ll} request) minus the indentation (as set with the @code{in} 6313request). Temporary indentation is ignored. 6314 6315As can be seen in the previous example, it is a common idiom to turn 6316on centering for a large number of lines, and to turn off centering 6317after text to be centered. This is useful for any request which takes 6318a number of lines as an argument. 6319 6320The @code{.ce} read-only number register contains the number of lines 6321remaining to be centered, as set by the @code{ce} request. 6322@endDefreq 6323 6324@DefreqList {rj, [@Var{nnn}]} 6325@DefregListEnd {.rj} 6326@cindex justifying text (@code{rj}) 6327@cindex text, justifying (@code{rj}) 6328@cindex right-justifying (@code{rj}) 6329Justify unfilled text to the right margin. Arguments are identical to 6330the @code{ce} request. The @code{.rj} read-only number register is 6331the number of lines to be right-justified as set by the @code{rj} 6332request. This request causes a break. The number of lines still to be 6333right-justified is associated with the current environment 6334(@pxref{Environments}). 6335@endDefreq 6336 6337 6338@c ===================================================================== 6339 6340@node Manipulating Hyphenation, Manipulating Spacing, Manipulating Filling and Adjusting, gtroff Reference 6341@section Manipulating Hyphenation 6342@cindex manipulating hyphenation 6343@cindex hyphenation, manipulating 6344 6345As discussed in @ref{Hyphenation}, @code{gtroff} hyphenates words. 6346There are a number of ways to influence hyphenation. 6347 6348@DefreqList {hy, [@Var{mode}]} 6349@DefregListEnd {.hy} 6350Enable hyphenation. The request has an optional numeric argument, 6351@var{mode}, to restrict hyphenation if necessary: 6352 6353@table @code 6354@item 1 6355The default argument if @var{mode} is omitted. Hyphenate without 6356restrictions. This is also the start-up value of @code{gtroff}. 6357 6358@item 2 6359Do not hyphenate the last word on a page or column. 6360 6361@item 4 6362Do not hyphenate the last two characters of a word. 6363 6364@item 8 6365Do not hyphenate the first two characters of a word. 6366@end table 6367 6368Values in the previous table are additive. For example, the 6369value@tie{}12 causes @code{gtroff} to neither hyphenate the last 6370two nor the first two characters of a word. 6371 6372@cindex hyphenation restrictions register (@code{.hy}) 6373The current hyphenation restrictions can be found in the read-only 6374number register @samp{.hy}. 6375 6376The hyphenation mode is associated with the current environment 6377(@pxref{Environments}). 6378@endDefreq 6379 6380@Defreq {nh, } 6381Disable hyphenation (i.e., set the hyphenation mode to zero). Note 6382that the hyphenation mode of the last call to @code{hy} is not 6383remembered. 6384 6385The hyphenation mode is associated with the current environment 6386(@pxref{Environments}). 6387@endDefreq 6388 6389@DefreqList {hlm, [@Var{nnn}]} 6390@DefregItem {.hlm} 6391@DefregListEnd {.hlc} 6392@cindex explicit hyphen (@code{\%}) 6393@cindex hyphen, explicit (@code{\%}) 6394@cindex consecutive hyphenated lines (@code{hlm}) 6395@cindex lines, consecutive hyphenated (@code{hlm}) 6396@cindex hyphenated lines, consecutive (@code{hlm}) 6397Set the maximum number of consecutive hyphenated lines to @var{nnn}. 6398If this number is negative, there is no maximum. The default value 6399is@tie{}@minus{}1 if @var{nnn} is omitted. This value is associated 6400with the current environment (@pxref{Environments}). Only lines 6401output from a given environment count towards the maximum associated 6402with that environment. Hyphens resulting from @code{\%} are counted; 6403explicit hyphens are not. 6404 6405The current setting of @code{hlm} is available in the @code{.hlm} 6406read-only number register. Also the number of immediately preceding 6407consecutive hyphenated lines are available in the read-only number 6408register @samp{.hlc}. 6409@endDefreq 6410 6411@Defreq {hw, word1 word2 @dots{}} 6412Define how @var{word1}, @var{word2}, etc.@: are to be hyphenated. The 6413words must be given with hyphens at the hyphenation points. For 6414example: 6415 6416@Example 6417.hw in-sa-lub-rious 6418@endExample 6419 6420@noindent 6421Besides the space character, any character whose hyphenation code value 6422is zero can be used to separate the arguments of @code{hw} (see the 6423documentation for the @code{hcode} request below for more information). 6424In addition, this request can be used more than once. 6425 6426Hyphenation exceptions specified with the @code{hw} request are 6427associated with the current hyphenation language; it causes an error 6428if there is no current hyphenation language. 6429 6430This request is ignored if there is no parameter. 6431 6432In old versions of @code{troff} there was a limited amount of space to 6433store such information; fortunately, with @code{gtroff}, this is no 6434longer a restriction. 6435@endDefreq 6436 6437@DefescList {\\%, , , } 6438@deffnx Escape @t{\:} 6439@ifnotinfo 6440@esindex \: 6441@end ifnotinfo 6442@ifinfo 6443@esindex \@r{<colon>} 6444@end ifinfo 6445@cindex hyphenation character (@code{\%}) 6446@cindex character, hyphenation (@code{\%}) 6447@cindex disabling hyphenation (@code{\%}) 6448@cindex hyphenation, disabling (@code{\%}) 6449To tell @code{gtroff} how to hyphenate words on the fly, use the 6450@code{\%} escape, also known as the @dfn{hyphenation character}. 6451Preceding a word with this character prevents it from being 6452hyphenated; putting it inside a word indicates to @code{gtroff} that 6453the word may be hyphenated at that point. Note that this mechanism 6454only affects that one occurrence of the word; to change the 6455hyphenation of a word for the entire document, use the @code{hw} 6456request. 6457 6458The @code{\:} escape inserts a zero-width break point 6459(that is, the word breaks but without adding a hyphen). 6460 6461@Example 6462... check the /var/log/\:httpd/\:access_log file ... 6463@endExample 6464 6465@cindex @code{\X}, followed by @code{\%} 6466@cindex @code{\Y}, followed by @code{\%} 6467@cindex @code{\%}, following @code{\X} or @code{\Y} 6468Note that @code{\X} and @code{\Y} start a word, that is, the @code{\%} 6469escape in (say) @w{@samp{\X'...'\%foobar}} and 6470@w{@samp{\Y'...'\%foobar}} no longer prevents hyphenation but inserts 6471a hyphenation point at the beginning of @samp{foobar}; most likely 6472this isn't what you want to do. 6473@endDefesc 6474 6475@Defreq {hc, [@Var{char}]} 6476Change the hyphenation character to @var{char}. This character then 6477works the same as the @code{\%} escape, and thus, no longer appears in 6478the output. Without an argument, @code{hc} resets the hyphenation 6479character to be @code{\%} (the default) only. 6480 6481The hyphenation character is associated with the current environment 6482(@pxref{Environments}). 6483@endDefreq 6484 6485@DefreqList {hpf, pattern_file} 6486@DefreqItem {hpfa, pattern_file} 6487@DefreqListEnd {hpfcode, a b [c d @dots{}]} 6488@cindex hyphenation patterns (@code{hpf}) 6489@cindex patterns for hyphenation (@code{hpf}) 6490Read in a file of hyphenation patterns. This file is searched for in 6491the same way as @file{@var{name}.tmac} (or @file{tmac.@var{name}}) is 6492searched for if the @option{-m@var{name}} option is specified. 6493 6494It should have the same format as (simple) @TeX{} patterns files. 6495More specifically, the following scanning rules are implemented. 6496 6497@itemize @bullet 6498@item 6499A percent sign starts a comment (up to the end of the line) 6500even if preceded by a backslash. 6501 6502@item 6503No support for `digraphs' like @code{\$}. 6504 6505@item 6506@code{^^@var{xx}} (@var{x} is 0-9 or a-f) and @code{^^@var{x}} (character 6507code of @var{x} in the range 0-127) are recognized; other use of @code{^} 6508causes an error. 6509 6510@item 6511No macro expansion. 6512 6513@item 6514@code{hpf} checks for the expression @code{\patterns@{@dots{}@}} 6515(possibly with whitespace before and after the braces). 6516Everything between the braces is taken as hyphenation patterns. 6517Consequently, @code{@{} and @code{@}} are not allowed in patterns. 6518 6519@item 6520Similarly, @code{\hyphenation@{@dots{}@}} gives a list of hyphenation 6521exceptions. 6522 6523@item 6524@code{\endinput} is recognized also. 6525 6526@item 6527For backwards compatibility, if @code{\patterns} is missing, 6528the whole file is treated as a list of hyphenation patterns 6529(only recognizing the @code{%} character as the start of a comment). 6530@end itemize 6531 6532If no @code{hpf} request is specified (either in the document or in a 6533macro package), @code{gtroff} won't hyphenate at all. 6534 6535The @code{hpfa} request appends a file of patterns to the current list. 6536 6537The @code{hpfcode} request defines mapping values for character codes in 6538hyphenation patterns. @code{hpf} or @code{hpfa} then apply the mapping 6539(after reading the patterns) before replacing or appending them to 6540the current list of patterns. Its arguments are pairs of character codes 6541-- integers from 0 to@tie{}255. The request maps character code@tie{}@var{a} 6542to code@tie{}@var{b}, code@tie{}@var{c} to code@tie{}@var{d}, and so on. You 6543can use character codes which would be invalid otherwise. 6544 6545@pindex troffrc 6546@pindex troffrc-end 6547@pindex hyphen.us 6548@pindex hyphenex.us 6549The set of hyphenation patterns is associated with the current language 6550set by the @code{hla} request. The @code{hpf} request is usually 6551invoked by the @file{troffrc} or @file{troffrc-end} file; by default, 6552@file{troffrc} loads hyphenation patterns and exceptions for American 6553English (in files @file{hyphen.us} and @file{hyphenex.us}). 6554 6555A second call to @code{hpf} (for the same language) will replace the 6556hyphenation patterns with the new ones. 6557 6558Invoking @code{hpf} causes an error if there is no current hyphenation 6559language. 6560@endDefreq 6561 6562@Defreq {hcode, c1 code1 c2 code2 @dots{}} 6563@cindex hyphenation code (@code{hcode}) 6564@cindex code, hyphenation (@code{hcode}) 6565Set the hyphenation code of character @var{c1} to @var{code1}, that of 6566@var{c2} to @var{code2}, etc. A hyphenation code must be a single 6567input character (not a special character) other than a digit or a 6568space. Initially each lower-case letter (@samp{a}-@samp{z}) has its 6569hyphenation code set to itself, and each upper-case letter 6570(@samp{A}-@samp{Z}) has a hyphenation code which is the lower-case 6571version of itself. 6572 6573This request is ignored if it has no parameter. 6574@endDefreq 6575 6576@DefreqList {hym, [@Var{length}]} 6577@DefregListEnd {.hym} 6578@cindex hyphenation margin (@code{hym}) 6579@cindex margin for hyphenation (@code{hym}) 6580@cindex @code{ad} request, and hyphenation margin 6581Set the (right) hyphenation margin to @var{length}. If the current 6582adjustment mode is not @samp{b} or @samp{n}, the line is not 6583hyphenated if it is shorter than @var{length}. Without an argument, 6584the hyphenation margin is reset to its default value, which is@tie{}0. 6585The default scaling indicator for this request is @samp{m}. The 6586hyphenation margin is associated with the current environment 6587(@pxref{Environments}). 6588 6589A negative argument resets the hyphenation margin to zero, emitting 6590a warning of type @samp{range}. 6591 6592@cindex hyphenation margin register (@code{.hym}) 6593The current hyphenation margin is available in the @code{.hym} read-only 6594number register. 6595@endDefreq 6596 6597@DefreqList {hys, [@Var{hyphenation_space}]} 6598@DefregListEnd {.hys} 6599@cindex hyphenation space (@code{hys}) 6600@cindex @code{ad} request, and hyphenation space 6601Set the hyphenation space to @var{hyphenation_space}. If the current 6602adjustment mode is @samp{b} or @samp{n}, don't hyphenate the line 6603if it can be justified by adding no more than @var{hyphenation_space} 6604extra space to each word space. Without argument, the hyphenation 6605space is set to its default value, which is@tie{}0. The default 6606scaling indicator for this request is @samp{m}. The hyphenation 6607space is associated with the current environment 6608(@pxref{Environments}). 6609 6610A negative argument resets the hyphenation space to zero, emitting a 6611warning of type @samp{range}. 6612 6613@cindex hyphenation space register (@code{.hys}) 6614The current hyphenation space is available in the @code{.hys} read-only 6615number register. 6616@endDefreq 6617 6618@Defreq {shc, [@Var{glyph}]} 6619@cindex soft hyphen character, setting (@code{shc}) 6620@cindex character, soft hyphen, setting (@code{shc}) 6621@cindex glyph, soft hyphen (@code{hy}) 6622@cindex soft hyphen glyph (@code{hy}) 6623@cindex @code{char} request, and soft hyphen character 6624@cindex @code{tr} request, and soft hyphen character 6625Set the @dfn{soft hyphen character} to @var{glyph}.@footnote{@dfn{Soft 6626hyphen character} is a misnomer since it is an output glyph.} If the 6627argument is omitted, the soft hyphen character is set to the default 6628glyph @code{\(hy} (this is the start-up value of @code{gtroff} also). 6629The soft hyphen character is the glyph that is inserted when a word is 6630hyphenated at a line break. If the soft hyphen character does not 6631exist in the font of the character immediately preceding a potential 6632break point, then the line is not broken at that point. Neither 6633definitions (specified with the @code{char} request) nor translations 6634(specified with the @code{tr} request) are considered when finding the 6635soft hyphen character. 6636@endDefreq 6637 6638@DefreqList {hla, language} 6639@DefregListEnd {.hla} 6640@cindex @code{hpf} request, and hyphenation language 6641@cindex @code{hw} request, and hyphenation language 6642@pindex troffrc 6643@pindex troffrc-end 6644Set the current hyphenation language to the string @var{language}. 6645Hyphenation exceptions specified with the @code{hw} request and 6646hyphenation patterns specified with the @code{hpf} and @code{hpfa} 6647requests are both associated with the current hyphenation language. 6648The @code{hla} request is usually invoked by the @file{troffrc} or the 6649@file{troffrc-end} files; @file{troffrc} sets the default language to 6650@samp{us}. 6651 6652@cindex hyphenation language register (@code{.hla}) 6653The current hyphenation language is available as a string in the 6654read-only number register @samp{.hla}. 6655 6656@Example 6657.ds curr_language \n[.hla] 6658\*[curr_language] 6659 @result{} us 6660@endExample 6661@endDefreq 6662 6663 6664@c ===================================================================== 6665 6666@node Manipulating Spacing, Tabs and Fields, Manipulating Hyphenation, gtroff Reference 6667@section Manipulating Spacing 6668@cindex manipulating spacing 6669@cindex spacing, manipulating 6670 6671@Defreq {sp, [@Var{distance}]} 6672Space downwards @var{distance}. With no argument it advances 66731@tie{}line. A negative argument causes @code{gtroff} to move up the page 6674the specified distance. If the argument is preceded by a @samp{|} 6675then @code{gtroff} moves that distance from the top of the page. This 6676request causes a line break. The default scaling indicator is @samp{v}. 6677 6678If a vertical trap is sprung during execution of @code{sp}, the amount of 6679vertical space after the trap is discarded. For example, this 6680 6681@Example 6682.de xxx 6683.. 6684. 6685.wh 0 xxx 6686. 6687.pl 5v 6688foo 6689.sp 2 6690bar 6691.sp 50 6692baz 6693@endExample 6694 6695@noindent 6696results in 6697 6698@Example 6699foo 6700 6701 6702bar 6703 6704baz 6705@endExample 6706 6707@cindex @code{sp} request, and traps 6708@cindex discarded space in traps 6709@cindex space, discarded, in traps 6710@cindex traps, and discarded space 6711The amount of discarded space is available in the number register 6712@code{.trunc}. 6713 6714To protect @code{sp} against vertical traps, use the @code{vpt} request: 6715 6716@Example 6717.vpt 0 6718.sp -3 6719.vpt 1 6720@endExample 6721@endDefreq 6722 6723@DefreqList {ls, [@Var{nnn}]} 6724@DefregListEnd {.L} 6725@cindex double-spacing (@code{ls}) 6726Output @w{@var{nnn}@minus{}1} blank lines after each line of text. 6727With no argument, @code{gtroff} uses the previous value before the 6728last @code{ls} call. 6729 6730@Example 6731.ls 2 \" This causes double-spaced output 6732.ls 3 \" This causes triple-spaced output 6733.ls \" Again double-spaced 6734@endExample 6735 6736The line spacing is associated with the current environment 6737(@pxref{Environments}). 6738 6739@cindex line spacing register (@code{.L}) 6740The read-only number register @code{.L} contains the current line 6741spacing setting. 6742@endDefreq 6743 6744@xref{Changing Type Sizes}, for the requests @code{vs} and @code{pvs} 6745as alternatives to @code{ls}. 6746 6747@DefescList {\\x, ', spacing, '} 6748@DefregListEnd {.a} 6749Sometimes, extra vertical spacing is only needed occasionally, e.g.@: 6750to allow space for a tall construct (like an equation). The @code{\x} 6751escape does this. The escape is given a numerical argument, usually 6752enclosed in quotes (like @samp{\x'3p'}); the default scaling indicator 6753is @samp{v}. If this number is positive extra vertical space is 6754inserted below the current line. A negative number adds space above. 6755If this escape is used multiple times on the same line, the maximum of 6756the values is used. 6757 6758@xref{Escapes}, for details on parameter delimiting characters. 6759 6760@cindex extra post-vertical line space register (@code{.a}) 6761The @code{.a} read-only number register contains the most recent 6762(nonnegative) extra vertical line space. 6763 6764Using @code{\x} can be necessary in combination with the @code{\b} 6765escape, as the following example shows. 6766 6767@Example 6768This is a test with the \[rs]b escape. 6769.br 6770This is a test with the \[rs]b escape. 6771.br 6772This is a test with \b'xyz'\x'-1m'\x'1m'. 6773.br 6774This is a test with the \[rs]b escape. 6775.br 6776This is a test with the \[rs]b escape. 6777@endExample 6778 6779@noindent 6780produces 6781 6782@Example 6783This is a test with the \b escape. 6784This is a test with the \b escape. 6785 x 6786This is a test with y. 6787 z 6788This is a test with the \b escape. 6789This is a test with the \b escape. 6790@endExample 6791@endDefesc 6792 6793@DefreqList {ns, } 6794@DefreqItem {rs, } 6795@DefregListEnd {.ns} 6796@cindex @code{sp} request, and no-space mode 6797@cindex no-space mode (@code{ns}) 6798@cindex mode, no-space (@code{ns}) 6799@cindex blank lines, disabling 6800@cindex lines, blank, disabling 6801Enable @dfn{no-space mode}. In this mode, spacing (either via 6802@code{sp} or via blank lines) is disabled. The @code{bp} request to 6803advance to the next page is also disabled, except if it is accompanied 6804by a page number (see @ref{Page Control}, for more information). This 6805mode ends when actual text is output or the @code{rs} request is 6806encountered which ends no-space mode. The read-only number register 6807@code{.ns} is set to@tie{}1 as long as no-space mode is active. 6808 6809This request is useful for macros that conditionally 6810insert vertical space before the text starts 6811(for example, a paragraph macro could insert some space 6812except when it is the first paragraph after a section header). 6813@endDefreq 6814 6815 6816@c ===================================================================== 6817 6818@node Tabs and Fields, Character Translations, Manipulating Spacing, gtroff Reference 6819@section Tabs and Fields 6820@cindex tabs, and fields 6821@cindex fields, and tabs 6822 6823@cindex @acronym{EBCDIC} encoding of a tab 6824A tab character (@acronym{ASCII} char@tie{}9, @acronym{EBCDIC} 6825char@tie{}5) causes a horizontal movement to the next tab stop (much 6826like it did on a typewriter). 6827 6828@Defesc {\\t, , , } 6829@cindex tab character, non-interpreted (@code{\t}) 6830@cindex character, tab, non-interpreted (@code{\t}) 6831This escape is a non-interpreted tab character. In copy mode 6832(@pxref{Copy-in Mode}), @code{\t} is the same as a real tab character. 6833@endDefesc 6834 6835@DefreqList {ta, [@Var{n1} @Var{n2} @dots{} @Var{nn} @t{T} @Var{r1} @Var{r2} @dots{} @Var{rn}]} 6836@DefregListEnd {.tabs} 6837Change tab stop positions. This request takes a series of tab 6838specifiers as arguments (optionally divided into two groups with the 6839letter @samp{T}) which indicate where each tab stop is to be 6840(overriding any previous settings). 6841 6842Tab stops can be specified absolutely, i.e., as the distance from the 6843left margin. For example, the following sets 6@tie{}tab stops every 6844one inch. 6845 6846@Example 6847.ta 1i 2i 3i 4i 5i 6i 6848@endExample 6849 6850Tab stops can also be specified using a leading @samp{+} 6851which means that the specified tab stop is set relative to 6852the previous tab stop. For example, the following is equivalent to the 6853previous example. 6854 6855@Example 6856.ta 1i +1i +1i +1i +1i +1i 6857@endExample 6858 6859@code{gtroff} supports an extended syntax to specify repeat values after 6860the @samp{T} mark (these values are always taken as relative) -- this is 6861the usual way to specify tabs set at equal intervals. The following is, 6862yet again, the same as the previous examples. It does even more since 6863it defines an infinite number of tab stops separated by one inch. 6864 6865@Example 6866.ta T 1i 6867@endExample 6868 6869Now we are ready to interpret the full syntax given at the beginning: 6870Set tabs at positions @var{n1}, @var{n2}, @dots{}, @var{nn} and then set 6871tabs at @var{nn}+@var{r1}, @var{nn}+@var{r2}, @dots{}, @var{nn}+@var{rn} 6872and then at @var{nn}+@var{rn}+@var{r1}, @var{nn}+@var{rn}+@var{r2}, 6873@dots{}, @var{nn}+@var{rn}+@var{rn}, and so on. 6874 6875Example: @samp{4c +6c T 3c 5c 2c} is equivalent to @samp{4c 10c 13c 18c 687620c 23c 28c 30c @dots{}}. 6877 6878The material in each tab column (i.e., the column between two tab stops) 6879may be justified to the right or left or centered in the column. This 6880is specified by appending @samp{R}, @samp{L}, or @samp{C} to the tab 6881specifier. The default justification is @samp{L}. Example: 6882 6883@Example 6884.ta 1i 2iC 3iR 6885@endExample 6886 6887Some notes: 6888 6889@itemize @bullet 6890@item 6891The default unit of the @code{ta} request is @samp{m}. 6892 6893@item 6894A tab stop is converted into a non-breakable horizontal movement which 6895can be neither stretched nor squeezed. For example, 6896 6897@Example 6898.ds foo a\tb\tc 6899.ta T 5i 6900\*[foo] 6901@endExample 6902 6903@noindent 6904creates a single line which is a bit longer than 10@tie{}inches (a string 6905is used to show exactly where the tab characters are). Now consider the 6906following: 6907 6908@Example 6909.ds bar a\tb b\tc 6910.ta T 5i 6911\*[bar] 6912@endExample 6913 6914@noindent 6915@code{gtroff} first converts the tab stops of the line into unbreakable 6916horizontal movements, then splits the line after the second @samp{b} 6917(assuming a sufficiently short line length). Usually, this isn't what 6918the user wants. 6919 6920@item 6921Superfluous tabs (i.e., tab characters which do not correspond to a tab 6922stop) are ignored except the first one which delimits the characters 6923belonging to the last tab stop for right-justifying or centering. 6924Consider the following example 6925 6926@Example 6927.ds Z foo\tbar\tfoo 6928.ds ZZ foo\tbar\tfoobar 6929.ds ZZZ foo\tbar\tfoo\tbar 6930.ta 2i 4iR 6931\*[Z] 6932.br 6933\*[ZZ] 6934.br 6935\*[ZZZ] 6936.br 6937@endExample 6938 6939@noindent 6940which produces the following output: 6941 6942@Example 6943foo bar foo 6944foo bar foobar 6945foo bar foobar 6946@endExample 6947 6948@noindent 6949The first line right-justifies the second `foo' relative to the tab 6950stop. The second line right-justifies `foobar'. The third line finally 6951right-justifies only `foo' because of the additional tab character which 6952marks the end of the string belonging to the last defined tab stop. 6953 6954@item 6955Tab stops are associated with the current environment 6956(@pxref{Environments}). 6957 6958@item 6959Calling @code{ta} without an argument removes all tab stops. 6960 6961@item 6962@cindex tab stops, for TTY output devices 6963The start-up value of @code{gtroff} is @w{@samp{T 0.8i}}. 6964@end itemize 6965 6966@cindex tab settings register (@code{.tabs}) 6967The read-only number register @code{.tabs} contains a string 6968representation of the current tab settings suitable for use as an 6969argument to the @code{ta} request. 6970 6971@Example 6972.ds tab-string \n[.tabs] 6973\*[tab-string] 6974 @result{} T120u 6975@endExample 6976 6977@cindex @code{.S} register, Plan@tie{}9 alias for @code{.tabs} 6978@cindex @code{.tabs} register, Plan@tie{}9 alias (@code{.S}) 6979The @code{troff} version of the Plan@tie{}9 operating system uses 6980register @code{.S} for the same purpose. 6981@endDefreq 6982 6983@Defreq {tc, [@Var{fill-glyph}]} 6984@cindex tab repetition character (@code{tc}) 6985@cindex character, tab repetition (@code{tc}) 6986@cindex glyph, tab repetition (@code{tc}) 6987Normally @code{gtroff} fills the space to the next tab stop with 6988whitespace. This can be changed with the @code{tc} request. With no 6989argument @code{gtroff} reverts to using whitespace, which is the 6990default. The value of this @dfn{tab repetition character} is 6991associated with the current environment 6992(@pxref{Environments}).@footnote{@dfn{Tab repetition character} is a 6993misnomer since it is an output glyph.} 6994@endDefreq 6995 6996@DefreqList {linetabs, n} 6997@DefregListEnd {.linetabs} 6998@cindex tab, line-tabs mode 6999@cindex line-tabs mode 7000@cindex mode, line-tabs 7001If @var{n} is missing or not zero, enable @dfn{line-tabs} mode, 7002or disable it otherwise (the default). 7003In line-tabs mode, @code{gtroff} computes tab distances 7004relative to the (current) output line instead of the input line. 7005 7006For example, the following code: 7007 7008@Example 7009.ds x a\t\c 7010.ds y b\t\c 7011.ds z c 7012.ta 1i 3i 7013\*x 7014\*y 7015\*z 7016@endExample 7017 7018@noindent 7019in normal mode, results in the output 7020 7021@Example 7022a b c 7023@endExample 7024 7025@noindent 7026in line-tabs mode, the same code outputs 7027 7028@Example 7029a b c 7030@endExample 7031 7032Line-tabs mode is associated with the current environment. 7033The read-only register @code{.linetabs} is set to@tie{}1 if in line-tabs 7034mode, and 0 in normal mode. 7035@endDefreq 7036 7037@menu 7038* Leaders:: 7039* Fields:: 7040@end menu 7041 7042@c --------------------------------------------------------------------- 7043 7044@node Leaders, Fields, Tabs and Fields, Tabs and Fields 7045@subsection Leaders 7046@cindex leaders 7047 7048Sometimes it may may be desirable to use the @code{tc} request to fill a 7049particular tab stop with a given glyph (for example dots in a table 7050of contents), but also normal tab stops on the rest of the line. For 7051this @code{gtroff} provides an alternate tab mechanism, called 7052@dfn{leaders} which does just that. 7053 7054@cindex leader character 7055A leader character (character code@tie{}1) behaves similarly to a tab 7056character: It moves to the next tab stop. The only difference is that 7057for this movement, the fill glyph defaults to a period character and 7058not to space. 7059 7060@Defesc {\\a, , , } 7061@cindex leader character, non-interpreted (@code{\a}) 7062@cindex character, leader, non-interpreted (@code{\a}) 7063This escape is a non-interpreted leader character. In copy mode 7064(@pxref{Copy-in Mode}), @code{\a} is the same as a real leader 7065character. 7066@endDefesc 7067 7068@Defreq {lc, [@Var{fill-glyph}]} 7069@cindex leader repetition character (@code{lc}) 7070@cindex character, leader repetition (@code{lc}) 7071@cindex glyph, leader repetition (@code{lc}) 7072Declare the @dfn{leader repetition character}.@footnote{@dfn{Leader 7073repetition character} is a misnomer since it is an output glyph.} 7074Without an argument, leaders act the same as tabs (i.e., using 7075whitespace for filling). @code{gtroff}'s start-up value is a dot 7076(@samp{.}). The value of the leader repetition character is 7077associated with the current environment (@pxref{Environments}). 7078@endDefreq 7079 7080@cindex table of contents 7081@cindex contents, table of 7082For a table of contents, to name an example, tab stops may be defined so 7083that the section number is one tab stop, the title is the second with 7084the remaining space being filled with a line of dots, and then the page 7085number slightly separated from the dots. 7086 7087@Example 7088.ds entry 1.1\tFoo\a\t12 7089.lc . 7090.ta 1i 5i +.25i 7091\*[entry] 7092@endExample 7093 7094@noindent 7095This produces 7096 7097@Example 70981.1 Foo.......................................... 12 7099@endExample 7100 7101@c --------------------------------------------------------------------- 7102 7103@node Fields, , Leaders, Tabs and Fields 7104@subsection Fields 7105@cindex fields 7106 7107@cindex field delimiting character (@code{fc}) 7108@cindex delimiting character, for fields (@code{fc}) 7109@cindex character, field delimiting (@code{fc}) 7110@cindex field padding character (@code{fc}) 7111@cindex padding character, for fields (@code{fc}) 7112@cindex character, field padding (@code{fc}) 7113@dfn{Fields} are a more general way of laying out tabular data. A field 7114is defined as the data between a pair of @dfn{delimiting characters}. 7115It contains substrings which are separated by @dfn{padding characters}. 7116The width of a field is the distance on the @emph{input} line from the 7117position where the field starts to the next tab stop. A padding 7118character inserts stretchable space similar to @TeX{}'s @code{\hss} 7119command (thus it can even be negative) to make the sum of all substring 7120lengths plus the stretchable space equal to the field width. If more 7121than one padding character is inserted, the available space is evenly 7122distributed among them. 7123 7124@Defreq {fc, [@Var{delim-char} [@Var{padding-char}]]} 7125Define a delimiting and a padding character for fields. If the latter 7126is missing, the padding character defaults to a space character. If 7127there is no argument at all, the field mechanism is disabled (which is 7128the default). Note that contrary to e.g.@: the tab repetition 7129character, delimiting and padding characters are @emph{not} associated 7130to the current environment (@pxref{Environments}). 7131 7132Example: 7133 7134@Example 7135.fc # ^ 7136.ta T 3i 7137#foo^bar^smurf# 7138.br 7139#foo^^bar^smurf# 7140@endExample 7141 7142@noindent 7143and here the result: 7144 7145@Example 7146foo bar smurf 7147foo bar smurf 7148@endExample 7149@endDefreq 7150 7151 7152@c ===================================================================== 7153 7154@node Character Translations, Troff and Nroff Mode, Tabs and Fields, gtroff Reference 7155@section Character Translations 7156@cindex character translations 7157@cindex translations of characters 7158 7159@cindex control character, changing (@code{cc}) 7160@cindex character, control, changing (@code{cc}) 7161@cindex no-break control character, changing (@code{c2}) 7162@cindex character, no-break control, changing (@code{c2}) 7163@cindex control character, no-break, changing (@code{c2}) 7164The control character (@samp{.}) and the no-break control character 7165(@samp{'}) can be changed with the @code{cc} and @code{c2} requests, 7166respectively. 7167 7168@Defreq {cc, [@Var{c}]} 7169Set the control character to@tie{}@var{c}. With no argument the default 7170control character @samp{.} is restored. The value of the control 7171character is associated with the current environment 7172(@pxref{Environments}). 7173@endDefreq 7174 7175@Defreq {c2, [@Var{c}]} 7176Set the no-break control character to@tie{}@var{c}. With no argument the 7177default control character @samp{'} is restored. The value of the 7178no-break control character is associated with the current environment 7179(@pxref{Environments}). 7180@endDefreq 7181 7182@Defreq {eo, } 7183@cindex disabling @code{\} (@code{eo}) 7184@cindex @code{\}, disabling (@code{eo}) 7185Disable the escape mechanism completely. After executing this 7186request, the backslash character @samp{\} no longer starts an escape 7187sequence. 7188 7189This request can be very helpful in writing macros since it is not 7190necessary then to double the escape character. Here an example: 7191 7192@Example 7193.\" This is a simplified version of the 7194.\" .BR request from the man macro package 7195.eo 7196.de BR 7197. ds result \& 7198. while (\n[.$] >= 2) \@{\ 7199. as result \fB\$1\fR\$2 7200. shift 2 7201. \@} 7202. if \n[.$] .as result \fB\$1 7203\*[result] 7204. ft R 7205.. 7206.ec 7207@endExample 7208@endDefreq 7209 7210@Defreq {ec, [@Var{c}]} 7211@cindex escape character, changing (@code{ec}) 7212@cindex character, escape, changing (@code{ec}) 7213Set the escape character to@tie{}@var{c}. With no argument the default 7214escape character @samp{\} is restored. It can be also used to 7215re-enable the escape mechanism after an @code{eo} request. 7216 7217Note that changing the escape character globally will likely break 7218macro packages since @code{gtroff} has no mechanism to `intern' macros, 7219i.e., to convert a macro definition into an internal form which is 7220independent of its representation (@TeX{} has this mechanism). 7221If a macro is called, it is executed literally. 7222@endDefreq 7223 7224@DefreqList {ecs, } 7225@DefreqListEnd {ecr, } 7226The @code{ecs} request saves the current escape character 7227in an internal register. 7228Use this request in combination with the @code{ec} request to 7229temporarily change the escape character. 7230 7231The @code{ecr} request restores the escape character 7232saved with @code{ecs}. 7233Without a previous call to @code{ecs}, this request 7234sets the escape character to @code{\}. 7235@endDefreq 7236 7237@DefescList {\\\\, , , } 7238@DefescItem {\\e, , , } 7239@DefescListEnd {\\E, , , } 7240Print the current escape character (which is the backslash character 7241@samp{\} by default). 7242 7243@code{\\} is a `delayed' backslash; more precisely, it is the default 7244escape character followed by a backslash, which no longer has special 7245meaning due to the leading escape character. It is @emph{not} an escape 7246sequence in the usual sense! In any unknown escape sequence 7247@code{\@var{X}} the escape character is ignored and @var{X} is printed. 7248But if @var{X} is equal to the current escape character, no warning is 7249emitted. 7250 7251As a consequence, only at top-level or in a diversion a backslash glyph is 7252printed; in copy-in mode, it expands to a single backslash which then 7253combines with the following character to an escape sequence. 7254 7255The @code{\E} escape differs from @code{\e} by printing an escape 7256character that is not interpreted in copy mode. 7257Use this to define strings with escapes that work 7258when used in copy mode (for example, as a macro argument). 7259The following example defines strings to begin and end 7260a superscript: 7261 7262@Example 7263.ds @{ \v'-.3m'\s'\En[.s]*60/100' 7264.ds @} \s0\v'.3m' 7265@endExample 7266 7267Another example to demonstrate the differences between the various escape 7268sequences, using a strange escape character, @samp{-}. 7269 7270@Example 7271.ec - 7272.de xxx 7273--A'123' 7274.. 7275.xxx 7276 @result{} -A'foo' 7277@endExample 7278 7279@noindent 7280The result is surprising for most users, expecting @samp{1} since 7281@samp{foo} is a valid identifier. What has happened? As mentioned 7282above, the leading escape character makes the following character 7283ordinary. Written with the default escape character the sequence 7284@samp{--} becomes @samp{\-} -- this is the minus sign. 7285 7286If the escape character followed by itself is a valid escape sequence, 7287only @code{\E} yields the expected result: 7288 7289@Example 7290.ec - 7291.de xxx 7292-EA'123' 7293.. 7294.xxx 7295 @result{} 1 7296@endExample 7297@endDefesc 7298 7299@Defesc {\\., , , } 7300Similar to @code{\\}, the sequence @code{\.} isn't a real escape sequence. 7301As before, a warning message is suppressed if the escape character is 7302followed by a dot, and the dot itself is printed. 7303 7304@Example 7305.de foo 7306. nop foo 7307. 7308. de bar 7309. nop bar 7310\\.. 7311. 7312.. 7313.foo 7314.bar 7315 @result{} foo bar 7316@endExample 7317 7318@noindent 7319The first backslash is consumed while the macro is read, and the second 7320is swallowed while exexuting macro @code{foo}. 7321@endDefesc 7322 7323A @dfn{translation} is a mapping of an input character to an output 7324glyph. The mapping occurs at output time, i.e., the input character 7325gets assigned the metric information of the mapped output character 7326right before input tokens are converted to nodes (@pxref{Gtroff 7327Internals}, for more on this process). 7328 7329@DefreqList {tr, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7330@DefreqListEnd {trin, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7331Translate character @var{a} to glyph@tie{}@var{b}, character @var{c} to 7332glyph@tie{}@var{d}, etc. If there is an odd number of arguments, the 7333last one is translated to an unstretchable space (@w{@samp{\ }}). 7334 7335The @code{trin} request is identical to @code{tr}, 7336but when you unformat a diversion with @code{asciify} 7337it ignores the translation. 7338@xref{Diversions}, for details about the @code{asciify} request. 7339 7340Some notes: 7341 7342@itemize @bullet 7343@item 7344@cindex @code{\(}, and translations 7345@cindex @code{\[}, and translations 7346@cindex @code{\'}, and translations 7347@cindex @code{\`}, and translations 7348@cindex @code{\-}, and translations 7349@cindex @code{\_}, and translations 7350@cindex @code{\C}, and translations 7351@cindex @code{\N}, and translations 7352@cindex @code{char} request, and translations 7353@cindex special characters 7354@cindex character, special 7355@cindex numbered glyph (@code{\N}) 7356@cindex glyph, numbered (@code{\N}) 7357Special characters (@code{\(@var{xx}}, @code{\[@var{xxx}]}, 7358@code{\C'@var{xxx}'}, @code{\'}, @code{\`}, @code{\-}, @code{\_}), 7359glyphs defined with the @code{char} request, and numbered glyphs 7360(@code{\N'@var{xxx}'}) can be translated also. 7361 7362@item 7363@cindex @code{\e}, and translations 7364The @code{\e} escape can be translated also. 7365 7366@item 7367@cindex @code{\%}, and translations 7368@cindex @code{\~}, and translations 7369Characters can be mapped onto the @code{\%} and @code{\~} escapes (but 7370@code{\%} and @code{\~} can't be mapped onto another glyph). 7371 7372@item 7373@cindex backspace character, and translations 7374@cindex character, backspace, and translations 7375@cindex leader character, and translations 7376@cindex character, leader, and translations 7377@cindex newline character, and translations 7378@cindex character, newline, and translations 7379@cindex tab character, and translations 7380@cindex character, tab, and translations 7381@cindex @code{\a}, and translations 7382@cindex @code{\t}, and translations 7383The following characters can't be translated: space (with one exception, 7384see below), backspace, newline, leader (and @code{\a}), tab (and 7385@code{\t}). 7386 7387@item 7388@cindex @code{shc} request, and translations 7389Translations are not considered for finding the soft hyphen character 7390set with the @code{shc} request. 7391 7392@item 7393@cindex @code{\&}, and translations 7394The pair @samp{@var{c}\&} (this is an arbitrary character@tie{}@var{c} 7395followed by the zero width space character) maps this character to nothing. 7396 7397@Example 7398.tr a\& 7399foo bar 7400 @result{} foo br 7401@endExample 7402 7403@noindent 7404It is even possible to map the space character to nothing: 7405 7406@Example 7407.tr aa \& 7408foo bar 7409 @result{} foobar 7410@endExample 7411 7412@noindent 7413As shown in the example, the space character can't be the first 7414character/glyph pair as an argument of @code{tr}. Additionally, it is 7415not possible to map the space character to any other glyph; requests 7416like @w{@samp{.tr aa x}} undo @w{@samp{.tr aa \&}} instead. 7417 7418If justification is active, lines are justified in spite of the 7419`empty' space character (but there is no minimal distance, i.e.@: the 7420space character, between words). 7421 7422@item 7423After an output glyph has been constructed (this happens at the 7424moment immediately before the glyph is appended to an output 7425glyph list, either by direct output, in a macro, diversion, or 7426string), it is no longer affected by @code{tr}. 7427 7428@item 7429Translating character to glyphs where one of them or both are 7430undefined is possible also; @code{tr} does not check whether the 7431entities in its argument do exist. 7432 7433@xref{Gtroff Internals}. 7434 7435@item 7436@code{troff} no longer has a hard-coded dependency on @w{Latin-1}; 7437all @code{char@var{XXX}} entities have been removed from the font 7438description files. This has a notable consequence which shows up in 7439warnings like @code{can't find character with input code @var{XXX}} 7440if the @code{tr} request isn't handled properly. 7441 7442Consider the following translation: 7443 7444@Example 7445.tr @'e@'E 7446@endExample 7447 7448@noindent 7449This maps input character @code{@'e} onto glyph @code{@'E}, which is 7450identical to glyph @code{char201}. But this glyph intentionally 7451doesn't exist! Instead, @code{\[char201]} is treated as an input 7452character entity and is by default mapped onto @code{\['E]}, and 7453@code{gtroff} doesn't handle translations of translations. 7454 7455The right way to write the above translation is 7456 7457@Example 7458.tr @'e\['E] 7459@endExample 7460 7461@noindent 7462With other words, the first argument of @code{tr} should be an input 7463character or entity, and the second one a glyph entity. 7464 7465@item 7466Without an argument, the @code{tr} request is ignored. 7467@end itemize 7468@endDefreq 7469 7470@Defreq {trnt, @Var{a}@Var{b}@Var{c}@Var{d}@dots{}} 7471@cindex @code{\!}, and @code{trnt} 7472@code{trnt} is the same as the @code{tr} request except that the 7473translations do not apply to text that is transparently throughput 7474into a diversion with @code{\!}. @xref{Diversions}, for more 7475information. 7476 7477For example, 7478 7479@Example 7480.tr ab 7481.di x 7482\!.tm a 7483.di 7484.x 7485@endExample 7486 7487@noindent 7488prints @samp{b} to the standard error stream; if @code{trnt} is used 7489instead of @code{tr} it prints @samp{a}. 7490@endDefreq 7491 7492 7493@c ===================================================================== 7494 7495@node Troff and Nroff Mode, Line Layout, Character Translations, gtroff Reference 7496@section Troff and Nroff Mode 7497@cindex troff mode 7498@cindex mode, troff 7499@cindex nroff mode 7500@cindex mode, nroff 7501 7502Originally, @code{nroff} and @code{troff} were two separate programs, 7503the former for TTY output, the latter for everything else. With GNU 7504@code{troff}, both programs are merged into one executable, sending 7505its output to a device driver (@code{grotty} for TTY devices, 7506@code{grops} for @sc{PostScript}, etc.) which interprets the 7507intermediate output of @code{gtroff}. For @acronym{UNIX} @code{troff} 7508it makes sense to talk about @dfn{Nroff mode} and @dfn{Troff mode} 7509since the differences are hardcoded. For GNU @code{troff}, this 7510distinction is not appropriate because @code{gtroff} simply takes the 7511information given in the font files for a particular device without 7512handling requests specially if a TTY output device is used. 7513 7514Usually, a macro package can be used with all output devices. 7515Nevertheless, it is sometimes necessary to make a distinction between 7516TTY and non-TTY devices: @code{gtroff} provides two built-in 7517conditions @samp{n} and @samp{t} for the @code{if}, @code{ie}, and 7518@code{while} requests to decide whether @code{gtroff} shall behave 7519like @code{nroff} or like @code{troff}. 7520 7521@Defreq {troff, } 7522@pindex troffrc 7523@pindex troffrc-end 7524Make the @samp{t} built-in condition true (and the @samp{n} built-in 7525condition false) for @code{if}, @code{ie}, and @code{while} 7526conditional requests. This is the default if @code{gtroff} 7527(@emph{not} @code{groff}) is started with the @option{-R} switch to 7528avoid loading of the start-up files @file{troffrc} and 7529@file{troffrc-end}. Without @option{-R}, @code{gtroff} stays in troff 7530mode if the output device is not a TTY (e.g.@: `ps'). 7531@endDefreq 7532 7533@Defreq {nroff, } 7534@pindex tty.tmac 7535Make the @samp{n} built-in condition true (and the @samp{t} built-in 7536condition false) for @code{if}, @code{ie}, and @code{while} 7537conditional requests. This is the default if @code{gtroff} uses a TTY 7538output device; the code for switching to nroff mode is in the file 7539@file{tty.tmac} which is loaded by the start-up file @code{troffrc}. 7540@endDefreq 7541 7542@xref{Conditionals and Loops}, for more details on built-in 7543conditions. 7544 7545 7546@c ===================================================================== 7547 7548@node Line Layout, Line Control, Troff and Nroff Mode, gtroff Reference 7549@section Line Layout 7550@cindex line layout 7551@cindex layout, line 7552 7553@cindex dimensions, line 7554@cindex line dimensions 7555The following drawing shows the dimensions which @code{gtroff} uses for 7556placing a line of output onto the page. They are labeled with the 7557request which manipulates each dimension. 7558 7559@Example 7560 -->| in |<-- 7561 |<-----------ll------------>| 7562 +----+----+----------------------+----+ 7563 | : : : | 7564 +----+----+----------------------+----+ 7565 -->| po |<-- 7566 |<--------paper width---------------->| 7567@endExample 7568 7569@noindent 7570These dimensions are: 7571 7572@ftable @code 7573@item po 7574@cindex left margin (@code{po}) 7575@cindex margin, left (@code{po}) 7576@cindex page offset (@code{po}) 7577@cindex offset, page (@code{po}) 7578@dfn{Page offset} -- this is the leftmost position of text on the final 7579output, defining the @dfn{left margin}. 7580 7581@item in 7582@cindex indentation (@code{in}) 7583@cindex line indentation (@code{in}) 7584@dfn{Indentation} -- this is the distance from the left margin where 7585text is printed. 7586 7587@item ll 7588@cindex line length (@code{ll}) 7589@cindex length of line (@code{ll}) 7590@dfn{Line length} -- this is the distance from the left margin to right 7591margin. 7592@end ftable 7593 7594A simple demonstration: 7595 7596@Example 7597.ll 3i 7598This is text without indentation. 7599The line length has been set to 3\~inch. 7600.in +.5i 7601.ll -.5i 7602Now the left and right margins are both increased. 7603.in 7604.ll 7605Calling .in and .ll without parameters restore 7606the previous values. 7607@endExample 7608 7609Result: 7610 7611@Example 7612This is text without indenta- 7613tion. The line length has 7614been set to 3 inch. 7615 Now the left and 7616 right margins are 7617 both increased. 7618Calling .in and .ll without 7619parameters restore the previ- 7620ous values. 7621@endExample 7622 7623@DefreqList {po, [@Var{offset}]} 7624@DefreqItem {po, @t{+}@Var{offset}} 7625@DefreqItem {po, @t{-}@Var{offset}} 7626@DefregListEnd {.o} 7627@pindex troffrc 7628Set horizontal page offset to @var{offset} (or increment or decrement 7629the current value by @var{offset}). Note that this request does not 7630cause a break, so changing the page offset in the middle of text being 7631filled may not yield the expected result. The initial value is 76321@dmn{i}. For TTY output devices, it is set to 0 in the startup file 7633@file{troffrc}; the default scaling indicator is @samp{m} (and 7634not @samp{v} as incorrectly documented in the original 7635@acronym{UNIX} troff manual). 7636 7637The current page offset can be found in the read-only number register 7638@samp{.o}. 7639 7640If @code{po} is called without an argument, the page offset is reset to 7641the previous value before the last call to @code{po}. 7642 7643@Example 7644.po 3i 7645\n[.o] 7646 @result{} 720 7647.po -1i 7648\n[.o] 7649 @result{} 480 7650.po 7651\n[.o] 7652 @result{} 720 7653@endExample 7654@endDefreq 7655 7656@DefreqList {in, [@Var{indent}]} 7657@DefreqItem {in, @t{+}@Var{indent}} 7658@DefreqItem {in, @t{-}@Var{indent}} 7659@DefregListEnd {.i} 7660Set indentation to @var{indent} (or increment or decrement the 7661current value by @var{indent}). This request causes a break. 7662Initially, there is no indentation. 7663 7664If @code{in} is called without an argument, the indentation is reset to 7665the previous value before the last call to @code{in}. The default 7666scaling indicator is @samp{m}. 7667 7668The indentation is associated with the current environment 7669(@pxref{Environments}). 7670 7671If a negative indentation value is specified (which is not allowed), 7672@code{gtroff} emits a warning of type @samp{range} and sets the 7673indentation to zero. 7674 7675The effect of @code{in} is delayed until a partially collected line (if 7676it exists) is output. A temporary indent value is reset to zero also. 7677 7678The current indentation (as set by @code{in}) can be found in the 7679read-only number register @samp{.i}. 7680@endDefreq 7681 7682@DefreqList {ti, offset} 7683@DefreqItem {ti, @t{+}@Var{offset}} 7684@DefreqItem {ti, @t{-}@Var{offset}} 7685@DefregListEnd {.in} 7686Temporarily indent the next output line by @var{offset}. If an 7687increment or decrement value is specified, adjust the temporary 7688indentation relative to the value set by the @code{in} request. 7689 7690This request causes a break; its value is associated with the current 7691environment (@pxref{Environments}). The default scaling indicator 7692is @samp{m}. A call of @code{ti} without an argument is ignored. 7693 7694If the total indentation value is negative (which is not allowed), 7695@code{gtroff} emits a warning of type @samp{range} and sets the 7696temporary indentation to zero. `Total indentation' is either 7697@var{offset} if specified as an absolute value, or the temporary plus 7698normal indentation, if @var{offset} is given as a relative value. 7699 7700The effect of @code{ti} is delayed until a partially collected line (if 7701it exists) is output. 7702 7703The read-only number register @code{.in} is the indentation that applies 7704to the current output line. 7705 7706The difference between @code{.i} and @code{.in} is that the latter takes 7707into account whether a partially collected line still uses the old 7708indentation value or a temporary indentation value is active. 7709@endDefreq 7710 7711@DefreqList {ll, [@Var{length}]} 7712@DefreqItem {ll, @t{+}@Var{length}} 7713@DefreqItem {ll, @t{-}@Var{length}} 7714@DefregItem {.l} 7715@DefregListEnd {.ll} 7716Set the line length to @var{length} (or increment or decrement the 7717current value by @var{length}). Initially, the line length is set to 77186.5@dmn{i}. The effect of @code{ll} is delayed until a partially 7719collected line (if it exists) is output. The default scaling 7720indicator is @samp{m}. 7721 7722If @code{ll} is called without an argument, the line length is reset to 7723the previous value before the last call to @code{ll}. If a negative 7724line length is specified (which is not allowed), @code{gtroff} emits a 7725warning of type @samp{range} and sets the line length to zero. 7726 7727The line length is associated with the current environment 7728(@pxref{Environments}). 7729 7730@cindex line length register (@code{.l}) 7731The current line length (as set by @code{ll}) can be found in the 7732read-only number register @samp{.l}. The read-only number register 7733@code{.ll} is the line length that applies to the current output line. 7734 7735Similar to @code{.i} and @code{.in}, the difference between @code{.l} 7736and @code{.ll} is that the latter takes into account whether a partially 7737collected line still uses the old line length value. 7738@endDefreq 7739 7740 7741@c ===================================================================== 7742 7743@node Line Control, Page Layout, Line Layout, gtroff Reference 7744@section Line Control 7745@cindex line control 7746@cindex control, line 7747 7748It is important to understand how @code{gtroff} handles input and output 7749lines. 7750 7751Many escapes use positioning relative to the input line. For example, 7752this 7753 7754@Example 7755This is a \h'|1.2i'test. 7756 7757This is a 7758\h'|1.2i'test. 7759@endExample 7760 7761@noindent 7762produces 7763 7764@Example 7765This is a test. 7766 7767This is a test. 7768@endExample 7769 7770The main usage of this feature is to define macros which act exactly 7771at the place where called. 7772 7773@Example 7774.\" A simple macro to underline a word 7775.de underline 7776. nop \\$1\l'|0\[ul]' 7777.. 7778@endExample 7779 7780@noindent 7781In the above example, @samp{|0} specifies a negative distance from the 7782current position (at the end of the just emitted argument @code{\$1}) back 7783to the beginning of the input line. Thus, the @samp{\l} escape draws a 7784line from right to left. 7785 7786@cindex input line continuation (@code{\}) 7787@cindex line, input, continuation (@code{\}) 7788@cindex continuation, input line (@code{\}) 7789@cindex output line, continuation (@code{\c}) 7790@cindex line, output, continuation (@code{\c}) 7791@cindex continuation, output line (@code{\c}) 7792@cindex interrupted line 7793@cindex line, interrupted 7794@code{gtroff} makes a difference between input and output line 7795continuation; the latter is also called @dfn{interrupting} a line. 7796 7797@DefescList {\\@key{RET}, , ,} 7798@DefescItem {\\c, , ,} 7799@DefregListEnd{.int} 7800Continue a line. @code{\@key{RET}} (this is a backslash at the end 7801of a line immediately followed by a newline) works on the input level, 7802suppressing the effects of the following newline in the input. 7803 7804@Example 7805This is a \ 7806.test 7807 @result{} This is a .test 7808@endExample 7809 7810The @samp{|} operator is also affected. 7811 7812@cindex @code{\R}, after @code{\c} 7813@code{\c} works on the output level. Anything after this escape on the 7814same line is ignored, except @code{\R} which works as usual. Anything 7815before @code{\c} on the same line will be appended to the current partial 7816output line. The next non-command line after an interrupted line counts 7817as a new input line. 7818 7819The visual results depend on whether no-fill mode is active. 7820 7821@itemize @bullet 7822@item 7823@cindex @code{\c}, and no-fill mode 7824@cindex no-fill mode, and @code{\c} 7825@cindex mode, no-fill, and @code{\c} 7826If no-fill mode is active (using the @code{nf} request), the next input 7827text line after @code{\c} will be handled as a continuation of the same 7828input text line. 7829 7830@Example 7831.nf 7832This is a \c 7833test. 7834 @result{} This is a test. 7835@endExample 7836 7837@item 7838@cindex @code{\c}, and fill mode 7839@cindex fill mode, and @code{\c} 7840@cindex mode, fill, and @code{\c} 7841If fill mode is active (using the @code{fi} request), a word interrupted 7842with @code{\c} will be continued with the text on the next input text line, 7843without an intervening space. 7844 7845@Example 7846This is a te\c 7847st. 7848 @result{} This is a test. 7849@endExample 7850@end itemize 7851 7852Note that an intervening control line which causes a break is stronger 7853than @code{\c}, flushing out the current partial line in the usual way. 7854 7855@cindex interrupted line register (@code{.int}) 7856The @code{.int} register contains a positive value 7857if the last output line was interrupted with @code{\c}; this is 7858associated with the current environment (@pxref{Environments}). 7859 7860@endDefesc 7861 7862@c ===================================================================== 7863 7864@node Page Layout, Page Control, Line Control, gtroff Reference 7865@section Page Layout 7866@cindex page layout 7867@cindex layout, page 7868 7869@code{gtroff} provides some very primitive operations for controlling 7870page layout. 7871 7872@DefreqList {pl, [@Var{length}]} 7873@DefreqItem {pl, @t{+}@Var{length}} 7874@DefreqItem {pl, @t{-}@Var{length}} 7875@DefregListEnd {.p} 7876@cindex page length (@code{pl}) 7877@cindex length of page (@code{pl}) 7878Set the @dfn{page length} to @var{length} (or increment or decrement 7879the current value by @var{length}). This is the length of the 7880physical output page. The default scaling indicator is @samp{v}. 7881 7882@cindex page length register (@code{.p}) 7883The current setting can be found in the read-only number register 7884@samp{.p}. 7885 7886@cindex top margin 7887@cindex margin, top 7888@cindex bottom margin 7889@cindex margin, bottom 7890Note that this only specifies the size of the page, not the top and 7891bottom margins. Those are not set by @code{gtroff} directly. 7892@xref{Traps}, for further information on how to do this. 7893 7894Negative @code{pl} values are possible also, but not very useful: No 7895trap is sprung, and each line is output on a single page (thus 7896suppressing all vertical spacing). 7897 7898If no argument or an invalid argument is given, @code{pl} sets the page 7899length to 11@dmn{i}. 7900@endDefreq 7901 7902@cindex headers 7903@cindex footers 7904@cindex titles 7905@code{gtroff} provides several operations which help in setting up top 7906and bottom titles (or headers and footers). 7907 7908@Defreq {tl, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}} 7909@cindex title line (@code{tl}) 7910@cindex three-part title (@code{tl}) 7911@cindex page number character (@code{%}) 7912Print a @dfn{title line}. It consists of three parts: a left 7913justified portion, a centered portion, and a right justified portion. 7914The argument separator @samp{'} can be replaced with any character not 7915occurring in the title line. The @samp{%} character is replaced with 7916the current page number. This character can be changed with the 7917@code{pc} request (see below). 7918 7919Without argument, @code{tl} is ignored. 7920 7921Some notes: 7922 7923@itemize @bullet 7924@item 7925A title line is not restricted to the top or bottom of a page. 7926 7927@item 7928@code{tl} prints the title line immediately, ignoring a partially filled 7929line (which stays untouched). 7930 7931@item 7932It is not an error to omit closing delimiters. For example, 7933@w{@samp{.tl /foo}} is equivalent to @w{@samp{.tl /foo///}}: It prints a 7934title line with the left justified word @samp{foo}; the centered and 7935right justfied parts are empty. 7936 7937@item 7938@code{tl} accepts the same parameter delimiting characters as the 7939@code{\A} escape; see @ref{Escapes}. 7940@end itemize 7941@endDefreq 7942 7943@DefreqList {lt, [@Var{length}]} 7944@DefreqItem {lt, @t{+}@Var{length}} 7945@DefreqItem {lt, @t{-}@Var{length}} 7946@DefregListEnd {.lt} 7947@cindex length of title line (@code{lt}) 7948@cindex title line, length (@code{lt}) 7949@cindex title line length register (@code{.lt}) 7950The title line is printed using its own line length, which is 7951specified (or incremented or decremented) with the @code{lt} request. 7952Initially, the title line length is set to 6.5@dmn{i}. If a negative 7953line length is specified (which is not allowed), @code{gtroff} emits a 7954warning of type @samp{range} and sets the title line length to zero. 7955The default scaling indicator is @samp{m}. If @code{lt} is called 7956without an argument, the title length is reset to the previous value 7957before the last call to @code{lt}. 7958 7959The current setting of this is available in the @code{.lt} read-only 7960number register; it is associated with the current environment 7961(@pxref{Environments}). 7962 7963@endDefreq 7964 7965@DefreqList {pn, page} 7966@DefreqItem {pn, @t{+}@Var{page}} 7967@DefreqItem {pn, @t{-}@Var{page}} 7968@DefregListEnd {.pn} 7969@cindex page number (@code{pn}) 7970@cindex number, page (@code{pn}) 7971Change (increase or decrease) the page number of the @emph{next} page. 7972The only argument is the page number; the request is ignored without a 7973parameter. 7974 7975The read-only number register @code{.pn} contains the number of the next 7976page: either the value set by a @code{pn} request, or the number of the 7977current page plus@tie{}1. 7978@endDefreq 7979 7980@Defreg {%} 7981@cindex page number register (@code{%}) 7982A read-write register holding the current page number. 7983@endDefreg 7984 7985@Defreq {pc, [@Var{char}]} 7986@cindex changing the page number character (@code{pc}) 7987@cindex page number character, changing (@code{pc}) 7988@vindex % 7989Change the page number character (used by the @code{tl} request) to a 7990different character. With no argument, this mechanism is disabled. 7991Note that this doesn't affect the number register@tie{}@code{%}. 7992@endDefreq 7993 7994@xref{Traps}. 7995 7996 7997@c ===================================================================== 7998 7999@node Page Control, Fonts and Symbols, Page Layout, gtroff Reference 8000@section Page Control 8001@cindex page control 8002@cindex control, page 8003 8004@DefreqList {bp, [@Var{page}]} 8005@DefreqItem {bp, @t{+}@Var{page}} 8006@DefreqListEnd {bp, @t{-}@Var{page}} 8007@cindex new page (@code{bp}) 8008@cindex page, new (@code{bp}) 8009Stop processing the current page and move to the next page. This 8010request causes a break. It can also take an argument to set 8011(increase, decrease) the page number of the next page. The only 8012difference between @code{bp} and @code{pn} is that @code{pn} does not 8013cause a break or actually eject a page. 8014 8015@Example 8016.de newpage \" define macro 8017'bp \" begin page 8018'sp .5i \" vertical space 8019.tl 'left top'center top'right top' \" title 8020'sp .3i \" vertical space 8021.. \" end macro 8022@endExample 8023 8024@cindex @code{bp} request, and top-level diversion 8025@cindex top-level diversion, and @code{bp} 8026@cindex diversion, top-level, and @code{bp} 8027@code{bp} has no effect if not called within the top-level diversion 8028(@pxref{Diversions}). 8029 8030The number register @code{.pe} is set to@tie{}1 while @code{bp} is 8031active. @xref{Page Location Traps}. 8032@endDefreq 8033 8034@Defreq {ne, [@Var{space}]} 8035@cindex orphan lines, preventing with @code{ne} 8036@cindex conditional page break (@code{ne}) 8037@cindex page break, conditional (@code{ne}) 8038It is often necessary to force a certain amount of space before a new 8039page occurs. This is most useful to make sure that there is not a 8040single @dfn{orphan} line left at the bottom of a page. The @code{ne} 8041request ensures that there is a certain distance, specified by the 8042first argument, before the next page is triggered (see @ref{Traps}, 8043for further information). The default scaling indicator for @code{ne} 8044is @samp{v}; the default value of @var{space} is@tie{}1@dmn{v} if no 8045argument is given. 8046 8047For example, to make sure that no fewer than 2@tie{}lines get orphaned, 8048do the following before each paragraph: 8049 8050@Example 8051.ne 2 8052text text text 8053@endExample 8054 8055@code{ne} will then automatically cause a page break if there is space 8056for one line only. 8057@endDefreq 8058 8059@DefreqList {sv, [@Var{space}]} 8060@DefreqListEnd {os, } 8061@cindex @code{ne} request, comparison with @code{sv} 8062@code{sv} is similar to the @code{ne} request; it reserves the 8063specified amount of vertical space. If the desired amount of space 8064exists before the next trap (or the bottom page boundary if no trap is 8065set), the space is output immediately (ignoring a partially filled line 8066which stays untouched). If there is not enough space, it is stored for 8067later output via the @code{os} request. The default value is@tie{}1@dmn{v} 8068if no argument is given; the default scaling indicator is @samp{v}. 8069 8070@cindex @code{sv} request, and no-space mode 8071@cindex @code{os} request, and no-space mode 8072Both @code{sv} and @code{os} ignore no-space mode. While the @code{sv} 8073request allows negative values for @var{space}, @code{os} will ignore 8074them. 8075@endDefreq 8076 8077@Defreg {nl} 8078This register contains the current vertical position. If the vertical 8079position is zero and the top of page transition hasn't happened yet, 8080@code{nl} is set to negative value. @code{gtroff} itself does this at 8081the very beginning of a document before anything has been printed, but 8082the main usage is to plant a header trap on a page if this page has 8083already started. 8084 8085Consider the following: 8086 8087@Example 8088.de xxx 8089. sp 8090. tl ''Header'' 8091. sp 8092.. 8093. 8094First page. 8095.bp 8096.wh 0 xxx 8097.nr nl (-1) 8098Second page. 8099@endExample 8100 8101@noindent 8102Result: 8103 8104@Example 8105First page. 8106 8107... 8108 8109 Header 8110 8111Second page. 8112 8113... 8114@endExample 8115 8116@noindent 8117Without resetting @code{nl} to a negative value, the just planted trap 8118would be active beginning with the @emph{next} page, not the current 8119one. 8120 8121@xref{Diversions}, for a comparison with the @code{.h} and @code{.d} 8122registers. 8123@endDefreg 8124 8125@c ===================================================================== 8126 8127@node Fonts and Symbols, Sizes, Page Control, gtroff Reference 8128@section Fonts and Symbols 8129@cindex fonts 8130 8131@code{gtroff} can switch fonts at any point in the text. 8132 8133The basic set of fonts is @samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 8134These are Times Roman, Italic, Bold, and Bold Italic. For non-TTY 8135devices, there is also at least one symbol font which contains various 8136special symbols (Greek, mathematics). 8137 8138@menu 8139* Changing Fonts:: 8140* Font Families:: 8141* Font Positions:: 8142* Using Symbols:: 8143* Special Fonts:: 8144* Artificial Fonts:: 8145* Ligatures and Kerning:: 8146@end menu 8147 8148@c --------------------------------------------------------------------- 8149 8150@node Changing Fonts, Font Families, Fonts and Symbols, Fonts and Symbols 8151@subsection Changing Fonts 8152@cindex fonts 8153 8154@DefreqList {ft, [@Var{font}]} 8155@DefescItem {\\f, , f, } 8156@DefescItem {\\f, @lparen{}, fn, } 8157@DefescListEnd {\\f, @lbrack{}, font, @rbrack} 8158@cindex changing fonts (@code{ft}, @code{\f}) 8159@cindex fonts, changing (@code{ft}, @code{\f}) 8160@cindex @code{sty} request, and changing fonts 8161@cindex @code{fam} request, and changing fonts 8162@cindex @code{\F}, and changing fonts 8163@kindex styles 8164@kindex family 8165@pindex DESC 8166The @code{ft} request and the @code{\f} escape change the current font 8167to @var{font} (one-character name@tie{}@var{f}, two-character name 8168@var{fn}). 8169 8170If @var{font} is a style name (as set with the @code{sty} request or 8171with the @code{styles} command in the @file{DESC} file), use it within 8172the current font family (as set with the @code{fam} request, @code{\F} 8173escape, or with the @code{family} command in the @file{DESC} file). 8174 8175@cindex previous font (@code{ft}, @code{\f[]}, @code{\fP}) 8176@cindex font, previous (@code{ft}, @code{\f[]}, @code{\fP}) 8177With no argument or using @samp{P} as an argument, @code{.ft} switches 8178to the previous font. Use @code{\f[]} to do this with the escape. The 8179old syntax forms @code{\fP} or @code{\f[P]} are also supported. 8180 8181Fonts are generally specified as upper-case strings, which are usually 81821@tie{}to 4 characters representing an abbreviation or acronym of the 8183font name. This is no limitation, just a convention. 8184 8185The example below produces two identical lines. 8186 8187@Example 8188eggs, bacon, 8189.ft B 8190spam 8191.ft 8192and sausage. 8193 8194eggs, bacon, \fBspam\fP and sausage. 8195@endExample 8196 8197Note that @code{\f} doesn't produce an input token in @code{gtroff}. 8198As a consequence, it can be used in requests like @code{mc} (which 8199expects a single character as an argument) to change the font on 8200the fly: 8201 8202@Example 8203.mc \f[I]x\f[] 8204@endExample 8205 8206@xref{Font Positions}, for an alternative syntax. 8207@endDefreq 8208 8209@Defreq {ftr, f [@Var{g}]} 8210@cindex @code{ft} request, and font translations 8211@cindex @code{ul} request, and font translations 8212@cindex @code{bd} request, and font translations 8213@cindex @code{\f}, and font translations 8214@cindex @code{cs} request, and font translations 8215@cindex @code{tkf} request, and font translations 8216@cindex @code{special} request, and font translations 8217@cindex @code{fspecial} request, and font translations 8218@cindex @code{fp} request, and font translations 8219@cindex @code{sty} request, and font translations 8220Translate font@tie{}@var{f} to font@tie{}@var{g}. Whenever a font 8221named@tie{}@var{f} is referred to in a @code{\f} escape sequence, or in the 8222@code{ft}, @code{ul}, @code{bd}, @code{cs}, @code{tkf}, 8223@code{special}, @code{fspecial}, @code{fp}, or @code{sty} requests, 8224font@tie{}@var{g} is used. If @var{g} is missing or equal to@tie{}@var{f} 8225the translation is undone. 8226@endDefreq 8227 8228@c --------------------------------------------------------------------- 8229 8230@node Font Families, Font Positions, Changing Fonts, Fonts and Symbols 8231@subsection Font Families 8232@cindex font families 8233@cindex families, font 8234@cindex font styles 8235@cindex styles, font 8236 8237Due to the variety of fonts available, @code{gtroff} has added the 8238concept of @dfn{font families} and @dfn{font styles}. The fonts are 8239specified as the concatenation of the font family and style. Specifying 8240a font without the family part causes @code{gtroff} to use that style of 8241the current family. 8242 8243@cindex PostScript fonts 8244@cindex fonts, PostScript 8245Currently, fonts for the devices @option{-Tps}, @option{-Tdvi}, and 8246@option{-Tlbp} are set up to this mechanism. 8247By default, @code{gtroff} uses the Times family with the four styles 8248@samp{R}, @samp{I}, @samp{B}, and @samp{BI}. 8249 8250This way, it is possible to use the basic four fonts and to select a 8251different font family on the command line (@pxref{Groff Options}). 8252 8253@DefreqList {fam, [@Var{family}]} 8254@DefregItem {.fam} 8255@DefescItem {\\F, , f, } 8256@DefescItem {\\F, @lparen{}, fm, } 8257@DefescItem {\\F, @lbrack{}, family, @rbrack} 8258@DefregListEnd {.fn} 8259@cindex changing font family (@code{fam}, @code{\F}) 8260@cindex font family, changing (@code{fam}, @code{\F}) 8261Switch font family to @var{family} (one-character name@tie{}@var{f}, 8262two-character name @var{fm}). If no argument is given, switch 8263back to the previous font family. Use @code{\F[]} to do this with the 8264escape. Note that @code{\FP} doesn't work; it selects font family 8265@samp{P} instead. 8266 8267The value at start-up is @samp{T}. 8268The current font family is available in the read-only number register 8269@samp{.fam} (this is a string-valued register); it is associated with 8270the current environment. 8271 8272@Example 8273spam, 8274.fam H \" helvetica family 8275spam, \" used font is family H + style R = HR 8276.ft B \" family H + style B = font HB 8277spam, 8278.fam T \" times family 8279spam, \" used font is family T + style B = TB 8280.ft AR \" font AR (not a style) 8281baked beans, 8282.ft R \" family T + style R = font TR 8283and spam. 8284@endExample 8285 8286Note that @code{\F} doesn't produce an input token in @code{gtroff}. 8287As a consequence, it can be used in requests like @code{mc} (which 8288expects a single character as an argument) to change the font family on 8289the fly: 8290 8291@Example 8292.mc \F[P]x\F[] 8293@endExample 8294 8295The @samp{.fn} register contains the current @dfn{real font name} 8296of the current font. 8297This is a string-valued register. 8298If the current font is a style, the value of @code{\n[.fn]} 8299is the proper concatenation of family and style name. 8300@endDefreq 8301 8302@Defreq {sty, n style} 8303@cindex changing font style (@code{sty}) 8304@cindex font style, changing (@code{sty}) 8305@cindex @code{cs} request, and font styles 8306@cindex @code{bd} request, and font styles 8307@cindex @code{tkf} request, and font styles 8308@cindex @code{uf} request, and font styles 8309@cindex @code{fspecial} request, and font styles 8310Associate @var{style} with font position@tie{}@var{n}. A font position 8311can be associated either with a font or with a style. The current 8312font is the index of a font position and so is also either a font or a 8313style. If it is a style, the font that is actually used is the font 8314which name is the concatenation of the name of the current 8315family and the name of the current style. For example, if the current 8316font is@tie{}1 and font position@tie{}1 is associated with style 8317@samp{R} and the current font family is @samp{T}, then font 8318@samp{TR} will be used. If the current font is not a style, then the 8319current family is ignored. If the requests @code{cs}, @code{bd}, 8320@code{tkf}, @code{uf}, or @code{fspecial} are applied to a style, 8321they will instead be applied to the member of the current family 8322corresponding to that style. 8323 8324@var{n}@tie{}must be a non-negative integer value. 8325 8326@pindex DESC 8327@kindex styles 8328The default family can be set with the @option{-f} option 8329(@pxref{Groff Options}). The @code{styles} command in the @file{DESC} 8330file controls which font positions (if any) are initially associated 8331with styles rather than fonts. For example, the default setting for 8332@sc{PostScript} fonts 8333 8334@Example 8335styles R I B BI 8336@endExample 8337 8338@noindent 8339is equivalent to 8340 8341@Example 8342.sty 1 R 8343.sty 2 I 8344.sty 3 B 8345.sty 4 BI 8346@endExample 8347 8348@code{fam} and @code{\F} always check whether the current font position 8349is valid; this can give surprising results if the current font position is 8350associated with a style. 8351 8352In the following example, we want to access the @sc{PostScript} font 8353@code{FooBar} from the font family @code{Foo}: 8354 8355@Example 8356.sty \n[.fp] Bar 8357.fam Foo 8358 @result{} warning: can't find font `FooR' 8359@endExample 8360 8361@noindent 8362The default font position at start-up is@tie{}1; for the 8363@sc{PostScript} device, this is associated with style @samp{R}, so 8364@code{gtroff} tries to open @code{FooR}. 8365 8366A solution to this problem is to use a dummy font like the following: 8367 8368@Example 8369.fp 0 dummy TR \" set up dummy font at position 0 8370.sty \n[.fp] Bar \" register style `Bar' 8371.ft 0 \" switch to font at position 0 8372.fam Foo \" activate family `Foo' 8373.ft Bar \" switch to font `FooBar' 8374@endExample 8375 8376@xref{Font Positions}. 8377@endDefreq 8378 8379@c --------------------------------------------------------------------- 8380 8381@node Font Positions, Using Symbols, Font Families, Fonts and Symbols 8382@subsection Font Positions 8383@cindex font positions 8384@cindex positions, font 8385 8386For the sake of old phototypesetters and compatibility with old versions 8387of @code{troff}, @code{gtroff} has the concept of font @dfn{positions}, 8388on which various fonts are mounted. 8389 8390@DefreqList {fp, pos font [@Var{external-name}]} 8391@DefregItem {.f} 8392@DefregListEnd {.fp} 8393@cindex mounting font (@code{fp}) 8394@cindex font, mounting (@code{fp}) 8395Mount font @var{font} at position @var{pos} (which must be a 8396non-negative integer). This numeric position can then be referred to 8397with font changing commands. When @code{gtroff} starts it is using 8398font position@tie{}1 (which must exist; position@tie{}0 is unused 8399usually at start-up). 8400 8401@cindex font position register (@code{.f}) 8402The current font in use, as a font position, is available in the 8403read-only number register @samp{.f}. This can be useful to remember the 8404current font for later recall. It is associated with the current 8405environment (@pxref{Environments}). 8406 8407@Example 8408.nr save-font \n[.f] 8409.ft B 8410... text text text ... 8411.ft \n[save-font] 8412@endExample 8413 8414@cindex next free font position register (@code{.fp}) 8415The number of the next free font position is available in the read-only 8416number register @samp{.fp}. This is useful when mounting a new font, 8417like so: 8418 8419@Example 8420.fp \n[.fp] NEATOFONT 8421@endExample 8422 8423@pindex DESC@r{, and font mounting} 8424Fonts not listed in the @file{DESC} file are automatically mounted on 8425the next available font position when they are referenced. If a font 8426is to be mounted explicitly with the @code{fp} request on an unused 8427font position, it should be mounted on the first unused font position, 8428which can be found in the @code{.fp} register. Although @code{gtroff} 8429does not enforce this strictly, it is not allowed to mount a font at a 8430position whose number is much greater (approx.@: 1000 positions) than 8431that of any currently used position. 8432 8433The @code{fp} request has an optional third argument. This argument 8434gives the external name of the font, which is used for finding the font 8435description file. The second argument gives the internal name of the 8436font which is used to refer to the font in @code{gtroff} after it has 8437been mounted. If there is no third argument then the internal name is 8438used as the external name. This feature makes it possible to use 8439fonts with long names in compatibility mode. 8440@endDefreq 8441 8442Both the @code{ft} request and the @code{\f} escape have alternative 8443syntax forms to access font positions. 8444 8445@DefreqList {ft, nnn} 8446@DefescItem {\\f, , n, } 8447@DefescItem {\\f, @lparen{}, nn, } 8448@DefescListEnd {\\f, @lbrack{}, nnn, @rbrack} 8449@cindex changing font position (@code{\f}) 8450@cindex font position, changing (@code{\f}) 8451@cindex @code{sty} request, and font positions 8452@cindex @code{fam} request, and font positions 8453@cindex @code{\F}, and font positions 8454@kindex styles 8455@kindex family 8456@pindex DESC 8457Change the current font position to @var{nnn} (one-digit 8458position@tie{}@var{n}, two-digit position @var{nn}), which must be a 8459non-negative integer. 8460 8461If @var{nnn} is associated with a style (as set with the @code{sty} 8462request or with the @code{styles} command in the @file{DESC} file), use 8463it within the current font family (as set with the @code{fam} request, 8464the @code{\F} escape, or with the @code{family} command in the @file{DESC} 8465file). 8466 8467@Example 8468this is font 1 8469.ft 2 8470this is font 2 8471.ft \" switch back to font 1 8472.ft 3 8473this is font 3 8474.ft 8475this is font 1 again 8476@endExample 8477 8478@xref{Changing Fonts}, for the standard syntax form. 8479@endDefreq 8480 8481@c --------------------------------------------------------------------- 8482 8483@node Using Symbols, Special Fonts, Font Positions, Fonts and Symbols 8484@subsection Using Symbols 8485@cindex using symbols 8486@cindex symbols, using 8487 8488@cindex glyph 8489@cindex character 8490@cindex ligature 8491A @dfn{glyph} is a graphical representation of a @dfn{character}. 8492While a character is an abstract entity containing semantic 8493information, a glyph is something which can be actually seen on screen 8494or paper. It is possible that a character has multiple glyph 8495representation forms (for example, the character `A' can be either 8496written in a roman or an italic font, yielding two different glyphs); 8497sometimes more than one character maps to a single glyph (this is a 8498@dfn{ligature} -- the most common is `fi'). 8499 8500@cindex symbol 8501@cindex special fonts 8502@kindex fonts 8503@pindex DESC 8504@cindex @code{special} request, and glyph search order 8505@cindex @code{fspecial} request, and glyph search order 8506A @dfn{symbol} is simply a named glyph. Within @code{gtroff}, all 8507glyph names of a particular font are defined in its font file. If the 8508user requests a glyph not available in this font, @code{gtroff} looks 8509up an ordered list of @dfn{special fonts}. By default, the 8510@sc{PostScript} output device supports the two special fonts @samp{SS} 8511(slanted symbols) and @samp{S} (symbols) (the former is looked up 8512before the latter). Other output devices use different names for 8513special fonts. Fonts mounted with the @code{fonts} keyword in the 8514@file{DESC} file are globally available. To install additional 8515special fonts locally (i.e.@: for a particular font), use the 8516@code{fspecial} request. 8517 8518Here the exact rules how @code{gtroff} searches a given symbol: 8519 8520@itemize @bullet 8521@item 8522If the symbol has been defined with the @code{char} request, use it. 8523This hides a symbol with the same name in the current font. 8524 8525@item 8526Check the current font. 8527 8528@item 8529If the symbol has been defined with the @code{fchar} request, use it. 8530 8531@item 8532Check whether the current font has a font-specific list of special fonts; 8533test all fonts in the order of appearance in the last @code{fspecial} 8534call if appropriate. 8535 8536@item 8537If the symbol has been defined with the @code{fschar} request for the 8538current font, use it. 8539 8540@item 8541Check all fonts in the order of appearance in the last @code{special} 8542call. 8543 8544@item 8545If the symbol has been defined with the @code{schar} request, use it. 8546 8547@item 8548As a last resort, consult all fonts loaded up to now for special fonts 8549and check them, starting with the lowest font number. Note that this can 8550sometimes lead to surprising results since the @code{fonts} line in the 8551@file{DESC} file often contains empty positions which are filled later 8552on. For example, consider the following: 8553 8554@Example 8555fonts 3 0 0 FOO 8556@endExample 8557 8558@noindent 8559This mounts font @code{foo} at font position@tie{}3. We assume that 8560@code{FOO} is a special font, containing glyph @code{foo}, 8561and that no font has been loaded yet. The line 8562 8563@Example 8564.fspecial BAR BAZ 8565@endExample 8566 8567@noindent 8568makes font @code{BAZ} special only if font @code{BAR} is active. We 8569further assume that @code{BAZ} is really a special font, i.e., the font 8570description file contains the @code{special} keyword, and that it 8571also contains glyph @code{foo} with a special shape fitting to font 8572@code{BAR}. After executing @code{fspecial}, font @code{BAR} is loaded at 8573font position@tie{}1, and @code{BAZ} at position@tie{}2. 8574 8575We now switch to a new font @code{XXX}, trying to access glyph @code{foo} 8576which is assumed to be missing. There are neither font-specific special 8577fonts for @code{XXX} nor any other fonts made special with the 8578@code{special} request, so @code{gtroff} starts the search for special 8579fonts in the list of already mounted fonts, with increasing font 8580positions. Consequently, it finds @code{BAZ} before @code{FOO} even for 8581@code{XXX} which is not the intended behaviour. 8582@end itemize 8583 8584@xref{Font Files}, and @ref{Special Fonts}, for more details. 8585 8586@cindex list of available glyphs (@cite{groff_char(7)} man page) 8587@cindex available glyphs, list (@cite{groff_char(7)} man page) 8588@cindex glyphs, available, list (@cite{groff_char(7)} man page) 8589The list of available symbols is device dependent; see the 8590@cite{groff_char(7)} man page for a complete list of all glyphs. For 8591example, say 8592 8593@Example 8594man -Tdvi groff_char > groff_char.dvi 8595@endExample 8596 8597@noindent 8598for a list using the default DVI fonts (not all versions of the 8599@code{man} program support the @option{-T} option). If you want to 8600use an additional macro package to change the used fonts, @code{groff} 8601must be called directly: 8602 8603@Example 8604groff -Tdvi -mec -man groff_char.7 > groff_char.dvi 8605@endExample 8606 8607@cindex composite glyph names 8608@cindex glyph names, composite 8609@cindex groff glyph list (GGL) 8610@cindex GGL (groff glyph list) 8611@cindex adobe glyph list (AGL) 8612@cindex AGL (adobe glyph list) 8613Glyph names not listed in groff_char(7) are derived algorithmically, 8614using a simplified version of the Adobe Glyph List (AGL) algorithm 8615described in 8616@uref{http://partners.adobe.com/asn/developer/typeforum/unicodegn.html}. 8617The (frozen) set of glyph names which can't be derived algorithmically 8618is called @dfn{groff glyph list (GGL)}. 8619 8620@itemize @bullet 8621@item 8622A glyph for Unicode character U+@var{XXXX}[@var{X}[@var{X}]] which is 8623not a composite character will be named 8624@code{u@var{XXXX}@r{[}@var{X}@r{[}@var{X}@r{]]}}. @var{X} must be an 8625uppercase hexadecimal digit. Examples: @code{u1234}, @code{u008E}, 8626@code{u12DB8}. The largest Unicode value is 0x10FFFF. There must be at 8627least four @code{X} digits; if necessary, add leading zeroes (after the 8628@samp{u}). No zero padding is allowed for character codes greater than 86290xFFFF. Surrogates (i.e., Unicode values greater than 0xFFFF 8630represented with character codes from the surrogate area U+D800-U+DFFF) 8631are not allowed too. 8632 8633@item 8634A glyph representing more than a single input character will be named 8635 8636@display 8637@samp{u} @var{component1} @samp{_} @var{component2} @samp{_} @var{component3} @dots{} 8638@end display 8639 8640@noindent 8641Example: @code{u0045_0302_0301}. 8642 8643For simplicity, all Unicode characters which are composites must be 8644decomposed maximally (this is normalization form@tie{}D in the Unicode 8645standard); for example, @code{u00CA_0301} is not a valid glyph name 8646since U+00CA (@sc{latin capital letter e with circumflex}) can be 8647further decomposed into U+0045 (@sc{latin capital letter e}) and U+0302 8648(@sc{combining circumflex accent}). @code{u0045_0302_0301} is thus the 8649glyph name for U+1EBE, @sc{latin capital letter e with circumflex and 8650acute}. 8651 8652@item 8653groff maintains a table to decompose all algorithmically derived glyph 8654names which are composites itself. For example, @code{u0100} (@sc{latin 8655letter a with macron}) will be automatically decomposed into 8656@code{u0041_0304}. Additionally, a glyph name of the GGL is preferred 8657to an algorithmically derived glyph name; groff also automatically does 8658the mapping. Example: The glyph @code{u0045_0302} will be mapped to 8659@code{^E}. 8660 8661@item 8662glyph names of the GGL can't be used in composite glyph names; for 8663example, @code{^E_u0301} is invalid. 8664@end itemize 8665 8666@DefescList {\\, @lparen{}, nm, } 8667@DefescItem {\\, @lbrack{}, name, @rbrack} 8668@DefescListEnd {\\, @lbrack{}, component1 component2 @dots{}, @rbrack} 8669Insert a symbol @var{name} (two-character name @var{nm}) or a composite 8670glyph with component glyphs @var{component1}, @var{component2}, 8671@enddots{} There is no special syntax for one-character names -- the 8672natural form @samp{\@var{n}} would collide with escapes.@footnote{Note 8673that a one-character symbol is not the same as an input character, i.e., 8674the character @code{a} is not the same as @code{\[a]}. By default, 8675@code{groff} defines only a single one-character symbol, @code{\[-]}; it 8676is usually accessed as @code{\-}. On the other hand, @code{gtroff} has 8677the special feature that @code{\[char@var{XXX}]} is the same as the 8678input character with character code @var{XXX}. For example, 8679@code{\[char97]} is identical to the letter @code{a} if @acronym{ASCII} 8680encoding is active.} 8681 8682If @var{name} is undefined, a warning of type @samp{char} is generated, 8683and the escape is ignored. @xref{Debugging}, for information about 8684warnings. 8685 8686groff resolves @code{\[...]} with more than a single component as 8687follows: 8688 8689@itemize @bullet 8690@item 8691Any component which is found in the GGL will be converted to the 8692@code{u@var{XXXX}} form. 8693 8694@item 8695Any component @code{u@var{XXXX}} which is found in the list of 8696decomposable glyphs will be decomposed. 8697 8698@item 8699The resulting elements are then concatenated with @samp{_} inbetween, 8700dropping the leading @samp{u} in all elements but the first. 8701@end itemize 8702 8703No check for the existence of any component (similar to @code{tr} 8704request) will be done. 8705 8706Examples: 8707 8708@table @code 8709@item \[A ho] 8710@samp{A} maps to @code{u0041}, @samp{ho} maps to @code{u02DB}, thus the 8711final glyph name would be @code{u0041_02DB}. Note this is not the 8712expected result: The ogonek glyph @samp{ho} is a spacing ogonek, but for 8713a proper composite a non-spacing ogonek (U+0328) is necessary. Looking 8714into the file @file{composite.tmac} one can find @w{@samp{.composite ho 8715u0328}} which changes the mapping of @samp{ho} while a composite glyph 8716name is constructed, causing the final glyph name to be 8717@code{u0041_0328}. 8718 8719@item \[^E u0301] 8720@itemx \[^E aa] 8721@itemx \[E a^ aa] 8722@itemx \[E ^ '] 8723@samp{^E} maps to @code{u0045_0302}, thus the final glyph name is 8724@code{u0045_0302_0301} in all forms (assuming proper calls of the 8725@code{composite} request). 8726@end table 8727 8728It is not possible to define glyphs with names like @w{@samp{A ho}} 8729within a groff font file. This is not really a limitation; instead, you 8730have to define @code{u0041_0328}. 8731@endDefesc 8732 8733@Defesc {\\C, ', xxx, '} 8734@cindex named character (@code{\C}) 8735@cindex character, named (@code{\C}) 8736Typeset the glyph named @var{xxx}.@footnote{@code{\C} is actually a 8737misnomer since it accesses an output glyph.} Normally it is more 8738convenient to use @code{\[@var{xxx}]}, but @code{\C} has the advantage 8739that it is compatible with newer versions of @acronym{AT&T} 8740@code{troff} and is available in compatibility mode. 8741@endDefesc 8742 8743@Defreq {composite, from to} 8744@pindex composite.tmac 8745Map glyph name @var{from} to glyph name @var{to} if it is used in 8746@code{\[...]} with more than one component. See above for examples. 8747 8748This mapping is based on glyph names only; no check for the existence of 8749either glyph is done. 8750 8751A set of default mappings for many accents can be found in the file 8752@file{composite.tmac} which is loaded at start-up. 8753@endDefreq 8754 8755@Defesc {\\N, ', n, '} 8756@cindex numbered glyph (@code{\N}) 8757@cindex glyph, numbered (@code{\N}) 8758@cindex @code{char} request, used with @code{\N} 8759@cindex Unicode 8760Typeset the glyph with code@tie{}@var{n} in the current font 8761(@code{n}@tie{}is @strong{not} the input character code). The 8762number @var{n}@tie{}can be any non-negative decimal integer. Most devices 8763only have glyphs with codes between 0 and@tie{}255; the Unicode 8764output device uses codes in the range 0--65535. If the current 8765font does not contain a glyph with that code, special fonts are 8766@emph{not} searched. The @code{\N} escape sequence can be 8767conveniently used in conjunction with the @code{char} request: 8768 8769@Example 8770.char \[phone] \f[ZD]\N'37' 8771@endExample 8772 8773@noindent 8774@pindex DESC 8775@cindex unnamed glyphs 8776@cindex glyphs, unnamed 8777The code of each glyph is given in the fourth column in the font 8778description file after the @code{charset} command. It is possible to 8779include unnamed glyphs in the font description file by using a 8780name of @samp{---}; the @code{\N} escape sequence is the only way to 8781use these. 8782 8783No kerning is applied to glyphs accessed with @code{\N}. 8784@endDefesc 8785 8786Some escape sequences directly map onto special glyphs. 8787 8788@Defesc {\\', , , } 8789This is a backslash followed by the apostrophe character, @acronym{ASCII} 8790character @code{0x27} (@acronym{EBCDIC} character @code{0x7D}). The same 8791as @code{\[aa]}, the acute accent. 8792@endDefesc 8793 8794@Defesc {\\`, , , } 8795This is a backslash followed by @acronym{ASCII} character @code{0x60} 8796(@acronym{EBCDIC} character @code{0x79} usually). The same as 8797@code{\[ga]}, the grave accent. 8798@endDefesc 8799 8800@Defesc {\\-, , , } 8801This is the same as @code{\[-]}, the minus sign in the current font. 8802@endDefesc 8803 8804@Defreq {cflags, n c1 c2 @dots{}} 8805@cindex glyph properties (@code{cflags}) 8806@cindex character properties (@code{cflags}) 8807@cindex properties of glyphs (@code{cflags}) 8808@cindex properties of characters (@code{cflags}) 8809Input characters and symbols have certain properties associated 8810with it.@footnote{Note that the output glyphs themselves don't have 8811such properties. For @code{gtroff}, a glyph is a numbered box with 8812a given width, depth, and height, nothing else. All manipulations 8813with the @code{cflags} request work on the input level.} These 8814properties can be modified with the @code{cflags} request. The 8815first argument is the sum of the desired flags and the remaining 8816arguments are the characters or symbols to have those properties. 8817It is possible to omit the spaces between the characters or symbols. 8818 8819@table @code 8820@item 1 8821@cindex end-of-sentence characters 8822@cindex characters, end-of-sentence 8823The character ends sentences (initially characters @samp{.?!} have this 8824property). 8825 8826@item 2 8827@cindex hyphenating characters 8828@cindex characters, hyphenation 8829Lines can be broken before the character (initially no characters have 8830this property). 8831 8832@item 4 8833@cindex @code{hy} glyph, and @code{cflags} 8834@cindex @code{em} glyph, and @code{cflags} 8835Lines can be broken after the character (initially the character 8836@samp{-} and the symbols @samp{\[hy]} and @samp{\[em]} have this property). 8837 8838@item 8 8839@cindex overlapping characters 8840@cindex characters, overlapping 8841@cindex @code{ul} glyph, and @code{cflags} 8842@cindex @code{rn} glyph, and @code{cflags} 8843@cindex @code{ru} glyph, and @code{cflags} 8844@cindex @code{radicalex} glyph, and @code{cflags} 8845@cindex @code{sqrtex} glyph, and @code{cflags} 8846The character overlaps horizontally (initially the symbols 8847@samp{\[ul]}, @samp{\[rn]}, @samp{\[ru]}, @samp{\[radicalex}, and 8848@samp{\[sqrtex]} have this property). 8849 8850@item 16 8851@cindex @code{br} glyph, and @code{cflags} 8852The character overlaps vertically (initially symbol @samp{\[br]} has 8853this property). 8854 8855@item 32 8856@cindex transparent characters 8857@cindex character, transparent 8858@cindex @code{"}, at end of sentence 8859@cindex @code{'}, at end of sentence 8860@cindex @code{)}, at end of sentence 8861@cindex @code{]}, at end of sentence 8862@cindex @code{*}, at end of sentence 8863@cindex @code{dg} glyph, at end of sentence 8864@cindex @code{rq} glyph, at end of sentence 8865An end-of-sentence character followed by any number of characters with 8866this property is treated as the end of a sentence if followed by a 8867newline or two spaces; in other words the character is 8868@dfn{transparent} for the purposes of end-of-sentence recognition -- 8869this is the same as having a zero space factor in @TeX{} (initially 8870characters @samp{"')]*} and the symbols @samp{\[dg]} and @samp{\[rq]} have 8871this property). 8872@end table 8873@endDefreq 8874 8875@DefreqList {char, g [@Var{string}]} 8876@DefreqItem {fchar, g [@Var{string}]} 8877@DefreqItem {fschar, f g [@Var{string}]} 8878@DefreqListEnd {schar, g [@Var{string}]} 8879@cindex defining character (@code{char}) 8880@cindex defining fallback character (@code{fchar}, @code{fschar}, @code{schar}) 8881@cindex character, defining (@code{char}) 8882@cindex character, defining fallback (@code{fchar}, @code{fschar}, @code{schar}) 8883@cindex fallback character, defining (@code{fchar}, @code{fschar}, @code{schar}) 8884@cindex creating new characters (@code{char}) 8885@cindex defining symbol (@code{char}) 8886@cindex symbol, defining (@code{char}) 8887@cindex defining glyph (@code{char}) 8888@cindex glyph, defining (@code{char}) 8889@cindex escape character, while defining glyph 8890@cindex character, escape, while defining glyph 8891@cindex @code{tr} request, and glyph definitions 8892@cindex @code{cp} request, and glyph definitions 8893@cindex @code{rc} request, and glyph definitions 8894@cindex @code{lc} request, and glyph definitions 8895@cindex @code{\l}, and glyph definitions 8896@cindex @code{\L}, and glyph definitions 8897@cindex @code{\&}, and glyph definitions 8898@cindex @code{\e}, and glyph definitions 8899@cindex @code{hcode} request, and glyph definitions 8900Define a new glyph@tie{}@var{g} to be @var{string} (which can be 8901empty).@footnote{@code{char} is a misnomer since an output glyph is 8902defined.} Every time glyph@tie{}@var{g} needs to be printed, 8903@var{string} is processed in a temporary environment and the result is 8904wrapped up into a single object. Compatibility mode is turned off and 8905the escape character is set to @samp{\} while @var{string} is being 8906processed. Any emboldening, constant spacing or track kerning is 8907applied to this object rather than to individual characters in 8908@var{string}. 8909 8910A glyph defined by these requests can be used just 8911like a normal glyph provided by the output device. In particular, 8912other characters can be translated to it with the @code{tr} or 8913@code{trin} requests; it can be made the leader character by the 8914@code{lc} request; repeated patterns can be drawn with the glyph 8915using the @code{\l} and @code{\L} escape sequences; words containing 8916the glyph can be hyphenated correctly if the @code{hcode} request 8917is used to give the glyph's symbol a hyphenation code. 8918 8919There is a special anti-recursion feature: Use of @code{g} within 8920the glyph's definition is handled like normal characters and symbols 8921not defined with @code{char}. 8922 8923Note that the @code{tr} and @code{trin} requests take precedence if 8924@code{char} accesses the same symbol. 8925 8926@Example 8927.tr XY 8928X 8929 @result{} Y 8930.char X Z 8931X 8932 @result{} Y 8933.tr XX 8934X 8935 @result{} Z 8936@endExample 8937 8938The @code{fchar} request defines a fallback glyph: 8939@code{gtroff} only checks for glyphs defined with @code{fchar} 8940if it cannot find the glyph in the current font. 8941@code{gtroff} carries out this test before checking special fonts. 8942 8943@code{fschar} defines a fallback glyph for font@tie{}@var{f}: @code{gtroff} 8944checks for glyphs defined with @code{fschar} after the list of fonts 8945declared as font-specific special fonts with the @code{fspecial} request, 8946but before the list of fonts declared as global special fonts with the 8947@code{special} request. 8948 8949Finally, the @code{schar} request defines a global fallback glyph: 8950@code{gtroff} checks for glyphs defined with @code{schar} after the list 8951of fonts declared as global special fonts with the @code{special} request, 8952but before the already mounted special fonts. 8953 8954@xref{Using Symbols}, for a detailed description of the glyph 8955searching mechanism in @code{gtroff}. 8956@endDefreq 8957 8958@DefreqList {rchar, c1 c2 @dots{}} 8959@DefreqListEnd {rfschar, f c1 c2 @dots{}} 8960@cindex removing glyph definition (@code{rchar}, @code{rfschar}) 8961@cindex glyph, removing definition (@code{rchar}, @code{rfschar}) 8962@cindex fallback glyph, removing definition (@code{rchar}, @code{rfschar}) 8963Remove the definitions of glyphs @var{c1}, @var{c2},@tie{}@enddots{} 8964This undoes the effect of a @code{char}, @code{fchar}, or 8965@code{schar} request. 8966 8967It is possible to omit the whitespace between arguments. 8968 8969The request @code{rfschar} removes glyph definitions defined with 8970@code{fschar} for glyph@tie{}f. 8971@endDefreq 8972 8973@xref{Special Characters}. 8974 8975@c --------------------------------------------------------------------- 8976 8977@node Special Fonts, Artificial Fonts, Using Symbols, Fonts and Symbols 8978@subsection Special Fonts 8979@cindex special fonts 8980@cindex fonts, special 8981 8982Special fonts are those that @code{gtroff} searches 8983when it cannot find the requested glyph in the current font. 8984The Symbol font is usually a special font. 8985 8986@code{gtroff} provides the following two requests to add more special 8987fonts. @xref{Using Symbols}, for a detailed description of the glyph 8988searching mechanism in @code{gtroff}. 8989 8990Usually, only non-TTY devices have special fonts. 8991 8992@DefreqList {special, [@Var{s1} @Var{s2} @dots{}]} 8993@DefreqListEnd {fspecial, f [@Var{s1} @Var{s2} @dots{}]} 8994@kindex fonts 8995@pindex DESC 8996Use the @code{special} request to define special fonts. Initially, this 8997list is empty. 8998 8999Use the @code{fspecial} request to designate special fonts only when 9000font@tie{}@var{f} is active. Initially, this list is empty. 9001 9002Previous calls to @code{special} or @code{fspecial} are overwritten; 9003without arguments, the particular list of special fonts is set to empty. 9004Special fonts are searched in the order they appear as arguments. 9005 9006All fonts which appear in a call to @code{special} or @code{fspecial} are 9007loaded. 9008 9009@xref{Using Symbols}, for the exact search order of glyphs. 9010@endDefreq 9011 9012@c --------------------------------------------------------------------- 9013 9014@node Artificial Fonts, Ligatures and Kerning, Special Fonts, Fonts and Symbols 9015@subsection Artificial Fonts 9016@cindex artificial fonts 9017@cindex fonts, artificial 9018 9019There are a number of requests and escapes for artificially creating 9020fonts. These are largely vestiges of the days when output devices 9021did not have a wide variety of fonts, and when @code{nroff} and 9022@code{troff} were separate programs. Most of them are no longer 9023necessary in GNU @code{troff}. Nevertheless, they are supported. 9024 9025@DefescList {\\H, ', height, '} 9026@DefescItem {\\H, ', @t{+}height, '} 9027@DefescItem {\\H, ', @t{-}height, '} 9028@DefregListEnd {.height} 9029@cindex changing the font height (@code{\H}) 9030@cindex font height, changing (@code{\H}) 9031@cindex height, font, changing (@code{\H}) 9032Change (increment, decrement) the height of the current font, but not 9033the width. If @var{height} is zero, restore the original height. 9034Default scaling indicator is @samp{z}. 9035 9036The read-only number register @code{.height} contains the font height as 9037set by @code{\H}. 9038 9039Currently, only the @option{-Tps} device supports this feature. 9040 9041Note that @code{\H} doesn't produce an input token in @code{gtroff}. 9042As a consequence, it can be used in requests like @code{mc} (which 9043expects a single character as an argument) to change the font on 9044the fly: 9045 9046@Example 9047.mc \H'+5z'x\H'0' 9048@endExample 9049 9050In compatibility mode, @code{gtroff} behaves differently: If an 9051increment or decrement is used, it is always taken relative to the 9052current point size and not relative to the previously selected font 9053height. Thus, 9054 9055@Example 9056.cp 1 9057\H'+5'test \H'+5'test 9058@endExample 9059 9060@noindent 9061prints the word @samp{test} twice with the same font height (five 9062points larger than the current font size). 9063@endDefesc 9064 9065@DefescList {\\S, ', slant, '} 9066@DefregListEnd {.slant} 9067@cindex changing the font slant (@code{\S}) 9068@cindex font slant, changing (@code{\S}) 9069@cindex slant, font, changing (@code{\S}) 9070Slant the current font by @var{slant} degrees. Positive values slant 9071to the right. Only integer values are possible. 9072 9073The read-only number register @code{.slant} contains the font slant as 9074set by @code{\S}. 9075 9076Currently, only the @option{-Tps} device supports this feature. 9077 9078Note that @code{\S} doesn't produce an input token in @code{gtroff}. 9079As a consequence, it can be used in requests like @code{mc} (which 9080expects a single character as an argument) to change the font on 9081the fly: 9082 9083@Example 9084.mc \S'20'x\S'0' 9085@endExample 9086 9087This request is incorrectly documented in the original @acronym{UNIX} 9088troff manual; the slant is always set to an absolute value. 9089@endDefesc 9090 9091@Defreq {ul, [@Var{lines}]} 9092@cindex underlining (@code{ul}) 9093The @code{ul} request normally underlines subsequent lines if a TTY 9094output device is used. Otherwise, the lines are printed in italics 9095(only the term `underlined' is used in the following). The single 9096argument is the number of input lines to be underlined; with no 9097argument, the next line is underlined. If @var{lines} is zero or 9098negative, stop the effects of @code{ul} (if it was active). Requests 9099and empty lines do not count for computing the number of underlined 9100input lines, even if they produce some output like @code{tl}. Lines 9101inserted by macros (e.g.@: invoked by a trap) do count. 9102 9103At the beginning of @code{ul}, the current font is stored and the 9104underline font is activated. Within the span of a @code{ul} request, 9105it is possible to change fonts, but after the last line affected by 9106@code{ul} the saved font is restored. 9107 9108This number of lines still to be underlined is associated with the 9109current environment (@pxref{Environments}). The underline font can be 9110changed with the @code{uf} request. 9111 9112@c XXX @xref should be changed to grotty 9113 9114@c @xref{Troff and Nroff Mode}, for a discussion how underlining is 9115@c implemented in for TTY output devices, and which problems can arise. 9116 9117The @code{ul} request does not underline spaces. 9118@endDefreq 9119 9120@Defreq {cu, [@Var{lines}]} 9121@cindex continuous underlining (@code{cu}) 9122@cindex underlining, continuous (@code{cu}) 9123The @code{cu} request is similar to @code{ul} but underlines spaces as 9124well (if a TTY output device is used). 9125@endDefreq 9126 9127@Defreq {uf, font} 9128@cindex underline font (@code{uf}) 9129@cindex font for underlining (@code{uf}) 9130Set the underline font (globally) used by @code{ul} and @code{cu}. By 9131default, this is the font at position@tie{}2. @var{font} can be either 9132a non-negative font position or the name of a font. 9133@endDefreq 9134 9135@DefreqList {bd, font [@Var{offset}]} 9136@DefreqItem {bd, font1 font2 [@Var{offset}]} 9137@DefregListEnd {.b} 9138@cindex imitating bold face (@code{bd}) 9139@cindex bold face, imitating (@code{bd}) 9140Artificially create a bold font by printing each glyph twice, 9141slightly offset. 9142 9143Two syntax forms are available. 9144 9145@itemize @bullet 9146@item 9147Imitate a bold font unconditionally. The first argument specifies the 9148font to embolden, and the second is the number of basic units, minus 9149one, by which the two glyphs are offset. If the second argument is 9150missing, emboldening is turned off. 9151 9152@var{font} can be either a non-negative font position or the name of a 9153font. 9154 9155@var{offset} is available in the @code{.b} read-only register if a 9156special font is active; in the @code{bd} request, its default unit is 9157@samp{u}. 9158 9159@cindex @code{fspecial} request, and imitating bold 9160@kindex special 9161@cindex embolding of special fonts 9162@cindex special fonts, emboldening 9163@item 9164Imitate a bold form conditionally. Embolden @var{font1} by 9165@var{offset} only if font @var{font2} is the current font. This 9166command can be issued repeatedly to set up different emboldening 9167values for different current fonts. If the second argument is 9168missing, emboldening is turned off for this particular current font. 9169 9170This affects special fonts only (either set up with the @code{special} 9171command in font files or with the @code{fspecial} request). 9172@end itemize 9173@endDefreq 9174 9175@Defreq {cs, font [@Var{width} [@Var{em-size}]]} 9176@cindex constant glyph space mode (@code{cs}) 9177@cindex mode for constant glyph space (@code{cs}) 9178@cindex glyph, constant space 9179@cindex @code{ps} request, and constant glyph space mode 9180Switch to and from @dfn{constant glyph space mode}. If activated, the 9181width of every glyph is @math{@var{width}/36} ems. The em size is 9182given absolutely by @var{em-size}; if this argument is missing, the em 9183value is taken from the current font size (as set with the @code{ps} 9184request) when the font is effectively in use. Without second and 9185third argument, constant glyph space mode is deactivated. 9186 9187Default scaling indicator for @var{em-size} is @samp{z}; @var{width} is 9188an integer. 9189@endDefreq 9190 9191@c --------------------------------------------------------------------- 9192 9193@node Ligatures and Kerning, , Artificial Fonts, Fonts and Symbols 9194@subsection Ligatures and Kerning 9195@cindex ligatures and kerning 9196@cindex kerning and ligatures 9197 9198Ligatures are groups of characters that are run together, i.e, producing 9199a single glyph. For example, the letters `f' and `i' can form a 9200ligature `fi' as in the word `file'. This produces a cleaner look 9201(albeit subtle) to the printed output. Usually, ligatures are not 9202available in fonts for TTY output devices. 9203 9204Most @sc{PostScript} fonts support the fi and fl ligatures. The C/A/T 9205typesetter that was the target of @acronym{AT&T} @code{troff} also 9206supported `ff', `ffi', and `ffl' ligatures. Advanced typesetters or 9207`expert' fonts may include ligatures for `ft' and `ct', although GNU 9208@code{troff} does not support these (yet). 9209 9210Only the current font is checked for ligatures and kerns; neither special 9211fonts nor entities defined with the @code{char} request (and its siblings) 9212are taken into account. 9213 9214@DefreqList {lg, [@Var{flag}]} 9215@DefregListEnd {.lg} 9216@cindex activating ligatures (@code{lg}) 9217@cindex ligatures, activating (@code{lg}) 9218@cindex ligatures enabled register (@code{.lg}) 9219Switch the ligature mechanism on or off; if the parameter is non-zero 9220or missing, ligatures are enabled, otherwise disabled. Default is on. 9221The current ligature mode can be found in the read-only number register 9222@code{.lg} (set to 1 or@tie{}2 if ligatures are enabled, 0@tie{}otherwise). 9223 9224Setting the ligature mode to@tie{}2 enables the two-character ligatures 9225(fi, fl, and ff) and disables the three-character ligatures (ffi and 9226ffl). 9227@endDefreq 9228 9229@dfn{Pairwise kerning} is another subtle typesetting mechanism that 9230modifies the distance between a glyph pair to improve readability. 9231In most cases (but not always) the distance is decreased. 9232@ifnotinfo 9233For example, compare the combination of the letters `V' and `A'. With 9234kerning, `VA' is printed. Without kerning it appears as `V@w{}A'. 9235@end ifnotinfo 9236Typewriter-like fonts and fonts for terminals where all glyphs 9237have the same width don't use kerning. 9238 9239@DefreqList {kern, [@Var{flag}]} 9240@DefregListEnd {.kern} 9241@cindex activating kerning (@code{kern}) 9242@cindex kerning, activating (@code{kern}) 9243@cindex kerning enabled register (@code{.kern}) 9244Switch kerning on or off. If the parameter is non-zero or missing, 9245enable pairwise kerning, otherwise disable it. The read-only number 9246register @code{.kern} is set to@tie{}1 if pairwise kerning is enabled, 92470@tie{}otherwise. 9248 9249@cindex zero width space character (@code{\&}) 9250@cindex character, zero width space (@code{\&}) 9251@cindex space character, zero width (@code{\&}) 9252If the font description file contains pairwise kerning information, 9253glyphs from that font are kerned. Kerning between two glyphs 9254can be inhibited by placing @code{\&} between them: @samp{V\&A}. 9255 9256@xref{Font File Format}. 9257@endDefreq 9258 9259@cindex track kerning 9260@cindex kerning, track 9261@dfn{Track kerning} expands or reduces the space between glyphs. 9262This can be handy, for example, if you need to squeeze a long word 9263onto a single line or spread some text to fill a narrow column. It 9264must be used with great care since it is usually considered bad 9265typography if the reader notices the effect. 9266 9267@Defreq {tkf, f s1 n1 s2 n2} 9268@cindex activating track kerning (@code{tkf}) 9269@cindex track kerning, activating (@code{tkf}) 9270Enable track kerning for font@tie{}@var{f}. If the current font 9271is@tie{}@var{f} the width of every glyph is increased by an amount 9272between @var{n1} and @var{n2} (@var{n1}, @var{n2} can be negative); if 9273the current point size is less than or equal to @var{s1} the width is 9274increased by @var{n1}; if it is greater than or equal to @var{s2} the 9275width is increased by @var{n2}; if the point size is greater than or 9276equal to @var{s1} and less than or equal to @var{s2} the increase in 9277width is a linear function of the point size. 9278 9279The default scaling indicator is @samp{z} for @var{s1} and @var{s2}, 9280@samp{p} for @var{n1} and @var{n2}. 9281 9282Note that the track kerning amount is added even to the rightmost glyph 9283in a line; for large values it is thus recommended to increase the line 9284length by the same amount to compensate it. 9285@endDefreq 9286 9287Sometimes, when typesetting letters of different fonts, more or less 9288space at such boundaries are needed. There are two escapes to help 9289with this. 9290 9291@Defesc {\\/, , , } 9292@cindex italic correction (@code{\/}) 9293@cindex correction, italic (@code{\/}) 9294@cindex correction between italic and roman glyph (@code{\/}, @code{\,}) 9295@cindex roman glyph, correction after italic glyph (@code{\/}) 9296@cindex italic glyph, correction before roman glyph (@code{\/}) 9297@cindex glyph, italic correction (@code{\/}) 9298Increase the width of the preceding glyph so that the spacing 9299between that glyph and the following glyph is correct if the 9300following glyph is a roman glyph. For example, if an 9301italic@tie{}@code{f} is immediately followed by a roman right 9302parenthesis, then in many fonts the top right portion of the@tie{}@code{f} 9303overlaps the top left of the right parenthesis. Use this escape 9304sequence whenever an italic glyph is immediately followed by a 9305roman glyph without any intervening space. This small amount of 9306space is also called @dfn{italic correction}. 9307 9308@iftex 9309@example 9310@group 9311\f[I]f\f[R]) 9312 @result{} {@it f}@r{)} 9313\f[I]f\/\f[R]) 9314 @result{} @i{f}@r{)} 9315@end group 9316@end example 9317@end iftex 9318@endDefesc 9319 9320@Defesc {\\\,, , , } 9321@cindex left italic correction (@code{\,}) 9322@cindex correction, left italic (@code{\,}) 9323@cindex glyph, left italic correction (@code{\,}) 9324@cindex roman glyph, correction before italic glyph (@code{\,}) 9325@cindex italic glyph, correction after roman glyph (@code{\,}) 9326Modify the spacing of the following glyph so that the spacing 9327between that glyph and the preceding glyph is correct if the 9328preceding glyph is a roman glyph. Use this escape sequence 9329whenever a roman glyph is immediately followed by an italic 9330glyph without any intervening space. In analogy to above, this 9331space could be called @dfn{left italic correction}, but this term 9332isn't used widely. 9333 9334@iftex 9335@example 9336@group 9337q\f[I]f 9338 @result{} @r{q}@i{f} 9339q\,\f[I]f 9340 @result{} @r{q}@math{@ptexcomma}@i{f} 9341@end group 9342@end example 9343@end iftex 9344@endDefesc 9345 9346@Defesc {\\&, , , } 9347Insert a zero-width character, which is invisible. Its intended use 9348is to stop interaction of a character with its surrounding. 9349 9350@itemize @bullet 9351@item 9352It prevents the insertion of extra space after an end-of-sentence 9353character. 9354 9355@Example 9356Test. 9357Test. 9358 @result{} Test. Test. 9359Test.\& 9360Test. 9361 @result{} Test. Test. 9362@endExample 9363 9364@item 9365It prevents interpretation of a control character at the beginning of 9366an input line. 9367 9368@Example 9369.Test 9370 @result{} warning: `Test' not defined 9371\&.Test 9372 @result{} .Test 9373@endExample 9374 9375@item 9376It prevents kerning between two glyphs. 9377 9378@ifnotinfo 9379@example 9380@group 9381VA 9382 @result{} @r{VA} 9383V\&A 9384 @result{} @r{V@w{}A} 9385@end group 9386@end example 9387@end ifnotinfo 9388 9389@item 9390It is needed to map an arbitrary character to nothing in the @code{tr} 9391request (@pxref{Character Translations}). 9392@end itemize 9393@endDefesc 9394 9395@Defesc {\\), , , } 9396This escape is similar to @code{\&} except that it behaves like a 9397character declared with the @code{cflags} request to be transparent 9398for the purposes of an end-of-sentence character. 9399 9400Its main usage is in macro definitions to protect against arguments 9401starting with a control character. 9402 9403@Example 9404.de xxx 9405\)\\$1 9406.. 9407.de yyy 9408\&\\$1 9409.. 9410This is a test.\c 9411.xxx ' 9412This is a test. 9413 @result{}This is a test.' This is a test. 9414This is a test.\c 9415.yyy ' 9416This is a test. 9417 @result{}This is a test.' This is a test. 9418@endExample 9419@endDefesc 9420 9421 9422@c ===================================================================== 9423 9424@node Sizes, Strings, Fonts and Symbols, gtroff Reference 9425@section Sizes 9426@cindex sizes 9427 9428@cindex baseline 9429@cindex type size 9430@cindex size of type 9431@cindex vertical spacing 9432@cindex spacing, vertical 9433@code{gtroff} uses two dimensions with each line of text, type size 9434and vertical spacing. The @dfn{type size} is approximately the height 9435of the tallest glyph.@footnote{This is usually the parenthesis. 9436Note that in most cases the real dimensions of the glyphs in a font 9437are @emph{not} related to its type size! For example, the standard 9438@sc{PostScript} font families `Times Roman', `Helvetica', and 9439`Courier' can't be used together at 10@dmn{pt}; to get acceptable 9440output, the size of `Helvetica' has to be reduced by one point, and 9441the size of `Courier' must be increased by one point.} @dfn{Vertical 9442spacing} is the amount of space @code{gtroff} allows for a line of 9443text; normally, this is about 20%@tie{}larger than the current type 9444size. Ratios smaller than this can result in hard-to-read text; 9445larger than this, it spreads the text out more vertically (useful for 9446term papers). By default, @code{gtroff} uses 10@tie{}point type on 944712@tie{}point spacing. 9448 9449@cindex leading 9450The difference between type size and vertical spacing is known, by 9451typesetters, as @dfn{leading} (this is pronounced `ledding'). 9452 9453@menu 9454* Changing Type Sizes:: 9455* Fractional Type Sizes:: 9456@end menu 9457 9458@c --------------------------------------------------------------------- 9459 9460@node Changing Type Sizes, Fractional Type Sizes, Sizes, Sizes 9461@subsection Changing Type Sizes 9462 9463@DefreqList {ps, [@Var{size}]} 9464@DefreqItem {ps, @t{+}@Var{size}} 9465@DefreqItem {ps, @t{-}@Var{size}} 9466@DefescItem {\\s, , size, } 9467@DefregListEnd {.s} 9468@cindex changing type sizes (@code{ps}, @code{\s}) 9469@cindex type sizes, changing (@code{ps}, @code{\s}) 9470@cindex point sizes, changing (@code{ps}, @code{\s}) 9471Use the @code{ps} request or the @code{\s} escape to change (increase, 9472decrease) the type size (in points). Specify @var{size} as either an 9473absolute point size, or as a relative change from the current size. 9474The size@tie{}0, or no argument, goes back to the previous size. 9475 9476Default scaling indicator of @code{size} is @samp{z}. If @code{size} 9477is zero or negative, it is set to 1@dmn{u}. 9478 9479@cindex type size registers (@code{.s}, @code{.ps}) 9480@cindex point size registers (@code{.s}, @code{.ps}) 9481The read-only number register @code{.s} returns the point size in 9482points as a decimal fraction. This is a string. To get the point 9483size in scaled points, use the @code{.ps} register instead. 9484 9485@code{.s} is associated with the current environment 9486(@pxref{Environments}). 9487 9488@Example 9489snap, snap, 9490.ps +2 9491grin, grin, 9492.ps +2 9493wink, wink, \s+2nudge, nudge,\s+8 say no more! 9494.ps 10 9495@endExample 9496 9497The @code{\s} escape may be called in a variety of ways. Much like 9498other escapes there must be a way to determine where the argument ends 9499and the text begins. Any of the following forms are valid: 9500 9501@table @code 9502@item \s@var{n} 9503Set the point size to @var{n}@tie{}points. @var{n}@tie{}must be either 95040 or in the range 4 to@tie{}39. 9505 9506@item \s+@var{n} 9507@itemx \s-@var{n} 9508Increase or decrease the point size by @var{n}@tie{}points. 9509@var{n}@tie{}must be exactly one digit. 9510 9511@item \s(@var{nn} 9512Set the point size to @var{nn}@tie{}points. @var{nn} must be exactly 9513two digits. 9514 9515@item \s+(@var{nn} 9516@itemx \s-(@var{nn} 9517@itemx \s(+@var{nn} 9518@itemx \s(-@var{nn} 9519Increase or decrease the point size by @var{nn}@tie{}points. @var{nn} 9520must be exactly two digits. 9521@end table 9522 9523Note that @code{\s} doesn't produce an input token in @code{gtroff}. 9524As a consequence, it can be used in requests like @code{mc} (which 9525expects a single character as an argument) to change the font on 9526the fly: 9527 9528@Example 9529.mc \s[20]x\s[0] 9530@endExample 9531 9532@xref{Fractional Type Sizes}, for yet another syntactical form of 9533using the @code{\s} escape. 9534@endDefreq 9535 9536@Defreq {sizes, s1 s2 @dots{} sn [0]} 9537Some devices may only have certain permissible sizes, in which case 9538@code{gtroff} rounds to the nearest permissible size. 9539The @file{DESC} file specifies which sizes are permissible for the device. 9540 9541Use the @code{sizes} request to change the permissible sizes 9542for the current output device. 9543Arguments are in scaled points; 9544the @code{sizescale} line in the 9545@file{DESC} file for the output device 9546provides the scaling factor. 9547For example, if the scaling factor is 1000, 9548then the value 12000 is 12@tie{}points. 9549 9550Each argument can be a single point size (such as @samp{12000}), 9551or a range of sizes (such as @samp{4000-72000}). 9552You can optionally end the list with a zero. 9553@endDefreq 9554 9555@DefreqList {vs, [@Var{space}]} 9556@DefreqItem {vs, @t{+}@Var{space}} 9557@DefreqItem {vs, @t{-}@Var{space}} 9558@DefregListEnd {.v} 9559@cindex changing vertical line spacing (@code{vs}) 9560@cindex vertical line spacing, changing (@code{vs}) 9561@cindex vertical line spacing register (@code{.v}) 9562Change (increase, decrease) the vertical spacing by @var{space}. The 9563default scaling indicator is @samp{p}. 9564 9565If @code{vs} is called without an argument, the vertical spacing is 9566reset to the previous value before the last call to @code{vs}. 9567 9568@cindex @code{.V} register, and @code{vs} 9569@code{gtroff} creates a warning of type @samp{range} if @var{space} is 9570negative; the vertical spacing is then set to the vertical 9571resolution (as given in the @code{.V} register). 9572 9573The read-only number register @code{.v} contains the current vertical 9574spacing; it is associated with the current environment 9575(@pxref{Environments}). 9576@endDefreq 9577 9578@cindex vertical line spacing, effective value 9579The effective vertical line spacing consists of four components. 9580 9581@itemize @bullet 9582@item 9583The vertical line spacing as set with the @code{vs} request. 9584 9585@cindex post-vertical line spacing 9586@cindex line spacing, post-vertical (@code{pvs}) 9587@item 9588The @dfn{post-vertical line spacing} as set with the @code{pvs} request. 9589This is vertical space which will be added after a line has been 9590output. 9591 9592@cindex extra pre-vertical line space (@code{\x}) 9593@cindex line space, extra pre-vertical (@code{\x}) 9594@item 9595The @dfn{extra pre-vertical line space} as set with the @code{\x} request, 9596using a negative value. This is vertical space which will be added once 9597before the current line has been output. 9598 9599@cindex extra post-vertical line space (@code{\x}) 9600@cindex line space, extra post-vertical (@code{\x}) 9601@item 9602The @dfn{extra post-vertical line space} as set with the @code{\x} request, 9603using a positive value. This is vertical space which will be added once 9604after the current line has been output. 9605@end itemize 9606 9607@cindex double-spacing (@code{vs}, @code{pvs}) 9608It is usually better to use @code{vs} or @code{pvs} instead of @code{ls} 9609to produce double-spaced documents: @code{vs} and @code{pvs} have a finer 9610granularity for the inserted vertical space compared to @code{ls}; 9611furthermore, certain preprocessors assume single-spacing. 9612 9613@xref{Manipulating Spacing}, for more details on the @code{\x} escape 9614and the @code{ls} request. 9615 9616@DefreqList {pvs, [@Var{space}]} 9617@DefreqItem {pvs, @t{+}@Var{space}} 9618@DefreqItem {pvs, @t{-}@Var{space}} 9619@DefregListEnd {.pvs} 9620@cindex @code{ls} request, alternative to (@code{pvs}) 9621@cindex post-vertical line spacing, changing (@code{pvs}) 9622@cindex post-vertical line spacing register (@code{.pvs}) 9623Change (increase, decrease) the post-vertical spacing by 9624@var{space}. The default scaling indicator is @samp{p}. 9625 9626If @code{pvs} is called without an argument, the post-vertical spacing is 9627reset to the previous value before the last call to @code{pvs}. 9628 9629@code{gtroff} creates a warning of type @samp{range} if @var{space} is 9630zero or negative; the vertical spacing is then set to zero. 9631 9632The read-only number register @code{.pvs} contains the current 9633post-vertical spacing; it is associated with the current environment 9634(@pxref{Environments}). 9635@endDefreq 9636 9637@c --------------------------------------------------------------------- 9638 9639@node Fractional Type Sizes, , Changing Type Sizes, Sizes 9640@subsection Fractional Type Sizes 9641@cindex fractional type sizes 9642@cindex fractional point sizes 9643@cindex type sizes, fractional 9644@cindex point sizes, fractional 9645@cindex sizes, fractional 9646 9647@cindex @code{s} unit 9648@cindex unit, @code{s} 9649@cindex @code{z} unit 9650@cindex unit, @code{z} 9651@cindex @code{ps} request, with fractional type sizes 9652@cindex @code{cs} request, with fractional type sizes 9653@cindex @code{tkf} request, with fractional type sizes 9654@cindex @code{\H}, with fractional type sizes 9655@cindex @code{\s}, with fractional type sizes 9656A @dfn{scaled point} is equal to @math{1/@var{sizescale}} points, 9657where @var{sizescale} is specified in the @file{DESC} file (1@tie{}by 9658default). There is a new scale indicator @samp{z} which has the 9659effect of multiplying by @var{sizescale}. Requests and escape 9660sequences in @code{gtroff} interpret arguments that represent a point 9661size as being in units of scaled points, but they evaluate each such 9662argument using a default scale indicator of @samp{z}. Arguments 9663treated in this way are the argument to the @code{ps} request, the 9664third argument to the @code{cs} request, the second and fourth 9665arguments to the @code{tkf} request, the argument to the @code{\H} 9666escape sequence, and those variants of the @code{\s} escape sequence 9667that take a numeric expression as their argument (see below). 9668 9669For example, suppose @var{sizescale} is@tie{}1000; then a scaled point 9670is equivalent to a millipoint; the request @w{@samp{.ps 10.25}} is 9671equivalent to @w{@samp{.ps 10.25z}} and thus sets the point size to 967210250@tie{}scaled points, which is equal to 10.25@tie{}points. 9673 9674@code{gtroff} disallows the use of the @samp{z} scale indicator in 9675instances where it would make no sense, such as a numeric 9676expression whose default scale indicator was neither @samp{u} nor 9677@samp{z}. Similarly it would make 9678no sense to use a scaling indicator other than @samp{z} or @samp{u} in a 9679numeric expression whose default scale indicator was @samp{z}, and so 9680@code{gtroff} disallows this as well. 9681 9682There is also new scale indicator @samp{s} which multiplies by the 9683number of units in a scaled point. So, for example, @samp{\n[.ps]s} is 9684equal to @samp{1m}. Be sure not to confuse the @samp{s} and @samp{z} 9685scale indicators. 9686 9687@Defreg {.ps} 9688A read-only number register returning the point size in scaled points. 9689 9690@code{.ps} is associated with the current environment 9691(@pxref{Environments}). 9692@endDefreg 9693 9694@DefregList {.psr} 9695@DefregListEnd {.sr} 9696@cindex last-requested point size registers (@code{.psr}, @code{.sr}) 9697@cindex point size registers, last-requested (@code{.psr}, @code{.sr}) 9698@cindex @code{.ps} register, in comparison with @code{.psr} 9699@cindex @code{.s} register, in comparison with @code{.sr} 9700The last-requested point size in scaled points is contained in the 9701@code{.psr} read-only number register. The last requested point size 9702in points as a decimal fraction can be found in @code{.sr}. This is a 9703string-valued read-only number register. 9704 9705Note that the requested point sizes are device-independent, whereas 9706the values returned by the @code{.ps} and @code{.s} registers are not. 9707For example, if a point size of 11@dmn{pt} is requested, and a 9708@code{sizes} request (or a @code{sizescale} line in a @file{DESC} file) 9709specifies 10.95@dmn{pt} instead, this value is actually used. 9710 9711Both registers are associated with the current environment 9712(@pxref{Environments}). 9713@endDefreg 9714 9715The @code{\s} escape has the following syntax for working with 9716fractional type sizes: 9717 9718@table @code 9719@item \s[@var{n}] 9720@itemx \s'@var{n}' 9721Set the point size to @var{n}@tie{}scaled points; @var{n}@tie{}is a numeric 9722expression with a default scale indicator of @samp{z}. 9723 9724@item \s[+@var{n}] 9725@itemx \s[-@var{n}] 9726@itemx \s+[@var{n}] 9727@itemx \s-[@var{n}] 9728@itemx \s'+@var{n}' 9729@itemx \s'-@var{n}' 9730@itemx \s+'@var{n}' 9731@itemx \s-'@var{n}' 9732Increase or or decrease the point size by @var{n}@tie{}scaled points; 9733@var{n}@tie{}is a numeric expression with a default scale indicator of 9734@samp{z}. 9735@end table 9736 9737@xref{Font Files}. 9738 9739 9740@c ===================================================================== 9741 9742@node Strings, Conditionals and Loops, Sizes, gtroff Reference 9743@section Strings 9744@cindex strings 9745 9746@code{gtroff} has string variables, which are entirely for user 9747convenience (i.e.@: there are no built-in strings exept @code{.T}, but 9748even this is a read-write string variable). 9749 9750@DefreqList {ds, name [@Var{string}]} 9751@DefreqItem {ds1, name [@Var{string}]} 9752@DefescItem {\\*, , n, } 9753@DefescItem {\\*, @lparen{}, nm, } 9754@DefescListEnd {\\*, @lbrack{}, name arg1 arg2 @dots{}, @rbrack{}} 9755@cindex string interpolation (@code{\*}) 9756@cindex string expansion (@code{\*}) 9757@cindex interpolation of strings (@code{\*}) 9758@cindex expansion of strings (@code{\*}) 9759@cindex string arguments 9760@cindex arguments, of strings 9761Define and access a string variable @var{name} (one-character 9762name@tie{}@var{n}, two-character name @var{nm}). If @var{name} already 9763exists, @code{ds} overwrites the previous definition. Only the syntax form 9764using brackets can take arguments which are handled identically to 9765macro arguments; the single exception is that a closing bracket as an 9766argument must be enclosed in double quotes. @xref{Request and Macro 9767Arguments}, and @ref{Parameters}. 9768 9769Example: 9770 9771@Example 9772.ds foo a \\$1 test 9773. 9774This is \*[foo nice]. 9775 @result{} This is a nice test. 9776@endExample 9777 9778The @code{\*} escape @dfn{interpolates} (expands in-place) a 9779previously-defined string variable. To be more precise, the stored 9780string is pushed onto the input stack which is then parsed by 9781@code{gtroff}. Similar to number registers, it is possible to nest 9782strings, i.e. string variables can be called within string variables. 9783 9784If the string named by the @code{\*} escape does not exist, it is 9785defined as empty, and a warning of type @samp{mac} is emitted (see 9786@ref{Debugging}, for more details). 9787 9788@cindex comments, with @code{ds} 9789@cindex @code{ds} request, and comments 9790@strong{Caution:} Unlike other requests, the second argument to the 9791@code{ds} request takes up the entire line including trailing spaces. 9792This means that comments on a line with such a request can introduce 9793unwanted space into a string. 9794 9795@Example 9796.ds UX \s-1UNIX\s0\u\s-3tm\s0\d \" UNIX trademark 9797@endExample 9798 9799@noindent 9800Instead the comment should be put on another line or have the comment 9801escape adjacent with the end of the string. 9802 9803@Example 9804.ds UX \s-1UNIX\s0\u\s-3tm\s0\d\" UNIX trademark 9805@endExample 9806 9807@cindex trailing quotes 9808@cindex quotes, trailing 9809@cindex leading spaces with @code{ds} 9810@cindex spaces with @code{ds} 9811@cindex @code{ds} request, and leading spaces 9812To produce leading space the string can be started with a double 9813quote. No trailing quote is needed; in fact, any trailing quote is 9814included in your string. 9815 9816@Example 9817.ds sign " Yours in a white wine sauce, 9818@endExample 9819 9820@cindex multi-line strings 9821@cindex strings, multi-line 9822@cindex newline character, in strings, escaping 9823@cindex escaping newline characters, in strings 9824Strings are not limited to a single line of text. A string can span 9825several lines by escaping the newlines with a backslash. The 9826resulting string is stored @emph{without} the newlines. 9827 9828@Example 9829.ds foo lots and lots \ 9830of text are on these \ 9831next several lines 9832@endExample 9833 9834It is not possible to have real newlines in a string. To put a single 9835double quote character into a string, use two consecutive double quote 9836characters. 9837 9838The @code{ds1} request turns off compatibility mode 9839while interpreting a string. To be more precise, a @dfn{compatibility 9840save} input token is inserted at the beginning of the string, and a 9841@dfn{compatibility restore} input token at the end. 9842 9843@Example 9844.nr xxx 12345 9845.ds aa The value of xxx is \\n[xxx]. 9846.ds1 bb The value of xxx ix \\n[xxx]. 9847. 9848.cp 1 9849. 9850\*(aa 9851 @result{} warning: number register `[' not defined 9852 @result{} The value of xxx is 0xxx]. 9853\*(bb 9854 @result{} The value of xxx ix 12345. 9855@endExample 9856 9857@cindex name space, common, of macros, diversions, and strings 9858@cindex common name space of macros, diversions, and strings 9859@cindex macros, shared name space with strings and diversions 9860@cindex strings, shared name space with macros and diversions 9861@cindex diversions, shared name space with macros and strings 9862Strings, macros, and diversions (and boxes) share the same name space. 9863Internally, even the same mechanism is used to store them. This has 9864some interesting consequences. For example, it is possible to call a 9865macro with string syntax and vice versa. 9866 9867@Example 9868.de xxx 9869a funny test. 9870.. 9871This is \*[xxx] 9872 @result{} This is a funny test. 9873 9874.ds yyy a funny test 9875This is 9876.yyy 9877 @result{} This is a funny test. 9878@endExample 9879 9880Diversions and boxes can be also called with string syntax. 9881 9882Another consequence is that you can copy one-line diversions or boxes 9883to a string. 9884 9885@Example 9886.di xxx 9887a \fItest\fR 9888.br 9889.di 9890.ds yyy This is \*[xxx]\c 9891\*[yyy]. 9892 @result{} @r{This is a }@i{test}. 9893@endExample 9894 9895@noindent 9896As the previous example shows, it is possible to store formatted 9897output in strings. The @code{\c} escape prevents the insertion of an 9898additional blank line in the output. 9899 9900Copying diversions longer than a single output line produces 9901unexpected results. 9902 9903@Example 9904.di xxx 9905a funny 9906.br 9907test 9908.br 9909.di 9910.ds yyy This is \*[xxx]\c 9911\*[yyy]. 9912 @result{} test This is a funny. 9913@endExample 9914 9915Usually, it is not predictable whether a diversion contains one or 9916more output lines, so this mechanism should be avoided. With 9917@acronym{UNIX} @code{troff}, this was the only solution to strip off a 9918final newline from a diversion. Another disadvantage is that the 9919spaces in the copied string are already formatted, making them 9920unstretchable. This can cause ugly results. 9921 9922@cindex stripping final newline in diversions 9923@cindex diversion, stripping final newline 9924@cindex final newline, stripping in diversions 9925@cindex newline, final, stripping in diversions 9926@cindex horizontal space, unformatting 9927@cindex space, horizontal, unformatting 9928@cindex unformatting horizontal space 9929A clean solution to this problem is available in GNU @code{troff}, 9930using the requests @code{chop} to remove the final newline of a 9931diversion, and @code{unformat} to make the horizontal spaces 9932stretchable again. 9933 9934@Example 9935.box xxx 9936a funny 9937.br 9938test 9939.br 9940.box 9941.chop xxx 9942.unformat xxx 9943This is \*[xxx]. 9944 @result{} This is a funny test. 9945@endExample 9946 9947@xref{Gtroff Internals}, for more information. 9948@endDefreq 9949 9950@DefreqList {as, name [@Var{string}]} 9951@DefreqListEnd {as1, name [@Var{string}]} 9952@cindex appending to a string (@code{as}) 9953@cindex string, appending (@code{as}) 9954The @code{as} request is similar to @code{ds} but appends @var{string} 9955to the string stored as @var{name} instead of redefining it. If 9956@var{name} doesn't exist yet, it is created. 9957 9958@Example 9959.as sign " with shallots, onions and garlic, 9960@endExample 9961 9962The @code{as1} request is similar to @code{as}, but compatibility mode 9963is switched off while the appended string is interpreted. To be more 9964precise, a @dfn{compatibility save} input token is inserted at the 9965beginning of the appended string, and a @dfn{compatibility restore} 9966input token at the end. 9967@endDefreq 9968 9969Rudimentary string manipulation routines are given with the next two 9970requests. 9971 9972@Defreq {substring, str n1 [@Var{n2}]} 9973@cindex substring (@code{substring}) 9974Replace the string named @var{str} with the substring 9975defined by the indices @var{n1} and@tie{}@var{n2}. The first character 9976in the string has index@tie{}0. If @var{n2} is omitted, it is taken to 9977be equal to the string's length. If the index value @var{n1} or 9978@var{n2} is negative, it is counted from the end of the 9979string, going backwards: The last character has index@tie{}@minus{}1, the 9980character before the last character has index@tie{}@minus{}2, etc. 9981 9982@Example 9983.ds xxx abcdefgh 9984.substring xxx 1 -4 9985\*[xxx] 9986 @result{} bcde 9987@endExample 9988@endDefreq 9989 9990@Defreq {length, reg str} 9991@cindex length of a string (@code{length}) 9992@cindex string, length of (@code{length}) 9993Compute the number of characters of @var{str} and return it in the 9994number register @var{reg}. If @var{reg} doesn't exist, it is created. 9995@code{str} is read in copy mode. 9996 9997@Example 9998.ds xxx abcd\h'3i'efgh 9999.length yyy \*[xxx] 10000\n[yyy] 10001 @result{} 14 10002@endExample 10003@endDefreq 10004 10005@Defreq {rn, xx yy} 10006@cindex renaming request (@code{rn}) 10007@cindex request, renaming (@code{rn}) 10008@cindex renaming macro (@code{rn}) 10009@cindex macro, renaming (@code{rn}) 10010@cindex renaming string (@code{rn}) 10011@cindex string, renaming (@code{rn}) 10012@cindex renaming diversion (@code{rn}) 10013@cindex diversion, renaming (@code{rn}) 10014Rename the request, macro, diversion, or string @var{xx} to @var{yy}. 10015@endDefreq 10016 10017@Defreq {rm, xx} 10018@cindex removing request (@code{rm}) 10019@cindex request, removing (@code{rm}) 10020@cindex removing macro (@code{rm}) 10021@cindex macro, removing (@code{rm}) 10022@cindex removing string (@code{rm}) 10023@cindex string, removing (@code{rm}) 10024@cindex removing diversion (@code{rm}) 10025@cindex diversion, removing (@code{rm}) 10026Remove the request, macro, diversion, or string @var{xx}. @code{gtroff} 10027treats subsequent invocations as if the object had never been defined. 10028@endDefreq 10029 10030@Defreq {als, new old} 10031@cindex alias, string, creating (@code{als}) 10032@cindex alias, macro, creating (@code{als}) 10033@cindex alias, diversion, creating (@code{als}) 10034@cindex creating alias, for string (@code{als}) 10035@cindex creating alias, for macro (@code{als}) 10036@cindex creating alias, for diversion (@code{als}) 10037@cindex string, creating alias (@code{als}) 10038@cindex macro, creating alias (@code{als}) 10039@cindex diversion, creating alias (@code{als}) 10040Create an alias named @var{new} for the request, string, macro, or 10041diversion object named @var{old}. The new name and the old name are 10042exactly equivalent (it is similar to a hard rather than a soft 10043link). If @var{old} is undefined, @code{gtroff} generates a warning of 10044type @samp{mac} and ignores the request. 10045@endDefreq 10046 10047@Defreq {chop, xx} 10048Remove (chop) the last character from the macro, string, or diversion 10049named @var{xx}. This is useful for removing the newline from the end 10050of diversions that are to be interpolated as strings. This command 10051can be used repeatedly; see @ref{Gtroff Internals}, for details on 10052nodes inserted additionally by @code{gtroff}. 10053@endDefreq 10054 10055@xref{Identifiers}, and @ref{Comments}. 10056 10057 10058@c ===================================================================== 10059 10060@node Conditionals and Loops, Writing Macros, Strings, gtroff Reference 10061@section Conditionals and Loops 10062@cindex conditionals and loops 10063@cindex loops and conditionals 10064 10065@menu 10066* Operators in Conditionals:: 10067* if-else:: 10068* while:: 10069@end menu 10070 10071@c --------------------------------------------------------------------- 10072 10073@node Operators in Conditionals, if-else, Conditionals and Loops, Conditionals and Loops 10074@subsection Operators in Conditionals 10075 10076@cindex @code{if} request, operators to use with 10077@cindex @code{while} request, operators to use with 10078In @code{if} and @code{while} requests, there are several more 10079operators available: 10080 10081@table @code 10082@item e 10083@itemx o 10084True if the current page is even or odd numbered (respectively). 10085 10086@item n 10087True if the document is being processed in nroff mode (i.e., the 10088@code{.nroff} command has been issued). 10089 10090@item t 10091True if the document is being processed in troff mode (i.e., the 10092@code{.troff} command has been issued). 10093 10094@item v 10095Always false. This condition is for compatibility with other 10096@code{troff} versions only. 10097 10098@item '@var{xxx}'@var{yyy}' 10099True if the string @var{xxx} is equal to the string @var{yyy}. Other 10100characters can be used in place of the single quotes; the same set of 10101delimiters as for the @code{\D} escape is used (@pxref{Escapes}). 10102@code{gtroff} formats the strings before being compared: 10103 10104@Example 10105.ie "|"\fR|\fP" \ 10106true 10107.el \ 10108false 10109 @result{} true 10110@endExample 10111 10112@noindent 10113The resulting motions, glyph sizes, and fonts have to 10114match,@footnote{The created output nodes must be identical. 10115@xref{Gtroff Internals}.} and not the individual motion, size, and 10116font requests. In the previous example, @samp{|} and @samp{\fR|\fP} 10117both result in a roman @samp{|} glyph with the same point size and 10118at the same location on the page, so the strings are equal. If 10119@samp{.ft@tie{}I} had been added before the @samp{.ie}, the result 10120would be ``false'' because (the first) @samp{|} produces an italic 10121@samp{|} rather than a roman one. 10122 10123@item r @var{xxx} 10124True if there is a number register named @var{xxx}. 10125 10126@item d @var{xxx} 10127True if there is a string, macro, diversion, or request named @var{xxx}. 10128 10129@item m @var{xxx} 10130True if there is a color named @var{xxx}. 10131 10132@item c @var{g} 10133True if there is a glyph @var{g} available@footnote{The name of this 10134conditional operator is a misnomer since it tests names of output 10135glyphs.}; @var{g} is either an @acronym{ASCII} character or a special 10136character (@code{\(@var{gg}} or @code{\[@var{ggg}]}); the condition 10137is also true if @var{g} has been defined by the @code{char} request. 10138@end table 10139 10140Note that these operators can't be combined with other operators like 10141@samp{:} or @samp{&}; only a leading @samp{!} (without whitespace 10142between the exclamation mark and the operator) can be used to negate 10143the result. 10144 10145@Example 10146.nr xxx 1 10147.ie !r xxx \ 10148true 10149.el \ 10150false 10151 @result{} false 10152@endExample 10153 10154A whitespace after @samp{!} always evaluates to zero (this bizarre 10155behaviour is due to compatibility with @acronym{UNIX} @code{troff}). 10156 10157@Example 10158.nr xxx 1 10159.ie ! r xxx \ 10160true 10161.el \ 10162false 10163 @result{} r xxx true 10164@endExample 10165 10166It is possible to omit the whitespace before the argument to the 10167@samp{r}, @samp{d}, and @samp{c} operators. 10168 10169@xref{Expressions}. 10170 10171@c --------------------------------------------------------------------- 10172 10173@node if-else, while, Operators in Conditionals, Conditionals and Loops 10174@subsection if-else 10175@cindex if-else 10176 10177@code{gtroff} has if-then-else constructs like other languages, although 10178the formatting can be painful. 10179 10180@Defreq {if, expr anything} 10181Evaluate the expression @var{expr}, and executes @var{anything} (the 10182remainder of the line) if @var{expr} evaluates to non-zero (true). 10183@var{anything} is interpreted as though it was on a line by itself 10184(except that leading spaces are swallowed). @xref{Expressions}, for 10185more info. 10186 10187@Example 10188.nr xxx 1 10189.nr yyy 2 10190.if ((\n[xxx] == 1) & (\n[yyy] == 2)) true 10191 @result{} true 10192@endExample 10193@endDefreq 10194 10195@Defreq{nop, anything} 10196Executes @var{anything}. 10197This is similar to @code{.if@tie{}1}. 10198@endDefreq 10199 10200@DefreqList {ie, expr anything} 10201@DefreqListEnd {el, anything} 10202Use the @code{ie} and @code{el} requests to write an if-then-else. 10203The first request is the `if' part and the latter is the `else' part. 10204 10205@Example 10206.ie n .ls 2 \" double-spacing in nroff 10207.el .ls 1 \" single-spacing in troff 10208@endExample 10209@endDefreq 10210 10211@c there is a bug in makeinfo <= 4.1a: you can't have `@{' as an argument 10212@c to @deffn 10213@c 10214@c and in 4.2 you still can't use @{ in macros. 10215 10216@c @DefescList {\@{, , , } 10217@c @DefescListEnd {\@}, , , } 10218@deffn Escape @t{\@{} 10219@deffnx Escape @t{\@}} 10220@esindex \@{ 10221@esindex \@} 10222@cindex begin of conditional block (@code{\@{}) 10223@cindex end of conditional block (@code{\@}}) 10224@cindex conditional block, begin (@code{\@{}) 10225@cindex conditional block, end (@code{\@}}) 10226@cindex block, conditional, begin (@code{\@{}) 10227@cindex block, condititional, end (@code{\@}}) 10228In many cases, an if (or if-else) construct needs to execute more than 10229one request. This can be done using the @code{\@{} and @code{\@}} 10230escapes. The following example shows the possible ways to use these 10231escapes (note the position of the opening and closing braces). 10232 10233@Example 10234.ie t \@{\ 10235. ds lq `` 10236. ds rq '' 10237.\@} 10238.el \ 10239.\@{\ 10240. ds lq " 10241. ds rq "\@} 10242@endExample 10243@c @endDefesc 10244@end deffn 10245 10246@xref{Expressions}. 10247 10248@c --------------------------------------------------------------------- 10249 10250@node while, , if-else, Conditionals and Loops 10251@subsection while 10252@cindex while 10253 10254@code{gtroff} provides a looping construct using the @code{while} 10255request, which is used much like the @code{if} (and related) requests. 10256 10257@Defreq {while, expr anything} 10258Evaluate the expression @var{expr}, and repeatedly execute 10259@var{anything} (the remainder of the line) until @var{expr} evaluates 10260to@tie{}0. 10261 10262@Example 10263.nr a 0 1 10264.while (\na < 9) \@{\ 10265\n+a, 10266.\@} 10267\n+a 10268 @result{} 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 10269@endExample 10270 10271Some remarks. 10272 10273@cindex @code{de} request, and @code{while} 10274@itemize @bullet 10275@item 10276The body of a @code{while} request is treated like the body of a 10277@code{de} request: @code{gtroff} temporarily stores it in a macro 10278which is deleted after the loop has been exited. It can considerably 10279slow down a macro if the body of the @code{while} request (within the 10280macro) is large. Each time the macro is executed, the @code{while} 10281body is parsed and stored again as a temporary macro. 10282 10283@Example 10284.de xxx 10285. nr num 10 10286. while (\\n[num] > 0) \@{\ 10287. \" many lines of code 10288. nr num -1 10289. \@} 10290.. 10291@endExample 10292 10293@cindex recursive macros 10294@cindex macros, recursive 10295@noindent 10296The traditional and ofter better solution (@acronym{UNIX} @code{troff} 10297doesn't have the @code{while} request) is to use a recursive macro 10298instead which is parsed only once during its definition. 10299 10300@Example 10301.de yyy 10302. if (\\n[num] > 0) \@{\ 10303. \" many lines of code 10304. nr num -1 10305. yyy 10306. \@} 10307.. 10308. 10309.de xxx 10310. nr num 10 10311. yyy 10312.. 10313@endExample 10314 10315@noindent 10316Note that the number of available recursion levels is set to@tie{}1000 10317(this is a compile-time constant value of @code{gtroff}). 10318 10319@item 10320The closing brace of a @code{while} body must end a line. 10321 10322@Example 10323.if 1 \@{\ 10324. nr a 0 1 10325. while (\n[a] < 10) \@{\ 10326. nop \n+[a] 10327.\@}\@} 10328 @result{} unbalanced \@{ \@} 10329@endExample 10330@end itemize 10331@endDefreq 10332 10333@Defreq {break, } 10334@cindex @code{while} request, confusing with @code{br} 10335@cindex @code{break} request, in a @code{while} loop 10336@cindex @code{continue} request, in a @code{while} loop 10337Break out of a @code{while} loop. Be sure not to confuse this with 10338the @code{br} request (causing a line break). 10339@endDefreq 10340 10341@Defreq {continue, } 10342Finish the current iteration of a @code{while} loop, immediately 10343restarting the next iteration. 10344@endDefreq 10345 10346@xref{Expressions}. 10347 10348 10349@c ===================================================================== 10350 10351@node Writing Macros, Page Motions, Conditionals and Loops, gtroff Reference 10352@section Writing Macros 10353@cindex writing macros 10354@cindex macros, writing 10355 10356A @dfn{macro} is a collection of text and embedded commands which can 10357be invoked multiple times. Use macros to define common operations. 10358 10359@DefreqList {de, name [@Var{end}]} 10360@DefreqItem {de1, name [@Var{end}]} 10361@DefreqListEnd {dei, name [@Var{end}]} 10362Define a new macro named @var{name}. @code{gtroff} copies subsequent 10363lines (starting with the next one) into an internal buffer until it 10364encounters the line @samp{..} (two dots). The optional second 10365argument to @code{de} changes this to a macro to @samp{.@var{end}}. 10366 10367There can be whitespace after the first dot in the line containing the 10368ending token (either @samp{.} or macro @samp{@var{end}}). 10369 10370Here a small example macro called @samp{P} which causes a break and 10371inserts some vertical space. It could be used to separate paragraphs. 10372 10373@Example 10374.de P 10375. br 10376. sp .8v 10377.. 10378@endExample 10379 10380The following example defines a macro within another. Remember that 10381expansion must be protected twice; once for reading the macro and 10382once for executing. 10383 10384@Example 10385\# a dummy macro to avoid a warning 10386.de end 10387.. 10388. 10389.de foo 10390. de bar end 10391. nop \f[B]Hallo \\\\$1!\f[] 10392. end 10393.. 10394. 10395.foo 10396.bar Joe 10397 @result{} @b{Hallo Joe!} 10398@endExample 10399 10400@noindent 10401Since @code{\f} has no expansion, it isn't necessary to protect its 10402backslash. Had we defined another macro within @code{bar} which takes 10403a parameter, eight backslashes would be necessary before @samp{$1}. 10404 10405The @code{de1} request turns off compatibility mode 10406while executing the macro. On entry, the current compatibility mode 10407is saved and restored at exit. 10408 10409@Example 10410.nr xxx 12345 10411. 10412.de aa 10413The value of xxx is \\n[xxx]. 10414.. 10415.de1 bb 10416The value of xxx ix \\n[xxx]. 10417.. 10418. 10419.cp 1 10420. 10421.aa 10422 @result{} warning: number register ' not defined 10423 @result{} The value of xxx is 0xxx]. 10424.bb 10425 @result{} The value of xxx ix 12345. 10426@endExample 10427 10428The @code{dei} request defines a macro indirectly. 10429That is, it expands strings whose names 10430are @var{name} or @var{end} before performing the append. 10431 10432This: 10433 10434@Example 10435.ds xx aa 10436.ds yy bb 10437.dei xx yy 10438@endExample 10439 10440@noindent 10441is equivalent to: 10442 10443@Example 10444.de aa bb 10445@endExample 10446 10447@pindex trace.tmac 10448Using @file{trace.tmac}, you can trace calls to @code{de} and @code{de1}. 10449 10450Note that macro identifiers are shared with identifiers for strings and 10451diversions. 10452@endDefreq 10453 10454@DefreqList {am, name [@Var{end}]} 10455@DefreqItem {am1, name [@Var{end}]} 10456@DefreqListEnd {ami, name [@Var{end}]} 10457@cindex appending to a macro (@code{am}) 10458@cindex macro, appending (@code{am}) 10459Works similarly to @code{de} except it appends onto the macro named 10460@var{name}. So, to make the previously defined @samp{P} macro actually 10461do indented instead of block paragraphs, add the necessary code to the 10462existing macro like this: 10463 10464@Example 10465.am P 10466.ti +5n 10467.. 10468@endExample 10469 10470The @code{am1} request turns off compatibility mode 10471while executing the appended macro piece. To be more precise, a 10472@dfn{compatibility save} input token is inserted at the beginning of 10473the appended code, and a @dfn{compatibility restore} input token at 10474the end. 10475 10476The @code{ami} request appends indirectly, 10477meaning that @code{gtroff} expands strings whose names 10478are @var{name} or @var{end} before performing the append. 10479 10480@pindex trace.tmac 10481Using @file{trace.tmac}, you can trace calls to @code{am} and @code{am1}. 10482@endDefreq 10483 10484@xref{Strings}, for the @code{als} request to rename a macro. 10485 10486The @code{de}, @code{am}, @code{di}, @code{da}, @code{ds}, and 10487@code{as} requests (together with its variants) only create a new object 10488if the name of the macro, diversion or string diversion is currently 10489undefined or if it is defined to be a request; normally they modify the 10490value of an existing object. 10491 10492@Defreq {return, } 10493Exit a macro, immediately returning to the caller. 10494@endDefreq 10495 10496@menu 10497* Copy-in Mode:: 10498* Parameters:: 10499@end menu 10500 10501@c --------------------------------------------------------------------- 10502 10503@node Copy-in Mode, Parameters, Writing Macros, Writing Macros 10504@subsection Copy-in Mode 10505@cindex copy-in mode 10506@cindex mode, copy-in 10507 10508@cindex @code{\n}, when reading text for a macro 10509@cindex @code{\$}, when reading text for a macro 10510@cindex @code{\*}, when reading text for a macro 10511@cindex @code{\\}, when reading text for a macro 10512@cindex \@key{RET}, when reading text for a macro 10513When @code{gtroff} reads in the text for a macro, string, or diversion, 10514it copies the text (including request lines, but excluding escapes) into 10515an internal buffer. Escapes are converted into an internal form, 10516except for @code{\n}, @code{\$}, @code{\*}, @code{\\} and 10517@code{\@key{RET}} which are evaluated and inserted into the text where 10518the escape was located. This is known as @dfn{copy-in} mode or 10519@dfn{copy} mode. 10520 10521What this means is that you can specify when these escapes are to be 10522evaluated (either at copy-in time or at the time of use) by insulating 10523the escapes with an extra backslash. Compare this to the @code{\def} 10524and @code{\edef} commands in @TeX{}. 10525 10526The following example prints the numbers 20 and@tie{}10: 10527 10528@Example 10529.nr x 20 10530.de y 10531.nr x 10 10532\&\nx 10533\&\\nx 10534.. 10535.y 10536@endExample 10537 10538@c --------------------------------------------------------------------- 10539 10540@node Parameters, , Copy-in Mode, Writing Macros 10541@subsection Parameters 10542@cindex parameters 10543 10544The arguments to a macro or string can be examined using a variety of 10545escapes. 10546 10547@Defreg {.$} 10548@cindex number of arguments register (@code{.$}) 10549The number of arguments passed to a macro or string. This is a read-only 10550number register. 10551@endDefreg 10552 10553Any individual argument can be retrieved with one of the following 10554escapes: 10555 10556@DefescList {\\$, , n, } 10557@DefescItem {\\$, @lparen{}, nn, } 10558@DefescListEnd {\\$, @lbrack{}, nnn, @rbrack{}} 10559@cindex copy-in mode, and macro arguments 10560@cindex macro, arguments (@code{\$}) 10561@cindex arguments, macro (@code{\$}) 10562Retrieve the @var{n}@dmn{th}, @var{nn}@dmn{th} or @var{nnn}@dmn{th} 10563argument. As usual, the first form only accepts a single number 10564(larger than zero), the second a two-digit number (larger or equal 10565to@tie{}10), and the third any positive integer value (larger 10566than zero). Macros and strings can have an unlimited number of arguments. 10567Note that due to copy-in mode, use two backslashes on these in actual use 10568to prevent interpolation until the macro is actually invoked. 10569@endDefesc 10570 10571@Defreq {shift, [@Var{n}]} 10572Shift the arguments 1@tie{}position, or as 10573many positions as specified by its argument. After executing this 10574request, argument@tie{}@var{i} becomes argument @math{@var{i}-@var{n}}; 10575arguments 1 to@tie{}@var{n} are no longer available. Shifting by 10576negative amounts is currently undefined. 10577@endDefreq 10578 10579@DefescList {\\$*, , , } 10580@DefescListEnd {\\$@@, , , } 10581In some cases it is convenient to use all of the arguments at once (for 10582example, to pass the arguments along to another macro). The @code{\$*} 10583escape concatenates all the arguments separated by spaces. A 10584similar escape is @code{\$@@}, which concatenates all the 10585arguments with each surrounded by double quotes, and separated by 10586spaces. If not in compatibility mode, the input level of double quotes 10587is preserved (see @ref{Request and Macro Arguments}). 10588@endDefesc 10589 10590@Defesc {\\$0, , , } 10591@cindex macro name register (@code{\$0}) 10592@cindex @code{als} request, and @code{\$0} 10593The name used to invoke the current macro. 10594The @code{als} request can make a macro have more than one name. 10595 10596@Example 10597.de generic-macro 10598. ... 10599. if \\n[error] \@{\ 10600. tm \\$0: Houston, we have a problem. 10601. return 10602. \@} 10603.. 10604. 10605.als foo generic-macro 10606.als bar generic-macro 10607@endExample 10608@endDefesc 10609 10610@xref{Request and Macro Arguments}. 10611 10612 10613@c ===================================================================== 10614 10615@node Page Motions, Drawing Requests, Writing Macros, gtroff Reference 10616@section Page Motions 10617@cindex page motions 10618@cindex motions, page 10619 10620@xref{Manipulating Spacing}, for a discussion of the main request for 10621vertical motion, @code{sp}. 10622 10623@DefreqList {mk, [@Var{reg}]} 10624@DefreqListEnd {rt, [@Var{dist}]} 10625@cindex marking vertical page location (@code{mk}) 10626@cindex page location, vertical, marking (@code{mk}) 10627@cindex location, vertical, page, marking (@code{mk}) 10628@cindex vertical page location, marking (@code{mk}) 10629@cindex returning to marked vertical page location (@code{rt}) 10630@cindex page location, vertical, returning to marked (@code{rt}) 10631@cindex location, vertical, page, returning to marked (@code{rt}) 10632@cindex vertical page location, returning to marked (@code{rt}) 10633The request @code{mk} can be used to mark a location on a page, for 10634movement to later. This request takes a register name as an argument 10635in which to store the current page location. With no argument it 10636stores the location in an internal register. The results of this can 10637be used later by the @code{rt} or the @code{sp} request (or the 10638@code{\v} escape). 10639 10640The @code{rt} request returns @emph{upwards} to the location marked 10641with the last @code{mk} request. If used with an argument, return to 10642a position which distance from the top of the page is @var{dist} (no 10643previous call to @code{mk} is necessary in this case). Default scaling 10644indicator is @samp{v}. 10645 10646Here a primitive solution for a two-column macro. 10647 10648@Example 10649.nr column-length 1.5i 10650.nr column-gap 4m 10651.nr bottom-margin 1m 10652. 10653@endExample 10654@Example 10655.de 2c 10656. br 10657. mk 10658. ll \\n[column-length]u 10659. wh -\\n[bottom-margin]u 2c-trap 10660. nr right-side 0 10661.. 10662. 10663@endExample 10664@Example 10665.de 2c-trap 10666. ie \\n[right-side] \@{\ 10667. nr right-side 0 10668. po -(\\n[column-length]u + \\n[column-gap]u) 10669. \" remove trap 10670. wh -\\n[bottom-margin]u 10671. \@} 10672. el \@{\ 10673. \" switch to right side 10674. nr right-side 1 10675. po +(\\n[column-length]u + \\n[column-gap]u) 10676. rt 10677. \@} 10678.. 10679. 10680@endExample 10681@Example 10682.pl 1.5i 10683.ll 4i 10684This is a small test which shows how the 10685rt request works in combination with mk. 10686 10687.2c 10688Starting here, text is typeset in two columns. 10689Note that this implementation isn't robust 10690and thus not suited for a real two-column 10691macro. 10692@endExample 10693 10694Result: 10695 10696@Example 10697This is a small test which shows how the 10698rt request works in combination with mk. 10699 10700Starting here, isn't robust 10701text is typeset and thus not 10702in two columns. suited for a 10703Note that this real two-column 10704implementation macro. 10705@endExample 10706@endDefreq 10707 10708The following escapes give fine control of movements about the page. 10709 10710@Defesc {\\v, ', e, '} 10711@cindex vertical motion (@code{\v}) 10712@cindex motion, vertical (@code{\v}) 10713Move vertically, usually from the current location on the page (if no 10714absolute position operator @samp{|} is used). The 10715argument@tie{}@var{e} specifies the distance to move; positive is 10716downwards and negative upwards. The default scaling indicator for this 10717escape is @samp{v}. Beware, however, that @code{gtroff} continues text 10718processing at the point where the motion ends, so you should always 10719balance motions to avoid interference with text processing. 10720 10721@code{\v} doesn't trigger a trap. This can be quite useful; for example, 10722consider a page bottom trap macro which prints a marker in the margin to 10723indicate continuation of a footnote or something similar. 10724@endDefesc 10725 10726There are some special-case escapes for vertical motion. 10727 10728@Defesc {\\r, , , } 10729Move upwards@tie{}1@dmn{v}. 10730@endDefesc 10731 10732@Defesc {\\u, , , } 10733Move upwards@tie{}.5@dmn{v}. 10734@endDefesc 10735 10736@Defesc {\\d, , , } 10737Move down@tie{}.5@dmn{v}. 10738@endDefesc 10739 10740@Defesc {\\h, ', e, '} 10741@cindex inserting horizontal space (@code{\h}) 10742@cindex horizontal space (@code{\h}) 10743@cindex space, horizontal (@code{\h}) 10744@cindex horizontal motion (@code{\h}) 10745@cindex motion, horizontal (@code{\h}) 10746Move horizontally, usually from the current location (if no absolute 10747position operator @samp{|} is used). The expression@tie{}@var{e} 10748indicates how far to move: positive is rightwards and negative 10749leftwards. The default scaling indicator for this escape is @samp{m}. 10750 10751This horizontal space is not discarded at the end of a line. To insert 10752discardable space of a certain length use the @code{ss} request. 10753@endDefesc 10754 10755There are a number of special-case escapes for horizontal motion. 10756 10757@Defesc {\\@key{SP}, , , } 10758@cindex space, unbreakable 10759@cindex unbreakable space 10760An unbreakable and unpaddable (i.e.@: not expanded during filling) 10761space. (Note: This is a backslash followed by a space.) 10762@endDefesc 10763 10764@Defesc {\\~, , , } 10765An unbreakable space that stretches like a normal inter-word space 10766when a line is adjusted. 10767@endDefesc 10768 10769@Defesc {\\|, , , } 10770A 1/6@dmn{th} em space. Ignored for TTY output devices (rounded to 10771zero). 10772@endDefesc 10773 10774@Defesc {\\^, , , } 10775A 1/12@dmn{th} em space. Ignored for TTY output devices (rounded to 10776zero). 10777@endDefesc 10778 10779@Defesc {\\0, , , } 10780@cindex space, width of a digit (@code{\0}) 10781@cindex digit width space (@code{\0}) 10782A space the size of a digit. 10783@endDefesc 10784 10785The following string sets the @TeX{} logo: 10786 10787@Example 10788.ds TeX T\h'-.1667m'\v'.224m'E\v'-.224m'\h'-.125m'X 10789@endExample 10790 10791@DefescList {\\w, ', text, '} 10792@DefregItem {st} 10793@DefregItem {sb} 10794@DefregItem {rst} 10795@DefregItem {rsb} 10796@DefregItem {ct} 10797@DefregItem {ssc} 10798@DefregListEnd {skw} 10799@cindex width escape (@code{\w}) 10800Return the width of the specified @var{text} in basic units. 10801This allows horizontal movement based on the width of some 10802arbitrary text (e.g.@: given as an argument to a macro). 10803 10804@Example 10805The length of the string `abc' is \w'abc'u. 10806 @result{} The length of the string `abc' is 72u. 10807@endExample 10808 10809Font changes may occur in @var{text} which don't affect current 10810settings. 10811 10812After use, @code{\w} sets several registers: 10813 10814@table @code 10815@item st 10816@itemx sb 10817The highest and lowest point of the baseline, respectively, in @var{text}. 10818 10819@item rst 10820@itemx rsb 10821Like the @code{st} and @code{sb} registers, but takes account of the 10822heights and depths of glyphs. With other words, this gives the 10823highest and lowest point of @var{text}. Values below the baseline are 10824negative. 10825 10826@item ct 10827Defines the kinds of glyphs occurring in @var{text}: 10828 10829@table @asis 10830@item 0 10831only short glyphs, no descenders or tall glyphs. 10832 10833@item 1 10834at least one descender. 10835 10836@item 2 10837at least one tall glyph. 10838 10839@item 3 10840at least one each of a descender and a tall glyph. 10841@end table 10842 10843@item ssc 10844The amount of horizontal space (possibly negative) that should be added 10845to the last glyph before a subscript. 10846 10847@item skw 10848How far to right of the center of the last glyph in the @code{\w} 10849argument, the center of an accent from a roman font should be placed 10850over that glyph. 10851@end table 10852@endDefesc 10853 10854@DefescList {\\k, , p, } 10855@DefescItem {\\k, @lparen{}, ps, } 10856@DefescListEnd {\\k, @lbrack{}, position, @rbrack} 10857@cindex saving horizontal input line position (@code{\k}) 10858@cindex horizontal input line position, saving (@code{\k}) 10859@cindex input line position, horizontal, saving (@code{\k}) 10860@cindex position, horizontal input line, saving (@code{\k}) 10861@cindex line, input, horizontal position, saving (@code{\k}) 10862Store the current horizontal position in the @emph{input} line in 10863number register with name @var{position} (one-character name@tie{}@var{p}, 10864two-character name @var{ps}). Use this, for example, to return to the 10865beginning of a string for highlighting or other decoration. 10866@endDefesc 10867 10868@Defreg {hp} 10869@cindex horizontal input line position register (@code{hp}) 10870@cindex input line, horizontal position, register (@code{hp}) 10871@cindex position, horizontal, in input line, register (@code{hp}) 10872@cindex line, input, horizontal position, register (@code{hp}) 10873The current horizontal position at the input line. 10874@endDefreg 10875 10876@Defreg {.k} 10877@cindex horizontal output line position register (@code{.k}) 10878@cindex output line, horizontal position, register (@code{.k}) 10879@cindex position, horizontal, in output line, register (@code{.k}) 10880@cindex line, output, horizontal position, register (@code{.k}) 10881A read-only number register containing the current horizontal output 10882position. 10883@endDefreg 10884 10885@Defesc {\\o, ', abc, '} 10886@cindex overstriking glyphs (@code{\o}) 10887@cindex glyphs, overstriking (@code{\o}) 10888Overstrike glyphs @var{a}, @var{b}, @var{c}, @dots{}; the glyphs 10889are centered, and the resulting spacing is the largest width of the 10890affected glyphs. 10891@endDefesc 10892 10893@Defesc {\\z, , g, , } 10894@cindex zero-width printing (@code{\z}, @code{\Z}) 10895@cindex printing, zero-width (@code{\z}, @code{\Z}) 10896Print glyph @var{g} with zero width, i.e., without spacing. Use 10897this to overstrike glyphs left-aligned. 10898@endDefesc 10899 10900@Defesc {\\Z, ', anything, '} 10901@cindex zero-width printing (@code{\z}, @code{\Z}) 10902@cindex printing, zero-width (@code{\z}, @code{\Z}) 10903Print @var{anything}, then restore the horizontal and vertical position. 10904The argument may not contain tabs or leaders. 10905 10906The following is an example of a strike-through macro: 10907 10908@Example 10909.de ST 10910.nr ww \w'\\$1' 10911\Z@@\v'-.25m'\l'\\n[ww]u'@@\\$1 10912.. 10913. 10914This is 10915.ST "a test" 10916an actual emergency! 10917@endExample 10918@endDefesc 10919 10920 10921@c ===================================================================== 10922 10923@node Drawing Requests, Traps, Page Motions, gtroff Reference 10924@section Drawing Requests 10925@cindex drawing requests 10926@cindex requests for drawing 10927 10928@code{gtroff} provides a number of ways to draw lines and other figures 10929on the page. Used in combination with the page motion commands (see 10930@ref{Page Motions}, for more info), a wide variety of figures can be 10931drawn. However, for complex drawings these operations can be quite 10932cumbersome, and it may be wise to use graphic preprocessors like 10933@code{gpic} or @code{ggrn}. @xref{gpic}, and @ref{ggrn}, for more 10934information. 10935 10936All drawing is done via escapes. 10937 10938@DefescList {\\l, ', l, '} 10939@DefescListEnd {\\l, ', lg, '} 10940@cindex drawing horizontal lines (@code{\l}) 10941@cindex horizontal line, drawing (@code{\l}) 10942@cindex line, horizontal, drawing (@code{\l}) 10943Draw a line horizontally. @var{l} is the length of the line to be 10944drawn. If it is positive, start the line at the current location and 10945draw to the right; its end point is the new current location. Negative 10946values are handled differently: The line starts at the current location 10947and draws to the left, but the current location doesn't move. 10948 10949@var{l} can also be specified absolutely (i.e.@: with a leading 10950@samp{|}) which draws back to the beginning of the input line. 10951Default scaling indicator is @samp{m}. 10952 10953@cindex underscore glyph (@code{\[ru]}) 10954@cindex glyph, underscore (@code{\[ru]}) 10955@cindex line drawing glyph 10956@cindex glyph, for line drawing 10957The optional second parameter@tie{}@var{g} is a glyph to draw the line 10958with. If this second argument is not specified, @code{gtroff} uses 10959the underscore glyph, @code{\[ru]}. 10960 10961@cindex zero width space character (@code{\&}) 10962@cindex character, zero width space (@code{\&}) 10963@cindex space character, zero width (@code{\&}) 10964To separate the two arguments (to prevent @code{gtroff} from 10965interpreting a drawing glyph as a scaling indicator if the glyph is 10966represented by a single character) use @code{\&}. 10967 10968Here a small useful example: 10969 10970@Example 10971.de box 10972\[br]\\$*\[br]\l'|0\[rn]'\l'|0\[ul]' 10973.. 10974@endExample 10975 10976@noindent 10977Note that this works by outputting a box rule (a vertical line), then 10978the text given as an argument and then another box rule. Finally, the 10979line drawing escapes both draw from the current location to the 10980beginning of the @emph{input} line -- this works because the line 10981length is negative, not moving the current point. 10982@endDefesc 10983 10984@DefescList {\\L, ', l, '} 10985@DefescListEnd {\\L, ', lg, '} 10986@cindex drawing vertical lines (@code{\L}) 10987@cindex vertical line drawing (@code{\L}) 10988@cindex line, vertical, drawing (@code{\L}) 10989@cindex line drawing glyph 10990@cindex glyph for line drawing 10991@cindex box rule glyph (@code{\[br]}) 10992@cindex glyph, box rule (@code{\[br]}) 10993Draw vertical lines. Its parameters are 10994similar to the @code{\l} escape, except that the default scaling 10995indicator is @samp{v}. The movement is downwards for positive values, 10996and upwards for negative values. The default glyph is the box rule 10997glyph, @code{\[br]}. As with the vertical motion escapes, text 10998processing blindly continues where the line ends. 10999 11000@Example 11001This is a \L'3v'test. 11002@endExample 11003 11004@noindent 11005Here the result, produced with @code{grotty}. 11006 11007@Example 11008This is a 11009 | 11010 | 11011 |test. 11012@endExample 11013@endDefesc 11014 11015@Defesc {\\D, ', command arg @dots{}, '} 11016The @code{\D} escape provides a variety of drawing functions. 11017Note that on character devices, only vertical and horizontal lines are 11018supported within @code{grotty}; other devices may only support a subset 11019of the available drawing functions. 11020 11021The default scaling indicator for all subcommands of @code{\D} is 11022@samp{m} for horizontal distances and @samp{v} for vertical ones. 11023Exceptions are @w{@code{\D'f @dots{}'}} and @w{@code{\D't @dots{}'}} 11024which use @code{u} as the default, and @w{@code{\D'F@var{x} @dots{}'}} 11025which arguments are treated similar to the @code{defcolor} request. 11026 11027@table @code 11028@item \D'l @var{dx} @var{dy}' 11029@cindex line, drawing (@w{@code{\D'l @dots{}'}}) 11030@cindex drawing a line (@w{@code{\D'l @dots{}'}}) 11031Draw a line from the current location to the relative point specified by 11032(@var{dx},@var{dy}). 11033 11034The following example is a macro for creating a box around a text string; 11035for simplicity, the box margin is taken as a fixed value, 0.2@dmn{m}. 11036 11037@Example 11038.de BOX 11039. nr @@wd \w'\\$1' 11040\h'.2m'\ 11041\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 11042\D'l 0 -(\\n[rst]u - \\n[rsb]u + .4m)'\ 11043\D'l (\\n[@@wd]u + .4m) 0'\ 11044\D'l 0 (\\n[rst]u - \\n[rsb]u + .4m)'\ 11045\D'l -(\\n[@@wd]u + .4m) 0'\ 11046\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 11047\\$1\ 11048\h'.2m' 11049.. 11050@endExample 11051 11052@noindent 11053First, the width of the string is stored in register @code{@@wd}. Then, 11054four lines are drawn to form a box, properly offset by the box margin. 11055The registers @code{rst} and @code{rsb} are set by the @code{\w} escape, 11056containing the largest height and depth of the whole string. 11057 11058@item \D'c @var{d}' 11059@cindex circle, drawing (@w{@code{\D'c @dots{}'}}) 11060@cindex drawing a circle (@w{@code{\D'c @dots{}'}}) 11061Draw a circle with a diameter of@tie{}@var{d} with the leftmost point at the 11062current position. After drawing, the current location is positioned at the 11063rightmost point of the circle. 11064 11065@item \D'C @var{d}' 11066@cindex circle, solid, drawing (@w{@code{\D'C @dots{}'}}) 11067@cindex drawing a solid circle (@w{@code{\D'C @dots{}'}}) 11068@cindex solid circle, drawing (@w{@code{\D'C @dots{}'}}) 11069Draw a solid circle with the same parameters and behaviour as an outlined 11070circle. No outline is drawn. 11071 11072@item \D'e @var{x} @var{y}' 11073@cindex drawing an ellipse (@w{@code{\D'e @dots{}'}}) 11074@cindex ellipse, drawing (@w{@code{\D'e @dots{}'}}) 11075Draw an ellipse with a horizontal diameter of @var{x} and a vertical 11076diameter of @var{y} with the leftmost point at the current position. 11077After drawing, the current location is positioned at the rightmost point of 11078the ellipse. 11079 11080@item \D'E @var{x} @var{y}' 11081@cindex ellipse, solid, drawing (@w{@code{\D'E @dots{}'}}) 11082@cindex drawing a solid ellipse (@w{@code{\D'E @dots{}'}}) 11083@cindex solid ellipse, drawing (@w{@code{\D'E @dots{}'}}) 11084Draw a solid ellipse with the same parameters and behaviour as an 11085outlined ellipse. No outline is drawn. 11086 11087@item \D'a @var{dx1} @var{dy1} @var{dx2} @var{dy2}' 11088@cindex arc, drawing (@w{@code{\D'a @dots{}'}}) 11089@cindex drawing an arc (@w{@code{\D'a @dots{}'}}) 11090Draw an arc clockwise from the current location through the two 11091specified relative locations (@var{dx1},@var{dy1}) and 11092(@var{dx2},@var{dy2}). The coordinates of the first point are relative 11093to the current position, and the coordinates of the second point are 11094relative to the first point. After drawing, the current position is moved 11095to the final point of the arc. 11096 11097@item \D'~ @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11098@cindex drawing a spline (@w{@code{\D'~ @dots{}'}}) 11099@cindex spline, drawing (@w{@code{\D'~ @dots{}'}}) 11100Draw a spline from the current location to the relative point 11101(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}), and so on. 11102The current position is moved to the terminal point of the drawn curve. 11103 11104@item \D'f @var{n}' 11105@cindex gray shading (@w{@code{\D'f @dots{}'}}) 11106@cindex shading filled objects (@w{@code{\D'f @dots{}'}}) 11107Set the shade of gray to be used for filling solid objects to@tie{}@var{n}; 11108@var{n}@tie{}must be an integer between 0 and@tie{}1000, where 0 11109corresponds solid white and 1000 to solid black, and values in between 11110correspond to intermediate shades of gray. This applies only to solid 11111circles, solid ellipses, and solid polygons. By default, a level of 111121000 is used. 11113 11114Despite of being silly, the current point is moved horizontally to the 11115right by@tie{}@var{n}. 11116 11117@cindex @w{@code{\D'f @dots{}'}} and horizontal resolution 11118Don't use this command! It has the serious drawback that it will be 11119always rounded to the next integer multiple of the horizontal resolution 11120(the value of the @code{hor} keyword in the @file{DESC} file). Use 11121@code{\M} (@pxref{Colors}) or @w{@code{\D'Fg @dots{}'}} instead. 11122 11123@item \D'p @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11124@cindex drawing a polygon (@w{@code{\D'p @dots{}'}}) 11125@cindex polygon, drawing (@w{@code{\D'p @dots{}'}}) 11126Draw a polygon from the current location to the relative position 11127(@var{dx1},@var{dy1}) and then to (@var{dx2},@var{dy2}) and so on. 11128When the specified data points are exhausted, a line is drawn back 11129to the starting point. The current position is changed by adding the 11130sum of all arguments with odd index to the actual horizontal position and 11131the even ones to the vertical position. 11132 11133@item \D'P @var{dx1} @var{dy1} @var{dx2} @var{dy2} @dots{}' 11134@cindex polygon, solid, drawing (@w{@code{\D'P @dots{}'}}) 11135@cindex drawing a solid polygon (@w{@code{\D'P @dots{}'}}) 11136@cindex solid polygon, drawing (@w{@code{\D'P @dots{}'}}) 11137Draw a solid polygon with the same parameters and behaviour as an 11138outlined polygon. No outline is drawn. 11139 11140Here a better variant of the box macro to fill the box with some color. 11141Note that the box must be drawn before the text since colors in 11142@code{gtroff} are not transparent; the filled polygon would hide the 11143text completely. 11144 11145@Example 11146.de BOX 11147. nr @@wd \w'\\$1' 11148\h'.2m'\ 11149\h'-.2m'\v'(.2m - \\n[rsb]u)'\ 11150\M[lightcyan]\ 11151\D'P 0 -(\\n[rst]u - \\n[rsb]u + .4m) \ 11152 (\\n[@@wd]u + .4m) 0 \ 11153 0 (\\n[rst]u - \\n[rsb]u + .4m) \ 11154 -(\\n[@@wd]u + .4m) 0'\ 11155\h'.2m'\v'-(.2m - \\n[rsb]u)'\ 11156\M[]\ 11157\\$1\ 11158\h'.2m' 11159.. 11160@endExample 11161 11162@item \D't @var{n}' 11163@cindex line thickness (@w{@code{\D't @dots{}'}}) 11164@cindex thickness of lines (@w{@code{\D't @dots{}'}}) 11165Set the current line thickness to @var{n}@tie{}machine units. A value of 11166zero selects the smallest available line thickness. A negative value 11167makes the line thickness proportional to the current point size (this is 11168the default behaviour of @acronym{AT&T} @code{troff}). 11169 11170Despite of being silly, the current point is moved horizontally to the 11171right by@tie{}@var{n}. 11172 11173@item \D'F@var{scheme} @var{color_components}' 11174@cindex unnamed fill colors (@code{\D'F@dots{}'}) 11175@cindex fill colors, unnamed (@code{\D'F@dots{}'}) 11176@cindex colors, fill, unnamed (@code{\D'F@dots{}'}) 11177Change current fill color. @var{scheme} is a single letter denoting the 11178color scheme: @samp{r} (rgb), @samp{c} (cmy), @samp{k} (cmyk), @samp{g} 11179(gray), or @samp{d} (default color). The color components use exactly 11180the same syntax as in the @code{defcolor} request (@pxref{Colors}); the 11181command @code{\D'Fd'} doesn't take an argument. 11182 11183@emph{No} position changing! 11184 11185Examples: 11186 11187@Example 11188@endExample 11189\D'Fg .3' \" same gray as \D'f 700' 11190\D'Fr #0000ff' \" blue 11191@end table 11192@endDefesc 11193 11194@xref{Graphics Commands}. 11195 11196@Defesc {\\b, ', string, '} 11197@cindex pile, glyph (@code{\b}) 11198@cindex glyph pile (@code{\b}) 11199@cindex stacking glyphs (@code{\b}) 11200@dfn{Pile} a sequence of glyphs vertically, and center it vertically 11201on the current line. Use it to build large brackets and braces. 11202 11203Here an example how to create a large opening brace: 11204 11205@Example 11206\b'\[lt]\[bv]\[lk]\[bv]\[lb]' 11207@endExample 11208 11209@cindex @code{\b}, limitations 11210@cindex limitations of @code{\b} escape 11211The first glyph is on the top, the last glyph in @var{string} is 11212at the bottom. Note that @code{gtroff} separates the glyphs 11213vertically by 1@dmn{m}, and the whole object is centered 0.5@dmn{m} 11214above the current baseline; the largest glyph width is used as the 11215width for the whole object. This rather unflexible positioning 11216algorithm doesn't work with @option{-Tdvi} since the bracket pieces vary 11217in height for this device. Instead, use the @code{eqn} preprocessor. 11218 11219@xref{Manipulating Spacing}, how to adjust the vertical spacing with 11220the @code{\x} escape. 11221@endDefesc 11222 11223 11224@c ===================================================================== 11225 11226@node Traps, Diversions, Drawing Requests, gtroff Reference 11227@section Traps 11228@cindex traps 11229 11230@dfn{Traps} are locations, which, when reached, call a specified 11231macro. These traps can occur at a given location on the page, at a 11232given location in the current diversion, at a blank line, 11233after a certain number of input lines, or at the end of input. 11234 11235@cindex planting a trap 11236@cindex trap, planting 11237Setting a trap is also called @dfn{planting}. 11238@cindex trap, springing 11239@cindex springing a trap 11240It is also said that a trap is @dfn{sprung} if the associated macro 11241is executed. 11242 11243@menu 11244* Page Location Traps:: 11245* Diversion Traps:: 11246* Input Line Traps:: 11247* Blank Line Traps:: 11248* End-of-input Traps:: 11249@end menu 11250 11251@c --------------------------------------------------------------------- 11252 11253@node Page Location Traps, Diversion Traps, Traps, Traps 11254@subsection Page Location Traps 11255@cindex page location traps 11256@cindex traps, page location 11257 11258@dfn{Page location traps} perform an action when @code{gtroff} 11259reaches or passes a certain vertical location on the page. Page 11260location traps have a variety of purposes, including: 11261 11262@itemize 11263@item 11264setting headers and footers 11265 11266@item 11267setting body text in multiple columns 11268 11269@item 11270setting footnotes 11271@end itemize 11272 11273@DefreqList {vpt, flag} 11274@DefregListEnd {.vpt} 11275@cindex enabling vertical position traps (@code{vpt}) 11276@cindex vertical position traps, enabling (@code{vpt}) 11277@cindex vertical position trap enable register (@code{.vpt}) 11278Enable vertical position traps if @var{flag} is non-zero, or disables 11279them otherwise. Vertical position traps are traps set by the @code{wh} 11280or @code{dt} requests. Traps set by the @code{it} request are not 11281vertical position traps. The parameter that controls whether vertical 11282position traps are enabled is global. Initially vertical position traps 11283are enabled. The current setting of this is available in the 11284@code{.vpt} read-only number register. 11285 11286Note that a page can't be ejected if @code{vpt} is set to zero. 11287@endDefreq 11288 11289@Defreq {wh, dist [@Var{macro}]} 11290Set a page location trap. Non-negative values for @var{dist} set 11291the trap relative to the top of the page; negative values set 11292the trap relative to the bottom of the page. Default scaling 11293indicator is @samp{v}. 11294 11295@var{macro} is the name of the macro to execute when the 11296trap is sprung. If @var{macro} is missing, remove the first trap 11297(if any) at @var{dist}. 11298 11299@cindex page headers 11300@cindex page footers 11301@cindex headers 11302@cindex footers 11303The following is a simple example of how many macro packages 11304set headers and footers. 11305 11306@Example 11307.de hd \" Page header 11308' sp .5i 11309. tl 'Title''date' 11310' sp .3i 11311.. 11312. 11313.de fo \" Page footer 11314' sp 1v 11315. tl ''%'' 11316' bp 11317.. 11318. 11319.wh 0 hd \" trap at top of the page 11320.wh -1i fo \" trap one inch from bottom 11321@endExample 11322 11323A trap at or below the bottom of the page is ignored; it can be made 11324active by either moving it up or increasing the page length so that the 11325trap is on the page. 11326 11327It is possible to have more than one trap at the same location; to do so, 11328the traps must be defined at different locations, then moved together with 11329the @code{ch} request; otherwise the second trap would replace the first 11330one. Earlier defined traps hide later defined traps if moved to the same 11331position (the many empty lines caused by the @code{bp} request are omitted 11332in the following example): 11333 11334@Example 11335.de a 11336. nop a 11337.. 11338.de b 11339. nop b 11340.. 11341.de c 11342. nop c 11343.. 11344. 11345.wh 1i a 11346.wh 2i b 11347.wh 3i c 11348.bp 11349 @result{} a b c 11350@endExample 11351@Example 11352.ch b 1i 11353.ch c 1i 11354.bp 11355 @result{} a 11356@endExample 11357@Example 11358.ch a 0.5i 11359.bp 11360 @result{} a b 11361@endExample 11362@endDefreq 11363 11364@Defreg {.t} 11365@cindex distance to next trap register (@code{.t}) 11366@cindex trap, distance, register (@code{.t}) 11367A read-only number register holding the distance to the next trap. 11368 11369If there are no traps between the current position and the bottom of the 11370page, it contains the distance to the page bottom. In a diversion, the 11371distance to the page bottom is infinite (the returned value is the biggest 11372integer which can be represented in @code{groff}) if there are no diversion 11373traps. 11374@endDefreg 11375 11376@Defreq {ch, macro [@Var{dist}]} 11377@cindex changing trap location (@code{ch}) 11378@cindex trap, changing location (@code{ch}) 11379Change the location of a trap. 11380The first argument is the name of the macro to be invoked at 11381the trap, and the second argument is the new location for the trap 11382(note that the parameters are specified in opposite order as in the 11383@code{wh} request). This is useful for building up footnotes in a 11384diversion to allow more space at the bottom of the page for them. 11385 11386Default scaling indicator for @var{dist} is @samp{v}. If @var{dist} 11387is missing, the trap is removed. 11388 11389@c XXX 11390 11391@ignore 11392@Example 11393... (simplified) footnote example ... 11394@endExample 11395@end ignore 11396@endDefreq 11397 11398@Defreg {.ne} 11399The read-only number register @code{.ne} contains the amount of space 11400that was needed in the last @code{ne} request that caused a trap to be 11401sprung. Useful in conjunction with the @code{.trunc} register. 11402@xref{Page Control}, for more information. 11403 11404Since the @code{.ne} register is only set by traps it doesn't make 11405much sense to use it outside of trap macros. 11406@endDefreg 11407 11408@Defreg {.trunc} 11409@cindex @code{ne} request, and the @code{.trunc} register 11410@cindex truncated vertical space register (@code{.trunc}) 11411A read-only register containing the amount of vertical space truncated 11412by the most recently sprung vertical position trap, or, if the trap was 11413sprung by an @code{ne} request, minus the amount of vertical motion 11414produced by the @code{ne} request. In other words, at the point a trap 11415is sprung, it represents the difference of what the vertical position 11416would have been but for the trap, and what the vertical position 11417actually is. 11418 11419Since the @code{.trunc} register is only set by traps and it doesn't make 11420much sense to use it outside of trap macros. 11421@endDefreg 11422 11423@Defreg {.pe} 11424@cindex @code{bp} request, and traps (@code{.pe}) 11425@cindex traps, sprung by @code{bp} request (@code{.pe}) 11426@cindex page ejecting register (@code{.pe}) 11427A read-only register which is set to@tie{}1 while a page is ejected with 11428the @code{bp} request (or by the end of input). 11429 11430Outside of traps this register is always zero. In the following example, 11431only the second call to@tie{}@code{x} is caused by @code{bp}. 11432 11433@Example 11434.de x 11435\&.pe=\\n[.pe] 11436.br 11437.. 11438.wh 1v x 11439.wh 4v x 11440A line. 11441.br 11442Another line. 11443.br 11444 @result{} A line. 11445 .pe=0 11446 Another line. 11447 11448 .pe=1 11449@endExample 11450@endDefreg 11451 11452@cindex diversions, and traps 11453@cindex traps, and diversions 11454An important fact to consider while designing macros is that diversions and 11455traps do not interact normally. For example, if a trap invokes a header 11456macro (while outputting a diversion) which tries to change the font on the 11457current page, the effect will not be visible before the diversion has 11458completely been printed (except for input protected with @code{\!} or 11459@code{\?}) since the data in the diversion is already formatted. In most 11460cases, this is not the expected behaviour. 11461 11462@c --------------------------------------------------------------------- 11463 11464@node Diversion Traps, Input Line Traps, Page Location Traps, Traps 11465@subsection Diversion Traps 11466@cindex diversion traps 11467@cindex traps, diversion 11468 11469@Defreq {dt, dist macro} 11470@cindex @code{.t} register, and diversions 11471@cindex setting diversion trap (@code{dt}) 11472@cindex diversion trap, setting (@code{dt}) 11473@cindex trap, diversion, setting (@code{dt}) 11474Set a trap @emph{within} a diversion. 11475@var{dist} is the location of the trap 11476(identical to the @code{wh} request; default scaling indicator is 11477@samp{v}) and @var{macro} is the name of the macro to be invoked. The 11478number register @code{.t} still works within diversions. 11479@xref{Diversions}, for more information. 11480@endDefreq 11481 11482@c --------------------------------------------------------------------- 11483 11484@node Input Line Traps, Blank Line Traps, Diversion Traps, Traps 11485@subsection Input Line Traps 11486@cindex input line traps 11487@cindex traps, input line 11488 11489@DefreqList {it, n macro} 11490@DefreqItem {itc, n macro} 11491@cindex setting input line trap (@code{it}) 11492@cindex input line trap, setting (@code{it}) 11493@cindex trap, input line, setting (@code{it}) 11494Set an input line trap. 11495@var{n}@tie{}is the number of lines of input which may be read before 11496springing the trap, @var{macro} is the macro to be invoked. 11497Request lines are not counted as input lines. 11498 11499For example, one possible use is to have a macro which prints the 11500next @var{n}@tie{}lines in a bold font. 11501 11502@Example 11503.de B 11504. it \\$1 B-end 11505. ft B 11506.. 11507. 11508.de B-end 11509. ft R 11510.. 11511@endExample 11512 11513@cindex input line traps and interrupted lines (@code{itc}) 11514@cindex interrupted lines and input line traps (@code{itc}) 11515@cindex traps, input line, and interrupted lines (@code{itc}) 11516@cindex lines, interrupted, and input line traps (@code{itc}) 11517The @code{itc} request is identical 11518except that an interrupted text line (ending with @code{\c}) 11519is not counted as a separate line. 11520 11521Both requests are associated with the current environment 11522(@pxref{Environments}); switching to another environment disables the 11523current input trap, and going back reactivates it, restoring the number 11524of already processed lines. 11525@endDefreq 11526 11527@c --------------------------------------------------------------------- 11528 11529@node Blank Line Traps, End-of-input Traps, Input Line Traps, Traps 11530@subsection Blank Line Traps 11531@cindex blank line traps 11532@cindex traps, blank line 11533 11534@Defreq {blm, macro} 11535@cindex blank line macro (@code{blm}) 11536Set a blank line trap. 11537@code{gtroff} executes @var{macro} when it encounters a blank line in 11538the input file. 11539@endDefreq 11540 11541@c --------------------------------------------------------------------- 11542 11543@node End-of-input Traps, , Blank Line Traps, Traps 11544@subsection End-of-input Traps 11545@cindex end-of-input traps 11546@cindex traps, end-of-input 11547 11548@Defreq {em, macro} 11549@cindex setting end-of-input trap (@code{em}) 11550@cindex end-of-input trap, setting (@code{em}) 11551@cindex trap, end-of-input, setting (@code{em}) 11552@cindex end-of-input macro (@code{em}) 11553@cindex macro, end-of-input (@code{em}) 11554Set a trap at the end of input. @var{macro} is executed after the 11555last line of the input file has been processed. 11556 11557For example, if the document had to have a section at the bottom of the 11558last page for someone to approve it, the @code{em} request could be 11559used. 11560 11561@Example 11562.de approval 11563. ne 5v 11564. sp |(\\n[.t] - 6v) 11565. in +4i 11566. lc _ 11567. br 11568Approved:\t\a 11569. sp 11570Date:\t\t\a 11571.. 11572. 11573.em approval 11574@endExample 11575@endDefreq 11576 11577 11578@c ===================================================================== 11579 11580@node Diversions, Environments, Traps, gtroff Reference 11581@section Diversions 11582@cindex diversions 11583 11584In @code{gtroff} it is possible to @dfn{divert} text into a named 11585storage area. Due to the similarity to defining macros it is sometimes 11586said to be stored in a macro. This is used for saving text for output 11587at a later time, which is useful for keeping blocks of text on the same 11588page, footnotes, tables of contents, and indices. 11589 11590@cindex top-level diversion 11591@cindex diversion, top-level 11592For orthogonality it is said that @code{gtroff} is in the @dfn{top-level 11593diversion} if no diversion is active (i.e., the data is diverted to the 11594output device). 11595 11596@DefreqList {di, macro} 11597@DefreqListEnd {da, macro} 11598@cindex beginning diversion (@code{di}) 11599@cindex diversion, beginning (@code{di}) 11600@cindex ending diversion (@code{di}) 11601@cindex diversion, ending (@code{di}) 11602@cindex appending to a diversion (@code{da}) 11603@cindex diversion, appending (@code{da}) 11604Begin a diversion. Like the @code{de} 11605request, it takes an argument of a macro name to divert subsequent text 11606into. The @code{da} macro appends to an existing diversion. 11607 11608@code{di} or @code{da} without an argument ends the diversion. 11609@endDefreq 11610 11611@DefreqList {box, macro} 11612@DefreqListEnd {boxa, macro} 11613Begin (or appends to) a diversion like the 11614@code{di} and @code{da} requests. 11615The difference is that @code{box} and @code{boxa} 11616do not include a partially-filled line in the diversion. 11617 11618Compare this: 11619 11620@Example 11621Before the box. 11622.box xxx 11623In the box. 11624.br 11625.box 11626After the box. 11627.br 11628 @result{} Before the box. After the box. 11629.xxx 11630 @result{} In the box. 11631@endExample 11632 11633@noindent 11634with this: 11635 11636@Example 11637Before the diversion. 11638.di yyy 11639In the diversion. 11640.br 11641.di 11642After the diversion. 11643.br 11644 @result{} After the diversion. 11645.yyy 11646 @result{} Before the diversion. In the diversion. 11647@endExample 11648 11649@code{box} or @code{boxa} without an argument ends the diversion. 11650@endDefreq 11651 11652@DefregList {.z} 11653@DefregListEnd {.d} 11654@cindex @code{nl} register, and @code{.d} 11655@cindex nested diversions 11656@cindex diversion, nested 11657@cindex diversion name register (@code{.z}) 11658@cindex vertical position in diversion register (@code{.d}) 11659@cindex position, vertical, in diversion, register (@code{.d}) 11660@cindex diversion, vertical position in, register (@code{.d}) 11661Diversions may be nested. The read-only number register @code{.z} 11662contains the name of the current diversion (this is a string-valued 11663register). The read-only number register @code{.d} contains the current 11664vertical place in the diversion. If not in a diversion it is the same 11665as register @code{nl}. 11666@endDefreg 11667 11668@Defreg {.h} 11669@cindex high-water mark register (@code{.h}) 11670@cindex mark, high-water, register (@code{.h}) 11671@cindex position of lowest text line (@code{.h}) 11672@cindex text line, position of lowest (@code{.h}) 11673The @dfn{high-water mark} on the current page. It corresponds to the 11674text baseline of the lowest line on the page. This is a read-only 11675register. 11676 11677@Example 11678.tm .h==\n[.h], nl==\n[nl] 11679 @result{} .h==0, nl==-1 11680This is a test. 11681.br 11682.sp 2 11683.tm .h==\n[.h], nl==\n[nl] 11684 @result{} .h==40, nl==120 11685@endExample 11686 11687@cindex @code{.h} register, difference to @code{nl} 11688@cindex @code{nl} register, difference to @code{.h} 11689@noindent 11690As can be seen in the previous example, empty lines are not considered 11691in the return value of the @code{.h} register. 11692@endDefreg 11693 11694@DefregList {dn} 11695@DefregListEnd {dl} 11696@cindex @code{dn} register, and @code{da} (@code{boxa}) 11697@cindex @code{dl} register, and @code{da} (@code{boxa}) 11698@cindex @code{da} request, and @code{dn} (@code{dl}) 11699@cindex @code{boxa} request, and @code{dn} (@code{dl}) 11700After completing a diversion, the read-write number registers @code{dn} 11701and @code{dl} contain the vertical and horizontal size of the diversion. 11702Note that only the just processed lines are counted: For the computation 11703of @code{dn} and @code{dl}, the requests @code{da} and @code{boxa} are 11704handled as if @code{di} and @code{box} had been used -- lines which have 11705been already stored in a macro are not taken into account. 11706 11707@Example 11708.\" Center text both horizontally & vertically 11709. 11710.\" Enclose macro definitions in .eo and .ec 11711.\" to avoid the doubling of the backslash 11712.eo 11713.\" macro .(c starts centering mode 11714.de (c 11715. br 11716. ev (c 11717. evc 0 11718. in 0 11719. nf 11720. di @@c 11721.. 11722@endExample 11723@Example 11724.\" macro .)c terminates centering mode 11725.de )c 11726. br 11727. ev 11728. di 11729. nr @@s (((\n[.t]u - \n[dn]u) / 2u) - 1v) 11730. sp \n[@@s]u 11731. ce 1000 11732. @@c 11733. ce 0 11734. sp \n[@@s]u 11735. br 11736. fi 11737. rr @@s 11738. rm @@s 11739. rm @@c 11740.. 11741.\" End of macro definitions, restore escape mechanism 11742.ec 11743@endExample 11744@endDefreg 11745 11746@DefescList {\\!, , , } 11747@DefescListEnd {\\?, , anything, \\?} 11748@cindex transparent output (@code{\!}, @code{\?}) 11749@cindex output, transparent (@code{\!}, @code{\?}) 11750Prevent requests, macros, and escapes from being 11751interpreted when read into a diversion. Both escapes take the given text 11752and @dfn{transparently} embed it into the diversion. This is useful for 11753macros which shouldn't be invoked until the diverted text is actually 11754output. 11755 11756The @code{\!} escape transparently embeds text up to 11757and including the end of the line. 11758The @code{\?} escape transparently embeds text until the next 11759occurrence of the @code{\?} escape. Example: 11760 11761@Example 11762\?@var{anything}\? 11763@endExample 11764 11765@noindent 11766@var{anything} may not contain newlines; use @code{\!} to embed 11767newlines in a diversion. The escape sequence @code{\?} is also 11768recognized in copy mode and turned into a single internal code; it is 11769this code that terminates @var{anything}. Thus the following example 11770prints@tie{}4. 11771 11772@Example 11773.nr x 1 11774.nf 11775.di d 11776\?\\?\\\\?\\\\\\\\nx\\\\?\\?\? 11777.di 11778.nr x 2 11779.di e 11780.d 11781.di 11782.nr x 3 11783.di f 11784.e 11785.di 11786.nr x 4 11787.f 11788@endExample 11789 11790Both escapes read the data in copy mode. 11791 11792@cindex @code{\!}, in top-level diversion 11793@cindex top-level diversion, and @code{\!} 11794@cindex diversion, top-level, and @code{\!} 11795If @code{\!} is used in the top-level diversion, its argument is 11796directly embedded into the @code{gtroff} intermediate output. This can 11797be used for example to control a postprocessor which processes the data 11798before it is sent to the device driver. 11799 11800@cindex @code{\?}, in top-level diversion 11801@cindex top-level diversion, and @code{\?} 11802@cindex diversion, top-level, and @code{\?} 11803The @code{\?} escape used in the top-level diversion produces no output 11804at all; its argument is simply ignored. 11805@endDefesc 11806 11807@cindex @code{\!}, and @code{output} 11808@cindex @code{output} request, and @code{\!} 11809@Defreq {output, string} 11810Emit @var{string} directly to the @code{gtroff} intermediate output 11811(subject to copy-mode interpretation); this is similar to @code{\!} used 11812at the top level. An initial double quote in @var{string} is stripped off 11813to allow initial blanks. 11814 11815This request can't be used before the first page has started -- if you get 11816an error, simply insert @code{.br} before the @code{output} request. 11817 11818Without argument, @code{output} is ignored. 11819 11820Use with caution! It is normally only needed for mark-up used by a 11821postprocessor which does something with the output before sending it to 11822the output device, filtering out @var{string} again. 11823@endDefreq 11824 11825@Defreq {asciify, div} 11826@cindex unformatting diversions (@code{asciify}) 11827@cindex diversion, unformatting (@code{asciify}) 11828@cindex @code{trin} request, and @code{asciify} 11829@dfn{Unformat} the diversion specified by @var{div} 11830in such a way that @acronym{ASCII} characters, characters translated with 11831the @code{trin} request, space characters, and some escape sequences that 11832were formatted and diverted are treated like ordinary input 11833characters when the diversion is reread. It can be also used for gross 11834hacks; for example, the following sets register@tie{}@code{n} to@tie{}1. 11835 11836@Example 11837.tr @@. 11838.di x 11839@@nr n 1 11840.br 11841.di 11842.tr @@@@ 11843.asciify x 11844.x 11845@endExample 11846 11847@xref{Copy-in Mode}. 11848@endDefreq 11849 11850@Defreq {unformat, div} 11851Like @code{asciify}, unformat the specified diversion. 11852However, @code{unformat} only unformats spaces and tabs 11853between words. 11854Unformatted tabs are treated as input tokens, 11855and spaces are stretchable again. 11856 11857The vertical size of lines is not preserved; glyph information (font, 11858font size, space width, etc.)@: is retained. 11859@endDefreq 11860 11861 11862@c ===================================================================== 11863 11864@node Environments, Suppressing output, Diversions, gtroff Reference 11865@section Environments 11866@cindex environments 11867 11868It happens frequently that some text should be printed in a certain 11869format regardless of what may be in effect at the time, for example, in 11870a trap invoked macro to print headers and footers. To solve this 11871@code{gtroff} processes text in @dfn{environments}. An 11872environment contains most of the parameters that control text 11873processing. It is possible to switch amongst these environments; by 11874default @code{gtroff} processes text in environment@tie{}0. The 11875following is the information kept in an environment. 11876 11877@itemize @bullet 11878@item 11879font parameters (size, family, style, glyph height and slant, space 11880and sentence space size) 11881 11882@item 11883page parameters (line length, title length, vertical spacing, 11884line spacing, indentation, line numbering, centering, right-justifying, 11885underlining, hyphenation data) 11886 11887@item 11888fill and adjust mode 11889 11890@item 11891tab stops, tab and leader characters, escape character, 11892no-break and hyphen indicators, margin character data 11893 11894@item 11895partially collected lines 11896 11897@item 11898input traps 11899 11900@item 11901drawing and fill colours 11902@end itemize 11903 11904These environments may be given arbitrary names (see @ref{Identifiers}, 11905for more info). Old versions of @code{troff} only had environments 11906named @samp{0}, @samp{1}, and @samp{2}. 11907 11908@DefreqList {ev, [@Var{env}]} 11909@DefregListEnd {.ev} 11910@cindex switching environments (@code{ev}) 11911@cindex environment, switching (@code{ev}) 11912@cindex environment number/name register (@code{.ev}) 11913Switch to another environment. The argument @var{env} is the name of 11914the environment to switch to. With no argument, @code{gtroff} switches 11915back to the previous environment. There is no limit on the number of 11916named environments; they are created the first time that they are 11917referenced. The @code{.ev} read-only register contains the name or 11918number of the current environment. This is a string-valued register. 11919 11920Note that a call to @code{ev} (with argument) pushes the previously 11921active environment onto a stack. If, say, environments @samp{foo}, 11922@samp{bar}, and @samp{zap} are called (in that order), the first 11923@code{ev} request without parameter switches back to environment 11924@samp{bar} (which is popped off the stack), and a second call 11925switches back to environment @samp{foo}. 11926 11927Here is an example: 11928 11929@Example 11930.ev footnote-env 11931.fam N 11932.ps 6 11933.vs 8 11934.ll -.5i 11935.ev 11936 11937... 11938 11939.ev footnote-env 11940\(dg Note the large, friendly letters. 11941.ev 11942@endExample 11943@endDefreq 11944 11945@Defreq {evc, env} 11946@cindex copying environment (@code{evc}) 11947@cindex environment, copying (@code{evc}) 11948Copy the environment @var{env} into the current environment. 11949 11950The following environment data is not copied: 11951 11952@itemize @bullet 11953@item 11954Partially filled lines. 11955 11956@item 11957The status whether the previous line was interrupted. 11958 11959@item 11960The number of lines still to center, or to right-justify, or to underline 11961(with or without underlined spaces); they are set to zero. 11962 11963@item 11964The status whether a temporary indent is active. 11965 11966@item 11967Input traps and its associated data. 11968 11969@item 11970Line numbering mode is disabled; it can be reactivated with 11971@w{@samp{.nm +0}}. 11972 11973@item 11974The number of consecutive hyphenated lines (set to zero). 11975@end itemize 11976@endDefreq 11977 11978@DefregList {.w} 11979@DefregItem {.cht} 11980@DefregItem {.cdp} 11981@DefregListEnd {.csk} 11982@cindex environment, dimensions of last glyph (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 11983@cindex width, of last glyph (@code{.w}) 11984@cindex height, of last glyph (@code{.cht}) 11985@cindex depth, of last glyph (@code{.cdp}) 11986@cindex skew, of last glyph (@code{.csk}) 11987@cindex last glyph, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 11988@cindex glyph, last, dimensions (@code{.w}, @code{.cht}, @code{.cdp}, @code{.csk}) 11989The @code{\n[.w]} register contains the 11990width of the last glyph added to the current environment. 11991 11992The @code{\n[.cht]} register contains the 11993height of the last glyph added to the current environment. 11994 11995The @code{\n[.cdp]} register contains the 11996depth of the last glyph added to the current environment. 11997It is positive for glyphs extending below the baseline. 11998 11999The @code{\n[.csk]} register contains the 12000@dfn{skew} (how far to the right of the glyph's center 12001that @code{gtroff} should place an accent) 12002of the last glyph added to the current environment. 12003@endDefreg 12004 12005@Defreg {.n} 12006@cindex environment, previous line length (@code{.n}) 12007@cindex line length, previous (@code{.n}) 12008@cindex length of previous line (@code{.n}) 12009@cindex previous line length (@code{.n}) 12010The @code{\n[.n]} register contains the 12011length of the previous output line in the current environment. 12012@endDefreg 12013 12014 12015@c ===================================================================== 12016 12017@node Suppressing output, Colors, Environments, gtroff Reference 12018@section Suppressing output 12019 12020@Defesc {\\O, , num, } 12021@cindex suppressing output (@code{\O}) 12022@cindex output, suppressing (@code{\O}) 12023Disable or enable output depending on the value of @var{num}: 12024 12025@table @samp 12026@item \O0 12027Disable any glyphs from being emitted to the device driver, provided that 12028the escape occurs at the outer level (see @code{\O[3]} and @code{\O[4]}). 12029Motion is not suppressed so effectively @code{\O[0]} means @emph{pen up}. 12030 12031@item \O1 12032Enable output of glyphs, provided that the escape occurs at the outer 12033level. 12034@end table 12035 12036@vindex opminx 12037@vindex opminy 12038@vindex opmaxx 12039@vindex opmaxy 12040@code{\O0} and @code{\O1} also reset the four registers @samp{opminx}, 12041@samp{opminy}, @samp{opmaxx}, and @samp{opmaxy} to @minus{}1. 12042@xref{Register Index}. These four registers mark the top left and 12043bottom right hand corners of a box which encompasses all written glyphs. 12044 12045For example the input text: 12046 12047@Example 12048Hello \O[0]world \O[1]this is a test. 12049@endExample 12050 12051@noindent 12052produces the following output: 12053 12054@Example 12055Hello this is a test. 12056@endExample 12057 12058@table @samp 12059@item \O2 12060Provided that the escape occurs at the outer level, enable output of 12061glyphs and also write out to @code{stderr} the page number and four 12062registers encompassing the glyphs previously written since the last call 12063to @code{\O}. 12064 12065@item \O3 12066Begin a nesting level. At start-up, @code{gtroff} is at outer level. 12067 12068@item \O4 12069End a nesting level. 12070 12071@item \O[5@var{P}@var{filename}] 12072This escape is @code{grohtml} specific. Provided that this escape 12073occurs at the outer nesting level write the @code{filename} to 12074@code{stderr}. The position of the image, @var{P}, must be specified 12075and must be one of @code{l}, @code{r}, @code{c}, or@tie{}@code{i} (left, 12076right, centered, inline). @var{filename} will be associated with the 12077production of the next inline image. 12078@end table 12079@endDefesc 12080 12081@c ===================================================================== 12082 12083@node Colors, I/O, Suppressing output, gtroff Reference 12084@section Colors 12085@cindex colors 12086 12087@DefreqList {color, [@Var{n}]} 12088@DefregListEnd {.color} 12089If @var{n} is missing or non-zero, activate colors (this is the default); 12090otherwise, turn it off. 12091 12092The read-only number register @code{.color} is@tie{}1 if colors are active, 120930@tie{}otherwise. 12094 12095Internally, @code{color} sets a global flag; it does not produce a token. 12096Similar to the @code{cp} request, you should use it at the beginning of 12097your document to control color output. 12098 12099Colors can be also turned off with the @option{-c} command line option. 12100@endDefreq 12101 12102@Defreq {defcolor, ident scheme color_components} 12103Define color with name @var{ident}. @var{scheme} can be one of the 12104following values: @code{rgb} (three components), @code{cmy} (three 12105components), @code{cmyk} (four components), and @code{gray} or 12106@code{grey} (one component). 12107 12108@cindex default color 12109@cindex color, default 12110Color components can be given either as a hexadecimal string or as 12111positive decimal integers in the range 0--65535. A hexadecimal string 12112contains all color components concatenated. It must start with either 12113@code{#} or @code{##}; the former specifies hex values in the range 121140--255 (which are internally multiplied by@tie{}257), the latter in the 12115range 0--65535. Examples: @code{#FFC0CB} (pink), @code{##ffff0000ffff} 12116(magenta). The default color name @c{default} can't be redefined; its 12117value is device-specific (usually black). It is possible that the 12118default color for @code{\m} and @code{\M} is not identical. 12119 12120@cindex @code{f} unit, and colors 12121@cindex unit, @code{f}, and colors 12122A new scaling indicator@tie{}@code{f} has been introduced which multiplies 12123its value by 65536; this makes it convenient to specify color components 12124as fractions in the range 0 to@tie{}1 (1f equals 65536u). Example: 12125 12126@Example 12127.defcolor darkgreen rgb 0.1f 0.5f 0.2f 12128@endExample 12129 12130Note that @code{f} is the default scaling indicator for the 12131@code{defcolor} request, thus the above statement is equivalent to 12132 12133@Example 12134.defcolor darkgreen rgb 0.1 0.5 0.2 12135@endExample 12136@endDefreq 12137 12138@DefescList {\\m, , c, } 12139@DefescItem {\\m, @lparen{}, co, } 12140@DefescListEnd {\\m, @lbrack{}, color, @rbrack} 12141Set drawing color. The following example shows how to turn the next four 12142words red. 12143 12144@Example 12145\m[red]these are in red\m[] and these words are in black. 12146@endExample 12147 12148The escape @code{\m[]} returns to the previous color. 12149 12150The drawing color is associated with the current environment 12151(@pxref{Environments}). 12152 12153Note that @code{\m} doesn't produce an input token in @code{gtroff}. 12154As a consequence, it can be used in requests like @code{mc} (which 12155expects a single character as an argument) to change the color on 12156the fly: 12157 12158@Example 12159.mc \m[red]x\m[] 12160@endExample 12161@endDefesc 12162 12163@DefescList {\\M, , c, } 12164@DefescItem {\\M, @lparen{}, co, } 12165@DefescListEnd {\\M, @lbrack{}, color, @rbrack} 12166Set background color for filled objects drawn with the 12167@code{\D'@dots{}'} commands. 12168 12169A red ellipse can be created with the following code: 12170 12171@Example 12172\M[red]\h'0.5i'\D'E 2i 1i'\M[] 12173@endExample 12174 12175The escape @code{\M[]} returns to the previous fill color. 12176 12177The fill color is associated with the current environment 12178(@pxref{Environments}). 12179 12180Note that @code{\M} doesn't produce an input token in @code{gtroff}. 12181@endDefesc 12182 12183 12184@c ===================================================================== 12185 12186@node I/O, Postprocessor Access, Colors, gtroff Reference 12187@section I/O 12188@cindex i/o 12189@cindex input and output requests 12190@cindex requests for input and output 12191@cindex output and input requests 12192 12193@code{gtroff} has several requests for including files: 12194 12195@Defreq {so, file} 12196@cindex including a file (@code{so}) 12197@cindex file, inclusion (@code{so}) 12198Read in the specified @var{file} and 12199includes it in place of the @code{so} request. This is quite useful for 12200large documents, e.g.@: keeping each chapter in a separate file. 12201@xref{gsoelim}, for more information. 12202 12203Since @code{gtroff} replaces the @code{so} request with the contents 12204of @code{file}, it makes a difference whether the data is terminated with 12205a newline or not: Assuming that file @file{xxx} contains the word 12206@samp{foo} without a final newline, this 12207 12208@Example 12209This is 12210.so xxx 12211bar 12212@endExample 12213 12214@noindent 12215yields @samp{This is foobar}. 12216@endDefreq 12217 12218@Defreq {pso, command} 12219Read the standard output from the specified @var{command} 12220and includes it in place of the @code{pso} request. 12221 12222@cindex safer mode 12223@cindex mode, safer 12224@cindex unsafe mode 12225@cindex mode, unsafe 12226This request causes an error if used in safer mode (which is the default). 12227Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12228mode. 12229 12230The comment regarding a final newline for the @code{so} request is valid 12231for @code{pso} also. 12232@endDefreq 12233 12234@Defreq {mso, file} 12235Identical to the @code{so} request except that @code{gtroff} searches for 12236the specified @var{file} in the same directories as macro files for the 12237the @option{-m} command line option. If the file name to be included 12238has the form @file{@var{name}.tmac} and it isn't found, @code{mso} tries 12239to include @file{tmac.@var{name}} and vice versa. 12240@endDefreq 12241 12242@DefreqList {trf, file} 12243@DefreqListEnd {cf, file} 12244@cindex transparent output (@code{cf}, @code{trf}) 12245@cindex output, transparent (@code{cf}, @code{trf}) 12246Transparently output the contents of @var{file}. Each line is output 12247as if it were preceded by @code{\!}; however, the lines are not subject 12248to copy mode interpretation. If the file does not end with a newline, 12249then a newline is added (@code{trf} only). For example, to define a 12250macro@tie{}@code{x} containing the contents of file@tie{}@file{f}, use 12251 12252@Example 12253.di x 12254.trf f 12255.di 12256@endExample 12257 12258Both @code{trf} and @code{cf}, when used in a diversion, 12259embeds an object in the diversion which, when reread, causes the 12260contents of @var{file} to be transparently copied through to the 12261output. In @acronym{UNIX} @code{troff}, the contents of @var{file} 12262is immediately copied through to the output regardless of whether there 12263is a current diversion; this behaviour is so anomalous that it must be 12264considered a bug. 12265 12266@cindex @code{trf} request, and invalid characters 12267@cindex characters, invalid for @code{trf} request 12268@cindex invalid characters for @code{trf} request 12269While @code{cf} copies the contents of @var{file} completely unprocessed, 12270@code{trf} disallows characters such as NUL that are not valid 12271@code{gtroff} input characters (@pxref{Identifiers}). 12272 12273Both requests cause a line break. 12274@endDefreq 12275 12276@Defreq {nx, [@Var{file}]} 12277@cindex processing next file (@code{nx}) 12278@cindex file, processing next (@code{nx}) 12279@cindex next file, processing (@code{nx}) 12280Force @code{gtroff} to continue processing of 12281the file specified as an argument. If no argument is given, immediately 12282jump to the end of file. 12283@endDefreq 12284 12285@Defreq {rd, [@Var{prompt} [@Var{arg1} @Var{arg2} @dots{}]]} 12286@cindex reading from standard input (@code{rd}) 12287@cindex standard input, reading from (@code{rd}) 12288@cindex input, standard, reading from (@code{rd}) 12289Read from standard input, and include what is read as though it 12290were part of the input file. Text is read until a blank line 12291is encountered. 12292 12293If standard input is a TTY input device (keyboard), write @var{prompt} 12294to standard error, followed by a colon (or send BEL for a beep if no 12295argument is given). 12296 12297Arguments after @var{prompt} are available for the input. For example, 12298the line 12299 12300@Example 12301.rd data foo bar 12302@endExample 12303 12304with the input @w{@samp{This is \$2.}} prints 12305 12306@Example 12307This is bar. 12308@endExample 12309@endDefreq 12310 12311@cindex form letters 12312@cindex letters, form 12313Using the @code{nx} and @code{rd} requests, 12314it is easy to set up form letters. The form 12315letter template is constructed like this, putting the following lines 12316into a file called @file{repeat.let}: 12317 12318@Example 12319.ce 12320\*(td 12321.sp 2 12322.nf 12323.rd 12324.sp 12325.rd 12326.fi 12327Body of letter. 12328.bp 12329.nx repeat.let 12330@endExample 12331 12332@cindex @code{ex} request, used with @code{nx} and @code{rd} 12333@noindent 12334When this is run, a file containing the following lines should be 12335redirected in. Note that requests included in this file are executed 12336as though they were part of the form letter. The last block of input 12337is the @code{ex} request which tells @code{groff} to stop processing. If 12338this was not there, @code{groff} would not know when to stop. 12339 12340@Example 12341Trent A. Fisher 12342708 NW 19th Av., #202 12343Portland, OR 97209 12344 12345Dear Trent, 12346 12347Len Adollar 123484315 Sierra Vista 12349San Diego, CA 92103 12350 12351Dear Mr. Adollar, 12352 12353.ex 12354@endExample 12355 12356@Defreq {pi, pipe} 12357Pipe the output of @code{gtroff} to the shell command(s) 12358specified by @var{pipe}. This request must occur before 12359@code{gtroff} has a chance to print anything. 12360 12361@cindex safer mode 12362@cindex mode, safer 12363@cindex unsafe mode 12364@cindex mode, unsafe 12365@code{pi} causes an error if used in safer mode (which is the default). 12366Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12367mode. 12368 12369Multiple calls to @code{pi} are allowed, acting as a chain. For example, 12370 12371@Example 12372.pi foo 12373.pi bar 12374... 12375@endExample 12376 12377is the same as @w{@samp{.pi foo | bar}}. 12378 12379@cindex @code{groff}, and @code{pi} request 12380@cindex @code{pi} request, and @code{groff} 12381Note that the intermediate output format of @code{gtroff} is piped to 12382the specified commands. Consequently, calling @code{groff} without the 12383@option{-Z} option normally causes a fatal error. 12384@endDefreq 12385 12386@DefreqList {sy, cmds} 12387@DefregListEnd {systat} 12388Execute the shell command(s) specified by @var{cmds}. The output is not 12389saved anyplace, so it is up to the user to do so. 12390 12391@cindex safer mode 12392@cindex mode, safer 12393@cindex unsafe mode 12394@cindex mode, unsafe 12395This request causes an error if used in safer mode (which is the default). 12396Use @code{groff}'s or @code{troff}'s @option{-U} option to activate unsafe 12397mode. 12398 12399For example, the following code fragment introduces the current time into a 12400document: 12401 12402@cindex time, current 12403@cindex current time 12404@pindex perl 12405@Example 12406.sy perl -e 'printf ".nr H %d\\n.nr M %d\\n.nr S %d\\n",\ 12407 (localtime(time))[2,1,0]' > /tmp/x\n[$$] 12408.so /tmp/x\n[$$] 12409.sy rm /tmp/x\n[$$] 12410\nH:\nM:\nS 12411@endExample 12412 12413@noindent 12414Note that this works by having the @code{perl} script (run by @code{sy}) 12415print out the @code{nr} requests which set the number registers 12416@code{H}, @code{M}, and @code{S}, and then reads those commands in with 12417the @code{so} request. 12418 12419For most practical purposes, the number registers @code{seconds}, 12420@code{minutes}, and @code{hours} which are initialized at start-up of 12421@code{gtroff} should be sufficient. Use the @code{af} request to get a 12422formatted output: 12423 12424@Example 12425.af hours 00 12426.af minutes 00 12427.af seconds 00 12428\n[hours]:\n[minutes]:\n[seconds] 12429@endExample 12430 12431@cindex @code{system()} return value register (@code{systat}) 12432The @code{systat} read-write number register contains the return value 12433of the @code{system()} function executed by the last @code{sy} request. 12434@endDefreq 12435 12436@DefreqList {open, stream file} 12437@DefreqListEnd {opena, stream file} 12438@cindex opening file (@code{open}) 12439@cindex file, opening (@code{open}) 12440@cindex appending to a file (@code{opena}) 12441@cindex file, appending to (@code{opena}) 12442Open the specified @var{file} for writing and 12443associates the specified @var{stream} with it. 12444 12445The @code{opena} request is like @code{open}, but if the file exists, 12446append to it instead of truncating it. 12447 12448@cindex safer mode 12449@cindex mode, safer 12450@cindex unsafe mode 12451@cindex mode, unsafe 12452Both @code{open} and @code{opena} cause an error if used in safer mode 12453(which is the default). Use @code{groff}'s or @code{troff}'s @option{-U} 12454option to activate unsafe mode. 12455@endDefreq 12456 12457@DefreqList {write, stream data} 12458@DefreqListEnd {writec, stream data} 12459@cindex copy-in mode, and @code{write} requests 12460@cindex mode, copy-in, and @code{write} requests 12461@cindex writing to file (@code{write}) 12462@cindex file, writing to (@code{write}) 12463Write to the file associated with the specified @var{stream}. 12464The stream must previously have 12465been the subject of an open request. The remainder of the line is 12466interpreted as the @code{ds} request reads its second argument: A 12467leading @samp{"} is stripped, and it is read in copy-in mode. 12468 12469The @code{writec} request is like @code{write}, but only 12470@code{write} appends a newline to the data. 12471@endDefreq 12472 12473@Defreq {writem, stream xx} 12474@cindex @code{asciify} request, and @code{writem} 12475Write the contents of the macro or string @var{xx} 12476to the file associated with the specified @var{stream}. 12477 12478@var{xx} is read in copy mode, i.e., already formatted elements are 12479ignored. Consequently, diversions must be unformatted with the 12480@code{asciify} request before calling @code{writem}. Usually, this 12481means a loss of information. 12482@endDefreq 12483 12484@Defreq {close, stream} 12485@cindex closing file (@code{close}) 12486@cindex file, closing (@code{close}) 12487Close the specified @var{stream}; 12488the stream is no longer an acceptable argument to the 12489@code{write} request. 12490 12491Here a simple macro to write an index entry. 12492 12493@Example 12494.open idx test.idx 12495. 12496.de IX 12497. write idx \\n[%] \\$* 12498.. 12499. 12500.IX test entry 12501. 12502.close idx 12503@endExample 12504@endDefreq 12505 12506@DefescList {\\V, , e, } 12507@DefescItem {\\V, @lparen{}, ev, } 12508@DefescListEnd {\\V, @lbrack{}, env, @rbrack} 12509Interpolate the contents of the specified environment variable 12510@var{env} (one-character name@tie{}@var{e}, two-character name @var{ev}) 12511as returned by the function @code{getenv}. @code{\V} is interpreted 12512in copy-in mode. 12513@endDefesc 12514 12515 12516@c ===================================================================== 12517 12518@node Postprocessor Access, Miscellaneous, I/O, gtroff Reference 12519@section Postprocessor Access 12520@cindex postprocessor access 12521@cindex access of postprocessor 12522 12523There are two escapes which give information directly to the 12524postprocessor. This is particularly useful for embedding 12525@sc{PostScript} into the final document. 12526 12527@Defesc {\\X, ', xxx, '} 12528Embeds its argument into the @code{gtroff} 12529output preceded with @w{@samp{x X}}. 12530 12531@cindex @code{\&}, in @code{\X} 12532@cindex @code{\)}, in @code{\X} 12533@cindex @code{\%}, in @code{\X} 12534@ifnotinfo 12535@cindex @code{\:}, in @code{\X} 12536@end ifnotinfo 12537@ifinfo 12538@cindex @code{\@r{<colon>}}, in @code{\X} 12539@end ifinfo 12540The escapes @code{\&}, @code{\)}, @code{\%}, and @code{\:} are ignored 12541within @code{\X}, @w{@samp{\ }} and @code{\~} are converted to single 12542space characters. All other escapes (except @code{\\} which produces a 12543backslash) cause an error. 12544 12545@kindex use_charnames_in_special 12546@pindex DESC@r{, and @code{use_charnames_in_special}} 12547@cindex @code{\X}, and special characters 12548If the @samp{use_charnames_in_special} keyword is set in the @file{DESC} 12549file, special characters no longer cause an error; the name @var{xx} is 12550represented as @samp{\(@var{xx})} in the @w{@samp{x X}} output command. 12551Additionally, the backslash is represented as @code{\\}. 12552 12553@samp{use_charnames_in_special} is currently used by @code{grohtml} only. 12554@endDefesc 12555 12556@DefescList {\\Y, , n, } 12557@DefescItem {\\Y, @lparen{}, nm, } 12558@DefescListEnd {\\Y, @lbrack{}, name, @rbrack} 12559This is approximately equivalent to @samp{\X'\*[@var{name}]'} 12560(one-character name@tie{}@var{n}, two-character name @var{nm}). 12561However, the contents of the string or macro @var{name} are not 12562interpreted; also it is permitted for @var{name} to have been defined 12563as a macro and thus contain newlines (it is not permitted for the 12564argument to @code{\X} to contain newlines). The inclusion of 12565newlines requires an extension to the @acronym{UNIX} @code{troff} 12566output format, and confuses drivers that do not know about this 12567extension (@pxref{Device Control Commands}). 12568@endDefesc 12569 12570@xref{Output Devices}. 12571 12572 12573@c ===================================================================== 12574 12575@node Miscellaneous, Gtroff Internals, Postprocessor Access, gtroff Reference 12576@section Miscellaneous 12577 12578This section documents parts of @code{gtroff} which cannot (yet) be 12579categorized elsewhere in this manual. 12580 12581@Defreq {nm, [@Var{start} [@Var{inc} [@Var{space} [@Var{indent}]]]]} 12582@cindex printing line numbers (@code{nm}) 12583@cindex line numbers, printing (@code{nm}) 12584@cindex numbers, line, printing (@code{nm}) 12585Print line numbers. 12586@var{start} is the line number of the @emph{next} 12587output line. @var{inc} indicates which line numbers are printed. 12588For example, the value@tie{}5 means to emit only line numbers which 12589are multiples of@tie{}5; this defaults to@tie{}1. @var{space} is the 12590space to be left between the number and the text; this defaults to 12591one digit space. The fourth argument is the indentation of the line 12592numbers, defaulting to zero. Both @var{space} and @var{indent} are 12593given as multiples of digit spaces; they can be negative also. 12594Without any arguments, line numbers are turned off. 12595 12596@code{gtroff} reserves three digit spaces for the line number (which is 12597printed right-justified) plus the amount given by @var{indent}; the 12598output lines are concatenated to the line numbers, separated by 12599@var{space}, and @emph{without} reducing the line length. Depending 12600on the value of the horizontal page offset (as set with the 12601@code{po} request), line numbers which are longer than the reserved 12602space stick out to the left, or the whole line is moved to the right. 12603 12604Parameters corresponding to missing arguments are not changed; any 12605non-digit argument (to be more precise, any argument starting with a 12606character valid as a delimiter for identifiers) is also treated as 12607missing. 12608 12609If line numbering has been disabled with a call to @code{nm} without 12610an argument, it can be reactivated with @samp{.nm +0}, using the 12611previously active line numbering parameters. 12612 12613The parameters of @code{nm} are associated with the current environment 12614(@pxref{Environments}). The current output line number is available 12615in the number register @code{ln}. 12616 12617@Example 12618.po 1m 12619.ll 2i 12620This test shows how line numbering works with groff. 12621.nm 999 12622This test shows how line numbering works with groff. 12623.br 12624.nm xxx 3 2 12625.ll -\w'0'u 12626This test shows how line numbering works with groff. 12627.nn 2 12628This test shows how line numbering works with groff. 12629@endExample 12630 12631@noindent 12632And here the result: 12633 12634@Example 12635 This test shows how 12636 line numbering works 12637 999 with groff. This 126381000 test shows how line 126391001 numbering works with 126401002 groff. 12641 This test shows how 12642 line numbering 12643 works with groff. 12644 This test shows how 126451005 line numbering 12646 works with groff. 12647@endExample 12648@endDefreq 12649 12650@Defreq {nn, [@Var{skip}]} 12651Temporarily turn off line numbering. The argument is the number 12652of lines not to be numbered; this defaults to@tie{}1. 12653@endDefreq 12654 12655@Defreq {mc, glyph [@Var{dist}]} 12656@cindex margin glyph (@code{mc}) 12657@cindex glyph, for margins (@code{mc}) 12658Print a @dfn{margin character} to the right of the 12659text.@footnote{@dfn{Margin character} is a misnomer since it is an 12660output glyph.} The first argument is the glyph to be 12661printed. The second argument is the distance away from the right 12662margin. If missing, the previously set value is used; default is 1266310@dmn{pt}). For text lines that are too long (that is, longer than 12664the text length plus @var{dist}), the margin character is directly 12665appended to the lines. 12666 12667With no arguments the margin character is turned off. 12668If this occurs before a break, no margin character is printed. 12669 12670@cindex @code{tl} request, and @code{mc} 12671For empty lines and lines produced by the @code{tl} request no margin 12672character is emitted. 12673 12674The margin character is associated with the current environment 12675(@pxref{Environments}). 12676 12677@pindex nrchbar 12678@pindex changebar 12679This is quite useful for indicating text that has changed, and, in fact, 12680there are programs available for doing this (they are called 12681@code{nrchbar} and @code{changebar} and can be found in any 12682@samp{comp.sources.unix} archive. 12683 12684@Example 12685.ll 3i 12686.mc | 12687This paragraph is highlighted with a margin 12688character. 12689.sp 12690Note that vertical space isn't marked. 12691.br 12692\& 12693.br 12694But we can fake it with `\&'. 12695@endExample 12696 12697Result: 12698 12699@Example 12700This paragraph is highlighted | 12701with a margin character. | 12702 12703Note that vertical space isn't | 12704marked. | 12705 | 12706But we can fake it with `\&'. | 12707@endExample 12708@endDefreq 12709 12710@DefreqList {psbb, filename} 12711@DefregItem {llx} 12712@DefregItem {lly} 12713@DefregItem {urx} 12714@DefregListEnd {ury} 12715@cindex PostScript, bounding box 12716@cindex bounding box 12717Retrieve the bounding box of the PostScript image 12718found in @var{filename}. 12719The file must conform to 12720Adobe's @dfn{Document Structuring Conventions} (DSC); 12721the command searches for a @code{%%BoundingBox} comment 12722and extracts the bounding box values into the number registers 12723@code{llx}, @code{lly}, @code{urx}, and @code{ury}. 12724If an error occurs (for example, @code{psbb} cannot find 12725the @code{%%BoundingBox} comment), 12726it sets the four number registers to zero. 12727@endDefreq 12728 12729 12730@c ===================================================================== 12731 12732@node Gtroff Internals, Debugging, Miscellaneous, gtroff Reference 12733@section @code{gtroff} Internals 12734 12735@cindex input token 12736@cindex token, input 12737@cindex output node 12738@cindex node, output 12739@code{gtroff} processes input in three steps. One or more input 12740characters are converted to an @dfn{input token}.@footnote{Except the 12741escapes @code{\f}, @code{\F}, @code{\H}, @code{\m}, @code{\M}, @code{\R}, 12742@code{\s}, and @code{\S} which are processed immediately if not in 12743copy-in mode.} Then, one or more input tokens are converted to an 12744@dfn{output node}. Finally, output nodes are converted to the 12745intermediate output language understood by all output devices. 12746 12747Actually, before step one happens, @code{gtroff} converts certain 12748escape sequences into reserved input characters (not accessible by 12749the user); such reserved characters are used for other internal 12750processing also -- this is the very reason why not all characters 12751are valid input. @xref{Identifiers}, for more on this topic. 12752 12753For example, the input string @samp{fi\[:u]} is converted into a 12754character token @samp{f}, a character token @samp{i}, and a special 12755token @samp{:u} (representing u@tie{}umlaut). Later on, the character 12756tokens @samp{f} and @samp{i} are merged to a single output node 12757representing the ligature glyph @samp{fi} (provided the current font 12758has a glyph for this ligature); the same happens with @samp{:u}. All 12759output glyph nodes are `processed' which means that they are invariably 12760associated with a given font, font size, advance width, etc. During 12761the formatting process, @code{gtroff} itself adds various nodes to 12762control the data flow. 12763 12764Macros, diversions, and strings collect elements in two chained lists: 12765a list of input tokens which have been passed unprocessed, and a list 12766of output nodes. Consider the following the diversion. 12767 12768@Example 12769.di xxx 12770a 12771\!b 12772c 12773.br 12774.di 12775@endExample 12776 12777@noindent 12778It contains these elements. 12779 12780@multitable {@i{vertical size node}} {token list} {element number} 12781@item node list @tab token list @tab element number 12782 12783@item @i{line start node} @tab --- @tab 1 12784@item @i{glyph node @code{a}} @tab --- @tab 2 12785@item @i{word space node} @tab --- @tab 3 12786@item --- @tab @code{b} @tab 4 12787@item --- @tab @code{\n} @tab 5 12788@item @i{glyph node @code{c}} @tab --- @tab 6 12789@item @i{vertical size node} @tab --- @tab 7 12790@item @i{vertical size node} @tab --- @tab 8 12791@item --- @tab @code{\n} @tab 9 12792@end multitable 12793 12794@cindex @code{\v}, internal representation 12795@noindent 12796Elements 1, 7, and@tie{}8 are inserted by @code{gtroff}; the latter two 12797(which are always present) specify the vertical extent of the last 12798line, possibly modified by @code{\x}. The @code{br} request finishes 12799the current partial line, inserting a newline input token which is 12800subsequently converted to a space when the diversion is reread. Note 12801that the word space node has a fixed width which isn't stretchable 12802anymore. To convert horizontal space nodes back to input tokens, use 12803the @code{unformat} request. 12804 12805Macros only contain elements in the token list (and the node list is 12806empty); diversions and strings can contain elements in both lists. 12807 12808Note that the @code{chop} request simply reduces the number of elements in a 12809macro, string, or diversion by one. Exceptions are @dfn{compatibility save} 12810and @dfn{compatibility ignore} input tokens which are ignored. The 12811@code{substring} request also ignores those input tokens. 12812 12813Some requests like @code{tr} or @code{cflags} work on glyph 12814identifiers only; this means that the associated glyph can be changed 12815without destroying this association. This can be very helpful for 12816substituting glyphs. In the following example, we assume that 12817glyph @samp{foo} isn't available by default, so we provide a 12818substitution using the @code{fchar} request and map it to input 12819character @samp{x}. 12820 12821@Example 12822.fchar \[foo] foo 12823.tr x \[foo] 12824@endExample 12825 12826@noindent 12827Now let us assume that we install an additional special font 12828@samp{bar} which has glyph @samp{foo}. 12829 12830@Example 12831.special bar 12832.rchar \[foo] 12833@endExample 12834 12835@noindent 12836Since glyphs defined with @code{fchar} are searched before glyphs 12837in special fonts, we must call @code{rchar} to remove the definition 12838of the fallback glyph. Anyway, the translation is still active; 12839@samp{x} now maps to the real glyph @samp{foo}. 12840 12841 12842@c ===================================================================== 12843 12844@node Debugging, Implementation Differences, Gtroff Internals, gtroff Reference 12845@section Debugging 12846@cindex debugging 12847 12848@code{gtroff} is not easy to debug, but there are some useful features 12849and strategies for debugging. 12850 12851@Defreq {lf, line [@Var{filename}]} 12852@pindex soelim 12853@cindex multi-file documents 12854@cindex documents, multi-file 12855@cindex setting input line number (@code{lf}) 12856@cindex input line number, setting (@code{lf}) 12857@cindex number, input line, setting (@code{lf}) 12858Change the line number and optionally the file name @code{gtroff} shall 12859use for error and warning messages. @var{line} is the input line number 12860of the @emph{next} line. 12861 12862Without argument, the request is ignored. 12863 12864This is a debugging aid for documents which are split into many files, 12865then put together with @code{soelim} and other preprocessors. Usually, 12866it isn't invoked manually. 12867 12868Note that other @code{troff} implementations (including the original 12869@acronym{AT&T} version) handle @code{lf} differently. For them, 12870@var{line} changes the line number of the @emph{current} line. 12871@endDefreq 12872 12873@DefreqList {tm, string} 12874@DefreqItem {tm1, string} 12875@DefreqListEnd {tmc, string} 12876@cindex printing to stderr (@code{tm}, @code{tm1}, @code{tmc}) 12877@cindex stderr, printing to (@code{tm}, @code{tm1}, @code{tmc}) 12878Send @var{string} to the standard error output; 12879this is very useful for printing debugging messages among other things. 12880 12881@var{string} is read in copy mode. 12882 12883The @code{tm} request ignores leading spaces of @var{string}; @code{tm1} 12884handles its argument similar to the @code{ds} request: a leading double 12885quote in @var{string} is stripped to allow initial blanks. 12886 12887The @code{tmc} request is similar to @code{tm1} but does 12888not append a newline (as is done in @code{tm} and @code{tm1}). 12889@endDefreq 12890 12891@Defreq {ab, [@Var{string}]} 12892@cindex aborting (@code{ab}) 12893Similar to the @code{tm} request, except that 12894it causes @code{gtroff} to stop processing. With no argument it 12895prints @samp{User Abort.} to standard error. 12896@endDefreq 12897 12898@Defreq {ex, } 12899@cindex @code{ex} request, use in debugging 12900@cindex exiting (@code{ex}) 12901The @code{ex} request also causes @code{gtroff} to stop processing; 12902see also @ref{I/O}. 12903@endDefreq 12904 12905When doing something involved it is useful to leave the debugging 12906statements in the code and have them turned on by a command line flag. 12907 12908@Example 12909.if \n(DB .tm debugging output 12910@endExample 12911 12912@noindent 12913To activate these statements say 12914 12915@Example 12916groff -rDB=1 file 12917@endExample 12918 12919If it is known in advance that there will be many errors and no useful 12920output, @code{gtroff} can be forced to suppress formatted output with 12921the @option{-z} flag. 12922 12923@Defreq {pm, } 12924@cindex dumping symbol table (@code{pm}) 12925@cindex symbol table, dumping (@code{pm}) 12926Print the entire symbol table on @code{stderr}. Names of all defined 12927macros, strings, and diversions are print together with their size in 12928bytes. Since @code{gtroff} sometimes adds nodes by itself, the 12929returned size can be larger than expected. 12930 12931This request differs from @acronym{UNIX} @code{troff}: @code{gtroff} 12932reports the sizes of diversions, ignores an additional argument to 12933print only the total of the sizes, and the size isn't returned in 12934blocks of 128 characters. 12935@endDefreq 12936 12937@Defreq {pnr, } 12938@cindex dumping number registers (@code{pnr}) 12939@cindex number registers, dumping (@code{pnr}) 12940Print the names and contents of all 12941currently defined number registers on @code{stderr}. 12942@endDefreq 12943 12944@Defreq {ptr, } 12945@cindex dumping traps (@code{ptr}) 12946@cindex traps, dumping (@code{ptr}) 12947Print the names and positions of all traps 12948(not including input line traps and diversion traps) on @code{stderr}. 12949Empty slots in the page trap list are printed as well, because they can 12950affect the priority of subsequently planted traps. 12951@endDefreq 12952 12953@Defreq {fl, } 12954@cindex flush output (@code{fl}) 12955@cindex output, flush (@code{fl}) 12956@cindex interactive use of @code{gtroff} 12957@cindex @code{gtroff}, interactive use 12958Instruct @code{gtroff} to flush its output immediately. The intent 12959is for interactive use, but this behaviour is currently not 12960implemented in @code{gtroff}. Contrary to @acronym{UNIX} @code{troff}, 12961TTY output is sent to a device driver also (@code{grotty}), making it 12962non-trivial to communicate interactively. 12963 12964This request causes a line break. 12965@endDefreq 12966 12967@Defreq {backtrace, } 12968@cindex backtrace of input stack (@code{backtrace}) 12969@cindex input stack, backtrace (@code{backtrace}) 12970Print a backtrace of the input stack to the standard error stream. 12971 12972Consider the following in file @file{test}: 12973 12974@Example 12975.de xxx 12976. backtrace 12977.. 12978.de yyy 12979. xxx 12980.. 12981. 12982.yyy 12983@endExample 12984 12985@noindent 12986On execution, @code{gtroff} prints the following: 12987 12988@Example 12989test:2: backtrace: macro `xxx' 12990test:5: backtrace: macro `yyy' 12991test:8: backtrace: file `test' 12992@endExample 12993 12994The option @option{-b} of @code{gtroff} internally calls a variant of 12995this request on each error and warning. 12996@endDefreq 12997 12998@Defreg {slimit} 12999@cindex input stack, setting limit 13000Use the @code{slimit} number register 13001to set the maximum number of objects on the input stack. 13002If @code{slimit} is less than or equal to@tie{}0, 13003there is no limit set. 13004With no limit, a buggy recursive macro can exhaust virtual memory. 13005 13006The default value is 1000; this is a compile-time constant. 13007@endDefreg 13008 13009@Defreq {warnscale, si} 13010Set the scaling indicator used in warnings to @var{si}. Valid values for 13011@var{si} are @samp{u}, @samp{i}, @samp{c}, @samp{p}, and @samp{P}. At 13012startup, it is set to @samp{i}. 13013@endDefreq 13014 13015@Defreq {spreadwarn, [@Var{limit}]} 13016Make @code{gtroff} emit a warning if the additional space inserted for 13017each space between words in an output line is larger or equal to 13018@var{limit}. A negative value is changed to zero; no argument toggles the 13019warning on and off without changing @var{limit}. The default scaling 13020indicator is @samp{m}. At startup, @code{spreadwarn} is deactivated, and 13021@var{limit} is set to 3@dmn{m}. 13022 13023For example, 13024 13025@Example 13026.spreadwarn 0.2m 13027@endExample 13028 13029@noindent 13030will cause a warning if @code{gtroff} must add 0.2@dmn{m} or more for each 13031interword space in a line. 13032 13033This request is active only if text is justified to both margins (using 13034@w{@samp{.ad b}}). 13035@endDefreq 13036 13037@cindex warnings 13038@code{gtroff} has command line options for printing out more warnings 13039(@option{-w}) and for printing backtraces (@option{-b}) when a warning 13040or an error occurs. The most verbose level of warnings is @option{-ww}. 13041 13042@DefreqList {warn, [@Var{flags}]} 13043@DefregListEnd {.warn} 13044@cindex level of warnings (@code{warn}) 13045@cindex warnings, level (@code{warn}) 13046Control the level of warnings checked for. The @var{flags} are the sum 13047of the numbers associated with each warning that is to be enabled; all 13048other warnings are disabled. The number associated with each warning is 13049listed below. For example, @w{@code{.warn 0}} disables all warnings, 13050and @w{@code{.warn 1}} disables all warnings except that about missing 13051glyphs. If no argument is given, all warnings are enabled. 13052 13053The read-only number register @code{.warn} contains the current warning 13054level. 13055@endDefreq 13056 13057@menu 13058* Warnings:: 13059@end menu 13060 13061@c --------------------------------------------------------------------- 13062 13063@node Warnings, , Debugging, Debugging 13064@subsection Warnings 13065@cindex warnings 13066 13067The warnings that can be given to @code{gtroff} are divided into the 13068following categories. The name associated with each warning is used by 13069the @option{-w} and @option{-W} options; the number is used by the 13070@code{warn} request and by the @code{.warn} register. 13071 13072@table @samp 13073@item char 13074@itemx 1 13075Non-existent glyphs.@footnote{@code{char} is a misnomer since it reports 13076missing glyphs -- there aren't missing input characters, only invalid 13077ones.} This is enabled by default. 13078 13079@item number 13080@itemx 2 13081Invalid numeric expressions. This is enabled by default. 13082@xref{Expressions}. 13083 13084@item break 13085@itemx 4 13086@cindex fill mode 13087@cindex mode, fill 13088In fill mode, lines which could not be broken so that their length was 13089less than the line length. This is enabled by default. 13090 13091@item delim 13092@itemx 8 13093Missing or mismatched closing delimiters. 13094 13095@item el 13096@itemx 16 13097@cindex @code{ie} request, and warnings 13098@cindex @code{el} request, and warnings 13099Use of the @code{el} request with no matching @code{ie} request. 13100@xref{if-else}. 13101 13102@item scale 13103@itemx 32 13104Meaningless scaling indicators. 13105 13106@item range 13107@itemx 64 13108Out of range arguments. 13109 13110@item syntax 13111@itemx 128 13112Dubious syntax in numeric expressions. 13113 13114@item di 13115@itemx 256 13116@cindex @code{di} request, and warnings 13117@cindex @code{da} request, and warnings 13118Use of @code{di} or @code{da} without an argument when there is no 13119current diversion. 13120 13121@item mac 13122@itemx 512 13123@cindex @code{de}, @code{de1}, @code{dei} requests, and warnings 13124@cindex @code{am}, @code{am1}, @code{ami} requests, and warnings 13125@cindex @code{ds}, @code{ds1} requests, and warnings 13126@cindex @code{as}, @code{as1} requests, and warnings 13127@cindex @code{di} request, and warnings 13128@cindex @code{da} request, and warnings 13129@cindex @code{box}, @code{boxa} requests, and warnings 13130@cindex @code{\*}, and warnings 13131Use of undefined strings, macros and diversions. When an undefined 13132string, macro, or diversion is used, that string is automatically 13133defined as empty. So, in most cases, at most one warning is given 13134for each name. 13135 13136@item reg 13137@itemx 1024 13138@cindex @code{nr} request, and warnings 13139@cindex @code{\R}, and warnings 13140@cindex @code{\n}, and warnings 13141Use of undefined number registers. When an undefined number register is 13142used, that register is automatically defined to have a value of@tie{}0. 13143So, in most cases, at most one warning is given for use of a particular 13144name. 13145 13146@item tab 13147@itemx 2048 13148@cindex @code{\t}, and warnings 13149Use of a tab character where a number was expected. 13150 13151@item right-brace 13152@itemx 4096 13153@cindex @code{\@}}, and warnings 13154Use of @code{\@}} where a number was expected. 13155 13156@item missing 13157@itemx 8192 13158Requests that are missing non-optional arguments. 13159 13160@item input 13161@itemx 16384 13162Invalid input characters. 13163 13164@item escape 13165@itemx 32768 13166Unrecognized escape sequences. When an unrecognized escape sequence 13167@code{\@var{X}} is encountered, the escape character is ignored, and 13168@var{X} is printed. 13169 13170@item space 13171@itemx 65536 13172@cindex compatibility mode 13173Missing space between a request or macro and its argument. This warning 13174is given when an undefined name longer than two characters is 13175encountered, and the first two characters of the name make a defined 13176name. The request or macro is not invoked. When this warning is 13177given, no macro is automatically defined. This is enabled by default. 13178This warning never occurs in compatibility mode. 13179 13180@item font 13181@itemx 131072 13182Non-existent fonts. This is enabled by default. 13183 13184@item ig 13185@itemx 262144 13186Invalid escapes in text ignored with the @code{ig} request. These are 13187conditions that are errors when they do not occur in ignored text. 13188 13189@item color 13190@itemx 524288 13191Color related warnings. 13192 13193@item all 13194All warnings except @samp{di}, @samp{mac} and @samp{reg}. It is 13195intended that this covers all warnings that are useful with traditional 13196macro packages. 13197 13198@item w 13199All warnings. 13200@end table 13201 13202 13203@c ===================================================================== 13204 13205@node Implementation Differences, , Debugging, gtroff Reference 13206@section Implementation Differences 13207@cindex implementation differences 13208@cindex differences in implementation 13209@cindex incompatibilities with @acronym{AT&T} @code{troff} 13210@cindex compatibility mode 13211@cindex mode, compatibility 13212 13213GNU @code{troff} has a number of features which cause incompatibilities 13214with documents written with old versions of @code{troff}. 13215 13216@cindex long names 13217@cindex names, long 13218Long names cause some incompatibilities. @acronym{UNIX} @code{troff} 13219interprets 13220 13221@Example 13222.dsabcd 13223@endExample 13224 13225@cindex @code{\*}, incompatibilities with @acronym{AT&T} @code{troff} 13226@cindex @code{\n}, incompatibilities with @acronym{AT&T} @code{troff} 13227@noindent 13228as defining a string @samp{ab} with contents @samp{cd}. Normally, GNU 13229@code{troff} interprets this as a call of a macro named 13230@code{dsabcd}. Also @acronym{UNIX} @code{troff} interprets 13231@code{\*[} or @code{\n[} as references to a string or number register 13232called @samp{[}. In GNU @code{troff}, however, this is normally 13233interpreted as the start of a long name. In compatibility mode GNU 13234@code{troff} interprets long names in the traditional way 13235(which means that they are not recognized as names). 13236 13237@DefreqList {cp, [@Var{n}]} 13238@DefreqItem {do, cmd} 13239@DefregListEnd {.C} 13240If @var{n} is missing or non-zero, turn on compatibility mode; 13241otherwise, turn it off. 13242 13243The read-only number register @code{.C} is@tie{}1 if compatibility mode is 13244on, 0@tie{}otherwise. 13245 13246Compatibility mode can be also turned on with the @option{-C} command line 13247option. 13248 13249The @code{do} request turns off compatibility mode 13250while executing its arguments as a @code{gtroff} command. 13251 13252@Example 13253.do fam T 13254@endExample 13255 13256@noindent 13257executes the @code{fam} request when compatibility mode 13258is enabled. 13259 13260@code{gtroff} restores the previous compatibility setting 13261before interpreting any files sourced by the @var{cmd}. 13262@endDefreq 13263 13264@cindex input level in delimited arguments 13265@cindex delimited arguments, incompatibilities with @acronym{AT&T} @code{troff} 13266Two other features are controlled by @option{-C}. If not in 13267compatibility mode, GNU @code{troff} preserves the input level in 13268delimited arguments: 13269 13270@Example 13271.ds xx ' 13272\w'abc\*(xxdef' 13273@endExample 13274 13275@noindent 13276In compatibility mode, the string @samp{72def'} is returned; without 13277@option{-C} the resulting string is @samp{168} (assuming a TTY output 13278device). 13279 13280@cindex @code{\f}, incompatibilities with @acronym{AT&T} @code{troff} 13281@cindex @code{\H}, incompatibilities with @acronym{AT&T} @code{troff} 13282@cindex @code{\s}, incompatibilities with @acronym{AT&T} @code{troff} 13283@cindex @code{\S}, incompatibilities with @acronym{AT&T} @code{troff} 13284Finally, the escapes @code{\f}, @code{\H}, @code{\m}, @code{\M}, 13285@code{\R}, @code{\s}, and @code{\S} are transparent for recognizing the 13286beginning of a line only in compatibility mode (this is a rather obscure 13287feature). For example, the code 13288 13289@Example 13290.de xx 13291Hallo! 13292.. 13293\fB.xx\fP 13294@endExample 13295 13296@noindent 13297prints @samp{Hallo!} in bold face if in compatibility mode, and 13298@samp{.xx} in bold face otherwise. 13299 13300@cindex @code{\A}, incompatibilities with @acronym{AT&T} @code{troff} 13301@cindex @code{\|}, incompatibilities with @acronym{AT&T} @code{troff} 13302@cindex @code{\^}, incompatibilities with @acronym{AT&T} @code{troff} 13303@cindex @code{\&}, incompatibilities with @acronym{AT&T} @code{troff} 13304@cindex @code{\@{}, incompatibilities with @acronym{AT&T} @code{troff} 13305@cindex @code{\@}}, incompatibilities with @acronym{AT&T} @code{troff} 13306@cindex @code{\@key{SP}}, incompatibilities with @acronym{AT&T} @code{troff} 13307@cindex @code{\'}, incompatibilities with @acronym{AT&T} @code{troff} 13308@cindex @code{\`}, incompatibilities with @acronym{AT&T} @code{troff} 13309@cindex @code{\-}, incompatibilities with @acronym{AT&T} @code{troff} 13310@cindex @code{\_}, incompatibilities with @acronym{AT&T} @code{troff} 13311@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 13312@cindex @code{\%}, incompatibilities with @acronym{AT&T} @code{troff} 13313@cindex @code{\c}, incompatibilities with @acronym{AT&T} @code{troff} 13314GNU @code{troff} does not allow the use of the escape sequences 13315@code{\|}, @code{\^}, @code{\&}, @code{\@{}, @code{\@}}, 13316@code{\@key{SP}}, @code{\'}, @code{\`}, @code{\-}, @code{\_}, @code{\!}, 13317@code{\%}, and @code{\c} in names of strings, macros, diversions, number 13318registers, fonts or environments; @acronym{UNIX} @code{troff} does. The 13319@code{\A} escape sequence (@pxref{Identifiers}) may be helpful in 13320avoiding use of these escape sequences in names. 13321 13322@cindex fractional point sizes 13323@cindex fractional type sizes 13324@cindex point sizes, fractional 13325@cindex type sizes, fractional 13326@cindex sizes, fractional 13327@cindex @code{ps} request, incompatibilities with @acronym{AT&T} @code{troff} 13328Fractional point sizes cause one noteworthy incompatibility. In 13329@acronym{UNIX} @code{troff} the @code{ps} request ignores scale 13330indicators and thus 13331 13332@Example 13333.ps 10u 13334@endExample 13335 13336@noindent 13337sets the point size to 10@tie{}points, whereas in GNU @code{troff} it 13338sets the point size to 10@tie{}scaled points. @xref{Fractional Type 13339Sizes}, for more information. 13340 13341@cindex @code{bd} request, incompatibilities with @acronym{AT&T} @code{troff} 13342@cindex @code{cs} request, incompatibilities with @acronym{AT&T} @code{troff} 13343@cindex @code{tr} request, incompatibilities with @acronym{AT&T} @code{troff} 13344@cindex @code{fp} request, incompatibilities with @acronym{AT&T} @code{troff} 13345@cindex input characters and output glyphs, compatibility with @acronym{AT&T} @code{troff} 13346@cindex output glyphs, and input characters,compatibility with @acronym{AT&T} @code{troff} 13347@cindex characters, input, and output glyphs, compatibility with @acronym{AT&T} @code{troff} 13348@cindex glyphs, output, and input characters, compatibility with @acronym{AT&T} @code{troff} 13349In GNU @code{troff} there is a fundamental difference between 13350(unformatted) input characters and (formatted) output glyphs. 13351Everything that affects how a glyph is output is stored 13352with the glyph node; once a glyph node has been constructed it is 13353unaffected by any subsequent requests that are executed, including 13354@code{bd}, @code{cs}, @code{tkf}, @code{tr}, or @code{fp} requests. 13355Normally glyphs are constructed from input characters at the 13356moment immediately before the glyph is added to the current output 13357line. Macros, diversions and strings are all, in fact, the same type of 13358object; they contain lists of input characters and glyph nodes in 13359any combination. A glyph node does not behave like an input 13360character for the purposes of macro processing; it does not inherit any 13361of the special properties that the input character from which it was 13362constructed might have had. For example, 13363 13364@Example 13365.di x 13366\\\\ 13367.br 13368.di 13369.x 13370@endExample 13371 13372@cindex printing backslash (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 13373@cindex backslash, printing (@code{\\}, @code{\e}, @code{\E}, @code{\[rs]}) 13374@cindex @code{\e}, incompatibilities with @acronym{AT&T} @code{troff} 13375@cindex @code{\!}, incompatibilities with @acronym{AT&T} @code{troff} 13376@cindex @code{\?}, incompatibilities with @acronym{AT&T} @code{troff} 13377@cindex transparent output, incompatibilities with @acronym{AT&T} @code{troff} 13378@cindex output, transparent, incompatibilities with @acronym{AT&T} @code{troff} 13379@noindent 13380prints @samp{\\} in GNU @code{troff}; each pair of input backslashes 13381is turned into one output backslash and the resulting output backslashes 13382are not interpreted as escape characters when they are reread. 13383@acronym{UNIX} @code{troff} would interpret them as escape characters 13384when they were reread and would end up printing one @samp{\}. The 13385correct way to obtain a printable backslash is to use the @code{\e} 13386escape sequence: This always prints a single instance of the current 13387escape character, regardless of whether or not it is used in a 13388diversion; it also works in both GNU @code{troff} and @acronym{UNIX} 13389@code{troff}.@footnote{To be completely independent of the current 13390escape character, use @code{\(rs} which represents a reverse solidus 13391(backslash) glyph.} To store, for some reason, an escape sequence in a 13392diversion that will be interpreted when the diversion is reread, either 13393use the traditional @code{\!} transparent output facility, or, if this 13394is unsuitable, the new @code{\?} escape sequence. 13395 13396@xref{Diversions}, and @ref{Gtroff Internals}, for more information. 13397 13398 13399 13400@c ===================================================================== 13401@c ===================================================================== 13402 13403@node Preprocessors, Output Devices, gtroff Reference, Top 13404@chapter Preprocessors 13405@cindex preprocessors 13406 13407This chapter describes all preprocessors that come with @code{groff} or 13408which are freely available. 13409 13410@menu 13411* geqn:: 13412* gtbl:: 13413* gpic:: 13414* ggrn:: 13415* grap:: 13416* grefer:: 13417* gsoelim:: 13418@end menu 13419 13420 13421@c ===================================================================== 13422 13423@node geqn, gtbl, Preprocessors, Preprocessors 13424@section @code{geqn} 13425@cindex @code{eqn}, the program 13426@cindex @code{geqn}, the program 13427 13428@c XXX 13429 13430@menu 13431* Invoking geqn:: 13432@end menu 13433 13434@c --------------------------------------------------------------------- 13435 13436@node Invoking geqn, , geqn, geqn 13437@subsection Invoking @code{geqn} 13438@cindex invoking @code{geqn} 13439@cindex @code{geqn}, invoking 13440 13441@c XXX 13442 13443 13444@c ===================================================================== 13445 13446@node gtbl, gpic, geqn, Preprocessors 13447@section @code{gtbl} 13448@cindex @code{tbl}, the program 13449@cindex @code{gtbl}, the program 13450 13451@c XXX 13452 13453@menu 13454* Invoking gtbl:: 13455@end menu 13456 13457@c --------------------------------------------------------------------- 13458 13459@node Invoking gtbl, , gtbl, gtbl 13460@subsection Invoking @code{gtbl} 13461@cindex invoking @code{gtbl} 13462@cindex @code{gtbl}, invoking 13463 13464@c XXX 13465 13466 13467@c ===================================================================== 13468 13469@node gpic, ggrn, gtbl, Preprocessors 13470@section @code{gpic} 13471@cindex @code{pic}, the program 13472@cindex @code{gpic}, the program 13473 13474@c XXX 13475 13476@menu 13477* Invoking gpic:: 13478@end menu 13479 13480@c --------------------------------------------------------------------- 13481 13482@node Invoking gpic, , gpic, gpic 13483@subsection Invoking @code{gpic} 13484@cindex invoking @code{gpic} 13485@cindex @code{gpic}, invoking 13486 13487@c XXX 13488 13489 13490@c ===================================================================== 13491 13492@node ggrn, grap, gpic, Preprocessors 13493@section @code{ggrn} 13494@cindex @code{grn}, the program 13495@cindex @code{ggrn}, the program 13496 13497@c XXX 13498 13499@menu 13500* Invoking ggrn:: 13501@end menu 13502 13503@c --------------------------------------------------------------------- 13504 13505@node Invoking ggrn, , ggrn, ggrn 13506@subsection Invoking @code{ggrn} 13507@cindex invoking @code{ggrn} 13508@cindex @code{ggrn}, invoking 13509 13510@c XXX 13511 13512 13513@c ===================================================================== 13514 13515@node grap, grefer, ggrn, Preprocessors 13516@section @code{grap} 13517@cindex @code{grap}, the program 13518 13519A free implementation of @code{grap}, written by Ted Faber, 13520is available as an extra package from the following address: 13521 13522@display 13523@uref{http://www.lunabase.org/~faber/Vault/software/grap/} 13524@end display 13525 13526 13527@c ===================================================================== 13528 13529@node grefer, gsoelim, grap, Preprocessors 13530@section @code{grefer} 13531@cindex @code{refer}, the program 13532@cindex @code{grefer}, the program 13533 13534@c XXX 13535 13536@menu 13537* Invoking grefer:: 13538@end menu 13539 13540@c --------------------------------------------------------------------- 13541 13542@node Invoking grefer, , grefer, grefer 13543@subsection Invoking @code{grefer} 13544@cindex invoking @code{grefer} 13545@cindex @code{grefer}, invoking 13546 13547@c XXX 13548 13549 13550@c ===================================================================== 13551 13552@node gsoelim, , grefer, Preprocessors 13553@section @code{gsoelim} 13554@cindex @code{soelim}, the program 13555@cindex @code{gsoelim}, the program 13556 13557@c XXX 13558 13559@menu 13560* Invoking gsoelim:: 13561@end menu 13562 13563@c --------------------------------------------------------------------- 13564 13565@node Invoking gsoelim, , gsoelim, gsoelim 13566@subsection Invoking @code{gsoelim} 13567@cindex invoking @code{gsoelim} 13568@cindex @code{gsoelim}, invoking 13569 13570@c XXX 13571 13572 13573 13574@c ===================================================================== 13575@c ===================================================================== 13576 13577@node Output Devices, File formats, Preprocessors, Top 13578@chapter Output Devices 13579@cindex output devices 13580@cindex devices for output 13581 13582@c XXX 13583 13584@menu 13585* Special Characters:: 13586* grotty:: 13587* grops:: 13588* grodvi:: 13589* grolj4:: 13590* grolbp:: 13591* grohtml:: 13592* gxditview:: 13593@end menu 13594 13595 13596@c ===================================================================== 13597 13598@node Special Characters, grotty, Output Devices, Output Devices 13599@section Special Characters 13600@cindex special characters 13601@cindex characters, special 13602 13603@c XXX 13604 13605@xref{Font Files}. 13606 13607 13608@c ===================================================================== 13609 13610@node grotty, grops, Special Characters, Output Devices 13611@section @code{grotty} 13612@cindex @code{grotty}, the program 13613 13614@c XXX 13615 13616@menu 13617* Invoking grotty:: 13618@end menu 13619 13620@c --------------------------------------------------------------------- 13621 13622@node Invoking grotty, , grotty, grotty 13623@subsection Invoking @code{grotty} 13624@cindex invoking @code{grotty} 13625@cindex @code{grotty}, invoking 13626 13627@c XXX 13628 13629@c The following is no longer true; fix and extend it. 13630 13631@c @pindex less 13632@c @cindex Teletype 13633@c @cindex ISO 6249 SGR 13634@c @cindex terminal control sequences 13635@c @cindex control sequences, for terminals 13636@c For TTY output devices, underlining is done by emitting sequences of 13637@c @samp{_} and @samp{\b} (the backspace character) before the actual 13638@c character. Literally, this is printing an underline character, then 13639@c moving back one character position, and printing the actual character 13640@c at the same position as the underline character (similar to a 13641@c typewriter). Usually, a modern terminal can't interpret this (and the 13642@c original Teletype machines for which this sequence was appropriate are 13643@c no longer in use). You need a pager program like @code{less} which 13644@c translates this into ISO 6429 SGR sequences to control terminals. 13645 13646 13647@c ===================================================================== 13648 13649@node grops, grodvi, grotty, Output Devices 13650@section @code{grops} 13651@cindex @code{grops}, the program 13652 13653@c XXX 13654 13655@menu 13656* Invoking grops:: 13657* Embedding PostScript:: 13658@end menu 13659 13660@c --------------------------------------------------------------------- 13661 13662@node Invoking grops, Embedding PostScript, grops, grops 13663@subsection Invoking @code{grops} 13664@cindex invoking @code{grops} 13665@cindex @code{grops}, invoking 13666 13667@c XXX 13668 13669@c --------------------------------------------------------------------- 13670 13671@node Embedding PostScript, , Invoking grops, grops 13672@subsection Embedding @sc{PostScript} 13673@cindex embedding PostScript 13674@cindex PostScript, embedding 13675 13676@c XXX 13677 13678 13679@c ===================================================================== 13680 13681@node grodvi, grolj4, grops, Output Devices 13682@section @code{grodvi} 13683@cindex @code{grodvi}, the program 13684 13685@c XXX 13686 13687@menu 13688* Invoking grodvi:: 13689@end menu 13690 13691@c --------------------------------------------------------------------- 13692 13693@node Invoking grodvi, , grodvi, grodvi 13694@subsection Invoking @code{grodvi} 13695@cindex invoking @code{grodvi} 13696@cindex @code{grodvi}, invoking 13697 13698@c XXX 13699 13700 13701@c ===================================================================== 13702 13703@node grolj4, grolbp, grodvi, Output Devices 13704@section @code{grolj4} 13705@cindex @code{grolj4}, the program 13706 13707@c XXX 13708 13709@menu 13710* Invoking grolj4:: 13711@end menu 13712 13713@c --------------------------------------------------------------------- 13714 13715@node Invoking grolj4, , grolj4, grolj4 13716@subsection Invoking @code{grolj4} 13717@cindex invoking @code{grolj4} 13718@cindex @code{grolj4}, invoking 13719 13720@c XXX 13721 13722 13723@c ===================================================================== 13724 13725@node grolbp, grohtml, grolj4, Output Devices 13726@section @code{grolbp} 13727@cindex @code{grolbp}, the program 13728 13729@c XXX 13730 13731@menu 13732* Invoking grolbp:: 13733@end menu 13734 13735@c --------------------------------------------------------------------- 13736 13737@node Invoking grolbp, , grolbp, grolbp 13738@subsection Invoking @code{grolbp} 13739@cindex invoking @code{grolbp} 13740@cindex @code{grolbp}, invoking 13741 13742@c XXX 13743 13744 13745@c ===================================================================== 13746 13747@node grohtml, gxditview, grolbp, Output Devices 13748@section @code{grohtml} 13749@cindex @code{grohtml}, the program 13750 13751@c XXX 13752 13753@menu 13754* Invoking grohtml:: 13755* grohtml specific registers and strings:: 13756@end menu 13757 13758@c --------------------------------------------------------------------- 13759 13760@node Invoking grohtml, grohtml specific registers and strings, grohtml, grohtml 13761@subsection Invoking @code{grohtml} 13762@cindex invoking @code{grohtml} 13763@cindex @code{grohtml}, invoking 13764 13765@c XXX 13766 13767@c --------------------------------------------------------------------- 13768 13769@node grohtml specific registers and strings, , Invoking grohtml, grohtml 13770@subsection @code{grohtml} specific registers and strings 13771@cindex registers specific to @code{grohtml} 13772@cindex strings specific to @code{grohtml} 13773@cindex @code{grohtml}, registers and strings 13774 13775@DefmpregList {ps4html, grohtml} 13776@DefstrListEnd {www-image-template, grohtml} 13777The registers @code{ps4html} and @code{www-image-template} are defined 13778by the @code{pre-grohtml} preprocessor. @code{pre-grohtml} reads in 13779the @code{troff} input, marks up the inline equations and passes the 13780result firstly to 13781 13782@Example 13783troff -Tps -rps4html=1 -dwww-image-template=@var{template} 13784@endExample 13785 13786@noindent 13787and secondly to 13788 13789@Example 13790troff -Thtml 13791@endExample 13792 13793The PostScript device is used to create all the image files, and the 13794register @code{ps4html} enables the macro sets to ignore floating 13795keeps, footers, and headings. 13796 13797The register @code{www-image-template} is set to the user specified 13798template name or the default name. 13799@endDefmpreg 13800 13801 13802@c ===================================================================== 13803 13804@node gxditview, , grohtml, Output Devices 13805@section @code{gxditview} 13806@cindex @code{gxditview}, the program 13807 13808@c XXX 13809 13810@menu 13811* Invoking gxditview:: 13812@end menu 13813 13814@c --------------------------------------------------------------------- 13815 13816@node Invoking gxditview, , gxditview, gxditview 13817@subsection Invoking @code{gxditview} 13818@cindex invoking @code{gxditview} 13819@cindex @code{gxditview}, invoking 13820 13821@c XXX 13822@c X11's xditview 13823 13824 13825 13826@c ===================================================================== 13827@c ===================================================================== 13828 13829@node File formats, Installation, Output Devices, Top 13830@chapter File formats 13831@cindex file formats 13832@cindex formats, file 13833 13834All files read and written by @code{gtroff} are text files. The 13835following two sections describe their format. 13836 13837@menu 13838* gtroff Output:: 13839* Font Files:: 13840@end menu 13841 13842 13843@c ===================================================================== 13844 13845@node gtroff Output, Font Files, File formats, File formats 13846@section @code{gtroff} Output 13847@cindex @code{gtroff}, output 13848@cindex output, @code{gtroff} 13849 13850This section describes the intermediate output format of GNU 13851@code{troff}. This output is produced by a run of @code{gtroff} 13852before it is fed into a device postprocessor program. 13853 13854As @code{groff} is a wrapper program around @code{gtroff} that 13855automatically calls a postprocessor, this output does not show up 13856normally. This is why it is called @dfn{intermediate}. 13857@code{groff} provides the option @option{-Z} to inhibit postprocessing, 13858such that the produced intermediate output is sent to standard output 13859just like calling @code{gtroff} manually. 13860 13861@cindex troff output 13862@cindex output, troff 13863@cindex intermediate output 13864@cindex output, intermediate 13865Here, the term @dfn{troff output} describes what is output by 13866@code{gtroff}, while @dfn{intermediate output} refers to the language 13867that is accepted by the parser that prepares this output for the 13868postprocessors. This parser is smarter on whitespace and implements 13869obsolete elements for compatibility, otherwise both formats are the 13870same.@footnote{The parser and postprocessor for intermediate output 13871can be found in the file@* 13872@file{@var{groff-source-dir}/src/libs/libdriver/input.cpp}.} 13873 13874The main purpose of the intermediate output concept is to facilitate 13875the development of postprocessors by providing a common programming 13876interface for all devices. It has a language of its own that is 13877completely different from the @code{gtroff} language. While the 13878@code{gtroff} language is a high-level programming language for text 13879processing, the intermediate output language is a kind of low-level 13880assembler language by specifying all positions on the page for writing 13881and drawing. 13882 13883The intermediate output produced by @code{gtroff} is fairly readable, 13884while output from @acronym{AT&T} @code{troff} is rather hard to 13885understand because of strange habits that are still supported, but not 13886used any longer by @code{gtroff}. 13887 13888@menu 13889* Language Concepts:: 13890* Command Reference:: 13891* Intermediate Output Examples:: 13892* Output Language Compatibility:: 13893@end menu 13894 13895@c --------------------------------------------------------------------- 13896 13897@node Language Concepts, Command Reference, gtroff Output, gtroff Output 13898@subsection Language Concepts 13899 13900During the run of @code{gtroff}, the input data is cracked down to the 13901information on what has to be printed at what position on the intended 13902device. So the language of the intermediate output format can be quite 13903small. Its only elements are commands with and without arguments. 13904In this section, the term @dfn{command} always refers to the intermediate 13905output language, and never to the @code{gtroff} language used for document 13906formatting. There are commands for positioning and text writing, for drawing, and 13907for device controlling. 13908 13909@menu 13910* Separation:: 13911* Argument Units:: 13912* Document Parts:: 13913@end menu 13914 13915@node Separation, Argument Units, Language Concepts, Language Concepts 13916@subsubsection Separation 13917 13918@acronym{AT&T} @code{troff} output has strange requirements on whitespace. 13919The @code{gtroff} output parser, however, is smart about whitespace by 13920making it maximally optional. The whitespace characters, i.e., the 13921tab, space, and newline characters, always have a syntactical meaning. 13922They are never printable because spacing within the output is always 13923done by positioning commands. 13924 13925Any sequence of space or tab characters is treated as a single 13926@dfn{syntactical space}. It separates commands and arguments, but is 13927only required when there would occur a clashing between the command code 13928and the arguments without the space. Most often, this happens when 13929variable-length command names, arguments, argument lists, or command 13930clusters meet. Commands and arguments with a known, fixed length need 13931not be separated by syntactical space. 13932 13933A line break is a syntactical element, too. Every command argument can be 13934followed by whitespace, a comment, or a newline character. Thus a 13935@dfn{syntactical line break} is defined to consist of optional 13936syntactical space that is optionally followed by a comment, and a 13937newline character. 13938 13939The normal commands, those for positioning and text, consist of a 13940single letter taking a fixed number of arguments. For historical reasons, 13941the parser allows to stack such commands on the same line, but 13942fortunately, in @code{gtroff}'s intermediate output, every command with 13943at least one argument is followed by a line break, thus providing 13944excellent readability. 13945 13946The other commands -- those for drawing and device controlling -- 13947have a more complicated structure; some recognize long command names, 13948and some take a variable number of arguments. So all @samp{D} and 13949@samp{x} commands were designed to request a syntactical line break 13950after their last argument. Only one command, @w{@samp{x X}}, 13951has an argument that can stretch over several lines; all other 13952commands must have all of their arguments on the same line as the 13953command, i.e., the arguments may not be splitted by a line break. 13954 13955Empty lines (these are lines containing only space and/or a comment), can 13956occur everywhere. They are just ignored. 13957 13958@node Argument Units, Document Parts, Separation, Language Concepts 13959@subsubsection Argument Units 13960 13961Some commands take integer arguments that are assumed to represent 13962values in a measurement unit, but the letter for the corresponding 13963scale indicator is not written with the output command arguments. 13964Most commands assume the scale indicator @samp{u}, the basic unit of 13965the device, some use @samp{z}, the scaled point unit of the device, 13966while others, such as the color commands, expect plain integers. 13967 13968Note that single characters can have the eighth bit set, as can the 13969names of fonts and special characters. The names of characters and 13970fonts can be of arbitrary length. A character that is to be printed 13971will always be in the current font. 13972 13973A string argument is always terminated by the next whitespace 13974character (space, tab, or newline); an embedded @samp{#} character is 13975regarded as part of the argument, not as the beginning of a comment 13976command. An integer argument is already terminated by the next 13977non-digit character, which then is regarded as the first character of 13978the next argument or command. 13979 13980@node Document Parts, , Argument Units, Language Concepts 13981@subsubsection Document Parts 13982 13983A correct intermediate output document consists of two parts, the 13984@dfn{prologue} and the @dfn{body}. 13985 13986The task of the prologue is to set the general device parameters 13987using three exactly specified commands. @code{gtroff}'s prologue 13988is guaranteed to consist of the following three lines (in that order): 13989 13990@Example 13991x T @var{device} 13992x res @var{n} @var{h} @var{v} 13993x init 13994@endExample 13995 13996@noindent 13997with the arguments set as outlined in @ref{Device Control Commands}. 13998Note that the parser for the intermediate output format is able to 13999swallow additional whitespace and comments as well even in the 14000prologue. 14001 14002The body is the main section for processing the document data. 14003Syntactically, it is a sequence of any commands different from the 14004ones used in the prologue. Processing is terminated as soon as the 14005first @w{@samp{x stop}} command is encountered; the last line of any 14006@code{gtroff} intermediate output always contains such a command. 14007 14008Semantically, the body is page oriented. A new page is started by a 14009@samp{p} command. Positioning, writing, and drawing commands are 14010always done within the current page, so they cannot occur before the 14011first @samp{p} command. Absolute positioning (by the @samp{H} and 14012@samp{V} commands) is done relative to the current page; all other 14013positioning is done relative to the current location within this page. 14014 14015@c --------------------------------------------------------------------- 14016 14017@node Command Reference, Intermediate Output Examples, Language Concepts, gtroff Output 14018@subsection Command Reference 14019 14020This section describes all intermediate output commands, both from 14021@acronym{AT&T} @code{troff} as well as the @code{gtroff} extensions. 14022 14023@menu 14024* Comment Command:: 14025* Simple Commands:: 14026* Graphics Commands:: 14027* Device Control Commands:: 14028* Obsolete Command:: 14029@end menu 14030 14031@node Comment Command, Simple Commands, Command Reference, Command Reference 14032@subsubsection Comment Command 14033 14034@table @code 14035@item #@var{anything}@angles{end of line} 14036A comment. Ignore any characters from the @samp{#} character up to 14037the next newline character. 14038 14039This command is the only possibility for commenting in the intermediate 14040output. Each comment can be preceded by arbitrary syntactical space; 14041every command can be terminated by a comment. 14042@end table 14043 14044@node Simple Commands, Graphics Commands, Comment Command, Command Reference 14045@subsubsection Simple Commands 14046 14047The commands in this subsection have a command code consisting of a 14048single character, taking a fixed number of arguments. Most of them 14049are commands for positioning and text writing. These commands are 14050smart about whitespace. Optionally, syntactical space can be inserted 14051before, after, and between the command letter and its arguments. 14052All of these commands are stackable, i.e., they can be preceded by 14053other simple commands or followed by arbitrary other commands on the 14054same line. A separating syntactical space is only necessary when two 14055integer arguments would clash or if the preceding argument ends with a 14056string argument. 14057 14058@table @code 14059@ignore 14060.if (\n[@USE_ENV_STACK] == 1) \{\ 14061.command { 14062Open a new environment by copying the actual device configuration data 14063to the environment stack. 14064. 14065The current environment is setup by the device specification and 14066manipulated by the setting commands. 14067. 14068. 14069.command } 14070Close the actual environment (opened by a preceding 14071.BR { \~command) 14072and restore the previous environment from the environment 14073stack as the actual device configuration data. 14074. 14075\} \" endif @USE_ENV_STACK 14076@end ignore 14077 14078@item C @var{xxx}@angles{whitespace} 14079Print a special character named @var{xxx}. The trailing 14080syntactical space or line break is necessary to allow glyph names 14081of arbitrary length. The glyph is printed at the current print 14082position; the glyph's size is read from the font file. The print 14083position is not changed. 14084 14085@item c @var{g} 14086Print glyph@tie{}@var{g} at the current print position;@footnote{@samp{c} 14087is actually a misnomer since it outputs a glyph.} the glyph's size is 14088read from the font file. The print position is not changed. 14089 14090@item f @var{n} 14091Set font to font number@tie{}@var{n} (a non-negative integer). 14092 14093@item H @var{n} 14094Move right to the absolute vertical position@tie{}@var{n} (a 14095non-negative integer in basic units @samp{u} relative to left edge 14096of current page. 14097 14098@item h @var{n} 14099Move @var{n} (a non-negative integer) basic units @samp{u} horizontally 14100to the right. The original @acronym{UNIX} troff manual allows negative 14101values for @var{n} also, but @code{gtroff} doesn't use this. 14102 14103@item m @var{color-scheme} @r{[}@var{component} @dots{}@r{]} 14104Set the color for text (glyphs), line drawing, and the outline of 14105graphic objects using different color schemes; the analoguous command 14106for the filling color of graphic objects is @samp{DF}. The color 14107components are specified as integer arguments between 0 and 65536. 14108The number of color components and their meaning vary for the 14109different color schemes. These commands are generated by 14110@code{gtroff}'s escape sequence @code{\m}. No position changing. 14111These commands are a @code{gtroff} extension. 14112 14113@table @code 14114@item mc @var{cyan} @var{magenta} @var{yellow} 14115Set color using the CMY color scheme, having the 3@tie{}color components 14116@var{cyan}, @var{magenta}, and @var{yellow}. 14117 14118@item md 14119Set color to the default color value (black in most cases). 14120No component arguments. 14121 14122@item mg @var{gray} 14123Set color to the shade of gray given by the argument, an integer 14124between 0 (black) and 65536 (white). 14125 14126@item mk @var{cyan} @var{magenta} @var{yellow} @var{black} 14127Set color using the CMYK color scheme, having the 4@tie{}color components 14128@var{cyan}, @var{magenta}, @var{yellow}, and @var{black}. 14129 14130@item mr @var{red} @var{green} @var{blue} 14131Set color using the RGB color scheme, having the 3@tie{}color components 14132@var{red}, @var{green}, and @var{blue}. 14133 14134@end table 14135 14136@item N @var{n} 14137Print glyph with index@tie{}@var{n} (a non-negative integer) of the 14138current font. This command is a @code{gtroff} extension. 14139 14140@item n @var{b} @var{a} 14141Inform the device about a line break, but no positioning is done by 14142this command. In @acronym{AT&T} @code{troff}, the integer arguments 14143@var{b} and@tie{}@var{a} informed about the space before and after the 14144current line to make the intermediate output more human readable 14145without performing any action. In @code{groff}, they are just ignored, but 14146they must be provided for compatibility reasons. 14147 14148@item p @var{n} 14149Begin a new page in the outprint. The page number is set 14150to@tie{}@var{n}. This page is completely independent of pages formerly 14151processed even if those have the same page number. The vertical 14152position on the outprint is automatically set to@tie{}0. All 14153positioning, writing, and drawing is always done relative to a page, 14154so a @samp{p} command must be issued before any of these commands. 14155 14156@item s @var{n} 14157Set point size to @var{n}@tie{}scaled points (this is unit @samp{z}). 14158@acronym{AT&T} @code{troff} used the unit points (@samp{p}) instead. 14159@xref{Output Language Compatibility}. 14160 14161@item t @var{xxx}@angles{whitespace} 14162@itemx t @var{xxx} @var{dummy-arg}@angles{whitespace} 14163Print a word, i.e., a sequence of characters @var{xxx} representing 14164output glyphs which names are single characters, terminated by 14165a space character or a line break; an optional second integer argument 14166is ignored (this allows the formatter to generate an even number of 14167arguments). The first glyph should be printed at the current 14168position, the current horizontal position should then be increased by 14169the width of the first glyph, and so on for each glyph. 14170The widths of the glyphs are read from the font file, scaled for the 14171current point size, and rounded to a multiple of the horizontal 14172resolution. Special characters cannot be printed using this command 14173(use the @samp{C} command for special characters). This command is a 14174@code{gtroff} extension; it is only used for devices whose @file{DESC} 14175file contains the @code{tcommand} keyword (@pxref{DESC File Format}). 14176 14177@item u @var{n} @var{xxx}@angles{whitespace} 14178Print word with track kerning. This is the same as the @samp{t} 14179command except that after printing each glyph, the current 14180horizontal position is increased by the sum of the width of that 14181glyph and@tie{}@var{n} (an integer in basic units @samp{u}). 14182This command is a @code{gtroff} extension; it is only used for devices 14183whose @file{DESC} file contains the @code{tcommand} keyword 14184(@pxref{DESC File Format}). 14185 14186@item V @var{n} 14187Move down to the absolute vertical position@tie{}@var{n} (a 14188non-negative integer in basic units @samp{u}) relative to upper edge 14189of current page. 14190 14191@item v @var{n} 14192Move @var{n}@tie{}basic units @samp{u} down (@var{n} is a non-negative 14193integer). The original @acronym{UNIX} troff manual allows negative 14194values for @var{n} also, but @code{gtroff} doesn't use this. 14195 14196@item w 14197Informs about a paddable white space to increase readability. 14198The spacing itself must be performed explicitly by a move command. 14199 14200@end table 14201 14202@node Graphics Commands, Device Control Commands, Simple Commands, Command Reference 14203@subsubsection Graphics Commands 14204 14205Each graphics or drawing command in the intermediate output starts 14206with the letter @samp{D}, followed by one or two characters that 14207specify a subcommand; this is followed by a fixed or variable number 14208of integer arguments that are separated by a single space character. 14209A @samp{D} command may not be followed by another command on the same line 14210(apart from a comment), so each @samp{D} command is terminated by a 14211syntactical line break. 14212 14213@code{gtroff} output follows the classical spacing rules (no space 14214between command and subcommand, all arguments are preceded by a 14215single space character), but the parser allows optional space between 14216the command letters and makes the space before the first argument 14217optional. As usual, each space can be any sequence of tab and space 14218characters. 14219 14220Some graphics commands can take a variable number of arguments. 14221In this case, they are integers representing a size measured in basic 14222units @samp{u}. The arguments called @var{h1}, @var{h2}, @dots{}, 14223@var{hn} stand for horizontal distances where positive means right, 14224negative left. The arguments called @var{v1}, @var{v2}, @dots{}, 14225@var{vn} stand for vertical distances where positive means down, 14226negative up. All these distances are offsets relative to the current 14227location. 14228 14229Each graphics command directly corresponds to a similar @code{gtroff} 14230@code{\D} escape sequence. @xref{Drawing Requests}. 14231 14232Unknown @samp{D} commands are assumed to be device-specific. 14233Its arguments are parsed as strings; the whole information is then 14234sent to the postprocessor. 14235 14236In the following command reference, the syntax element 14237@angles{line break} means a syntactical line break as defined above. 14238 14239@table @code 14240@item D~ @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14241Draw B-spline from current position to offset (@var{h1},@var{v1}), 14242then to offset (@var{h2},@var{v2}), if given, etc.@: up to 14243(@var{hn},@var{vn}). This command takes a variable number of argument 14244pairs; the current position is moved to the terminal point of the drawn 14245curve. 14246 14247@item Da @var{h1} @var{v1} @var{h2} @var{v2}@angles{line break} 14248Draw arc from current position to 14249(@var{h1},@var{v1})@math{+}(@var{h2},@var{v2}) with center at 14250(@var{h1},@var{v1}); then move the current position to the final point 14251of the arc. 14252 14253@item DC @var{d}@angles{line break} 14254@itemx DC @var{d} @var{dummy-arg}@angles{line break} 14255Draw a solid circle using the current fill color with 14256diameter@tie{}@var{d} (integer in basic units @samp{u}) with leftmost 14257point at the current position; then move the current position to the 14258rightmost point of the circle. An optional second integer argument is 14259ignored (this allows the formatter to generate an even number of 14260arguments). This command is a @code{gtroff} extension. 14261 14262@item Dc @var{d}@angles{line break} 14263Draw circle line with diameter@tie{}@var{d} (integer in basic units 14264@samp{u}) with leftmost point at the current position; then move the 14265current position to the rightmost point of the circle. 14266 14267@item DE @var{h} @var{v}@angles{line break} 14268Draw a solid ellipse in the current fill color with a horizontal 14269diameter of@tie{}@var{h} and a vertical diameter of@tie{}@var{v} (both 14270integers in basic units @samp{u}) with the leftmost point at the 14271current position; then move to the rightmost point of the ellipse. 14272This command is a @code{gtroff} extension. 14273 14274@item De @var{h} @var{v}@angles{line break} 14275Draw an outlined ellipse with a horizontal diameter of@tie{}@var{h} 14276and a vertical diameter of@tie{}@var{v} (both integers in basic units 14277@samp{u}) with the leftmost point at current position; then move to 14278the rightmost point of the ellipse. 14279 14280@item DF @var{color-scheme} @r{[}@var{component} @dots{}@r{]}@angles{line break} 14281Set fill color for solid drawing objects using different color 14282schemes; the analoguous command for setting the color of text, line 14283graphics, and the outline of graphic objects is @samp{m}. 14284The color components are specified as integer arguments between 0 and 1428565536. The number of color components and their meaning vary for the 14286different color schemes. These commands are generated by @code{gtroff}'s 14287escape sequences @w{@code{\D'F @dots{}'}} and @code{\M} (with no other 14288corresponding graphics commands). No position changing. This command 14289is a @code{gtroff} extension. 14290 14291@table @code 14292@item DFc @var{cyan} @var{magenta} @var{yellow}@angles{line break} 14293Set fill color for solid drawing objects using the CMY color scheme, 14294having the 3@tie{}color components @var{cyan}, @var{magenta}, and 14295@var{yellow}. 14296 14297@item DFd@angles{line break} 14298Set fill color for solid drawing objects to the default fill color value 14299(black in most cases). No component arguments. 14300 14301@item DFg @var{gray}@angles{line break} 14302Set fill color for solid drawing objects to the shade of gray given by 14303the argument, an integer between 0 (black) and 65536 (white). 14304 14305@item DFk @var{cyan} @var{magenta} @var{yellow} @var{black}@angles{line break} 14306Set fill color for solid drawing objects using the CMYK color scheme, 14307having the 4@tie{}color components @var{cyan}, @var{magenta}, @var{yellow}, 14308and @var{black}. 14309 14310@item DFr @var{red} @var{green} @var{blue}@angles{line break} 14311Set fill color for solid drawing objects using the RGB color scheme, 14312having the 3@tie{}color components @var{red}, @var{green}, and @var{blue}. 14313 14314@end table 14315 14316@item Df @var{n}@angles{line break} 14317The argument@tie{}@var{n} must be an integer in the range @math{-32767} 14318to 32767. 14319 14320@table @asis 14321@item @math{0 @LE @var{n} @LE 1000} 14322Set the color for filling solid drawing objects to a shade of gray, 14323where 0 corresponds to solid white, 1000 (the default) to solid black, 14324and values in between to intermediate shades of gray; this is 14325obsoleted by command @samp{DFg}. 14326 14327@item @math{@var{n} < 0} or @math{@var{n} > 1000} 14328Set the filling color to the color that is currently being used for 14329the text and the outline, see command @samp{m}. For example, the 14330command sequence 14331 14332@Example 14333mg 0 0 65536 14334Df -1 14335@endExample 14336 14337@noindent 14338sets all colors to blue. 14339 14340@end table 14341 14342@noindent 14343No position changing. This command is a @code{gtroff} extension. 14344 14345@item Dl @var{h} @var{v}@angles{line break} 14346Draw line from current position to offset (@var{h},@var{v}) (integers 14347in basic units @samp{u}); then set current position to the end of the 14348drawn line. 14349 14350@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14351Draw a polygon line from current position to offset (@var{h1},@var{v1}), 14352from there to offset (@var{h2},@var{v2}), etc.@: up to offset 14353(@var{hn},@var{vn}), and from there back to the starting position. 14354For historical reasons, the position is changed by adding the sum of 14355all arguments with odd index to the actual horizontal position and the 14356even ones to the vertical position. Although this doesn't make sense 14357it is kept for compatibility. 14358@ignore 14359As the polygon is closed, the end of drawing is the starting point, so 14360the position doesn't change. 14361@end ignore 14362This command is a @code{gtroff} extension. 14363 14364@item Dp @var{h1} @var{v1} @var{h2} @var{v2} @dots{} @var{hn} @var{vn}@angles{line break} 14365Draw a solid polygon in the current fill color rather than an outlined 14366polygon, using the same arguments and positioning as the corresponding 14367@samp{Dp} command. 14368@ignore 14369No position changing. 14370@end ignore 14371This command is a @code{gtroff} extension. 14372 14373@item Dt @var{n}@angles{line break} 14374Set the current line thickness to@tie{}@var{n} (an integer in basic 14375units @samp{u}) if @math{@var{n}>0}; if @math{@var{n}=0} select the 14376smallest available line thickness; if @math{@var{n}<0} set the line 14377thickness proportional to the point size (this is the default before 14378the first @samp{Dt} command was specified). For historical reasons, 14379the horizontal position is changed by adding the argument to the actual 14380horizontal position, while the vertical position is not changed. 14381Although this doesn't make sense it is kept for compatibility. 14382@ignore 14383No position changing. 14384@end ignore 14385This command is a @code{gtroff} extension. 14386 14387@end table 14388 14389@node Device Control Commands, Obsolete Command, Graphics Commands, Command Reference 14390@subsubsection Device Control Commands 14391 14392Each device control command starts with the letter @samp{x}, 14393followed by a space character (optional or arbitrary space or tab in 14394@code{gtroff}) and a subcommand letter or word; each argument (if any) 14395must be preceded by a syntactical space. All @samp{x} commands are 14396terminated by a syntactical line break; no device control command can 14397be followed by another command on the same line (except a comment). 14398 14399The subcommand is basically a single letter, but to increase 14400readability, it can be written as a word, i.e., an arbitrary sequence 14401of characters terminated by the next tab, space, or newline character. 14402All characters of the subcommand word but the first are simply ignored. 14403For example, @code{gtroff} outputs the initialization command 14404@w{@samp{x i}} as @w{@samp{x init}} and the resolution command 14405@w{@samp{x r}} as @w{@samp{x res}}. 14406 14407In the following, the syntax element @angles{line break} means a 14408syntactical line break (@pxref{Separation}). 14409 14410@table @code 14411@item xF @var{name}@angles{line break} 14412The @samp{F} stands for @var{Filename}. 14413 14414Use @var{name} as the intended name for the current file in error 14415reports. This is useful for remembering the original file name when 14416@code{gtroff} uses an internal piping mechanism. The input file is 14417not changed by this command. This command is a @code{gtroff} extension. 14418 14419@item xf @var{n} @var{s}@angles{line break} 14420The @samp{f} stands for @var{font}. 14421 14422Mount font position@tie{}@var{n} (a non-negative integer) with font 14423named@tie{}@var{s} (a text word). @xref{Font Positions}. 14424 14425@item xH @var{n}@angles{line break} 14426The @samp{H} stands for @var{Height}. 14427 14428Set glyph height to@tie{}@var{n} (a positive integer in scaled 14429points @samp{z}). @acronym{AT&T} @code{troff} uses the unit points 14430(@samp{p}) instead. @xref{Output Language Compatibility}. 14431 14432@item xi@angles{line break} 14433The @samp{i} stands for @var{init}. 14434 14435Initialize device. This is the third command of the prologue. 14436 14437@item xp@angles{line break} 14438The @samp{p} stands for @var{pause}. 14439 14440Parsed but ignored. The original @acronym{UNIX} troff manual writes 14441 14442@display 14443pause device, can be restarted 14444@end display 14445 14446@item xr @var{n} @var{h} @var{v}@angles{line break} 14447The @samp{r} stands for @var{resolution}. 14448 14449Resolution is@tie{}@var{n}, while @var{h} is the minimal horizontal 14450motion, and @var{v} the minimal vertical motion possible with this 14451device; all arguments are positive integers in basic units @samp{u} 14452per inch. This is the second command of the prologue. 14453 14454@item xS @var{n}@angles{line break} 14455The @samp{S} stands for @var{Slant}. 14456 14457Set slant to@tie{}@var{n} (an integer in basic units @samp{u}). 14458 14459@item xs@angles{line break} 14460The @samp{s} stands for @var{stop}. 14461 14462Terminates the processing of the current file; issued as the last 14463command of any intermediate troff output. 14464 14465@item xt@angles{line break} 14466The @samp{t} stands for @var{trailer}. 14467 14468Generate trailer information, if any. In @var{gtroff}, this is 14469actually just ignored. 14470 14471@item xT @var{xxx}@angles{line break} 14472The @samp{T} stands for @var{Typesetter}. 14473 14474Set name of device to word @var{xxx}, a sequence of characters ended 14475by the next white space character. The possible device names coincide 14476with those from the @code{groff} @option{-T} option. This is the first 14477command of the prologue. 14478 14479@item xu @var{n}@angles{line break} 14480The @samp{u} stands for @var{underline}. 14481 14482Configure underlining of spaces. If @var{n} is@tie{}1, start 14483underlining of spaces; if @var{n} is@tie{}0, stop underlining of spaces. 14484This is needed for the @code{cu} request in nroff mode and is ignored 14485otherwise. This command is a @code{gtroff} extension. 14486 14487@item xX @var{anything}@angles{line break} 14488The @samp{x} stands for @var{X-escape}. 14489 14490Send string @var{anything} uninterpreted to the device. If the line 14491following this command starts with a @samp{+} character this line is 14492interpreted as a continuation line in the following sense. The 14493@samp{+} is ignored, but a newline character is sent instead to the 14494device, the rest of the line is sent uninterpreted. The same applies 14495to all following lines until the first character of a line is not a 14496@samp{+} character. This command is generated by the @code{gtroff} 14497escape sequence @code{\X}. The line-continuing feature is a 14498@code{gtroff} extension. 14499 14500@end table 14501 14502@node Obsolete Command, , Device Control Commands, Command Reference 14503@subsubsection Obsolete Command 14504In @acronym{AT&T} @code{troff} output, the writing of a single 14505glyph is mostly done by a very strange command that combines a 14506horizontal move and a single character giving the glyph name. It 14507doesn't have a command code, but is represented by a 3-character 14508argument consisting of exactly 2@tie{}digits and a character. 14509 14510@table @asis 14511@item @var{dd}@var{g} 14512Move right @var{dd} (exactly two decimal digits) basic units @samp{u}, 14513then print glyph@tie{}@var{g} (represented as a single character). 14514 14515In @code{gtroff}, arbitrary syntactical space around and within this 14516command is allowed to be added. Only when a preceding command on the 14517same line ends with an argument of variable length a separating space 14518is obligatory. In @acronym{AT&T} @code{troff}, large clusters of these 14519and other commands are used, mostly without spaces; this made such output 14520almost unreadable. 14521 14522@end table 14523 14524For modern high-resolution devices, this command does not make sense 14525because the width of the glyphs can become much larger than two 14526decimal digits. In @code{gtroff}, this is only used for the devices 14527@code{X75}, @code{X75-12}, @code{X100}, and @code{X100-12}. For other 14528devices, the commands @samp{t} and @samp{u} provide a better 14529functionality. 14530 14531@c --------------------------------------------------------------------- 14532 14533@node Intermediate Output Examples, Output Language Compatibility, Command Reference, gtroff Output 14534@subsection Intermediate Output Examples 14535 14536This section presents the intermediate output generated from the same 14537input for three different devices. The input is the sentence 14538@samp{hell world} fed into @code{gtroff} on the command line. 14539 14540@table @asis 14541@item High-resolution device @code{ps} 14542 14543This is the standard output of @code{gtroff} if no @option{-T} option 14544is given. 14545 14546@example 14547@group 14548shell> echo "hell world" | groff -Z -T ps 14549 14550x T ps 14551x res 72000 1 1 14552x init 14553@end group 14554p1 14555x font 5 TR 14556f5 14557s10000 14558V12000 14559H72000 14560thell 14561wh2500 14562tw 14563H96620 14564torld 14565n12000 0 14566@group 14567x trailer 14568V792000 14569x stop 14570@end group 14571@end example 14572 14573@noindent 14574This output can be fed into @code{grops} to get its representation as 14575a PostScript file. 14576 14577@item Low-resolution device @code{latin1} 14578 14579This is similar to the high-resolution device except that the 14580positioning is done at a minor scale. Some comments (lines starting 14581with @samp{#}) were added for clarification; they were not generated 14582by the formatter. 14583 14584@example 14585@group 14586shell> echo "hell world" | groff -Z -T latin1 14587 14588# prologue 14589x T latin1 14590x res 240 24 40 14591x init 14592@end group 14593# begin a new page 14594p1 14595# font setup 14596x font 1 R 14597f1 14598s10 14599# initial positioning on the page 14600V40 14601H0 14602# write text `hell' 14603thell 14604# inform about space, and issue a horizontal jump 14605wh24 14606# write text `world' 14607tworld 14608# announce line break, but do nothing because ... 14609n40 0 14610@group 14611# ... the end of the document has been reached 14612x trailer 14613V2640 14614x stop 14615@end group 14616@end example 14617 14618@noindent 14619This output can be fed into @code{grotty} to get a formatted text 14620document. 14621 14622@item @acronym{AT&T} @code{troff} output 14623Since a computer monitor has a very low resolution compared to modern 14624printers the intermediate output for the X@tie{}Window devices can use 14625the jump-and-write command with its 2-digit displacements. 14626 14627@example 14628@group 14629shell> echo "hell world" | groff -Z -T X100 14630 14631x T X100 14632x res 100 1 1 14633x init 14634@end group 14635p1 14636x font 5 TR 14637f5 14638s10 14639V16 14640H100 14641# write text with jump-and-write commands 14642ch07e07l03lw06w11o07r05l03dh7 14643n16 0 14644@group 14645x trailer 14646V1100 14647x stop 14648@end group 14649@end example 14650 14651@noindent 14652This output can be fed into @code{xditview} or @code{gxditview} 14653for displaying in@tie{}X. 14654 14655Due to the obsolete jump-and-write command, the text clusters in the 14656@acronym{AT&T} @code{troff} output are almost unreadable. 14657 14658@end table 14659 14660@c --------------------------------------------------------------------- 14661 14662@node Output Language Compatibility, , Intermediate Output Examples, gtroff Output 14663@subsection Output Language Compatibility 14664 14665The intermediate output language of @acronym{AT&T} @code{troff} 14666was first documented in the @acronym{UNIX} troff manual, with later 14667additions documented in @cite{A Typesetter-indenpendent TROFF}, 14668written by Brian Kernighan. 14669 14670The @code{gtroff} intermediate output format is compatible with this 14671specification except for the following features. 14672 14673@itemize @bullet 14674@item 14675The classical quasi device independence is not yet implemented. 14676 14677@item 14678The old hardware was very different from what we use today. So the 14679@code{groff} devices are also fundamentally different from the ones in 14680@acronym{AT&T} @code{troff}. For example, the @acronym{AT&T} 14681PostScript device is called @code{post} and has a resolution of only 14682720 units per inch, suitable for printers 20 years ago, while 14683@code{groff}'s @code{ps} device has a resolution of 1468472000 units per inch. Maybe, by implementing some rescaling 14685mechanism similar to the classical quasi device independence, 14686@code{groff} could emulate @acronym{AT&T}'s @code{post} device. 14687 14688@item 14689The B-spline command @samp{D~} is correctly handled by the 14690intermediate output parser, but the drawing routines aren't 14691implemented in some of the postprocessor programs. 14692 14693@item 14694The argument of the commands @samp{s} and @w{@samp{x H}} has the 14695implicit unit scaled point @samp{z} in @code{gtroff}, while 14696@acronym{AT&T} @code{troff} has point (@samp{p}). This isn't an 14697incompatibility but a compatible extension, for both units coincide 14698for all devices without a @code{sizescale} parameter in the @file{DESC} 14699file, including all postprocessors from @acronym{AT&T} and 14700@code{groff}'s text devices. The few @code{groff} devices with 14701a @code{sizescale} parameter either do not exist for @acronym{AT&T} 14702@code{troff}, have a different name, or seem to have a different 14703resolution. So conflicts are very unlikely. 14704 14705@item 14706The position changing after the commands @samp{Dp}, @samp{DP}, and 14707@samp{Dt} is illogical, but as old versions of @code{gtroff} used this 14708feature it is kept for compatibility reasons. 14709 14710@ignore 14711Temporarily, there existed some confusion on the positioning after the 14712@samp{D} commands that are groff extensions. This has been clarified 14713by establishing the classical rule for all @code{groff} drawing commands: 14714 14715@itemize 14716@item 14717The position after a graphic object has been drawn is at its end; 14718for circles and ellipses, the `end' is at the right side. 14719 14720@item 14721From this, the positionings specified for the drawing commands above 14722follow quite naturally. 14723@end itemize 14724@end ignore 14725 14726@end itemize 14727 14728 14729@c ===================================================================== 14730 14731@node Font Files, , gtroff Output, File formats 14732@section Font Files 14733@cindex font files 14734@cindex files, font 14735 14736The @code{gtroff} font format is roughly a superset of the 14737@code{ditroff} font format (as used in later versions of @acronym{AT&T} 14738@code{troff} and its descendants). Unlike the @code{ditroff} font 14739format, there is no associated binary format; all files are text 14740files.@footnote{Plan@tie{}9 @code{troff} has also abandoned the binary 14741format.} The font files for device @var{name} are stored in a directory 14742@file{dev@var{name}}. There are two types of file: a device description 14743file called @file{DESC} and for each font@tie{}@var{f} a font file 14744called@tie{}@file{@var{f}}. 14745 14746@menu 14747* DESC File Format:: 14748* Font File Format:: 14749@end menu 14750 14751@c --------------------------------------------------------------------- 14752 14753@node DESC File Format, Font File Format, Font Files, Font Files 14754@subsection @file{DESC} File Format 14755@cindex @file{DESC} file, format 14756@cindex font description file, format 14757@cindex format of font description file 14758@pindex DESC@r{ file format} 14759 14760The @file{DESC} file can contain the following types of line. Except 14761for the @code{charset} keyword which must comes last (if at all), the 14762order of the lines is not important. 14763 14764@table @code 14765@item res @var{n} 14766@kindex res 14767@cindex device resolution 14768@cindex resolution, device 14769There are @var{n}@tie{}machine units per inch. 14770 14771@item hor @var{n} 14772@kindex hor 14773@cindex horizontal resolution 14774@cindex resolution, horizontal 14775The horizontal resolution is @var{n}@tie{}machine units. All horizontal 14776quantities are rounded to be multiples of this value. 14777 14778@item vert @var{n} 14779@kindex vert 14780@cindex vertical resolution 14781@cindex resolution, vertical 14782The vertical resolution is @var{n}@tie{}machine units. All vertical 14783quantities are rounded to be multiples of this value. 14784 14785@item sizescale @var{n} 14786@kindex sizescale 14787The scale factor for point sizes. By default this has a value of@tie{}1. 14788One scaled point is equal to one point/@var{n}. The arguments to the 14789@code{unitwidth} and @code{sizes} commands are given in scaled points. 14790@xref{Fractional Type Sizes}, for more information. 14791 14792@item unitwidth @var{n} 14793@kindex unitwidth 14794Quantities in the font files are given in machine units for fonts whose 14795point size is @var{n}@tie{}scaled points. 14796 14797@item prepro @var{program} 14798@kindex prepro 14799Call @var{program} as a preprocessor. Currently, this keyword is used 14800by @code{groff} with option @option{-Thtml} only. 14801 14802@item postpro @var{program} 14803@kindex postpro 14804Call @var{program} as a postprocessor. For example, the line 14805 14806@Example 14807postpro grodvi 14808@endExample 14809 14810@noindent 14811in the file @file{devdvi/DESC} makes @code{groff} call @code{grodvi} 14812if option @option{-Tdvi} is given (and @option{-Z} isn't used). 14813 14814@item tcommand 14815@kindex tcommand 14816This means that the postprocessor can handle the @samp{t} and @samp{u} 14817intermediate output commands. 14818 14819@item sizes @var{s1} @var{s2} @dots{} @var{sn} 0 14820@kindex sizes 14821This means that the device has fonts at @var{s1}, @var{s2}, @dots{} 14822@var{sn} scaled points. The list of sizes must be terminated by@tie{}0 14823(this is digit zero). Each @var{si} can also be a range of sizes 14824@var{m}-@var{n}. The list can extend over more than one line. 14825 14826@item styles @var{S1} @var{S2} @dots{} @var{Sm} 14827@kindex styles 14828The first @var{m}@tie{}font positions are associated with styles 14829@var{S1} @dots{} @var{Sm}. 14830 14831@item fonts @var{n} @var{F1} @var{F2} @var{F3} @dots{} @var{Fn} 14832@kindex fonts 14833Fonts @var{F1} @dots{} @var{Fn} are mounted in the font positions 14834@var{m}+1, @dots{}, @var{m}+@var{n} where @var{m} is the number of 14835styles. This command may extend over more than one line. A font name 14836of@tie{}0 means no font is mounted on the corresponding font position. 14837 14838@item family @var{fam} 14839@kindex family 14840The default font family is @var{fam}. 14841 14842@item use_charnames_in_special 14843@kindex use_charnames_in_special 14844This command indicates that @code{gtroff} should encode special 14845characters inside special commands. Currently, this is only used 14846by the @acronym{HTML} output device. @xref{Postprocessor Access}. 14847 14848@item papersize @var{string} @dots{} 14849@kindex papersize 14850Select a paper size. Valid values for @var{string} are the ISO paper 14851types @code{A0}-@code{A7}, @code{B0}-@code{B7}, @code{C0}-@code{C7}, 14852@code{D0}-@code{D7}, @code{DL}, and the US paper types @code{letter}, 14853@code{legal}, @code{tabloid}, @code{ledger}, @code{statement}, 14854@code{executive}, @code{com10}, and @code{monarch}. Case is not significant 14855for @var{string} if it holds predefined paper types. Alternatively, 14856@var{string} can be a file name (e.g.@: @file{/etc/papersize}); if the file 14857can be opened, @code{groff} reads the first line and tests for the above 14858paper sizes. Finally, @var{string} can be a custom paper size in the format 14859@code{@var{length},@var{width}} (no spaces before and after the comma). 14860Both @var{length} and @var{width} must have a unit appended; valid values 14861are @samp{i} for inches, @samp{C} for centimeters, @samp{p} for points, and 14862@samp{P} for picas. Example: @code{12c,235p}. An argument which starts 14863with a digit is always treated as a custom paper format. @code{papersize} 14864sets both the vertical and horizontal dimension of the output medium. 14865 14866More than one argument can be specified; @code{groff} scans from left to 14867right and uses the first valid paper specification. 14868 14869@item pass_filenames 14870@kindex pass_filenames 14871Tell @code{gtroff} to emit the name of the source file currently 14872being processed. This is achieved by the intermediate output command 14873@samp{F}. Currently, this is only used by the @acronym{HTML} output 14874device. 14875 14876@item print @var{program} 14877@kindex print 14878Use @var{program} as a spooler program for printing. If omitted, 14879the @option{-l} and @option{-L} options of @code{groff} are ignored. 14880 14881@item charset 14882@kindex charset 14883This line and everything following in the file are ignored. It is 14884allowed for the sake of backwards compatibility. 14885@end table 14886 14887The @code{res}, @code{unitwidth}, @code{fonts}, and @code{sizes} lines 14888are mandatory. Other commands are ignored by @code{gtroff} but may be 14889used by postprocessors to store arbitrary information about the device 14890in the @file{DESC} file. 14891 14892@kindex spare1 14893@kindex spare2 14894@kindex biggestfont 14895Here a list of obsolete keywords which are recognized by @code{groff} 14896but completely ignored: @code{spare1}, @code{spare2}, 14897@code{biggestfont}. 14898 14899@c --------------------------------------------------------------------- 14900 14901@node Font File Format, , DESC File Format, Font Files 14902@subsection Font File Format 14903@cindex font file, format 14904@cindex font description file, format 14905@cindex format of font files 14906@cindex format of font description files 14907 14908A @dfn{font file}, also (and probably better) called a @dfn{font 14909description file}, has two sections. The first section is a sequence 14910of lines each containing a sequence of blank delimited words; the first 14911word in the line is a key, and subsequent words give a value for that 14912key. 14913 14914@table @code 14915@item name @var{f} 14916@kindex name 14917The name of the font is@tie{}@var{f}. 14918 14919@item spacewidth @var{n} 14920@kindex spacewidth 14921The normal width of a space is@tie{}@var{n}. 14922 14923@item slant @var{n} 14924@kindex slant 14925The glyphs of the font have a slant of @var{n}@tie{}degrees. 14926(Positive means forward.) 14927 14928@item ligatures @var{lig1} @var{lig2} @dots{} @var{lign} [0] 14929@kindex ligatures 14930Glyphs @var{lig1}, @var{lig2}, @dots{}, @var{lign} are ligatures; 14931possible ligatures are @samp{ff}, @samp{fi}, @samp{fl}, @samp{ffi} and 14932@samp{ffl}. For backwards compatibility, the list of ligatures may be 14933terminated with a@tie{}0. The list of ligatures may not extend over more 14934than one line. 14935 14936@item special 14937@cindex special fonts 14938@kindex special 14939The font is @dfn{special}; this means that when a glyph is requested 14940that is not present in the current font, it is searched for in any 14941special fonts that are mounted. 14942@end table 14943 14944Other commands are ignored by @code{gtroff} but may be used by 14945postprocessors to store arbitrary information about the font in the font 14946file. 14947 14948@cindex comments in font files 14949@cindex font files, comments 14950@kindex # 14951The first section can contain comments which start with the @samp{#} 14952character and extend to the end of a line. 14953 14954The second section contains one or two subsections. It must contain a 14955@code{charset} subsection and it may also contain a @code{kernpairs} 14956subsection. These subsections can appear in any order. Each 14957subsection starts with a word on a line by itself. 14958 14959@kindex charset 14960The word @code{charset} starts the character set 14961subsection.@footnote{This keyword is misnamed since it starts a list 14962of ordered glyphs, not characters.} The @code{charset} line is 14963followed by a sequence of lines. Each line gives information for one 14964glyph. A line comprises a number of fields separated by blanks or 14965tabs. The format is 14966 14967@quotation 14968@var{name} @var{metrics} @var{type} @var{code} 14969[@var{entity-name}] [@code{--} @var{comment}] 14970@end quotation 14971 14972@cindex 8-bit input 14973@cindex input, 8-bit 14974@cindex accessing unnamed glyphs with @code{\N} 14975@cindex unnamed glyphs, accessing with @code{\N} 14976@cindex characters, unnamed, accessing with @code{\N} 14977@cindex glyphs, unnamed, accessing with @code{\N} 14978@kindex --- 14979@noindent 14980@var{name} identifies the glyph name@footnote{The distinction between 14981input, characters, and output, glyphs, is not clearly separated in the 14982terminology of @code{groff}; for example, the @code{char} request 14983should be called @code{glyph} since it defines an output entity.}: 14984If @var{name} is a single character@tie{}@var{c} then it corresponds 14985to the @code{gtroff} input character@tie{}@var{c}; if it is of the form 14986@samp{\@var{c}} where @var{c} is a single character, then it 14987corresponds to the special character @code{\[@var{c}]}; otherwise it 14988corresponds to the special character @samp{\[@var{name}]}. If it 14989is exactly two characters @var{xx} it can be entered as 14990@samp{\(@var{xx}}. Note that single-letter special characters can't 14991be accessed as @samp{\@var{c}}; the only exception is @samp{\-} which 14992is identical to @code{\[-]}. 14993 14994@code{gtroff} supports 8-bit input characters; however some utilities 14995have difficulties with eight-bit characters. For this reason, there is 14996a convention that the entity name @samp{char@var{n}} is equivalent to 14997the single input character whose code is@tie{}@var{n}. For example, 14998@samp{char163} would be equivalent to the character with code@tie{}163 14999which is the pounds sterling sign in the ISO@tie{}@w{Latin-1} character set. 15000You shouldn't use @samp{char@var{n}} entities in font description files 15001since they are related to input, not output. Otherwise, you get 15002hard-coded connections between input and output encoding which 15003prevents use of different (input) character sets. 15004 15005The name @samp{---} is special and indicates that the glyph is 15006unnamed; such glyphs can only be used by means of the @code{\N} 15007escape sequence in @code{gtroff}. 15008 15009The @var{type} field gives the glyph type: 15010 15011@table @code 15012@item 1 15013the glyph has a descender, for example, @samp{p}; 15014 15015@item 2 15016the glyph has an ascender, for example, @samp{b}; 15017 15018@item 3 15019the glyph has both an ascender and a descender, for example, @samp{(}. 15020@end table 15021 15022The @var{code} field gives the code which the postprocessor uses to 15023print the glyph. The glyph can also be input to @code{gtroff} 15024using this code by means of the @code{\N} escape sequence. @var{code} 15025can be any integer. If it starts with @samp{0} it is interpreted as 15026octal; if it starts with @samp{0x} or @samp{0X} it is interpreted as 15027hexadecimal. Note, however, that the @code{\N} escape sequence only 15028accepts a decimal integer. 15029 15030The @var{entity-name} field gives an @acronym{ASCII} string 15031identifying the glyph which the postprocessor uses to print the 15032@code{gtroff} glyph @var{name}. This field is optional and has been 15033introduced so that the @acronym{HTML} device driver can encode its 15034character set. For example, the glyph @samp{\[Po]} is 15035represented as @samp{£} in @acronym{HTML} 4.0. 15036 15037Anything on the line after the @var{entity-name} field resp.@: after 15038@samp{--} will be ignored. 15039 15040The @var{metrics} field has the form: 15041 15042@display 15043@group 15044@var{width}[@code{,}@var{height}[@code{,}@var{depth}[@code{,}@var{italic-correction} 15045 [@code{,}@var{left-italic-correction}[@code{,}@var{subscript-correction}]]]]] 15046@end group 15047@end display 15048 15049@noindent 15050There must not be any spaces between these subfields (it has been split 15051here into two lines for better legibility only). Missing subfields are 15052assumed to be@tie{}0. The subfields are all decimal integers. Since 15053there is no associated binary format, these values are not required to 15054fit into a variable of type @samp{char} as they are in @code{ditroff}. 15055The @var{width} subfield gives the width of the glyph. The @var{height} 15056subfield gives the height of the glyph (upwards is positive); if a 15057glyph does not extend above the baseline, it should be given a zero 15058height, rather than a negative height. The @var{depth} subfield gives 15059the depth of the glyph, that is, the distance from the baseline to the 15060lowest point below the baseline to which the glyph extends (downwards is 15061positive); if a glyph does not extend below the baseline, it should be 15062given a zero depth, rather than a negative depth. The 15063@var{italic-correction} subfield gives the amount of space that should 15064be added after the glyph when it is immediately to be followed by a 15065glyph from a roman font. The @var{left-italic-correction} subfield 15066gives the amount of space that should be added before the glyph when it 15067is immediately to be preceded by a glyph from a roman font. The 15068@var{subscript-correction} gives the amount of space that should be 15069added after a glyph before adding a subscript. This should be less 15070than the italic correction. 15071 15072A line in the @code{charset} section can also have the format 15073 15074@Example 15075@var{name} " 15076@endExample 15077 15078@noindent 15079This indicates that @var{name} is just another name for the glyph 15080mentioned in the preceding line. 15081 15082@kindex kernpairs 15083The word @code{kernpairs} starts the kernpairs section. This contains a 15084sequence of lines of the form: 15085 15086@Example 15087@var{c1} @var{c2} @var{n} 15088@endExample 15089 15090@noindent 15091This means that when glyph @var{c1} appears next to glyph @var{c2} 15092the space between them should be increased by@tie{}@var{n}. Most 15093entries in the kernpairs section have a negative value for@tie{}@var{n}. 15094 15095 15096 15097@c ===================================================================== 15098@c ===================================================================== 15099 15100@node Installation, Copying This Manual, File formats, Top 15101@chapter Installation 15102@cindex installation 15103 15104@c XXX 15105 15106 15107 15108@c ===================================================================== 15109@c ===================================================================== 15110 15111@node Copying This Manual, Request Index, Installation, Top 15112@appendix Copying This Manual 15113 15114@menu 15115* GNU Free Documentation License:: License for copying this manual. 15116@end menu 15117 15118@include fdl.texi 15119 15120 15121 15122@c ===================================================================== 15123@c ===================================================================== 15124 15125@node Request Index, Escape Index, Copying This Manual, Top 15126@appendix Request Index 15127 15128Requests appear without the leading control character (normally either 15129@samp{.} or @samp{'}). 15130 15131@printindex rq 15132 15133 15134 15135@c ===================================================================== 15136@c ===================================================================== 15137 15138@node Escape Index, Operator Index, Request Index, Top 15139@appendix Escape Index 15140 15141Any escape sequence @code{\@var{X}} with @var{X} not in the list below 15142emits a warning, printing glyph @var{X}. 15143 15144@printindex es 15145 15146 15147 15148@c ===================================================================== 15149@c ===================================================================== 15150 15151@node Operator Index, Register Index, Escape Index, Top 15152@appendix Operator Index 15153 15154@printindex op 15155 15156 15157 15158@c ===================================================================== 15159@c ===================================================================== 15160 15161@node Register Index, Macro Index, Operator Index, Top 15162@appendix Register Index 15163 15164The macro package or program a specific register belongs to is appended in 15165brackets. 15166 15167A register name@tie{}@code{x} consisting of exactly one character can be 15168accessed as @samp{\nx}. A register name @code{xx} consisting of exactly 15169two characters can be accessed as @samp{\n(xx}. Register names @code{xxx} 15170of any length can be accessed as @samp{\n[xxx]}. 15171 15172@printindex vr 15173 15174 15175 15176@c ===================================================================== 15177@c ===================================================================== 15178 15179@node Macro Index, String Index, Register Index, Top 15180@appendix Macro Index 15181 15182The macro package a specific macro belongs to is appended in brackets. 15183They appear without the leading control character (normally @samp{.}). 15184 15185@printindex ma 15186 15187 15188 15189@c ===================================================================== 15190@c ===================================================================== 15191 15192@node String Index, Glyph Name Index, Macro Index, Top 15193@appendix String Index 15194 15195The macro package or program a specific string belongs to is appended in 15196brackets. 15197 15198A string name@tie{}@code{x} consisting of exactly one character can be 15199accessed as @samp{\*x}. A string name @code{xx} consisting of exactly 15200two characters can be accessed as @samp{\*(xx}. String names @code{xxx} 15201of any length can be accessed as @samp{\*[xxx]}. 15202 15203 15204@printindex st 15205 15206 15207 15208@c ===================================================================== 15209@c ===================================================================== 15210 15211@node Glyph Name Index, Font File Keyword Index, String Index, Top 15212@appendix Glyph Name Index 15213 15214A glyph name @code{xx} consisting of exactly two characters can be 15215accessed as @samp{\(xx}. Glyph names @code{xxx} of any length can be 15216accessed as @samp{\[xxx]}. 15217 15218@c XXX 15219 15220 15221 15222@c ===================================================================== 15223@c ===================================================================== 15224 15225@node Font File Keyword Index, Program and File Index, Glyph Name Index, Top 15226@appendix Font File Keyword Index 15227 15228@printindex ky 15229 15230 15231 15232@c ===================================================================== 15233@c ===================================================================== 15234 15235@node Program and File Index, Concept Index, Font File Keyword Index, Top 15236@appendix Program and File Index 15237 15238@printindex pg 15239 15240 15241 15242@c ===================================================================== 15243@c ===================================================================== 15244 15245@node Concept Index, , Program and File Index, Top 15246@appendix Concept Index 15247 15248@printindex cp 15249 15250 15251@bye 15252