groff-1 revision 114402
1This is groff, produced by makeinfo version 4.3d from ./groff.texinfo. 2 3This manual documents GNU `troff' version 1.19. 4 5 Copyright (C) 1994-2000, 2001, 2002, 2003 Free Software Foundation, 6Inc. 7 8 Permission is granted to copy, distribute and/or modify this 9 document under the terms of the GNU Free Documentation License, 10 Version 1.1 or any later version published by the Free Software 11 Foundation; with no Invariant Sections, with the Front-Cover texts 12 being `A GNU Manual," and with the Back-Cover Texts as in (a) 13 below. A copy of the license is included in the section entitled 14 `GNU Free Documentation License." 15 16 (a) The FSF's Back-Cover Text is: `You have freedom to copy and 17 modify this GNU Manual, like GNU software. Copies published by 18 the Free Software Foundation raise funds for GNU development." 19 20INFO-DIR-SECTION Typesetting 21START-INFO-DIR-ENTRY 22* Groff: (groff). The GNU troff document formatting system. 23END-INFO-DIR-ENTRY 24 25 26File: groff, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) 27 28GNU troff 29********* 30 31This manual documents GNU `troff' version 1.19. 32 33 Copyright (C) 1994-2000, 2001, 2002, 2003 Free Software Foundation, 34Inc. 35 36 Permission is granted to copy, distribute and/or modify this 37 document under the terms of the GNU Free Documentation License, 38 Version 1.1 or any later version published by the Free Software 39 Foundation; with no Invariant Sections, with the Front-Cover texts 40 being `A GNU Manual," and with the Back-Cover Texts as in (a) 41 below. A copy of the license is included in the section entitled 42 `GNU Free Documentation License." 43 44 (a) The FSF's Back-Cover Text is: `You have freedom to copy and 45 modify this GNU Manual, like GNU software. Copies published by 46 the Free Software Foundation raise funds for GNU development." 47 48* Menu: 49 50* Introduction:: 51* Invoking groff:: 52* Tutorial for Macro Users:: 53* Macro Packages:: 54* gtroff Reference:: 55* Preprocessors:: 56* Output Devices:: 57* File formats:: 58* Installation:: 59* Copying This Manual:: 60* Request Index:: 61* Escape Index:: 62* Operator Index:: 63* Register Index:: 64* Macro Index:: 65* String Index:: 66* Glyph Name Index:: 67* Font File Keyword Index:: 68* Program and File Index:: 69* Concept Index:: 70 71 72File: groff, Node: Introduction, Next: Invoking groff, Prev: Top, Up: Top 73 74Introduction 75************ 76 77 GNU `troff' (or `groff') is a system for typesetting documents. 78`troff' is very flexible and has been in existence (and use) for about 793 decades. It is quite widespread and firmly entrenched in the UNIX 80community. 81 82* Menu: 83 84* What Is groff?:: 85* History:: 86* groff Capabilities:: 87* Macro Package Intro:: 88* Preprocessor Intro:: 89* Output device intro:: 90* Credits:: 91 92 93File: groff, Node: What Is groff?, Next: History, Prev: Introduction, Up: Introduction 94 95What Is `groff'? 96================ 97 98 `groff' belongs to an older generation of document preparation 99systems, which operate more like compilers than the more recent 100interactive WYSIWYG(1) (*note What Is groff?-Footnote-1::) systems. 101`groff' and its contemporary counterpart, TeX, both work using a 102"batch" paradigm: The input (or "source") files are normal text files 103with embedded formatting commands. These files can then be processed 104by `groff' to produce a typeset document on a variety of devices. 105 106 Likewise, `groff' should not be confused with a "word processor", 107since that term connotes an integrated system that includes an editor 108and a text formatter. Also, many word processors follow the WYSIWYG 109paradigm discussed earlier. 110 111 Although WYSIWYG systems may be easier to use, they have a number of 112disadvantages compared to `troff': 113 114 * They must be used on a graphics display to work on a document. 115 116 * Most of the WYSIWYG systems are either non-free or are not very 117 portable. 118 119 * `troff' is firmly entrenched in all UNIX systems. 120 121 * It is difficult to have a wide range of capabilities available 122 within the confines of a GUI/window system. 123 124 * It is more difficult to make global changes to a document. 125 126 "GUIs normally make it simple to accomplish simple actions and 127 impossible to accomplish complex actions." -Doug Gwyn (22/Jun/91 128 in `comp.unix.wizards') 129 130 131File: groff, Node: What Is groff?-Footnotes, Up: What Is groff? 132 133 (1) What You See Is What You Get 134 135 136File: groff, Node: History, Next: groff Capabilities, Prev: What Is groff?, Up: Introduction 137 138History 139======= 140 141 `troff' can trace its origins back to a formatting program called 142`runoff', written by J. E. Saltzer, which ran on MIT's CTSS operating 143system in the mid-sixties. This name came from the common phrase of 144the time "I'll run off a document." Bob Morris ported it to the 635 145architecture and called the program `roff' (an abbreviation of 146`runoff'). It was rewritten as `rf' for the PDP-7 (before having 147UNIX), and at the same time (1969), Doug McIllroy rewrote an extended 148and simplified version of `roff' in the BCPL programming language. 149 150 The first version of UNIX was developed on a PDP-7 which was sitting 151around Bell Labs. In 1971 the developers wanted to get a PDP-11 for 152further work on the operating system. In order to justify the cost for 153this system, they proposed that they would implement a document 154formatting system for the AT&T patents division. This first formatting 155program was a reimplementation of McIllroy's `roff', written by 156J. F. Ossanna. 157 158 When they needed a more flexible language, a new version of `roff' 159called `nroff' ("Newer `roff'") was written. It had a much more 160complicated syntax, but provided the basis for all future versions. 161When they got a Graphic Systems CAT Phototypesetter, Ossanna wrote a 162version of `nroff' that would drive it. It was dubbed `troff', for 163"typesetter `roff'", although many people have speculated that it 164actually means "Times `roff'" because of the use of the Times font 165family in `troff' by default. As such, the name `troff' is pronounced 166`t-roff' rather than `trough'. 167 168 With `troff' came `nroff' (they were actually the same program 169except for some `#ifdef's), which was for producing output for line 170printers and character terminals. It understood everything `troff' 171did, and ignored the commands which were not applicable (e.g. font 172changes). 173 174 Since there are several things which cannot be done easily in 175`troff', work on several preprocessors began. These programs would 176transform certain parts of a document into `troff', which made a very 177natural use of pipes in UNIX. 178 179 The `eqn' preprocessor allowed mathematical formulae to be specified 180in a much simpler and more intuitive manner. `tbl' is a preprocessor 181for formatting tables. The `refer' preprocessor (and the similar 182program, `bib') processes citations in a document according to a 183bibliographic database. 184 185 Unfortunately, Ossanna's `troff' was written in PDP-11 assembly 186language and produced output specifically for the CAT phototypesetter. 187He rewrote it in C, although it was now 7000 lines of uncommented code 188and still dependent on the CAT. As the CAT became less common, and was 189no longer supported by the manufacturer, the need to make it support 190other devices became a priority. However, before this could be done, 191Ossanna was killed in a car accident. 192 193 So, Brian Kernighan took on the task of rewriting `troff'. The 194newly rewritten version produced device independent code which was very 195easy for postprocessors to read and translate to the appropriate 196printer codes. Also, this new version of `troff' (called `ditroff' for 197"device independent `troff'") had several extensions, which included 198drawing functions. 199 200 Due to the additional abilities of the new version of `troff', 201several new preprocessors appeared. The `pic' preprocessor provides a 202wide range of drawing functions. Likewise the `ideal' preprocessor did 203the same, although via a much different paradigm. The `grap' 204preprocessor took specifications for graphs, but, unlike other 205preprocessors, produced `pic' code. 206 207 James Clark began work on a GNU implementation of `ditroff' in 208early 1989. The first version, `groff' 0.3.1, was released June 1990. 209`groff' included: 210 211 * A replacement for `ditroff' with many extensions. 212 213 * The `soelim', `pic', `tbl', and `eqn' preprocessors. 214 215 * Postprocessors for character devices, POSTSCRIPT, TeX DVI, and 216 X Windows. GNU `troff' also eliminated the need for a separate 217 `nroff' program with a postprocessor which would produce ASCII 218 output. 219 220 * A version of the `me' macros and an implementation of the `man' 221 macros. 222 223 Also, a front-end was included which could construct the, sometimes 224painfully long, pipelines required for all the post- and preprocessors. 225 226 Development of GNU `troff' progressed rapidly, and saw the additions 227of a replacement for `refer', an implementation of the `ms' and `mm' 228macros, and a program to deduce how to format a document (`grog'). 229 230 It was declared a stable (i.e. non-beta) package with the release of 231version 1.04 around November 1991. 232 233 Beginning in 1999, `groff' has new maintainers (the package was an 234orphan for a few years). As a result, new features and programs like 235`grn', a preprocessor for gremlin images, and an output device to 236produce HTML output have been added. 237 238 239File: groff, Node: groff Capabilities, Next: Macro Package Intro, Prev: History, Up: Introduction 240 241`groff' Capabilities 242==================== 243 244 So what exactly is `groff' capable of doing? `groff' provides a 245wide range of low-level text formatting operations. Using these, it is 246possible to perform a wide range of formatting tasks, such as 247footnotes, table of contents, multiple columns, etc. Here's a list of 248the most important operations supported by `groff': 249 250 * text filling, adjusting, and centering 251 252 * hyphenation 253 254 * page control 255 256 * font and glyph size control 257 258 * vertical spacing (e.g. double-spacing) 259 260 * line length and indenting 261 262 * macros, strings, diversions, and traps 263 264 * number registers 265 266 * tabs, leaders, and fields 267 268 * input and output conventions and character translation 269 270 * overstrike, bracket, line drawing, and zero-width functions 271 272 * local horizontal and vertical motions and the width function 273 274 * three-part titles 275 276 * output line numbering 277 278 * conditional acceptance of input 279 280 * environment switching 281 282 * insertions from the standard input 283 284 * input/output file switching 285 286 * output and error messages 287 288 289File: groff, Node: Macro Package Intro, Next: Preprocessor Intro, Prev: groff Capabilities, Up: Introduction 290 291Macro Packages 292============== 293 294 Since `groff' provides such low-level facilities, it can be quite 295difficult to use by itself. However, `groff' provides a "macro" 296facility to specify how certain routine operations (e.g. starting 297paragraphs, printing headers and footers, etc.) should be done. These 298macros can be collected together into a "macro package". There are a 299number of macro packages available; the most common (and the ones 300described in this manual) are `man', `mdoc', `me', `ms', and `mm'. 301 302 303File: groff, Node: Preprocessor Intro, Next: Output device intro, Prev: Macro Package Intro, Up: Introduction 304 305Preprocessors 306============= 307 308 Although `groff' provides most functions needed to format a 309document, some operations would be unwieldy (e.g. to draw pictures). 310Therefore, programs called "preprocessors" were written which 311understand their own language and produce the necessary `groff' 312operations. These preprocessors are able to differentiate their own 313input from the rest of the document via markers. 314 315 To use a preprocessor, UNIX pipes are used to feed the output from 316the preprocessor into `groff'. Any number of preprocessors may be used 317on a given document; in this case, the preprocessors are linked 318together into one pipeline. However, with `groff', the user does not 319need to construct the pipe, but only tell `groff' what preprocessors to 320use. 321 322 `groff' currently has preprocessors for producing tables (`tbl'), 323typesetting equations (`eqn'), drawing pictures (`pic' and `grn'), and 324for processing bibliographies (`refer'). An associated program which 325is useful when dealing with preprocessors is `soelim'. 326 327 A free implementation of `grap', a preprocessor for drawing graphs, 328can be obtained as an extra package; `groff' can use `grap' also. 329 330 There are other preprocessors in existence, but, unfortunately, no 331free implementations are available. Among them are preprocessors for 332drawing mathematical pictures (`ideal') and chemical structures 333(`chem'). 334 335 336File: groff, Node: Output device intro, Next: Credits, Prev: Preprocessor Intro, Up: Introduction 337 338Output Devices 339============== 340 341 `groff' actually produces device independent code which may be fed 342into a postprocessor to produce output for a particular device. 343Currently, `groff' has postprocessors for POSTSCRIPT devices, character 344terminals, X Windows (for previewing), TeX DVI format, HP LaserJet 4 345and Canon LBP printers (which use CAPSL), and HTML. 346 347 348File: groff, Node: Credits, Prev: Output device intro, Up: Introduction 349 350Credits 351======= 352 353 Large portions of this manual were taken from existing documents, 354most notably, the manual pages for the `groff' package by James Clark, 355and Eric Allman's papers on the `me' macro package. 356 357 The section on the `man' macro package is partly based on Susan G. 358Kleinmann's `groff_man' manual page written for the Debian GNU/Linux 359system. 360 361 Larry Kollar contributed the section in the `ms' macro package. 362 363 364File: groff, Node: Invoking groff, Next: Tutorial for Macro Users, Prev: Introduction, Up: Top 365 366Invoking `groff' 367**************** 368 369 This section focuses on how to invoke the `groff' front end. This 370front end takes care of the details of constructing the pipeline among 371the preprocessors, `gtroff' and the postprocessor. 372 373 It has become a tradition that GNU programs get the prefix `g' to 374distinguish it from its original counterparts provided by the host (see 375*Note Environment::, for more details). Thus, for example, `geqn' is 376GNU `eqn'. On operating systems like GNU/Linux or the Hurd, which 377don't contain proprietary versions of `troff', and on 378MS-DOS/MS-Windows, where `troff' and associated programs are not 379available at all, this prefix is omitted since GNU `troff' is the only 380used incarnation of `troff'. Exception: `groff' is never replaced by 381`roff'. 382 383 In this document, we consequently say `gtroff' when talking about 384the GNU `troff' program. All other implementations of `troff' are 385called AT&T `troff' which is the common origin of all `troff' derivates 386(with more or less compatible changes). Similarly, we say `gpic', 387`geqn', etc. 388 389* Menu: 390 391* Groff Options:: 392* Environment:: 393* Macro Directories:: 394* Font Directories:: 395* Paper Size:: 396* Invocation Examples:: 397 398 399File: groff, Node: Groff Options, Next: Environment, Prev: Invoking groff, Up: Invoking groff 400 401Options 402======= 403 404 `groff' normally runs the `gtroff' program and a postprocessor 405appropriate for the selected device. The default device is `ps' (but 406it can be changed when `groff' is configured and built). It can 407optionally preprocess with any of `gpic', `geqn', `gtbl', `ggrn', 408`grap', `grefer', or `gsoelim'. 409 410 This section only documents options to the `groff' front end. Many 411of the arguments to `groff' are passed on to `gtroff', therefore those 412are also included. Arguments to pre- or postprocessors can be found in 413*Note Invoking gpic::, *Note Invoking geqn::, *Note Invoking gtbl::, 414*Note Invoking ggrn::, *Note Invoking grefer::, *Note Invoking 415gsoelim::, *Note Invoking grotty::, *Note Invoking grops::, *Note 416Invoking grohtml::, *Note Invoking grodvi::, *Note Invoking grolj4::, 417*Note Invoking grolbp::, and *Note Invoking gxditview::. 418 419 The command line format for `groff' is: 420 421 422 groff [ -abceghilpstvzCEGNRSUVXZ ] [ -FDIR ] [ -mNAME ] 423 [ -TDEF ] [ -fFAM ] [ -wNAME ] [ -WNAME ] 424 [ -MDIR ] [ -dCS ] [ -rCN ] [ -nNUM ] 425 [ -oLIST ] [ -PARG ] [ -LARG ] [ -IDIR ] 426 [ FILES... ] 427 428 The command line format for `gtroff' is as follows. 429 430 431 gtroff [ -abcivzCERU ] [ -wNAME ] [ -WNAME ] [ -dCS ] 432 [ -fFAM ] [ -mNAME ] [ -nNUM ] 433 [ -oLIST ] [ -rCN ] [ -TNAME ] 434 [ -FDIR ] [ -MDIR ] [ FILES... ] 435 436Obviously, many of the options to `groff' are actually passed on to 437`gtroff'. 438 439 Options without an argument can be grouped behind a single `-'. A 440filename of `-' denotes the standard input. It is possible to have 441whitespace between an option and its parameter. 442 443 The `grog' command can be used to guess the correct `groff' command 444to format a file. 445 446 Here's the description of the command-line options: 447 448`-h' 449 Print a help message. 450 451`-e' 452 Preprocess with `geqn'. 453 454`-t' 455 Preprocess with `gtbl'. 456 457`-g' 458 Preprocess with `ggrn'. 459 460`-G' 461 Preprocess with `grap'. 462 463`-p' 464 Preprocess with `gpic'. 465 466`-s' 467 Preprocess with `gsoelim'. 468 469`-c' 470 Suppress color output. 471 472`-R' 473 Preprocess with `grefer'. No mechanism is provided for passing 474 arguments to `grefer' because most `grefer' options have 475 equivalent commands which can be included in the file. *Note 476 grefer::, for more details. 477 478 Note that `gtroff' also accepts a `-R' option, which is not 479 accessible via `groff'. This option prevents the loading of the 480 `troffrc' and `troffrc-end' files. 481 482`-v' 483 Make programs run by `groff' print out their version number. 484 485`-V' 486 Print the pipeline on `stdout' instead of executing it. 487 488`-z' 489 Suppress output from `gtroff'. Only error messages are printed. 490 491`-Z' 492 Do not postprocess the output of `gtroff'. Normally `groff' 493 automatically runs the appropriate postprocessor. 494 495`-PARG' 496 Pass ARG to the postprocessor. Each argument should be passed 497 with a separate `-P' option. Note that `groff' does not prepend 498 `-' to ARG before passing it to the postprocessor. 499 500`-l' 501 Send the output to a spooler for printing. The command used for 502 this is specified by the `print' command in the device description 503 file (see *Note Font Files::, for more info). If not present, 504 `-l' is ignored. 505 506`-LARG' 507 Pass ARG to the spooler. Each argument should be passed with a 508 separate `-L' option. Note that `groff' does not prepend a `-' to 509 ARG before passing it to the postprocessor. If the `print' 510 keyword in the device description file is missing, `-L' is ignored. 511 512`-TDEV' 513 Prepare output for device DEV. The default device is `ps', unless 514 changed when `groff' was configured and built. The following are 515 the output devices currently available: 516 517 `ps' 518 For POSTSCRIPT printers and previewers. 519 520 `dvi' 521 For TeX DVI format. 522 523 `X75' 524 For a 75dpi X11 previewer. 525 526 `X75-12' 527 For a 75dpi X11 previewer with a 12pt base font in the 528 document. 529 530 `X100' 531 For a 100dpi X11 previewer. 532 533 `X100-12' 534 For a 100dpi X11 previewer with a 12pt base font in the 535 document. 536 537 `ascii' 538 For typewriter-like devices using the (7-bit) ASCII character 539 set. 540 541 `latin1' 542 For typewriter-like devices that support the Latin-1 543 (ISO 8859-1) character set. 544 545 `utf8' 546 For typewriter-like devices which use the Unicode (ISO 10646) 547 character set with UTF-8 encoding. 548 549 `cp1047' 550 For typewriter-like devices which use the EBCDIC encoding IBM 551 cp1047. 552 553 `lj4' 554 For HP LaserJet4-compatible (or other PCL5-compatible) 555 printers. 556 557 `lbp' 558 For Canon CAPSL printers (LBP-4 and LBP-8 series laser 559 printers). 560 561 `html' 562 To produce HTML output. Note that the HTML driver consists 563 of two parts, a preprocessor (`pre-grohtml') and a 564 postprocessor (`post-grohtml'). 565 566 The predefined `gtroff' string register `.T' contains the current 567 output device; the read-only number register `.T' is set to 1 if 568 this option is used (which is always true if `groff' is used to 569 call `gtroff'). *Note Built-in Registers::. 570 571 The postprocessor to be used for a device is specified by the 572 `postpro' command in the device description file. (*Note Font 573 Files::, for more info.) This can be overridden with the `-X' 574 option. 575 576`-X' 577 Preview with `gxditview' instead of using the usual postprocessor. 578 This is unlikely to produce good results except with `-Tps'. 579 580 Note that this is not the same as using `-TX75' or `-TX100' to 581 view a document with `gxditview': The former uses the metrics of 582 the specified device, whereas the latter uses X-specific fonts and 583 metrics. 584 585`-N' 586 Don't allow newlines with `eqn' delimiters. This is the same as 587 the `-N' option in `geqn'. 588 589`-S' 590 Safer mode. Pass the `-S' option to `gpic' and disable the 591 `open', `opena', `pso', `sy', and `pi' requests. For security 592 reasons, this is enabled by default. 593 594`-U' 595 Unsafe mode. This enables the `open', `opena', `pso', `sy', and 596 `pi' requests. 597 598`-a' 599 Generate an ASCII approximation of the typeset output. The 600 read-only register `.A' is then set to 1. *Note Built-in 601 Registers::. A typical example is 602 603 604 groff -a -man -Tdvi troff.man | less 605 606 which shows how lines are broken for the DVI device. Note that 607 this option is rather useless today since graphic output devices 608 are available virtually everywhere. 609 610`-b' 611 Print a backtrace with each warning or error message. This 612 backtrace should help track down the cause of the error. The line 613 numbers given in the backtrace may not always be correct: `gtroff' 614 can get confused by `as' or `am' requests while counting line 615 numbers. 616 617`-i' 618 Read the standard input after all the named input files have been 619 processed. 620 621`-wNAME' 622 Enable warning NAME. Available warnings are described in *Note 623 Debugging::. Multiple `-w' options are allowed. 624 625`-WNAME' 626 Inhibit warning NAME. Multiple `-W' options are allowed. 627 628`-E' 629 Inhibit all error messages. 630 631`-C' 632 Enable compatibility mode. *Note Implementation Differences::, 633 for the list of incompatibilities between `groff' and AT&T `troff'. 634 635`-dCS' 636`-dNAME=S' 637 Define C or NAME to be a string S. C must be a one-letter name; 638 NAME can be of arbitrary length. All string assignments happen 639 before loading any macro file (including the start-up file). 640 641`-fFAM' 642 Use FAM as the default font family. *Note Font Families::. 643 644`-mNAME' 645 Read in the file `NAME.tmac'. Normally `groff' searches for this 646 in its macro directories. If it isn't found, it tries `tmac.NAME' 647 (searching in the same directories). 648 649`-nNUM' 650 Number the first page NUM. 651 652`-oLIST' 653 Output only pages in LIST, which is a comma-separated list of page 654 ranges; `N' means print page N, `M-N' means print every page 655 between M and N, `-N' means print every page up to N, `N-' means 656 print every page beginning with N. `gtroff' exits after printing 657 the last page in the list. All the ranges are inclusive on both 658 ends. 659 660 Within `gtroff', this information can be extracted with the `.P' 661 register. *Note Built-in Registers::. 662 663 If your document restarts page numbering at the beginning of each 664 chapter, then `gtroff' prints the specified page range for each 665 chapter. 666 667`-rCN' 668`-rNAME=N' 669 Set number register C or NAME to the value N. C must be a 670 one-letter name; NAME can be of arbitrary length. N can be any 671 `gtroff' numeric expression. All register assignments happen 672 before loading any macro file (including the start-up file). 673 674`-FDIR' 675 Search `DIR' for subdirectories `devNAME' (NAME is the name of the 676 device), for the `DESC' file, and for font files before looking in 677 the standard directories (*note Font Directories::). This option 678 is passed to all pre- and postprocessors using the 679 `GROFF_FONT_PATH' environment variable. 680 681`-MDIR' 682 Search directory `DIR' for macro files before the standard 683 directories (*note Macro Directories::). 684 685`-IDIR' 686 This option is as described in *Note gsoelim::. It implies the 687 `-s' option. 688 689 690File: groff, Node: Environment, Next: Macro Directories, Prev: Groff Options, Up: Invoking groff 691 692Environment 693=========== 694 695 There are also several environment variables (of the operating 696system, not within `gtroff') which can modify the behavior of `groff'. 697 698`GROFF_COMMAND_PREFIX' 699 If this is set to X, then `groff' runs `Xtroff' instead of 700 `gtroff'. This also applies to `tbl', `pic', `eqn', `grn', 701 `refer', and `soelim'. It does not apply to `grops', `grodvi', 702 `grotty', `pre-grohtml', `post-grohtml', `grolj4', and `gxditview'. 703 704 The default command prefix is determined during the installation 705 process. If a non-GNU troff system is found, prefix `g' is used, 706 none otherwise. 707 708`GROFF_TMAC_PATH' 709 A colon-separated list of directories in which to search for macro 710 files (before the default directories are tried). *Note Macro 711 Directories::. 712 713`GROFF_TYPESETTER' 714 The default output device. 715 716`GROFF_FONT_PATH' 717 A colon-separated list of directories in which to search for the 718 `dev'NAME directory (before the default directories are tried). 719 *Note Font Directories::. 720 721`GROFF_BIN_PATH' 722 This search path, followed by `PATH', is used for commands executed 723 by `groff'. 724 725`GROFF_TMPDIR' 726 The directory in which `groff' creates temporary files. If this is 727 not set and `TMPDIR' is set, temporary files are created in that 728 directory. Otherwise temporary files are created in a 729 system-dependent default directory (on Unix and GNU/Linux systems, 730 this is usually `/tmp'). `grops', `grefer', `pre-grohtml', and 731 `post-grohtml' can create temporary files in this directory. 732 733 Note that MS-DOS and MS-Windows ports of `groff' use semi-colons, 734rather than colons, to separate the directories in the lists described 735above. 736 737 738File: groff, Node: Macro Directories, Next: Font Directories, Prev: Environment, Up: Invoking groff 739 740Macro Directories 741================= 742 743 All macro file names must be named `NAME.tmac' or `tmac.NAME' to 744make the `-mNAME' command line option work. The `mso' request doesn't 745have this restriction; any file name can be used, and `gtroff' won't 746try to append or prepend the `tmac' string. 747 748 Macro files are kept in the "tmac directories", all of which 749constitute the "tmac path". The elements of the search path for macro 750files are (in that order): 751 752 * The directories specified with `gtroff''s or `groff''s `-M' 753 command line option. 754 755 * The directories given in the `GROFF_TMAC_PATH' environment 756 variable. 757 758 * The current directory (only if in unsafe mode using the `-U' 759 command line switch). 760 761 * The home directory. 762 763 * A platform-dependent directory, a site-specific 764 (platform-independent) directory, and the main tmac directory; the 765 default locations are 766 767 768 /usr/local/lib/groff/site-tmac 769 /usr/local/share/groff/site-tmac 770 /usr/local/share/groff/1.18.2/tmac 771 772 assuming that the version of `groff' is 1.18.2, and the 773 installation prefix was `/usr/local'. It is possible to fine-tune 774 those directories during the installation process. 775 776 777File: groff, Node: Font Directories, Next: Paper Size, Prev: Macro Directories, Up: Invoking groff 778 779Font Directories 780================ 781 782 Basically, there is no restriction how font files for `groff' are 783named and how long font names are; however, to make the font family 784mechanism work (*note Font Families::), fonts within a family should 785start with the family name, followed by the shape. For example, the 786Times family uses `T' for the family name and `R', `B', `I', and `BI' 787to indicate the shapes `roman', `bold', `italic', and `bold italic', 788respectively. Thus the final font names are `TR', `TB', `TI', and 789`TBI'. 790 791 All font files are kept in the "font directories" which constitute 792the "font path". The file search functions will always append the 793directory `dev'NAME, where NAME is the name of the output device. 794Assuming, say, DVI output, and `/foo/bar' as a font directory, the font 795files for `grodvi' must be in `/foo/bar/devdvi'. 796 797 The elements of the search path for font files are (in that order): 798 799 * The directories specified with `gtroff''s or `groff''s `-F' 800 command line option. All device drivers and some preprocessors 801 also have this option. 802 803 * The directories given in the `GROFF_FONT_PATH' environment 804 variable. 805 806 * A site-specific directory and the main font directory; the default 807 locations are 808 809 810 /usr/local/share/groff/site-font 811 /usr/local/share/groff/1.18.2/font 812 813 assuming that the version of `groff' is 1.18.2, and the 814 installation prefix was `/usr/local'. It is possible to fine-tune 815 those directories during the installation process. 816 817 818File: groff, Node: Paper Size, Next: Invocation Examples, Prev: Font Directories, Up: Invoking groff 819 820Paper Size 821========== 822 823 In groff, the page size for `gtroff' and for output devices are 824handled separately. *Note Page Layout::, for vertical manipulation of 825the page size. *Note Line Layout::, for horizontal changes. 826 827 A default paper size can be set in the device's `DESC' file. Most 828output devices also have a command line option `-p' to override the 829default paper size and option `-l' to use landscape orientation. *Note 830DESC File Format::, for a description of the `papersize' keyword which 831takes the same argument as `-p'. 832 833 A convenient shorthand to set a particular paper size for `gtroff' 834is command line option `-dpaper=SIZE'. This defines string `paper' 835which is processed in file `papersize.tmac' (loaded in the start-up 836file `troffrc' by default). Possible values for SIZE are the same as 837the predefined values for the `papersize' keyword (but only in 838lowercase) except `a7'-`d7'. An appended `l' (ell) character denotes 839landscape orientation. 840 841 For example, use the following for PS output on A4 paper in landscape 842orientation: 843 844 845 groff -Tps -dpaper=a4l -P-pa4 -P-l -ms foo.ms > foo.ps 846 847 Note that it is up to the particular macro package to respect default 848page dimensions set in this way (most do). 849 850 851File: groff, Node: Invocation Examples, Prev: Paper Size, Up: Invoking groff 852 853Invocation Examples 854=================== 855 856 This section lists several common uses of `groff' and the 857corresponding command lines. 858 859 860 groff file 861 862This command processes `file' without a macro package or a 863preprocessor. The output device is the default, `ps', and the output 864is sent to `stdout'. 865 866 867 groff -t -mandoc -Tascii file | less 868 869This is basically what a call to the `man' program does. `gtroff' 870processes the manual page `file' with the `mandoc' macro file (which in 871turn either calls the `man' or the `mdoc' macro package), using the 872`tbl' preprocessor and the ASCII output device. Finally, the `less' 873pager displays the result. 874 875 876 groff -X -m me file 877 878Preview `file' with `gxditview', using the `me' macro package. Since 879no `-T' option is specified, use the default device (`ps'). Note that 880you can either say `-m me' or `-me'; the latter is an anachronism from 881the early days of UNIX.(1) (*note Invocation Examples-Footnote-1::) 882 883 884 groff -man -rD1 -z file 885 886Check `file' with the `man' macro package, forcing double-sided 887printing - don't produce any output. 888 889* Menu: 890 891* grog:: 892 893 894File: groff, Node: Invocation Examples-Footnotes, Up: Invocation Examples 895 896 (1) The same is true for the other main macro packages that come 897with `groff': `man', `mdoc', `ms', `mm', and `mandoc'. This won't work 898in general; for example, to load `trace.tmac', either `-mtrace' or 899`-m trace' must be used. 900 901 902File: groff, Node: grog, Prev: Invocation Examples, Up: Invocation Examples 903 904`grog' 905------ 906 907 `grog' reads files, guesses which of the `groff' preprocessors 908and/or macro packages are required for formatting them, and prints the 909`groff' command including those options on the standard output. It 910generates one or more of the options `-e', `-man', `-me', `-mm', 911`-mom', `-ms', `-mdoc', `-mdoc-old', `-p', `-R', `-g', `-G', `-s', and 912`-t'. 913 914 A special file name `-' refers to the standard input. Specifying no 915files also means to read the standard input. Any specified options are 916included in the printed command. No space is allowed between options 917and their arguments. The only options recognized are `-C' (which is 918also passed on) to enable compatibility mode, and `-v' to print the 919version number and exit. 920 921 For example, 922 923 924 grog -Tdvi paper.ms 925 926guesses the appropriate command to print `paper.ms' and then prints it 927to the command line after adding the `-Tdvi' option. For direct 928execution, enclose the call to `grog' in backquotes at the UNIX shell 929prompt: 930 931 932 `grog -Tdvi paper.ms` > paper.dvi 933 934As seen in the example, it is still necessary to redirect the output to 935something meaningful (i.e. either a file or a pager program like 936`less'). 937 938 939File: groff, Node: Tutorial for Macro Users, Next: Macro Packages, Prev: Invoking groff, Up: Top 940 941Tutorial for Macro Users 942************************ 943 944 Most users tend to use a macro package to format their papers. This 945means that the whole breadth of `groff' is not necessary for most 946people. This chapter covers the material needed to efficiently use a 947macro package. 948 949* Menu: 950 951* Basics:: 952* Common Features:: 953 954 955File: groff, Node: Basics, Next: Common Features, Prev: Tutorial for Macro Users, Up: Tutorial for Macro Users 956 957Basics 958====== 959 960 This section covers some of the basic concepts necessary to 961understand how to use a macro package.(1) (*note Basics-Footnote-1::) 962References are made throughout to more detailed information, if desired. 963 964 `gtroff' reads an input file prepared by the user and outputs a 965formatted document suitable for publication or framing. The input 966consists of text, or words to be printed, and embedded commands 967("requests" and "escapes"), which tell `gtroff' how to format the 968output. For more detail on this, see *Note Embedded Commands::. 969 970 The word "argument" is used in this chapter to mean a word or number 971which appears on the same line as a request, and which modifies the 972meaning of that request. For example, the request 973 974 975 .sp 976 977spaces one line, but 978 979 980 .sp 4 981 982spaces four lines. The number 4 is an argument to the `sp' request 983which says to space four lines instead of one. Arguments are separated 984from the request and from each other by spaces (_no_ tabs). More 985details on this can be found in *Note Request and Macro Arguments::. 986 987 The primary function of `gtroff' is to collect words from input 988lines, fill output lines with those words, justify the right-hand margin 989by inserting extra spaces in the line, and output the result. For 990example, the input: 991 992 993 Now is the time 994 for all good men 995 to come to the aid 996 of their party. 997 Four score and seven 998 years ago, etc. 999 1000is read, packed onto output lines, and justified to produce: 1001 1002 Now is the time for all good men to come to the aid of their party. 1003 Four score and seven years ago, etc. 1004 1005 Sometimes a new output line should be started even though the current 1006line is not yet full; for example, at the end of a paragraph. To do 1007this it is possible to cause a "break", which starts a new output line. 1008Some requests cause a break automatically, as normally do blank input 1009lines and input lines beginning with a space. 1010 1011 Not all input lines are text to be formatted. Some input lines are 1012requests which describe how to format the text. Requests always have a 1013period (`.') or an apostrophe (`'') as the first character of the input 1014line. 1015 1016 The text formatter also does more complex things, such as 1017automatically numbering pages, skipping over page boundaries, putting 1018footnotes in the correct place, and so forth. 1019 1020 Here are a few hints for preparing text for input to `gtroff'. 1021 1022 * First, keep the input lines short. Short input lines are easier to 1023 edit, and `gtroff' packs words onto longer lines anyhow. 1024 1025 * In keeping with this, it is helpful to begin a new line after every 1026 comma or phrase, since common corrections are to add or delete 1027 sentences or phrases. 1028 1029 * End each sentence with two spaces - or better, start each sentence 1030 on a new line. `gtroff' recognizes characters that usually end a 1031 sentence, and inserts sentence space accordingly. 1032 1033 * Do not hyphenate words at the end of lines - `gtroff' is smart 1034 enough to hyphenate words as needed, but is not smart enough to 1035 take hyphens out and join a word back together. Also, words such 1036 as "mother-in-law" should not be broken over a line, since then a 1037 space can occur where not wanted, such as "mother- in-law". 1038 1039 `gtroff' double-spaces output text automatically if you use the 1040request `.ls 2'. Reactivate single-spaced mode by typing `.ls 1'.(2) 1041(*note Basics-Footnote-2::) 1042 1043 A number of requests allow to change the way the output looks, 1044sometimes called the "layout" of the output page. Most of these 1045requests adjust the placing of "whitespace" (blank lines or spaces). 1046 1047 The `bp' request starts a new page, causing a line break. 1048 1049 The request `.sp N' leaves N lines of blank space. N can be omitted 1050(meaning skip a single line) or can be of the form Ni (for N inches) or 1051Nc (for N centimeters). For example, the input: 1052 1053 1054 .sp 1.5i 1055 My thoughts on the subject 1056 .sp 1057 1058leaves one and a half inches of space, followed by the line "My 1059thoughts on the subject", followed by a single blank line (more 1060measurement units are available, see *Note Measurements::). 1061 1062 Text lines can be centered by using the `ce' request. The line 1063after `ce' is centered (horizontally) on the page. To center more than 1064one line, use `.ce N' (where N is the number of lines to center), 1065followed by the N lines. To center many lines without counting them, 1066type: 1067 1068 1069 .ce 1000 1070 lines to center 1071 .ce 0 1072 1073The `.ce 0' request tells `groff' to center zero more lines, in other 1074words, stop centering. 1075 1076 All of these requests cause a break; that is, they always start a new 1077line. To start a new line without performing any other action, use 1078`br'. 1079 1080 1081File: groff, Node: Basics-Footnotes, Up: Basics 1082 1083 (1) This section is derived from `Writing Papers with nroff using 1084-me' by Eric P. Allman. 1085 1086 (2) If you need finer granularity of the vertical space, use the 1087`pvs' request (*note Changing Type Sizes::). 1088 1089 1090File: groff, Node: Common Features, Prev: Basics, Up: Tutorial for Macro Users 1091 1092Common Features 1093=============== 1094 1095 `gtroff' provides very low-level operations for formatting a 1096document. There are many common routine operations which are done in 1097all documents. These common operations are written into "macros" and 1098collected into a "macro package". 1099 1100 All macro packages provide certain common capabilities which fall 1101into the following categories. 1102 1103* Menu: 1104 1105* Paragraphs:: 1106* Sections and Chapters:: 1107* Headers and Footers:: 1108* Page Layout Adjustment:: 1109* Displays:: 1110* Footnotes and Annotations:: 1111* Table of Contents:: 1112* Indices:: 1113* Paper Formats:: 1114* Multiple Columns:: 1115* Font and Size Changes:: 1116* Predefined Strings:: 1117* Preprocessor Support:: 1118* Configuration and Customization:: 1119 1120 1121File: groff, Node: Paragraphs, Next: Sections and Chapters, Prev: Common Features, Up: Common Features 1122 1123Paragraphs 1124---------- 1125 1126 One of the most common and most used capability is starting a 1127paragraph. There are a number of different types of paragraphs, any of 1128which can be initiated with macros supplied by the macro package. 1129Normally, paragraphs start with a blank line and the first line 1130indented, like the text in this manual. There are also block style 1131paragraphs, which omit the indentation: 1132 1133 1134 Some men look at constitutions with sanctimonious 1135 reverence, and deem them like the ark of the covenant, too 1136 sacred to be touched. 1137 1138And there are also indented paragraphs which begin with a tag or label 1139at the margin and the remaining text indented. 1140 1141 1142 one This is the first paragraph. Notice how the first 1143 line of the resulting paragraph lines up with the 1144 other lines in the paragraph. 1145 1146 1147 longlabel 1148 This paragraph had a long label. The first 1149 character of text on the first line does not line up 1150 with the text on second and subsequent lines, 1151 although they line up with each other. 1152 1153 A variation of this is a bulleted list. 1154 1155 1156 . Bulleted lists start with a bullet. It is possible 1157 to use other glyphs instead of the bullet. In nroff 1158 mode using the ASCII character set for output, a dot 1159 is used instead of a real bullet. 1160 1161 1162File: groff, Node: Sections and Chapters, Next: Headers and Footers, Prev: Paragraphs, Up: Common Features 1163 1164Sections and Chapters 1165--------------------- 1166 1167 Most macro packages supply some form of section headers. The 1168simplest kind is simply the heading on a line by itself in bold type. 1169Others supply automatically numbered section heading or different 1170heading styles at different levels. Some, more sophisticated, macro 1171packages supply macros for starting chapters and appendices. 1172 1173 1174File: groff, Node: Headers and Footers, Next: Page Layout Adjustment, Prev: Sections and Chapters, Up: Common Features 1175 1176Headers and Footers 1177------------------- 1178 1179 Every macro package gives some way to manipulate the "headers" and 1180"footers" (also called "titles") on each page. This is text put at the 1181top and bottom of each page, respectively, which contain data like the 1182current page number, the current chapter title, and so on. Its 1183appearance is not affected by the running text. Some packages allow 1184for different ones on the even and odd pages (for material printed in a 1185book form). 1186 1187 The titles are called "three-part titles", that is, there is a 1188left-justified part, a centered part, and a right-justified part. An 1189automatically generated page number may be put in any of these fields 1190with the `%' character (see *Note Page Layout::, for more details). 1191 1192 1193File: groff, Node: Page Layout Adjustment, Next: Displays, Prev: Headers and Footers, Up: Common Features 1194 1195Page Layout 1196----------- 1197 1198 Most macro packages let the user specify top and bottom margins and 1199other details about the appearance of the printed pages. 1200 1201 1202File: groff, Node: Displays, Next: Footnotes and Annotations, Prev: Page Layout Adjustment, Up: Common Features 1203 1204Displays 1205-------- 1206 1207 "Displays" are sections of text to be set off from the body of the 1208paper. Major quotes, tables, and figures are types of displays, as are 1209all the examples used in this document. 1210 1211 "Major quotes" are quotes which are several lines long, and hence 1212are set in from the rest of the text without quote marks around them. 1213 1214 A "list" is an indented, single-spaced, unfilled display. Lists 1215should be used when the material to be printed should not be filled and 1216justified like normal text, such as columns of figures or the examples 1217used in this paper. 1218 1219 A "keep" is a display of lines which are kept on a single page if 1220possible. An example for a keep might be a diagram. Keeps differ from 1221lists in that lists may be broken over a page boundary whereas keeps are 1222not. 1223 1224 "Floating keeps" move relative to the text. Hence, they are good for 1225things which are referred to by name, such as "See figure 3". A 1226floating keep appears at the bottom of the current page if it fits; 1227otherwise, it appears at the top of the next page. Meanwhile, the 1228surrounding text `flows' around the keep, thus leaving no blank areas. 1229 1230 1231File: groff, Node: Footnotes and Annotations, Next: Table of Contents, Prev: Displays, Up: Common Features 1232 1233Footnotes and Annotations 1234------------------------- 1235 1236 There are a number of requests to save text for later printing. 1237 1238 "Footnotes" are printed at the bottom of the current page. 1239 1240 "Delayed text" is very similar to a footnote except that it is 1241printed when called for explicitly. This allows a list of references to 1242appear (for example) at the end of each chapter, as is the convention in 1243some disciplines. 1244 1245 Most macro packages which supply this functionality also supply a 1246means of automatically numbering either type of annotation. 1247 1248 1249File: groff, Node: Table of Contents, Next: Indices, Prev: Footnotes and Annotations, Up: Common Features 1250 1251Table of Contents 1252----------------- 1253 1254 "Tables of contents" are a type of delayed text having a tag 1255(usually the page number) attached to each entry after a row of dots. 1256The table accumulates throughout the paper until printed, usually after 1257the paper has ended. Many macro packages provide the ability to have 1258several tables of contents (e.g. a standard table of contents, a list 1259of tables, etc). 1260 1261 1262File: groff, Node: Indices, Next: Paper Formats, Prev: Table of Contents, Up: Common Features 1263 1264Indices 1265------- 1266 1267 While some macro packages use the term "index", none actually 1268provide that functionality. The facilities they call indices are 1269actually more appropriate for tables of contents. 1270 1271 To produce a real index in a document, external tools like the 1272`makeindex' program are necessary. 1273 1274 1275File: groff, Node: Paper Formats, Next: Multiple Columns, Prev: Indices, Up: Common Features 1276 1277Paper Formats 1278------------- 1279 1280 Some macro packages provide stock formats for various kinds of 1281documents. Many of them provide a common format for the title and 1282opening pages of a technical paper. The `mm' macros in particular 1283provide formats for letters and memoranda. 1284 1285 1286File: groff, Node: Multiple Columns, Next: Font and Size Changes, Prev: Paper Formats, Up: Common Features 1287 1288Multiple Columns 1289---------------- 1290 1291 Some macro packages (but not `man') provide the ability to have two 1292or more columns on a page. 1293 1294 1295File: groff, Node: Font and Size Changes, Next: Predefined Strings, Prev: Multiple Columns, Up: Common Features 1296 1297Font and Size Changes 1298--------------------- 1299 1300 The built-in font and size functions are not always intuitive, so all 1301macro packages provide macros to make these operations simpler. 1302 1303 1304File: groff, Node: Predefined Strings, Next: Preprocessor Support, Prev: Font and Size Changes, Up: Common Features 1305 1306Predefined Strings 1307------------------ 1308 1309 Most macro packages provide various predefined strings for a variety 1310of uses; examples are sub- and superscripts, printable dates, quotes and 1311various special characters. 1312 1313 1314File: groff, Node: Preprocessor Support, Next: Configuration and Customization, Prev: Predefined Strings, Up: Common Features 1315 1316Preprocessor Support 1317-------------------- 1318 1319 All macro packages provide support for various preprocessors and may 1320extend their functionality. 1321 1322 For example, all macro packages mark tables (which are processed with 1323`gtbl') by placing them between `TS' and `TE' macros. The `ms' macro 1324package has an option, `.TS H', that prints a caption at the top of a 1325new page (when the table is too long to fit on a single page). 1326 1327 1328File: groff, Node: Configuration and Customization, Prev: Preprocessor Support, Up: Common Features 1329 1330Configuration and Customization 1331------------------------------- 1332 1333 Some macro packages provide means of customizing many of the details 1334of how the package behaves. This ranges from setting the default type 1335size to changing the appearance of section headers. 1336 1337 1338File: groff, Node: Macro Packages, Next: gtroff Reference, Prev: Tutorial for Macro Users, Up: Top 1339 1340Macro Packages 1341************** 1342 1343 This chapter documents the main macro packages that come with 1344`groff'. 1345 1346 Different main macro packages can't be used at the same time; for 1347example 1348 1349 1350 groff -m man foo.man -m ms bar.doc 1351 1352doesn't work. Note that option arguments are processed before 1353non-option arguments; the above (failing) sample is thus reordered to 1354 1355 1356 groff -m man -m ms foo.man bar.doc 1357 1358* Menu: 1359 1360* man:: 1361* mdoc:: 1362* ms:: 1363* me:: 1364* mm:: 1365 1366 1367File: groff, Node: man, Next: mdoc, Prev: Macro Packages, Up: Macro Packages 1368 1369`man' 1370===== 1371 1372 This is the most popular and probably the most important macro 1373package of `groff'. It is easy to use, and a vast majority of manual 1374pages are based on it. 1375 1376* Menu: 1377 1378* Man options:: 1379* Man usage:: 1380* Man font macros:: 1381* Miscellaneous man macros:: 1382* Predefined man strings:: 1383* Preprocessors in man pages:: 1384* Optional man extensions:: 1385 1386