/contrib/groff/doc/groff.texinfo
Unknown | 15454 lines | 12574 code | 2880 blank | 0 comment | 0 complexity | 8b088c4112aed0fed1c425e0f04bd15a MD5 | raw file
Possible License(s): MPL-2.0-no-copyleft-exception, BSD-3-Clause, LGPL-2.0, LGPL-2.1, BSD-2-Clause, 0BSD, JSON, AGPL-1.0, GPL-2.0
Large files files are truncated, but you can click here to view the full file
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.6 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@documentlanguage en 18@documentencoding ISO-8859-1 19 20 21@smallbook 22 23@finalout 24 25 26@copying 27This manual documents GNU @code{troff} version 1.19.2. 28 29Copyright @copyright{} 1994-2000, 2001, 2002, 2003, 2004, 2005 30Free Software Foundation, Inc. 31 32@quotation 33Permission is granted to copy, distribute and/or modify this document 34under the terms of the GNU Free Documentation License, Version 1.1 or 35any later version published by the Free Software Foundation; with no 36Invariant Sections, with the Front-Cover texts being `A GNU Manual,'' 37and with the Back-Cover Texts as in (a) below. A copy of the 38license is included in the section entitled `GNU Free Documentation 39License.'' 40 41(a) The FSF's Back-Cover Text is: `You have freedom to copy and modify 42this GNU Manual, like GNU software. Copies published by the Free 43Software Foundation raise funds for GNU development.'' 44@end quotation 45@end copying 46 47 48@c We use the following indices: 49@c 50@c cindex: concepts 51@c rqindex: requests 52@c esindex: escapes 53@c vindex: registers 54@c kindex: commands in font files 55@c pindex: programs and files 56@c tindex: environment variables 57@c maindex: macros 58@c stindex: strings 59@c opindex: operators 60@c 61@c tindex and cindex are merged. 62 63@defcodeindex rq 64@defcodeindex es 65@defcodeindex ma 66@defcodeindex st 67@defcodeindex op 68@syncodeindex tp cp 69 70 71@c To avoid uppercasing in @deffn while converting to info, we define 72@c our special @Var{}. 73 74@macro Var{arg} 75@r{@slanted{\arg\}} 76@end macro 77 78 79@c To assure correct HTML translation, some ugly hacks are necessary. 80@c While processing a @def... request, the HTML translator looks at the 81@c next line to decide whether it should start indentation or not. If 82@c it is something starting with @def... (e.g. @deffnx), it doesn't. 83@c So we must assure during macro expansion that a @def... is seen. 84@c 85@c The following macros have to be used: 86@c 87@c One item: 88@c 89@c @Def... 90@c 91@c Two items: 92@c 93@c @Def...List 94@c @Def...ListEnd 95@c 96@c More than two: 97@c 98@c @Def...List 99@c @Def...Item 100@c @Def...Item 101@c ... 102@c @Def...ListEnd 103@c 104@c The definition block must end with 105@c 106@c @endDef... 107@c 108@c The above is valid for texinfo 4.0f and above. 109 110 111@c a dummy macro to assure the `@def...' 112 113@macro defdummy 114@c 115@end macro 116 117 118@c definition of requests 119 120@macro Defreq{name, arg} 121@deffn Request @t{.\name\} \arg\ 122@rqindex \name\ 123@c 124@end macro 125 126@macro DefreqList{name, arg} 127@deffn Request @t{.\name\} \arg\ 128@defdummy 129@rqindex \name\ 130@c 131@end macro 132 133@macro DefreqItem{name, arg} 134@deffnx Request @t{.\name\} \arg\ 135@defdummy 136@rqindex \name\ 137@c 138@end macro 139 140@macro DefreqListEnd{name, arg} 141@deffnx Request @t{.\name\} \arg\ 142@rqindex \name\ 143@c 144@end macro 145 146@macro endDefreq 147@end deffn 148@end macro 149 150 151@c definition of escapes 152 153@macro Defesc{name, delimI, arg, delimII} 154@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 155@esindex \name\ 156@c 157@end macro 158 159@macro DefescList{name, delimI, arg, delimII} 160@deffn Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 161@defdummy 162@esindex \name\ 163@c 164@end macro 165 166@macro DefescItem{name, delimI, arg, delimII} 167@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 168@defdummy 169@esindex \name\ 170@c 171@end macro 172 173@macro DefescListEnd{name, delimI, arg, delimII} 174@deffnx Escape @t{\name\\delimI\}@Var{\arg\}@t{\delimII\} 175@esindex \name\ 176@c 177@end macro 178 179@macro endDefesc 180@end deffn 181@end macro 182 183 184@c definition of registers 185 186@macro Defreg{name} 187@deffn Register @t{\\n[\name\]} 188@vindex \name\ 189@c 190@end macro 191 192@macro DefregList{name} 193@deffn Register @t{\\n[\name\]} 194@defdummy 195@vindex \name\ 196@c 197@end macro 198 199@macro DefregItem{name} 200@deffnx Register @t{\\n[\name\]} 201@defdummy 202@vindex \name\ 203@c 204@end macro 205 206@macro DefregListEnd{name} 207@deffnx Register @t{\\n[\name\]} 208@vindex \name\ 209@c 210@end macro 211 212@macro endDefreg 213@end deffn 214@end macro 215 216 217@c definition of registers specific to macro packages, preprocessors, etc. 218 219@macro Defmpreg{name, package} 220@deffn Register @t{\\n[\name\]} 221@vindex \name\ @r{[}\package\@r{]} 222@c 223@end macro 224 225@macro DefmpregList{name, package} 226@deffn Register @t{\\n[\name\]} 227@defdummy 228@vindex \name\ @r{[}\package\@r{]} 229@c 230@end macro 231 232@macro DefmpregItem{name, package} 233@deffnx Register @t{\\n[\name\]} 234@defdummy 235@vindex \name\ @r{[}\package\@r{]} 236@c 237@end macro 238 239@macro DefmpregListEnd{name, package} 240@deffnx Register @t{\\n[\name\]} 241@vindex \name\ @r{[}\package\@r{]} 242@c 243@end macro 244 245@macro endDefmpreg 246@end deffn 247@end macro 248 249 250@c definition of macros 251 252@macro Defmac{name, arg, package} 253@defmac @t{.\name\} \arg\ 254@maindex \name\ @r{[}\package\@r{]} 255@c 256@end macro 257 258@macro DefmacList{name, arg, package} 259@defmac @t{.\name\} \arg\ 260@defdummy 261@maindex \name\ @r{[}\package\@r{]} 262@c 263@end macro 264 265@macro DefmacItem{name, arg, package} 266@defmacx @t{.\name\} \arg\ 267@defdummy 268@maindex \name\ @r{[}\package\@r{]} 269@c 270@end macro 271 272@macro DefmacListEnd{name, arg, package} 273@defmacx @t{.\name\} \arg\ 274@maindex \name\ @r{[}\package\@r{]} 275@c 276@end macro 277 278@macro endDefmac 279@end defmac 280@end macro 281 282 283@c definition of strings 284 285@macro Defstr{name, package} 286@deffn String @t{\\*[\name\]} 287@stindex \name\ @r{[}\package\@r{]} 288@c 289@end macro 290 291@macro DefstrList{name, package} 292@deffn String @t{\\*[\name\]} 293@defdummy 294@stindex \name\ @r{[}\package\@r{]} 295@c 296@end macro 297 298@macro DefstrItem{name, package} 299@deffnx String @t{\\*[\name\]} 300@defdummy 301@stindex \name\ @r{[}\package\@r{]} 302@c 303@end macro 304 305@macro DefstrListEnd{name, package} 306@deffnx String @t{\\*[\name\]} 307@stindex \name\ @r{[}\package\@r{]} 308@c 309@end macro 310 311@macro endDefstr 312@end deffn 313@end macro 314 315 316@c our example macro 317 318@macro Example 319@example 320@group 321@end macro 322 323@macro endExample 324@end group 325@end example 326@end macro 327 328 329@c <text> 330 331@tex 332\gdef\Langlemacro{\angleleft} 333\gdef\Ranglemacro{\angleright} 334@end tex 335 336@iftex 337@set Langlemacro @Langlemacro 338@set Ranglemacro @Ranglemacro 339@end iftex 340 341@ifnottex 342@set Langlemacro < 343@set Ranglemacro > 344@end ifnottex 345 346@macro angles{text} 347@value{Langlemacro}@r{\text\}@value{Ranglemacro} 348@end macro 349 350 351@c a <= sign 352@c 353@c A value defined with @set is embedded into three group levels if 354@c called with @value, so we need seven \aftergroup to put \le outside 355@c of the groups -- this is necessary to get proper mathematical spacing. 356 357@tex 358\gdef\LEmacro{\aftergroup\aftergroup\aftergroup\aftergroup 359 \aftergroup\aftergroup\aftergroup\le} 360@end tex 361 362@iftex 363@set LEmacro @LEmacro 364@end iftex 365 366@ifnottex 367@set LEmacro <= 368@end ifnottex 369 370@macro LE 371@value{LEmacro} 372@end macro 373 374 375@c We need special parentheses, brackets, and braces: 376@c 377@c . Real parentheses in @deffn produce an error while compiling with 378@c TeX. 379@c . Real brackets use the wrong font in @deffn, overriding @t{}. 380@c 381@c . @{ and @} fail with info if used in a macro. 382@c 383@c Since macros aren't expanded in @deffn during -E, the following 384@c definitions are for non-TeX only. 385@c 386@c This is true for texinfo 4.0 and above. 387 388@iftex 389@set Lparenmacro @lparen 390@set Rparenmacro @rparen 391@set Lbrackmacro @lbrack 392@set Rbrackmacro @rbrack 393@set Lbracemacro @{ 394@set Rbracemacro @} 395@end iftex 396 397@ifnottex 398@set Lparenmacro ( 399@set Rparenmacro ) 400@set Lbrackmacro [ 401@set Rbrackmacro ] 402@set Lbracemacro @{ 403@set Rbracemacro @} 404@end ifnottex 405 406@macro Lparen{} 407@value{Lparenmacro} 408@end macro 409@macro Rparen{} 410@value{Rparenmacro} 411@end macro 412@macro Lbrack{} 413@value{Lbrackmacro} 414@end macro 415@macro Rbrack{} 416@value{Rbrackmacro} 417@end macro 418@macro Lbrace{} 419@value{Lbracemacro} 420@end macro 421@macro Rbrace{} 422@value{Rbracemacro} 423@end macro 424 425 426@c This suppresses the word `Appendix' in the appendix headers. 427 428@tex 429\gdef\gobblefirst#1#2{#2} 430\gdef\putwordAppendix{\gobblefirst} 431@end tex 432 433 434@c We map some latin-1 characters to corresponding texinfo macros. 435 436@tex 437\global\catcode`^^e4\active % ä 438\gdef^^e4{\"a} 439\global\catcode`^^c4\active % Ä 440\gdef^^c4{\"A} 441\global\catcode`^^e9\active % é 442\gdef^^e9{\'e} 443\global\catcode`^^c9\active % É 444\gdef^^c9{\'E} 445\global\catcode`^^f6\active % ö 446\gdef^^f6{\"o} 447\global\catcode`^^d6\active % Ö 448\gdef^^d6{\"O} 449\global\catcode`^^fc\active % ü 450\gdef^^fc{\"u} 451\global\catcode`^^dc\active % Ü 452\gdef^^dc{\"U} 453\global\catcode`^^e6\active % ć 454\gdef^^e6{\ae} 455\global\catcode`^^c6\active % Ć 456\gdef^^c6{\AE} 457\global\catcode`^^df\active % ß 458\gdef^^df{\ss} 459@end tex 460 461 462@c Note: We say `Roman numerals' but `roman font'. 463 464 465@dircategory Typesetting 466@direntry 467* Groff: (groff). The GNU troff document formatting system. 468@end direntry 469 470 471@titlepage 472@title groff 473@subtitle The GNU implementation of @code{troff} 474@subtitle Edition 1.19.2 475@subtitle Summer 2005 476@author by Trent A.@tie{}Fisher 477@author and Werner Lemberg (@email{bug-groff@@gnu.org}) 478 479@page 480@vskip 0pt plus 1filll 481@insertcopying 482@end titlepage 483 484 485@contents 486 487@ifinfo 488@node Top, Introduction, (dir), (dir) 489@top GNU troff 490 491@insertcopying 492@end ifinfo 493 494@ifhtml 495@menu 496* Introduction:: 497* Invoking groff:: 498* Tutorial for Macro Users:: 499* Macro Packages:: 500* gtroff Reference:: 501* Preprocessors:: 502* Output Devices:: 503* File formats:: 504* Installation:: 505* Copying This Manual:: 506* Request Index:: 507* Escape Index:: 508* Operator Index:: 509* Register Index:: 510* Macro Index:: 511* String Index:: 512* Glyph Name Index:: 513* Font File Keyword Index:: 514* Program and File Index:: 515* Concept Index:: 516@end menu 517 518@node Top, Introduction, (dir), (dir) 519@top GNU troff 520 521@insertcopying 522@end ifhtml 523 524@menu 525* Introduction:: 526* Invoking groff:: 527* Tutorial for Macro Users:: 528* Macro Packages:: 529* gtroff Reference:: 530* Preprocessors:: 531* Output Devices:: 532* File formats:: 533* Installation:: 534* Copying This Manual:: 535* Request Index:: 536* Escape Index:: 537* Operator Index:: 538* Register Index:: 539* Macro Index:: 540* String Index:: 541* Glyph Name Index:: 542* Font File Keyword Index:: 543* Program and File Index:: 544* Concept Index:: 545@end menu 546 547 548 549@c ===================================================================== 550@c ===================================================================== 551 552@node Introduction, Invoking groff, Top, Top 553@chapter Introduction 554@cindex introduction 555 556GNU @code{troff} (or @code{groff}) is a system for typesetting 557documents. @code{troff} is very flexible and has been in existence (and 558use) for about 3@tie{}decades. It is quite widespread and firmly 559entrenched in the @acronym{UNIX} community. 560 561@menu 562* What Is groff?:: 563* History:: 564* groff Capabilities:: 565* Macro Package Intro:: 566* Preprocessor Intro:: 567* Output device intro:: 568* Credits:: 569@end menu 570 571 572@c ===================================================================== 573 574@node What Is groff?, History, Introduction, Introduction 575@section What Is @code{groff}? 576@cindex what is @code{groff}? 577@cindex @code{groff} -- what is it? 578 579@code{groff} belongs to an older generation of document preparation 580systems, which operate more like compilers than the more recent 581interactive @acronym{WYSIWYG}@footnote{What You See Is What You Get} 582systems. @code{groff} and its contemporary counterpart, @TeX{}, both 583work using a @dfn{batch} paradigm: The input (or @dfn{source}) files are 584normal text files with embedded formatting commands. These files can 585then be processed by @code{groff} to produce a typeset document on a 586variety of devices. 587 588Likewise, @code{groff} should not be confused with a @dfn{word 589processor}, since that term connotes an integrated system that includes 590an editor and a text formatter. Also, many word processors follow the 591@acronym{WYSIWYG} paradigm discussed earlier. 592 593Although @acronym{WYSIWYG} systems may be easier to use, they have a 594number of disadvantages compared to @code{troff}: 595 596@itemize @bullet 597@item 598They must be used on a graphics display to work on a document. 599 600@item 601Most of the @acronym{WYSIWYG} systems are either non-free or are not 602very portable. 603 604@item 605@code{troff} is firmly entrenched in all @acronym{UNIX} systems. 606 607@item 608It is difficult to have a wide range of capabilities available within 609the confines of a GUI/window system. 610 611@item 612It is more difficult to make global changes to a document. 613@end itemize 614 615@quotation 616``GUIs normally make it simple to accomplish simple actions and 617impossible to accomplish complex actions.'' --Doug Gwyn (22/Jun/91 in 618@code{comp.unix.wizards}) 619@end quotation 620 621 622@c ===================================================================== 623 624@node History, groff Capabilities, What Is groff?, Introduction 625@section History 626@cindex history 627 628@cindex @code{runoff}, the program 629@cindex @code{rf}, the program 630@code{troff} can trace its origins back to a formatting program called 631@code{runoff}, written by J.@tie{}E.@tie{}Saltzer, which ran on MIT's CTSS 632operating system in the mid-sixties. This name came from the common 633phrase of the time ``I'll run off a document.'' Bob Morris ported it to 634the 635 architecture and called the program @code{roff} (an abbreviation 635of @code{runoff}). It was rewritten as @code{rf} for the @w{PDP-7} 636(before having @acronym{UNIX}), and at the same time (1969), Doug 637McIllroy rewrote an extended and simplified version of @code{roff} in 638the @acronym{BCPL} programming language. 639 640@cindex @code{roff}, the program 641The first version of @acronym{UNIX} was developed on a @w{PDP-7} which 642was sitting around Bell Labs. In 1971 the developers wanted to get a 643@w{PDP-11} for further work on the operating system. In order to 644justify the cost for this system, they proposed that they would 645implement a document formatting system for the @acronym{AT&T} patents 646division. This first formatting program was a reimplementation of 647McIllroy's @code{roff}, written by J.@tie{}F.@tie{}Ossanna. 648 649@cindex @code{nroff}, the program 650When they needed a more flexible language, a new version of @code{roff} 651called @code{nroff} (``Newer @code{roff}'') was written. It had a much 652more complicated syntax, but provided the basis for all future versions. 653When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 654version of @code{nroff} that would drive it. It was dubbed 655@code{troff}, for ``typesetter @code{roff}'', although many people have 656speculated that it actually means ``Times @code{roff}'' because of the 657use of the Times font family in @code{troff} by default. As such, the 658name @code{troff} is pronounced `@w{t-roff}' rather than `trough'. 659 660With @code{troff} came @code{nroff} (they were actually the same program 661except for some @samp{#ifdef}s), which was for producing output for line 662printers and character terminals. It understood everything @code{troff} 663did, and ignored the commands which were not applicable (e.g.@: font 664changes). 665 666Since there are several things which cannot be done easily in 667@code{troff}, work on several preprocessors began. These programs would 668transform certain parts of a document into @code{troff}, which made a 669very natural use of pipes in @acronym{UNIX}. 670 671The @code{eqn} preprocessor allowed mathematical formulć to be 672specified in a much simpler and more intuitive manner. @code{tbl} is a 673preprocessor for formatting tables. The @code{refer} preprocessor (and 674the similar program, @code{bib}) processes citations in a document 675according to a bibliographic database. 676 677Unfortunately, Ossanna's @code{troff} was written in @w{PDP-11} assembly 678language and produced output specifically for the CAT phototypesetter. 679He rewrote it in C, although it was now 7000@tie{}lines of uncommented 680code and still dependent on the CAT. As the CAT became less common, and 681was no longer supported by the manufacturer, the need to make it support 682other devices became a priority. However, before this could be done, 683Ossanna was killed in a car accident. 684 685@pindex ditroff 686@cindex @code{ditroff}, the program 687So, Brian Kernighan took on the task of rewriting @code{troff}. The 688newly rewritten version produced device independent code which was 689very easy for postprocessors to read and translate to the appropriate 690printer codes. Also, this new version of @code{troff} (called 691@code{ditroff} for ``device independent @code{troff}'') had several 692extensions, which included drawing functions. 693 694Due to the additional abilities of the new version of @code{troff}, 695several new preprocessors appeared. The @code{pic} preprocessor 696provides a wide range of drawing functions. Likewise the @code{ideal} 697preprocessor did the same, although via a much different paradigm. The 698@code{grap} preprocessor took specifications for graphs, but, unlike 699other preprocessors, produced @code{pic} code. 700 701James Clark began work on a GNU implementation of @code{ditroff} in 702early@tie{}1989. The first version, @code{groff}@tie{}0.3.1, was released 703June@tie{}1990. @code{groff} included: 704 705@itemize @bullet 706@item 707A replacement for @code{ditroff} with many extensions. 708 709@item 710The @code{soelim}, @code{pic}, @code{tbl}, and @code{eqn} preprocessors. 711 712@item 713Postprocessors for character devices, @sc{PostScript}, @TeX{} DVI, and 714X@tie{}Windows. GNU @code{troff} also eliminated the need for a 715separate @code{nroff} program with a postprocessor which would produce 716@acronym{ASCII} output. 717 718@item 719A version of the @file{me} macros and an implementation of the 720@file{man} macros. 721@end itemize 722 723Also, a front-end was included which could construct the, sometimes 724painfully long, pipelines required for all the post- and preprocessors. 725 726Development of GNU @code{troff} progressed rapidly, and saw the 727additions of a replacement for @code{refer}, an implementation of the 728@file{ms} and @file{mm} macros, and a program to deduce how to format a 729document (@code{grog}). 730 731It was declared a stable (i.e.@: non-beta) package with the release of 732version@tie{}1.04 around November@tie{}1991. 733 734Beginning in@tie{}1999, @code{groff} has new maintainers (the package was 735an orphan for a few years). As a result, new features and programs like 736@code{grn}, a preprocessor for gremlin images, and an output device to 737produce @acronym{HTML} output have been added. 738 739 740@c ===================================================================== 741 742@node groff Capabilities, Macro Package Intro, History, Introduction 743@section @code{groff} Capabilities 744@cindex @code{groff} capabilities 745@cindex capabilities of @code{groff} 746 747So what exactly is @code{groff} capable of doing? @code{groff} provides 748a wide range of low-level text formatting operations. Using these, it 749is possible to perform a wide range of formatting tasks, such as 750footnotes, table of contents, multiple columns, etc. Here's a list of 751the most important operations supported by @code{groff}: 752 753@itemize @bullet 754@item 755text filling, adjusting, and centering 756 757@item 758hyphenation 759 760@item 761page control 762 763@item 764font and glyph size control 765 766@item 767vertical spacing (e.g.@: double-spacing) 768 769@item 770line length and indenting 771 772@item 773macros, strings, diversions, and traps 774 775@item 776number registers 777 778@item 779tabs, leaders, and fields 780 781@item 782input and output conventions and character translation 783 784@item 785overstrike, bracket, line drawing, and zero-width functions 786 787@item 788local horizontal and vertical motions and the width function 789 790@item 791three-part titles 792 793@item 794output line numbering 795 796@item 797conditional acceptance of input 798 799@item 800environment switching 801 802@item 803insertions from the standard input 804 805@item 806input/output file switching 807 808@item 809output and error messages 810@end itemize 811 812 813@c ===================================================================== 814 815@node Macro Package Intro, Preprocessor Intro, groff Capabilities, Introduction 816@section Macro Packages 817@cindex macro packages 818 819Since @code{groff} provides such low-level facilities, it can be quite 820difficult to use by itself. However, @code{groff} provides a 821@dfn{macro} facility to specify how certain routine operations 822(e.g.@tie{}starting paragraphs, printing headers and footers, etc.)@: 823should be done. These macros can be collected together into a @dfn{macro 824package}. There are a number of macro packages available; the most 825common (and the ones described in this manual) are @file{man}, 826@file{mdoc}, @file{me}, @file{ms}, and @file{mm}. 827 828 829@c ===================================================================== 830 831@node Preprocessor Intro, Output device intro, Macro Package Intro, Introduction 832@section Preprocessors 833@cindex preprocessors 834 835Although @code{groff} provides most functions needed to format a 836document, some operations would be unwieldy (e.g.@: to draw pictures). 837Therefore, programs called @dfn{preprocessors} were written which 838understand their own language and produce the necessary @code{groff} 839operations. These preprocessors are able to differentiate their own 840input from the rest of the document via markers. 841 842To use a preprocessor, @acronym{UNIX} pipes are used to feed the output 843from the preprocessor into @code{groff}. Any number of preprocessors 844may be used on a given document; in this case, the preprocessors are 845linked together into one pipeline. However, with @code{groff}, the user 846does not need to construct the pipe, but only tell @code{groff} what 847preprocessors to use. 848 849@code{groff} currently has preprocessors for producing tables 850(@code{tbl}), typesetting equations (@code{eqn}), drawing pictures 851(@code{pic} and @code{grn}), and for processing bibliographies 852(@code{refer}). An associated program which is useful when dealing with 853preprocessors is @code{soelim}. 854 855A free implementation of @code{grap}, a preprocessor for drawing graphs, 856can be obtained as an extra package; @code{groff} can use @code{grap} 857also. 858 859There are other preprocessors in existence, but, unfortunately, no free 860implementations are available. Among them are preprocessors for drawing 861mathematical pictures (@code{ideal}) and chemical structures 862(@code{chem}). 863 864 865@c ===================================================================== 866 867@node Output device intro, Credits, Preprocessor Intro, Introduction 868@section Output Devices 869@cindex postprocessors 870@cindex output devices 871@cindex devices for output 872 873@code{groff} actually produces device independent code which may be 874fed into a postprocessor to produce output for a particular device. 875Currently, @code{groff} has postprocessors for @sc{PostScript} 876devices, character terminals, X@tie{}Windows (for previewing), @TeX{} 877DVI format, HP LaserJet@tie{}4 and Canon LBP printers (which use 878@acronym{CAPSL}), and @acronym{HTML}. 879 880 881@c ===================================================================== 882 883@node Credits, , Output device intro, Introduction 884@section Credits 885@cindex credits 886 887Large portions of this manual were taken from existing documents, most 888notably, the manual pages for the @code{groff} package by James Clark, 889and Eric Allman's papers on the @file{me} macro package. 890 891The section on the @file{man} macro package is partly based on 892Susan@tie{}G.@: Kleinmann's @file{groff_man} manual page written for the 893Debian GNU/Linux system. 894 895Larry Kollar contributed the section in the @file{ms} macro package. 896 897 898 899@c ===================================================================== 900@c ===================================================================== 901 902@node Invoking groff, Tutorial for Macro Users, Introduction, Top 903@chapter Invoking @code{groff} 904@cindex invoking @code{groff} 905@cindex @code{groff} invocation 906 907This section focuses on how to invoke the @code{groff} front end. This 908front end takes care of the details of constructing the pipeline among 909the preprocessors, @code{gtroff} and the postprocessor. 910 911It has become a tradition that GNU programs get the prefix @samp{g} to 912distinguish it from its original counterparts provided by the host (see 913@ref{Environment}, for more details). Thus, for example, @code{geqn} is 914GNU @code{eqn}. On operating systems like GNU/Linux or the Hurd, which 915don't contain proprietary versions of @code{troff}, and on 916MS-DOS/MS-Windows, where @code{troff} and associated programs are not 917available at all, this prefix is omitted since GNU @code{troff} is the 918only used incarnation of @code{troff}. Exception: @samp{groff} is never 919replaced by @samp{roff}. 920 921In this document, we consequently say @samp{gtroff} when talking about 922the GNU @code{troff} program. All other implementations of @code{troff} 923are called @acronym{AT&T} @code{troff} which is the common origin of 924all @code{troff} derivates (with more or less compatible changes). 925Similarly, we say @samp{gpic}, @samp{geqn}, etc. 926 927@menu 928* Groff Options:: 929* Environment:: 930* Macro Directories:: 931* Font Directories:: 932* Paper Size:: 933* Invocation Examples:: 934@end menu 935 936 937@c ===================================================================== 938 939@node Groff Options, Environment, Invoking groff, Invoking groff 940@section Options 941@cindex options 942 943@pindex groff 944@pindex gtroff 945@pindex gpic 946@pindex geqn 947@pindex ggrn 948@pindex grap 949@pindex gtbl 950@pindex grefer 951@pindex gsoelim 952@code{groff} normally runs the @code{gtroff} program and a postprocessor 953appropriate for the selected device. The default device is @samp{ps} 954(but it can be changed when @code{groff} is configured and built). It 955can optionally preprocess with any of @code{gpic}, @code{geqn}, 956@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}. 957 958This section only documents options to the @code{groff} front end. Many 959of the arguments to @code{groff} are passed on to @code{gtroff}, 960therefore those are also included. Arguments to pre- or postprocessors 961can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking 962gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking 963gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking 964grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking 965grolbp}, and @ref{Invoking gxditview}. 966 967The command line format for @code{groff} is: 968 969@Example 970groff [ -abceghilpstvzCEGNRSUVXZ ] [ -F@var{dir} ] [ -m@var{name} ] 971 [ -T@var{def} ] [ -f@var{fam} ] [ -w@var{name} ] [ -W@var{name} ] 972 [ -M@var{dir} ] [ -d@var{cs} ] [ -r@var{cn} ] [ -n@var{num} ] 973 [ -o@var{list} ] [ -P@var{arg} ] [ -L@var{arg} ] [ -I@var{dir} ] 974 [ @var{files}@dots{} ] 975@endExample 976 977The command line format for @code{gtroff} is as follows. 978 979@Example 980gtroff [ -abcivzCERU ] [ -w@var{name} ] [ -W@var{name} ] [ -d@var{cs} ] 981 [ -f@var{fam} ] [ -m@var{name} ] [ -n@var{num} ] 982 [ -o@var{list} ] [ -r@var{cn} ] [ -T@var{name} ] 983 [ -F@var{dir} ] [ -M@var{dir} ] [ @var{files}@dots{} ] 984@endExample 985 986@noindent 987Obviously, many of the options to @code{groff} are actually passed on to 988@code{gtroff}. 989 990Options without an argument can be grouped behind a single@tie{}@option{-}. 991A filename of@tie{}@file{-} denotes the standard input. It is possible to 992have whitespace between an option and its parameter. 993 994The @code{grog} command can be used to guess the correct @code{groff} 995command to format a file. 996 997Here's the description of the command-line options: 998 999@cindex command-line options 1000@table @samp 1001@item -h 1002Print a help message. 1003 1004@item -e 1005Preprocess with @code{geqn}. 1006 1007@item -t 1008Preprocess with @code{gtbl}. 1009 1010@item -g 1011Preprocess with @code{ggrn}. 1012 1013@item -G 1014Preprocess with @code{grap}. 1015 1016@item -p 1017Preprocess with @code{gpic}. 1018 1019@item -s 1020Preprocess with @code{gsoelim}. 1021 1022@item -c 1023Suppress color output. 1024 1025@item -R 1026Preprocess with @code{grefer}. No mechanism is provided for passing 1027arguments to @code{grefer} because most @code{grefer} options have 1028equivalent commands which can be included in the file. @xref{grefer}, 1029for more details. 1030 1031@pindex troffrc 1032@pindex troffrc-end 1033Note that @code{gtroff} also accepts a @option{-R} option, which is not 1034accessible via @code{groff}. This option prevents the loading of the 1035@file{troffrc} and @file{troffrc-end} files. 1036 1037@item -v 1038Make programs run by @code{groff} print out their version number. 1039 1040@item -V 1041Print the pipeline on @code{stdout} instead of executing it. If specified 1042more than once, print the pipeline on @code{stderr} and execute it. 1043 1044@item -z 1045Suppress output from @code{gtroff}. Only error messages are printed. 1046 1047@item -Z 1048Do not postprocess the output of @code{gtroff}. Normally @code{groff} 1049automatically runs the appropriate postprocessor. 1050 1051@item -P@var{arg} 1052Pass @var{arg} to the postprocessor. Each argument should be passed 1053with a separate @option{-P} option. Note that @code{groff} does not 1054prepend @samp{-} to @var{arg} before passing it to the postprocessor. 1055 1056@item -l 1057Send the output to a spooler for printing. The command used for this is 1058specified by the @code{print} command in the device description file 1059(see @ref{Font Files}, for more info). If not present, @option{-l} is 1060ignored. 1061 1062@item -L@var{arg} 1063Pass @var{arg} to the spooler. Each argument should be passed with a 1064separate @option{-L} option. Note that @code{groff} does not prepend 1065a @samp{-} to @var{arg} before passing it to the postprocessor. 1066If the @code{print} keyword in the device description file is missing, 1067@option{-L} is ignored. 1068 1069@item -T@var{dev} 1070Prepare output for device @var{dev}. The default device is @samp{ps}, 1071unless changed when @code{groff} was configured and built. The 1072following are the output devices currently available: 1073 1074@table @code 1075@item ps 1076For @sc{PostScript} printers and previewers. 1077 1078@item dvi 1079For @TeX{} DVI format. 1080 1081@item X75 1082For a 75@dmn{dpi} X11 previewer. 1083 1084@item X75-12 1085For a 75@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 1086document. 1087 1088@item X100 1089For a 100@dmn{dpi} X11 previewer. 1090 1091@item X100-12 1092For a 100@dmn{dpi} X11 previewer with a 12@dmn{pt} base font in the 1093document. 1094 1095@item ascii 1096@cindex encoding, output, @acronym{ASCII} 1097@cindex @acronym{ASCII}, output encoding 1098@cindex output encoding, @acronym{ASCII} 1099For typewriter-like devices using the (7-bit) @acronym{ASCII} 1100character set. 1101 1102@item latin1 1103@cindex encoding, output, @w{latin-1} (ISO @w{8859-1}) 1104@cindex @w{latin-1} (ISO @w{8859-1}), output encoding 1105@cindex ISO @w{8859-1} (@w{latin-1}), output encoding 1106@cindex output encoding, @w{latin-1} (ISO @w{8859-1}) 1107For typewriter-like devices that support the @w{Latin-1} 1108(ISO@tie{}@w{8859-1}) character set. 1109 1110@item utf8 1111@cindex encoding, output, @w{utf-8} 1112@cindex @w{utf-8}, output encoding 1113@cindex output encoding, @w{utf-8} 1114For typewriter-like devices which use the Unicode (ISO@tie{}10646) 1115character set with @w{UTF-8} encoding. 1116 1117@item cp1047 1118@cindex encoding, output, @acronym{EBCDIC} 1119@cindex @acronym{EBCDIC}, output encoding 1120@cindex output encoding, @acronym{EBCDIC} 1121@cindex encoding, output, cp1047 1122@cindex cp1047, output encoding 1123@cindex output encoding, cp1047 1124@cindex IBM cp1047 output encoding 1125For typewriter-like devices which use the @acronym{EBCDIC} encoding IBM 1126cp1047. 1127 1128@item lj4 1129For HP LaserJet4-compatible (or other PCL5-compatible) printers. 1130 1131@item lbp 1132For Canon @acronym{CAPSL} printers (@w{LBP-4} and @w{LBP-8} series laser 1133printers). 1134 1135@pindex pre-grohtml 1136@pindex post-grohtml 1137@cindex @code{grohtml}, the program 1138@item html 1139To produce @acronym{HTML} output. Note that the @acronym{HTML} driver 1140consists of two parts, a preprocessor (@code{pre-grohtml}) and a 1141postprocessor (@code{post-grohtml}). 1142@end table 1143 1144@cindex output device name string register (@code{.T}) 1145@cindex output device usage number register (@code{.T}) 1146The predefined @code{gtroff} string register @code{.T} contains the 1147current output device; the read-only number register @code{.T} is set 1148to@tie{}1 if this option is used (which is always true if @code{groff} is 1149used to call @code{gtroff}). @xref{Built-in Registers}. 1150 1151The postprocessor to be used for a device is specified by the 1152@code{postpro} command in the device description file. (@xref{Font 1153Files}, for more info.) This can be overridden with the @option{-X} 1154option. 1155 1156@item -X 1157Preview with @code{gxditview} instead of using the usual postprocessor. 1158This is unlikely to produce good results except with @option{-Tps}. 1159 1160Note that this is not the same as using @option{-TX75} or 1161@option{-TX100} to view a document with @code{gxditview}: The former 1162uses the metrics of the specified device, whereas the latter uses 1163X-specific fonts and metrics. 1164 1165@item -N 1166Don't allow newlines with @code{eqn} delimiters. This is the same as 1167the @option{-N} option in @code{geqn}. 1168 1169@item -S 1170@cindex @code{open} request, and safer mode 1171@cindex @code{opena} request, and safer mode 1172@cindex @code{pso} request, and safer mode 1173@cindex @code{sy} request, and safer mode 1174@cindex @code{pi} request, and safer mode 1175@cindex safer mode 1176@cindex mode, safer 1177Safer mode. Pass the @option{-S} option to @code{gpic} and disable the 1178@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi} 1179requests. For security reasons, this is enabled by default. 1180 1181@item -U 1182@cindex mode, unsafe 1183@cindex unsafe mode 1184Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso}, 1185@code{sy}, and @code{pi} requests. 1186 1187@item -a 1188@cindex @acronym{ASCII} approximation output register (@code{.A}) 1189Generate an @acronym{ASCII} approximation of the typeset output. The 1190read-only register @code{.A} is then set to@tie{}1. @xref{Built-in 1191Registers}. A typical example is 1192 1193@Example 1194groff -a -man -Tdvi troff.man | less 1195@endExample 1196 1197@noindent 1198which shows how lines are broken for the DVI device. Note that this 1199option is rather useless today since graphic output devices are 1200available virtually everywhere. 1201 1202@item -b 1203Print a backtrace with each warning or error message. This backtrace 1204should help track down the cause of the error. The line numbers given 1205in the backtrace may not always be correct: @code{gtroff} can get 1206confused by @code{as} or @code{am} requests while counting line numbers. 1207 1208@item -i 1209Read the standard input after all the named input files have been 1210processed. 1211 1212@item -w@var{name} 1213Enable warning @var{name}. Available warnings are described in 1214@ref{Debugging}. Multiple @option{-w} options are allowed. 1215 1216@item -W@var{name} 1217Inhibit warning @var{name}. Multiple @option{-W} options are allowed. 1218 1219@item -E 1220Inhibit all error messages. 1221 1222@item -C 1223Enable compatibility mode. @xref{Implementation Differences}, for the 1224list of incompatibilities between @code{groff} and @acronym{AT&T} 1225@code{troff}. 1226 1227@item -d@var{c}@var{s} 1228@itemx -d@var{name}=@var{s} 1229Define @var{c} or @var{name} to be a string@tie{}@var{s}. @var{c}@tie{}must 1230be a one-letter name; @var{name} can be of arbitrary length. All string 1231assignments happen before loading any macro file (including the start-up 1232file). 1233 1234@item -f@var{fam} 1235Use @var{fam} as the default font family. @xref{Font Families}. 1236 1237@item -m@var{name} 1238Read in the file @file{@var{name}.tmac}. Normally @code{groff} searches 1239for this in its macro directories. If it isn't found, it tries 1240@file{tmac.@var{name}} (searching in the same directories). 1241 1242@item -n@var{num} 1243Number the first page @var{num}. 1244 1245@item -o@var{list} 1246@cindex print current page register (@code{.P}) 1247Output only pages in @var{list}, which is a comma-separated list of page 1248ranges; @samp{@var{n}} means print page@tie{}@var{n}, @samp{@var{m}-@var{n}} 1249means print every page between @var{m} and@tie{}@var{n}, @samp{-@var{n}} 1250means print every page up to@tie{}@var{n}, @samp{@var{n}-} means print every 1251page beginning with@tie{}@var{n}. @code{gtroff} exits after printing the 1252last page in the list. All the ranges are inclusive on both ends. 1253 1254Within @code{gtroff}, this information can be extracted with the 1255@samp{.P} register. @xref{Built-in Registers}. 1256 1257If your document restarts page numbering at the beginning of each 1258chapter, then @code{gtroff} prints the specified page range for each 1259chapter. 1260 1261@item -r@var{c}@var{n} 1262@itemx -r@var{name}=@var{n} 1263Set number register@tie{}@var{c} or @var{name} to the value@tie{}@var{n}. 1264@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary 1265length. @var{n}@tie{}can be any @code{gtroff} numeric expression. All 1266register assignments happen before loading any macro file (including 1267the start-up file). 1268 1269@item -F@var{dir} 1270Search @file{@var{dir}} for subdirectories @file{dev@var{name}} 1271(@var{name} is the name of the device), for the @file{DESC} file, and 1272for font files before looking in the standard directories (@pxref{Font 1273Directories}). This option is passed to all pre- and postprocessors 1274using the @env{GROFF_FONT_PATH} environment variable. 1275 1276@item -M@var{dir} 1277Search directory @file{@var{dir}} for macro files before the standard 1278directories (@pxref{Macro Directories}). 1279 1280@item -I@var{dir} 1281This option may be used to specify a directory to search for files. 1282It is passed to the following programs: 1283 1284@itemize 1285@item 1286@code{gsoelim} (see @ref{gsoelim} for more details); 1287it also implies @code{groff}'s @option{-s} option. 1288 1289@item 1290@code{gtroff}; it is used to search files named in the @code{psbb} and 1291@code{so} requests. 1292 1293@item 1294@code{grops}; it is used to search files named in the 1295@w{@code{\X'ps: import}} and @w{@code{\X'ps: file}} escapes. 1296@end itemize 1297 1298The current directory is always searched first. This option may be specified 1299more than once; the directories will be searched in the order specified. No 1300directory search is performed for files specified using an absolute path. 1301@end table 1302 1303 1304@c ===================================================================== 1305 1306@node Environment, Macro Directories, Groff Options, Invoking groff 1307@section Environment 1308@cindex environment variables 1309@cindex variables in environment 1310 1311There are also several environment variables (of the operating system, 1312not within @code{gtroff}) which can modify the behavior of @code{groff}. 1313 1314@table @code 1315@item GROFF_COMMAND_PREFIX 1316@tindex GROFF_COMMAND_PREFIX@r{, environment variable} 1317@cindex command prefix 1318@cindex prefix, for commands 1319If this is set to@tie{}@var{X}, then @code{groff} runs @code{@var{X}troff} 1320instead of @code{gtroff}. This also applies to @code{tbl}, @code{pic}, 1321@code{eqn}, @code{grn}, @code{refer}, and @code{soelim}. It does not 1322apply to @code{grops}, @code{grodvi}, @code{grotty}, @code{pre-grohtml}, 1323@code{post-grohtml}, @code{grolj4}, and @code{gxditview}. 1324 1325The default command prefix is determined during the installation process. 1326If a non-GNU troff system is found, prefix @samp{g} is used, none 1327otherwise. 1328 1329@item GROFF_TMAC_PATH 1330@tindex GROFF_TMAC_PATH@r{, environment variable} 1331A colon-separated list of directories in which to search for macro files 1332(before the default directories are tried). @xref{Macro Directories}. 1333 1334@item GROFF_TYPESETTER 1335@tindex GROFF_TYPESETTER@r{, environment variable} 1336The default output device. 1337 1338@item GROFF_FONT_PATH 1339@tindex GROFF_FONT_PATH@r{, environment variable} 1340A colon-separated list of directories in which to search for the 1341@code{dev}@var{name} directory (before the default directories are 1342tried). @xref{Font Directories}. 1343 1344@item GROFF_BIN_PATH 1345@tindex GROFF_BIN_PATH@r{, environment variable} 1346This search path, followed by @code{PATH}, is used for commands executed 1347by @code{groff}. 1348 1349@item GROFF_TMPDIR 1350@tindex GROFF_TMPDIR@r{, environment variable} 1351@tindex TMPDIR@r{, environment variable} 1352The directory in which @code{groff} creates temporary files. If this is 1353not set and @env{TMPDIR} is set, temporary files are created in that 1354directory. Otherwise temporary files are created in a system-dependent 1355default directory (on Unix and GNU/Linux systems, this is usually 1356@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and 1357@code{post-grohtml} can create temporary files in this directory. 1358@end table 1359 1360Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons, 1361rather than colons, to separate the directories in the lists described 1362above. 1363 1364 1365@c ===================================================================== 1366 1367@node Macro Directories, Font Directories, Environment, Invoking groff 1368@section Macro Directories 1369@cindex macro directories 1370@cindex directories for macros 1371@cindex searching macros 1372@cindex macros, searching 1373 1374All macro file names must be named @code{@var{name}.tmac} or 1375@code{tmac.@var{name}} to make the @option{-m@var{name}} command line 1376option work. The @code{mso} request doesn't have this restriction; any 1377file name can be used, and @code{gtroff} won't try to append or prepend 1378the @samp{tmac} string. 1379 1380@cindex tmac, directory 1381@cindex directory, for tmac files 1382@cindex tmac, path 1383@cindex path, for tmac files 1384@cindex searching macro files 1385@cindex macro files, searching 1386@cindex files, macro, searching 1387Macro files are kept in the @dfn{tmac directories}, all of which 1388constitute the @dfn{tmac path}. The elements of the search path for 1389macro files are (in that order): 1390 1391@itemize @bullet 1392@item 1393The directories specified with @code{gtroff}'s or @code{groff}'s 1394@option{-M} command line option. 1395 1396@item 1397@tindex GROFF_TMAC_PATH@r{, environment variable} 1398The directories given in the @env{GROFF_TMAC_PATH} environment 1399variable. 1400 1401@item 1402@cindex safer mode 1403@cindex mode, safer 1404@cindex unsafe mode 1405@cindex mode, unsafe 1406@cindex current directory 1407@cindex directory, current 1408The current directory (only if in unsafe mode using the @option{-U} 1409command line switch). 1410 1411@item 1412@cindex home directory 1413@cindex directory, home 1414The home directory. 1415 1416@item 1417@cindex site-specific directory 1418@cindex directory, site-specific 1419@cindex platform-specific directory 1420@cindex directory, platform-specific 1421A platform-dependent directory, a site-specific (platform-independent) 1422directory, and the main tmac directory; the default locations are 1423 1424@Example 1425/usr/local/lib/groff/site-tmac 1426/usr/local/share/groff/site-tmac 1427/usr/local/share/groff/1.18.2/tmac 1428@endExample 1429 1430@noindent 1431assuming that the version of @code{groff} is 1.18.2, and the installation 1432prefix was @file{/usr/local}. It is possible to fine-tune those 1433directories during the installation process. 1434@end itemize 1435 1436 1437@c ===================================================================== 1438 1439@node Font Directories, Paper Size, Macro Directories, Invoking groff 1440@section Font Directories 1441@cindex font directories 1442@cindex directories for fonts 1443@cindex searching fonts 1444@cindex fonts, searching 1445 1446Basically, there is no restriction how font files for @code{groff} are 1447named and how long font names are; however, to make the font family 1448mechanism work (@pxref{Font Families}), fonts within a family should 1449start with the family name, followed by the shape. For example, the 1450Times family uses @samp{T} for the family name and @samp{R}, @samp{B}, 1451@samp{I}, and @samp{BI} to indicate the shapes `roman', `bold', 1452`italic', and `bold italic', respectively. Thus the final font names 1453are @samp{TR}, @samp{TB}, @samp{TI}, and @samp{TBI}. 1454 1455@cindex font path 1456@cindex path, for font files 1457All font files are kept in the @dfn{font directories} which constitute 1458the @dfn{font path}. The file search functions will always append the 1459directory @code{dev}@var{name}, where @var{name} is the name of the 1460output device. Assuming, say, DVI output, and @file{/foo/bar} as a 1461font directory, the font files for @code{grodvi} must be in 1462@file{/foo/bar/devdvi}. 1463 1464The elements of the search path for font files are (in that order): 1465 1466@itemize @bullet 1467@item 1468The directories specified with @code{gtroff}'s or @code{groff}'s 1469@option{-F} command line option. All device drivers and some 1470preprocessors also have this option. 1471 1472@item 1473@tindex GROFF_FONT_PATH@r{, environment variable} 1474The directories given in the @env{GROFF_FONT_PATH} environment 1475variable. 1476 1477@item 1478@cindex site-specific directory 1479@cindex directory, site-specific 1480A site-specific directory and the main font directory; the default 1481locations are 1482 1483@Example 1484/usr/local/share/groff/site-font 1485/usr/local/share/groff/1.18.2/font 1486@endExample 1487 1488@noindent 1489assuming that the version of @code{groff} is 1.18.2, and the installation 1490prefix was @file{/usr/local}. It is possible to fine-tune those 1491directories during the installation process. 1492@end itemize 1493 1494 1495@c ===================================================================== 1496 1497@node Paper Size, Invocation Examples, Font Directories, Invoking groff 1498@section Paper Size 1499@cindex paper size 1500@cindex size, paper 1501@cindex landscape page orientation 1502@cindex orientation, landscape 1503@cindex page orientation, landscape 1504 1505In groff, the page size for @code{gtroff} and for output devices are 1506handled separately. @xref{Page Layout}, for vertical manipulation of 1507the page size. @xref{Line Layout}, for horizontal changes. 1508 1509A default paper size can be set in the device's @file{DESC} file. Most 1510output devices also have a command line option @option{-p} to override 1511the default paper size and option @option{-l} to use landscape 1512orientation. @xref{DESC File Format}, for a description of the 1513@code{papersize} keyword which takes the same argument as @option{-p}. 1514 1515@pindex papersize.tmac 1516@pindex troffrc 1517A convenient shorthand to set a particular paper size for @code{gtroff} 1518is command line option @option{-dpaper=@var{size}}. This defines string 1519@code{paper} which is processed in file @file{papersize.tmac} (loaded in 1520the start-up file @file{troffrc} by default). Possible values for 1521@var{size} are the same as the predefined values for the 1522@code{papersize} keyword (but only in lowercase) except 1523@code{a7}-@code{d7}. An appended @samp{l} (ell) character denotes 1524landscape orientation. 1525 1526For example, use the following for PS output on A4 paper in landscape 1527orientation: 1528 1529@Example 1530groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps 1531@endExample 1532 1533Note that it is up to the particular macro package to respect default 1534page dimensions set in this way (most do). 1535 1536 1537@c ===================================================================== 1538 1539@node Invocation Examples, , Paper Size, Invoking groff 1540@section Invocation Examples 1541@cindex invocation examples 1542@cindex examples of invocation 1543 1544This section lists several common uses of @code{groff} and the 1545corresponding command lines. 1546 1547@Example 1548groff file 1549@endExample 1550 1551@noindent 1552This command processes @file{file} without a macro package or a 1553preprocessor. The output device is the default, @samp{ps}, and the 1554output is sent to @code{stdout}. 1555 1556@Example 1557groff -t -mandoc -Tascii file | less 1558@endExample 1559 1560@noindent 1561This is basically what a call to the @code{man} program does. 1562@code{gtroff} processes the manual page @file{file} with the 1563@file{mandoc} macro file (which in turn either calls the @file{man} or 1564the @file{mdoc} macro package), using the @code{tbl} preprocessor and 1565the @acronym{ASCII} output device. Finally, the @code{less} pager 1566displays the result. 1567 1568@Example 1569groff -X -m me file 1570@endExample 1571 1572@noindent 1573Preview @file{file} with @code{gxditview}, using the @file{me} macro 1574package. Since no @option{-T} option is specified, use the default 1575device (@samp{ps}). Note that you can either say @w{@samp{-m me}} or 1576@w{@samp{-me}}; the latter is an anachronism from the early days of 1577@acronym{UNIX}.@footnote{The same is true for the other main macro 1578packages that come with @code{groff}: @file{man}, @file{mdoc}, 1579@file{ms}, @file{mm}, and @file{mandoc}. This won't work in general; 1580for example, to load @file{trace.tmac}, either @samp{-mtrace} or 1581@w{@samp{-m trace}} must be used.} 1582 1583@Example 1584groff -man -rD1 -z file 1585@endExample 1586 1587@noindent 1588Check @file{file} with the @file{man} macro package, forcing 1589double-sided printing -- don't produce any output. 1590 1591@menu 1592* grog:: 1593@end menu 1594 1595@c --------------------------------------------------------------------- 1596 1597@node grog, , Invocation Examples, Invocation Examples 1598@subsection @code{grog} 1599 1600@pindex grog 1601@code{grog} reads files, guesses which of the @code{groff} preprocessors 1602and/or macro packages are required for formatting them, and prints the 1603@code{groff} command including those options on the standard output. It 1604generates one or more of the options @option{-e}, @option{-man}, 1605@option{-me}, @option{-mm}, @option{-mom}, @option{-ms}, @option{-mdoc}, 1606@option{-mdoc-old}, @option{-p}, @option{-R}, @option{-g}, @option{-G}, 1607@option{-s}, and @option{-t}. 1608 1609A special file name@tie{}@file{-} refers to the standard input. Specifying 1610no files also means to read the standard input. Any specified options 1611are included in the printed command. No space is allowed between 1612options and their arguments. The only options recognized are 1613@option{-C} (which is also passed on) to enable compatibility mode, and 1614@option{-v} to print the version number and exit. 1615 1616For example, 1617 1618@Example 1619grog -Tdvi paper.ms 1620@endExample 1621 1622@noindent 1623guesses the appropriate command to print @file{paper.ms} and then prints 1624it to the command line after adding the @option{-Tdvi} option. For 1625direct execution, enclose the call to @code{grog} in backquotes at the 1626@acronym{UNIX} shell prompt: 1627 1628@Example 1629`grog -Tdvi paper.ms` > paper.dvi 1630@endExample 1631 1632@noindent 1633As seen in the example, it is still necessary to redirect the output to 1634something meaningful (i.e.@: either a file or a pager program like 1635@code{less}). 1636 1637 1638 1639@c ===================================================================== 1640@c ===================================================================== 1641 1642@node Tutorial for Macro Users, Macro Packages, Invoking groff, Top 1643@chapter Tutorial for Macro Users 1644@cindex tutorial for macro users 1645@cindex macros, tutorial for users 1646@cindex user's tutorial for macros 1647@cindex user's macro tutorial 1648 1649Most users tend to use a macro package to format their papers. This 1650means that the whole breadth of @code{groff} is not necessary for most 1651people. This chapter covers the material needed to efficiently use a 1652macro package. 1653 1654@menu 1655* Basics:: 1656* Common Features:: 1657@end menu 1658 1659 1660@c ===================================================================== 1661 1662@node Basics, Common Features, Tutorial for Macro Users, Tutorial for Macro Users 1663@section Basics 1664@cindex basics of macros 1665@cindex macro basics 1666 1667This section covers some of the basic concepts necessary to understand 1668how to use a macro package.@footnote{This section is derived from 1669@cite{Writing Papers with nroff using -me} by Eric P.@tie{}Allman.} 1670References are made throughout to more detailed information, if desired. 1671 1672@code{gtroff} reads an input file prepared by the user and outputs a 1673formatted document suitable for publication or framing. The input 1674consists of text, or words to be printed, and embedded commands 1675(@dfn{requests} and @dfn{escapes}), which tell @code{gtroff} how to 1676format the output…
Large files files are truncated, but you can click here to view the full file