PageRenderTime 140ms CodeModel.GetById 42ms app.highlight 61ms RepoModel.GetById 1ms app.codeStats 1ms

/contrib/groff/doc/groff.texinfo

https://bitbucket.org/freebsd/freebsd-head/
Unknown | 15454 lines | 12574 code | 2880 blank | 0 comment | 0 complexity | 8b088c4112aed0fed1c425e0f04bd15a MD5 | raw file

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