contrib/groff/src/roff/groff/groff.man

   1 .ig
   2 groff.man
   3
   4 Last update: 14 July 2002
   5
   6 Copyright (C) 1989, 2002 Free Software Foundation, Inc.
   7 Rewritten in 2002 by Bernd Warken <bwarken@mayn.de>
   8
   9 Permission is granted to copy, distribute and/or modify this document
  10 under the terms of the GNU Free Documentation License, Version 1.1 or
  11 any later version published by the Free Software Foundation; with the
  12 Invariant Sections being this .ig-section and AUTHOR, with no
  13 Front-Cover Texts, and with no Back-Cover Texts.
  14
  15 A copy of the Free Documentation License is included as a file called
  16 FDL in the main directory of the groff source package.
  17
  18 $FreeBSD: src/contrib/groff/src/roff/groff/groff.man,v 1.6.2.3 2003/02/14 15:22:08 ru Exp $
  19
  20 ..
  21 .
  22 .\" --------------------------------------------------------------------
  23 .\" Setup
  24 .\" --------------------------------------------------------------------
  25 .
  26 .mso www.tmac
  27 .
  28 .\" set adjust to both
  29 .ad b
  30 .
  31 .\" fonts of fixed length
  32 .
  33 .if n \{\
  34 .  mso tty-char.tmac
  35 .  ftr CR R
  36 .  ftr CI I
  37 .  ftr CB B
  38 .\}
  39 .
  40 .if '\*[.T]'dvi' \
  41 .  ftr CB CW
  42 .
  43 .\" --------------------------------------------------------------------
  44 .\" String definitions
  45 .
  46 .ds @- "\-\"
  47 .ds @-- "\-\^\-\"
  48 .
  49 .ds Ellipsis .\|.\|.\"
  50 .
  51 .
  52 .\" --------------------------------------------------------------------
  53 .\" Begin of macro definitions
  54 .de c
  55 .\" this is like a comment request when escape mechanism is off
  56 ..
  57 .eo
  58 .
  59 .c --------------------------------------------------------------------
  60 .de TP+
  61 .br
  62 .ns
  63 .TP \$1
  64 ..
  65 .c --------------------------------------------------------------------
  66 .c Like TP, but if specified indent is more than half
  67 .c the current line-length - indent, use the default indent.
  68 .de Tp
  69 .  ie \n[.$]=0:((0\$1)*2u>(\n.lu-\n(.iu)) .TP
  70 .  el .TP "\$1"
  71 ..
  72 .c --------------------------------------------------------------------
  73 .de Text
  74 .  nop \)\$*
  75 ..
  76 .c --------------------------------------------------------------------
  77 .de Synopsis
  78 .  ds @arg1 \$1\"
  79 .  nr @old_indent \n[.i]
  80 .  ad l
  81 .  in +\w'\f[B]\*[@arg1]\0'u
  82 .  ti \n[@old_indent]u
  83 .  B \*[@arg1]\0\c
  84 .  rr @old_indent
  85 .  rm @arg1
  86 ..
  87 .c --------------------------------------------------------------------
  88 .de EndSynopsis
  89 .  ad
  90 .  in
  91 ..
  92 .c --------------------------------------------------------------------
  93 .c ShortOpt[]  (name [arg])
  94 .c
  95 .c short option in synopsis
  96 .c
  97 .de ShortOpt[]
  98 .  if \n[.$]=0 \
  99 .    return
 100 .  ds @opt \$1\"
 101 .  shift
 102 .  ie \n[.$]=0 \
 103 .    Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\f[]\f[R]]\f[]
 104 .  el \
 105 .    Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\~\f[]\f[I]\/\$*\f[]\f[R]]\f[]
 106 .  rm @opt
 107 ..
 108 .c --------------------------------------------------------------------
 109 .c Option in synopsis (short option)
 110 .de SynOpt
 111 .  if \n[.$]=0 \
 112 .    return
 113 .  ds @opt \$1\"
 114 .  shift
 115 .  ie \n[.$]=0 \
 116 .    Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\f[]\f[R]]\f[]
 117 .  el \
 118 .    Text \f[R][\f[]\f[CB]\*[@-]\*[@opt]\~\f[]\f[I]\/\$*\f[]\f[R]]\f[]
 119 .  rm @opt
 120 ..
 121 .c --------------------------------------------------------------------
 122 .c ShortOpt ([char [punct]])
 123 .c
 124 .c `-c' somwhere in the text
 125 .c second arg is punctuation
 126 .c
 127 .de ShortOpt
 128 .  ds @opt \$1\"
 129 .  shift
 130 .  Text \f[CB]\*[@-]\*[@opt]\f[]\/\$*
 131 .  rm @opt
 132 ..
 133 .c --------------------------------------------------------------------
 134 .c LongOpt  ([name [punct]])
 135 .c
 136 .c `--name' somwhere in the text
 137 .c second arg is punctuation
 138 .c
 139 .de LongOpt
 140 .  ds @opt \$1\"
 141 .  shift
 142 .  Text \f[CB]\*[@--]\f[]\f[B]\*[@opt]\f[]\/\$*
 143 .  rm @opt
 144 ..
 145 .c --------------------------------------------------------------------
 146 .c OptDef  (shortopt [longopt [argument]])
 147 .c
 148 .c option documentation
 149 .c args : `shortopt', `longopt' can be ""
 150 .c
 151 .de OptDef
 152 .  ds @short
 153 .  ds @long
 154 .  ds @arg
 155 .  if \n[.$]>=1 \{\
 156 .    ds @arg1 "\$1\"
 157 .    if !'\*[@arg1]'' \
 158 .      ds @short "\f[CB]\*[@-]\*[@arg1]\f[]\"
 159 .    if \n[.$]>=2 \{\
 160 .      if !'\*[@short]'' \
 161 .        as @short \f[CW]\0\f[]
 162 .      ds @arg2 "\$2\"
 163 .      if !'\*[@arg2]'' \
 164 .        ds @long "\f[CB]\*[@--]\f[]\f[B]\*[@arg2]\f[]\"
 165 .      if \n[.$]>=3 \{\
 166 .        if !'\*[@long]'' \
 167 .          as @long \|=\|\"
 168 .        shift 2
 169 .        ds @arg \f[I]\$*\"
 170 .      \}
 171 .    \}
 172 .  \}
 173 .  IP "\f[R]\*[@short]\*[@long]\*[@arg]\f[]"
 174 .  rm @arg
 175 .  rm @arg1
 176 .  rm @arg2
 177 .  rm @short
 178 .  rm @long
 179 ..
 180 .c --------------------------------------------------------------------
 181 .c Continuation of an OptDef header.
 182 .de OptDef+
 183 .  br
 184 .  ns
 185 .  OptDef \$@
 186 ..
 187 .c --------------------------------------------------------------------
 188 .c Environment variable
 189 .de EnvVar
 190 .  SM
 191 .  BR \$1 \$2
 192 ..
 193 .c --------------------------------------------------------------------
 194 .c a shell command line
 195 .de ShellCommand
 196 .  nr @font \n[.f]
 197 .  c replace argument separator by unbreakable space
 198 .  ds @args \$1\""
 199 .  shift
 200 .  while (\n[.$]>0) \{\
 201 .    ds @args \*[@args]\~\$1
 202 .    shift
 203 .  \}
 204 .  br
 205 .  ad l
 206 .  nh
 207 .  Text \f[I]sh#\h'1m'\f[P]\f[CR]\*[@args]\f[P]\&\"
 208 .  ft R
 209 .  ft P
 210 .  hy
 211 .  ad
 212 .  ft \n[@font]
 213 .  br
 214 .  rr @font
 215 .  rm @args
 216 ..
 217 .c --------------------------------------------------------------------
 218 .c `char or string'
 219 .de Quoted
 220 .  ft CR
 221 .  Text \[oq]\$*\[cq]
 222 .  ft
 223 ..
 224 .c --------------------------------------------------------------------
 225 .c End of macro definitions
 226 .ec
 227 .
 228 .
 229 .\" --------------------------------------------------------------------
 230 .\" Title
 231 .\" --------------------------------------------------------------------
 232 .
 233 .TH GROFF @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
 234 .SH NAME
 235 groff \- front-end for the groff document formatting system
 236 .
 237 .
 238 .\" --------------------------------------------------------------------
 239 .SH SYNOPSIS
 240 .\" --------------------------------------------------------------------
 241 .
 242 .ad l
 243 .Synopsis groff
 244 .ShortOpt[] abcegilpstzCEGNRSUVXZ
 245 .ShortOpt[] d cs
 246 .ShortOpt[] f fam
 247 .ShortOpt[] F dir
 248 .ShortOpt[] I dir
 249 .ShortOpt[] L arg
 250 .ShortOpt[] m name
 251 .ShortOpt[] M dir
 252 .ShortOpt[] n num
 253 .ShortOpt[] o list
 254 .ShortOpt[] P arg
 255 .ShortOpt[] r cn
 256 .ShortOpt[] T dev
 257 .ShortOpt[] w name
 258 .ShortOpt[] W name
 259 .RI [ file
 260 .Text \*[Ellipsis]]
 261 .EndSynopsis
 262 .
 263 .Synopsis groff
 264 .ShortOpt h
 265 |
 266 .LongOpt help
 267 .EndSynopsis
 268 .
 269 .Synopsis groff
 270 .ShortOpt v
 271 |
 272 .LongOpt version
 273 .RI [ option
 274 .Text \*[Ellipsis]]
 275 .EndSynopsis
 276 .
 277 .P
 278 The command line is parsed according to the usual GNU convention.
 279 .
 280 The whitespace between a command line option and its argument is
 281 optional.
 282 .
 283 Options can be grouped behind a single
 284 .ShortOpt
 285 (minus character).
 286 .
 287 A filename of
 288 .ShortOpt
 289 (minus character) denotes the standard input.
 290 .
 291 .
 292 .\" --------------------------------------------------------------------
 293 .SH DESCRIPTION
 294 .\" --------------------------------------------------------------------
 295 .
 296 This document describes the
 297 .B groff
 298 program, the main front-end for the
 299 .I groff
 300 document formatting system.
 301 .
 302 The
 303 .I groff
 304 program and macro suite is the implementation of a
 305 .BR roff (@MAN7EXT@)
 306 system within the free software collection
 307 .URL http://\:www.gnu.org "GNU" .
 308 .
 309 The
 310 .I groff
 311 system has all features of the classical
 312 .IR roff ,
 313 but adds many extensions.
 314 .
 315 .P
 316 The
 317 .B groff
 318 program allows to control the whole
 319 .I groff
 320 system by comand line options.
 321 .
 322 This is a great simplification in comparison to the classical case (which
 323 uses pipes only).
 324 .
 325 .
 326 .\" --------------------------------------------------------------------
 327 .SH OPTIONS
 328 .\" --------------------------------------------------------------------
 329 .
 330 As
 331 .B groff
 332 is a wrapper program for
 333 .B @g@troff
 334 both programs share a set of options.
 335 .
 336 But the
 337 .B groff
 338 program has some additional, native options and gives a new meaning to
 339 some
 340 .B @g@troff
 341 options.
 342 .
 343 On the other hand, not all
 344 .B @g@troff
 345 options can be fed into
 346 .BR groff .
 347 .
 348 .
 349 .\" --------------------------------------------------------------------
 350 .SS Native groff Options
 351 .\" --------------------------------------------------------------------
 352 .
 353 The following options either do not exist for
 354 .B @g@troff
 355 or are differently interpreted by
 356 .BR groff .
 357 .
 358 .
 359 .OptDef e
 360 Preprocess with
 361 .BR @g@eqn .
 362 .
 363 .
 364 .OptDef g
 365 Preprocess with
 366 .BR @g@grn .
 367 .
 368 .
 369 .OptDef G
 370 Preprocess with
 371 .BR grap .
 372 .
 373 .
 374 .OptDef h help
 375 Print a help message.
 376 .
 377 .
 378 .OptDef I "" dir
 379 Add search directory for
 380 .BR \%@g@soelim (@MAN1EXT@).
 381 This option implies the
 382 .ShortOpt s
 383 option.
 384 .
 385 .
 386 .OptDef l
 387 Send the output to a spooler program for printing.
 388 .
 389 The command that should be used for this is specified by the
 390 .B print
 391 command in the device description file, see
 392 .BR \%groff_font (@MAN5EXT@).
 393 If this command is not present, the output is piped into the
 394 .BR lpr (1)
 395 program by default.
 396 .
 397 See options
 398 .ShortOpt L
 399 and
 400 .ShortOpt X .
 401 .
 402 .
 403 .OptDef L "" arg
 404 Pass
 405 .I arg
 406 to the spooler program.
 407 Several arguments should be passed with a separate
 408 .ShortOpt L
 409 option each.
 410 .
 411 Note that
 412 .B groff
 413 does not prepend
 414 .ShortOpt\" just a minus sign
 415 (a minus sign) to
 416 .I arg
 417 before passing it to the spooler program.
 418 .
 419 .
 420 .OptDef N
 421 Don't allow newlines within
 422 .I eqn
 423 delimiters.
 424 .
 425 This is the same as the
 426 .ShortOpt N
 427 option in
 428 .BR @g@eqn .
 429 .
 430 .
 431 .OptDef p
 432 Preprocess with
 433 .BR @g@pic .
 434 .
 435 .
 436 .OptDef P "" "-option"
 437 .OptDef+ P "" "-option \f[CB]-P\f[] arg"
 438 Pass
 439 .I -option
 440 or
 441 .I -option arg
 442 to the postprocessor.
 443 .
 444 The option must be specified with the necessary preceding minus
 445 sign(s)
 446 .Quoted \*[@-]
 447 or
 448 .Quoted \*[@--]
 449 because groff does not prepend any dashes before passing it to the
 450 postprocessor.
 451 .
 452 For example, to pass a title to the gxditview postprocessor, the shell
 453 command
 454 .IP
 455 .ShellCommand groff -X -P -title -P 'groff it' \f[I]foo\f[]
 456 .IP
 457 is equivalent to
 458 .IP
 459 .ShellCommand groff -X -Z \f[I]foo\f[] | gxditview -title 'groff it' -
 460 .
 461 .
 462 .OptDef R
 463 Preprocess with
 464 .BR @g@refer .
 465 .
 466 No mechanism is provided for passing arguments to
 467 .B @g@refer
 468 because most
 469 .B @g@refer
 470 options have equivalent language elements that can be specified within
 471 the document.
 472 .
 473 See
 474 .BR \%@g@refer (@MAN1EXT@)
 475 for more details.
 476 .
 477 .
 478 .OptDef s
 479 Preprocess with
 480 .BR @g@soelim .
 481 .
 482 .
 483 .OptDef S
 484 Safer mode.
 485 .
 486 Pass the
 487 .ShortOpt S
 488 option to
 489 .B @g@pic
 490 and disable the following
 491 .B @g@troff
 492 requests:
 493 .BR .open ,
 494 .BR .opena ,
 495 .BR .pso ,
 496 .BR .sy ,
 497 and
 498 .BR .pi .
 499 For security reasons, safer mode is enabled by default.
 500 .
 501 .
 502 .OptDef t
 503 Preprocess with
 504 .BR @g@tbl .
 505 .
 506 .
 507 .OptDef T "" dev
 508 Set output device to
 509 .IR dev .
 510 The possible values in
 511 .I groff
 512 are
 513 .BR ascii ,
 514 .BR cp1047 ,
 515 .BR dvi ,
 516 .BR html ,
 517 .BR latin1 ,
 518 .BR lbp ,
 519 .BR lj4 ,
 520 .BR ps ,
 521 .BR utf8 ,
 522 .BR X75 ,
 523 and
 524 .BR X100 .
 525 .
 526 Additionally,
 527 .B X75-12
 528 and
 529 .B X100-12
 530 are available for documents which use 12\|pt as the base document size.
 531 .
 532 The default device is
 533 .BR @DEVICE@ .
 534 .
 535 .
 536 .OptDef U
 537 Unsafe mode.
 538 .
 539 Reverts to the (old) unsafe behaviour; see option
 540 .ShortOpt S .
 541 .
 542 .
 543 .OptDef v version
 544 Output version information of
 545 .B groff
 546 and of all programs that are run by it; that is, the given command line
 547 is parsed in the usual way, passing
 548 .ShortOpt v
 549 to all subprograms.
 550 .
 551 .
 552 .OptDef V
 553 Output the pipeline that would be run by
 554 .BR groff
 555 (as a wrapper program), but do not execute it.
 556 .
 557 .
 558 .OptDef X
 559 Use
 560 .B gxditview
 561 instead of using the usual postprocessor to (pre)view a document.
 562 .
 563 The printing spooler behavior as outlined with options
 564 .ShortOpt l
 565 and
 566 .ShortOpt L
 567 is carried over to
 568 .BR \%gxditview (@MAN1EXT@)
 569 by determining an argument for the
 570 .B -printCommand
 571 option of
 572 .BR \%gxditview (@MAN1EXT@).
 573 .
 574 This sets the default
 575 .B Print
 576 action and the corresponding menu entry to that value.
 577 .
 578 .ShortOpt X
 579 only produces good results with
 580 .ShortOpt Tps ,
 581 .ShortOpt TX75 ,
 582 .ShortOpt TX75-12 ,
 583 .ShortOpt TX100 ,
 584 and
 585 .ShortOpt TX100-12 .
 586 .
 587 The default resolution for previewing
 588 .ShortOpt Tps
 589 output is 75\|dpi; this can be changed by passing the
 590 .ShortOpt resolution
 591 option to
 592 .BR gxditview ,
 593 for example
 594 .
 595 .IP
 596 .ShellCommand groff -X -P-resolution -P100 -man foo.1
 597 .
 598 .
 599 .OptDef z
 600 Suppress output generated by
 601 .BR @g@troff .
 602 Only error messages will be printed.
 603 .
 604 .
 605 .OptDef Z
 606 Do not postprocess the output of
 607 .B @g@troff
 608 that is normally
 609 called automatically by
 610 .BR groff .
 611 This will print the intermediate output to standard output; see
 612 .BR \%groff_out (@MAN5EXT@).
 613 .
 614 .
 615 .\" --------------------------------------------------------------------
 616 .SS Tranparent Options
 617 .\" --------------------------------------------------------------------
 618 .
 619 The following options are transparently handed over to the formatter
 620 program
 621 .B @g@troff
 622 that is called by groff subsequently.
 623 .
 624 These options are described in more detail in
 625 .BR @g@troff (@MAN1EXT@).
 626 .
 627 .OptDef a
 628 ascii approximation of output.
 629 .
 630 .OptDef b
 631 backtrace on error or warning.
 632 .
 633 .OptDef c
 634 disable color output.
 635 .
 636 .OptDef C
 637 enable compatibility mode.
 638 .
 639 .OptDef d "" cs
 640 .OptDef+ d "" name=s
 641 define string.
 642 .
 643 .OptDef E
 644 disable
 645 .B @g@troff
 646 error messages.
 647 .
 648 .OptDef f "" fam
 649 set default font family.
 650 .
 651 .OptDef F "" dir
 652 set path for font DESC files.
 653 .
 654 .OptDef i
 655 process standard input after the specified input files.
 656 .
 657 .OptDef m "" name
 658 include macro file \f[I]name\f[]\f[B].tmac\f[] (or
 659 \f[B]tmac.\f[]\f[I]name\f[]); see also
 660 .BR \%groff_tmac (@MAN5EXT@).
 661 .
 662 .OptDef M "" dir
 663 path for macro files.
 664 .
 665 .OptDef n "" num
 666 number the first page
 667 .IR num .
 668 .
 669 .OptDef o "" list
 670 output only pages in
 671 .IR list .
 672 .
 673 .OptDef r "" cn
 674 .OptDef+ r "" name=n
 675 set number register.
 676 .
 677 .OptDef w "" name
 678 enable warning
 679 .IR name .
 680 .
 681 .OptDef W "" name
 682 disable warning
 683 .IR name .
 684 .
 685 .
 686 .\" --------------------------------------------------------------------
 687 .SH "USING GROFF"
 688 .\" --------------------------------------------------------------------
 689 .
 690 The
 691 .I groff system
 692 implements the infrastructure of classical roff; see
 693 .BR roff (@MAN7EXT@)
 694 for a survey on how a roff system works in general.
 695 .
 696 Due to the front-end programs available within the groff system, using
 697 .I groff
 698 is much easier than
 699 .IR "classical roff" .
 700 .
 701 This section gives an overview of the parts that consitute the groff
 702 system.
 703 .
 704 It complements
 705 .BR roff (@MAN7EXT@)
 706 with groff-specific features.
 707 .
 708 This section can be regarded as a guide to the documentation around
 709 the groff system.
 710 .
 711 .
 712 .\" --------------------------------------------------------------------
 713 .SS Front-ends
 714 .\" --------------------------------------------------------------------
 715 .
 716 The
 717 .B groff
 718 program is a wrapper around the
 719 .BR @g@troff (@MAN1EXT@)
 720 program.
 721 .
 722 It allows to specify the preprocessors by command line options and
 723 automatically runs the postprocessor that is appropriate for the
 724 selected device.
 725 .
 726 Doing so, the sometimes tedious piping mechanism of classical
 727 .BR roff (@MAN7EXT@)
 728 can be avoided.
 729 .
 730 .P
 731 The
 732 .BR grog (@MAN1EXT@)
 733 program can be used for guessing the correct groff command line to
 734 format a file.
 735 .
 736 .P
 737 The
 738 .BR \%groffer (@MAN1EXT@)
 739 program is an allround-viewer for groff files and man pages.
 740 .
 741 .
 742 .\" --------------------------------------------------------------------
 743 .SS Preprocessors
 744 .\" --------------------------------------------------------------------
 745 .
 746 The groff preprocessors are reimplementations of the classical
 747 preprocessors with moderate extensions.
 748 .
 749 The preprocessors distributed with the
 750 .I groff
 751 package are
 752 .
 753 .TP
 754 .BR @g@eqn (@MAN1EXT@)
 755 for mathematical formul\(ae,
 756 .TP
 757 .BR @g@grn (@MAN1EXT@)
 758 for including
 759 .BR gremlin (1)
 760 pictures,
 761 .TP
 762 .BR @g@pic (@MAN1EXT@)
 763 for drawing diagrams,
 764 .TP
 765 .BR \%@g@refer (@MAN1EXT@)
 766 for bibliographic references,
 767 .TP
 768 .BR \%@g@soelim (@MAN1EXT@)
 769 for including macro files from standard locations,
 770 .
 771 .P
 772 and
 773 .TP
 774 .BR @g@tbl (@MAN1EXT@)
 775 for tables.
 776 .
 777 .P
 778 Besides these, there are some internal preprocessors that are
 779 automatically run with some devices.
 780 .
 781 These aren't visible to the user.
 782 .
 783 .
 784 .\" --------------------------------------------------------------------
 785 .SS "Macro Packages"
 786 .\" --------------------------------------------------------------------
 787 .
 788 Macro packages can be included by option
 789 .ShortOpt m .
 790 .
 791 The groff system implements and extends all classical macro packages
 792 in a compatible way and adds some packages of its own.
 793 .
 794 Actually, the following macro packages come with
 795 .IR groff :
 796 .
 797 .TP
 798 .B man
 799 The traditional man page format; see
 800 .BR \%groff_man (@MAN7EXT@).
 801 It can be specified on the command line as
 802 .ShortOpt man
 803 or
 804 .ShortOpt m
 805 .BR man .
 806 .
 807 .TP
 808 .B mandoc
 809 The general package for man pages; it automatically recognizes
 810 whether the documents uses the
 811 .I man
 812 or the
 813 .I mdoc
 814 format and branches to the corresponding macro package.
 815 .
 816 It can be specified on the command line as
 817 .ShortOpt mandoc
 818 or
 819 .ShortOpt m
 820 .BR mandoc .
 821 .
 822 .TP
 823 .B mdoc
 824 The BSD-style man page format; see
 825 .BR \%groff_mdoc (@MAN7EXT@).
 826 It can be specified on the command line as
 827 .ShortOpt mdoc
 828 or
 829 .ShortOpt m
 830 .BR mdoc .
 831 .
 832 .TP
 833 .B me
 834 The classical
 835 .I me
 836 document format; see
 837 .BR \%groff_me (@MAN7EXT@).
 838 It can be specified on the command line as
 839 .ShortOpt me
 840 or
 841 .ShortOpt m
 842 .BR me .
 843 .
 844 .TP
 845 .B mm
 846 The classical
 847 .I mm
 848 document format; see
 849 .BR \%groff_mm (@MAN7EXT@).
 850 It can be specified on the command line as
 851 .ShortOpt mm
 852 or
 853 .ShortOpt m
 854 .BR mm .
 855 .
 856 .TP
 857 .B ms
 858 The classical
 859 .I ms
 860 document format; see
 861 .BR \%groff_ms (@MAN7EXT@).
 862 It can be specified on the command line as
 863 .ShortOpt ms
 864 or
 865 .ShortOpt m
 866 .BR ms .
 867 .
 868 .TP
 869 .B www
 870 HTML-like macros for inclusion in arbitrary groff documents; see
 871 .BR \%groff_www (@MAN7EXT@).
 872 .
 873 .P
 874 Details on the naming of macro files and their placement can be found
 875 in
 876 .BR \%groff_tmac (@MAN5EXT@).
 877 .
 878 .
 879 .\" --------------------------------------------------------------------
 880 .SS "Programming Language"
 881 .\" --------------------------------------------------------------------
 882 .
 883 General concepts common to all roff programming languages are
 884 described in
 885 .BR roff (@MAN7EXT@).
 886 .
 887 .P
 888 The groff extensions to the classical troff language are documented in
 889 .BR \%groff_diff (@MAN7EXT@).
 890 .
 891 .P
 892 The groff language as a whole is described in the (still incomplete)
 893 .IR "groff info file" ;
 894 a short (but complete) reference can be found in
 895 .BR groff (@MAN7EXT@).
 896 .
 897 .
 898 .\" --------------------------------------------------------------------
 899 .SS Formatters
 900 .\" --------------------------------------------------------------------
 901 .
 902 The central roff formatter within the groff system is
 903 .BR @g@troff (@MAN1EXT@).
 904 It provides the features of both the classical troff and nroff, as
 905 well as the groff extensions.
 906 .
 907 The command line option
 908 .ShortOpt C
 909 switches
 910 .B @g@troff
 911 into
 912 .I "compatibility mode"
 913 which tries to emulate classical roff as much as possible.
 914 .
 915 .P
 916 There is a shell script
 917 .BR @g@nroff (@MAN1EXT@)
 918 that emulates the behavior of classical nroff.
 919 .
 920 It tries to automatically select the proper output encoding, according to
 921 the current locale.
 922 .
 923 .P
 924 The formatter program generates
 925 .IR "intermediate output" ;
 926 see
 927 .BR \%groff_out (@MAN7EXT@).
 928 .
 929 .
 930 .\" --------------------------------------------------------------------
 931 .SS Devices
 932 .\" --------------------------------------------------------------------
 933 .
 934 In roff, the output targets are called
 935 .IR devices .
 936 A device can be a piece of hardware, e.g. a printer, or a software
 937 file format.
 938 .
 939 A device is specified by the option
 940 .ShortOpt T .
 941 The groff devices are as follows.
 942 .
 943 .TP
 944 .B ascii
 945 Text output using the
 946 .BR ascii (7)
 947 character set.
 948 .
 949 .TP
 950 .B cp1047
 951 Text output using the EBCDIC code page IBM cp1047 (e.g. OS/390 Unix).
 952 .
 953 .TP
 954 .B dvi
 955 TeX DVI format.
 956 .
 957 .TP
 958 .B html
 959 HTML output.
 960 .
 961 .TP
 962 .B latin1
 963 Text output using the ISO Latin-1 (ISO 8859-1) character set; see
 964 .BR iso_8859_1 (7).
 965 .
 966 .TP
 967 .B koi8-r
 968 Text output using the Russian KOI8-R character set.
 969 .
 970 .TP
 971 .B lbp
 972 Output for Canon CAPSL printers (LBP-4 and LBP-8 series laser printers).
 973 .
 974 .TP
 975 .B lj4
 976 HP LaserJet4-compatible (or other PCL5-compatible) printers.
 977 .
 978 .TP
 979 .B ps
 980 PostScript output; suitable for printers and previewers like
 981 .BR gv (1).
 982 .
 983 .TP
 984 .B utf8
 985 Text output using the Unicode (ISO 10646) character set with UTF-8
 986 encoding; see
 987 .BR unicode (7).
 988 .
 989 .TP
 990 .B X75
 991 75dpi X Window System output suitable for the previewers
 992 .BR xditview (1x)
 993 and
 994 .BR \%gxditview (@MAN1EXT@).
 995 A variant for a 12\|pt document base font is
 996 .BR X75-12 .
 997 .
 998 .TP
 999 .B X100
1000 100dpi X Window System output suitable for the previewers
1001 .BR xditview (1x)
1002 and
1003 .BR \%gxditview (@MAN1EXT@).
1004 A variant for a 12\|pt document base font is
1005 .BR X100-12 .
1006 .
1007 .P
1008 The postprocessor to be used for a device is specified by the
1009 .B postpro
1010 command in the device description file; see
1011 .BR \%groff_font (@MAN5EXT@).
1012 .
1013 This can be overridden with the
1014 .B \-X
1015 option.
1016 .
1017 .P
1018 The default device is
1019 .BR @DEVICE@ .
1020 .
1021 .
1022 .\" --------------------------------------------------------------------
1023 .SS Postprocessors
1024 .\" --------------------------------------------------------------------
1025 .
1026 groff provides 3\~hardware postprocessors:
1027 .
1028 .TP
1029 .BR \%grolbp (@MAN1EXT@)
1030 for some Canon printers,
1031 .TP
1032 .BR \%grolj4 (@MAN1EXT@)
1033 for printers compatible to the HP LaserJet\~4 and PCL5,
1034 .TP
1035 .BR \%grotty (@MAN1EXT@)
1036 for text output using various encodings, e.g. on text-oriented
1037 terminals or line-printers.
1038 .
1039 .P
1040 Today, most printing or drawing hardware is handled by the operating
1041 system, by device drivers, or by software interfaces, usally accepting
1042 PostScript.
1043 .
1044 Consequently, there isn't an urgent need for more hardware device
1045 postprocessors.
1046 .
1047 .P
1048 The groff software devices for conversion into other document file
1049 formats are
1050 .
1051 .TP
1052 .BR \%grodvi (@MAN1EXT@)
1053 for the DVI format,
1054 .TP
1055 .BR \%grohtml (@MAN1EXT@)
1056 for HTML format,
1057 .TP
1058 .BR grops (@MAN1EXT@)
1059 for PostScript.
1060 .
1061 .P
1062 Combined with the many existing free conversion tools this should
1063 be sufficient to convert a troff document into virtually any existing
1064 data format.
1065 .
1066 .
1067 .\" --------------------------------------------------------------------
1068 .SS Utilities
1069 .\" --------------------------------------------------------------------
1070 .
1071 The following utility programs around groff are available.
1072 .
1073 .TP
1074 .BR \%addftinfo (@MAN1EXT@)
1075 Add information to troff font description files for use with groff.
1076 .
1077 .TP
1078 .BR \%afmtodit (@MAN1EXT@)
1079 Create font description files for PostScript device.
1080 .
1081 .TP
1082 .BR \%groffer (@MAN1EXT@)
1083 General viewer program for groff files and man pages.
1084 .
1085 .TP
1086 .BR \%gxditview (@MAN1EXT@)
1087 The groff X viewer, the GNU version of xditview.
1088 .
1089 .TP
1090 .BR \%hpftodit (@MAN1EXT@)
1091 Create font description files for lj4 device.
1092 .
1093 .TP
1094 .BR \%indxbib (@MAN1EXT@)
1095 Make inverted index for bibliographic databases.
1096 .
1097 .TP
1098 .BR lkbib (@MAN1EXT@)
1099 Search bibliographic databases.
1100 .
1101 .TP
1102 .BR \%lookbib (@MAN1EXT@)
1103 Interactively search bibliographic databases.
1104 .
1105 .TP
1106 .BR \%pfbtops (@MAN1EXT@)
1107 Translate a PostScript font in .pfb format to ASCII.
1108 .
1109 .TP
1110 .BR \%tfmtodit (@MAN1EXT@)
1111 Create font description files for TeX DVI device.
1112 .
1113 .TP
1114 .BR \%xditview (1x)
1115 roff viewer distributed with X window.
1116 .
1117 .
1118 .\" --------------------------------------------------------------------
1119 .SH ENVIRONMENT
1120 .\" --------------------------------------------------------------------
1121 .
1122 Normally, the path separator in the following environment variables is the
1123 colon; this may vary depending on the operating system.
1124 .
1125 For example, DOS and Windows use a semicolon instead.
1126 .
1127 .TP
1128 .EnvVar GROFF_BIN_PATH
1129 This search path, followed by
1130 .EnvVar $PATH ,
1131 will be used for commands that are executed by
1132 .BR groff .
1133 .
1134 If it is not set then the directory where the groff binaries were
1135 installed is prepended to
1136 .EnvVar PATH .
1137 .
1138 .TP
1139 .EnvVar GROFF_COMMAND_PREFIX
1140 When there is a need to run different roff implementations at the same
1141 time
1142 .I groff
1143 provides the facility to prepend a prefix to most of its programs that
1144 could provoke name clashings at run time (default is to have none).
1145 .
1146 Historically, this prefix was the character
1147 .BR g ,
1148 but it can be anything.
1149 .
1150 For example,
1151 .BR gtroff
1152 stood for
1153 .IR groff 's
1154 .BR troff ,
1155 .BR gtbl
1156 for the
1157 .I groff
1158 version of
1159 .BR tbl .
1160 .
1161 By setting
1162 .EnvVar GROFF_COMMAND_PREFIX
1163 to different values, the different roff installations can be
1164 addressed.
1165 .
1166 More exactly, if it is set to prefix
1167 .I xxx
1168 then
1169 .B groff
1170 as a wrapper program will internally call
1171 .IB xxx troff
1172 instead of
1173 .BR troff .
1174 This also applies to the preprocessors
1175 .BR \%eqn ,
1176 .BR \%grn ,
1177 .BR \%pic ,
1178 .BR \%refer ,
1179 .BR \%tbl ,
1180 .BR \%soelim ,
1181 and to the utilities
1182 .B \%@g@indxbib
1183 and
1184 .BR \%@g@lookbib .
1185 .
1186 This feature does not apply to any programs different from the ones
1187 above (most notably
1188 .B groff
1189 itself) since they are unique to the groff package.
1190 .
1191 .
1192 .TP
1193 .EnvVar GROFF_FONT_PATH
1194 A list of directories in which to search for the
1195 .BI dev name
1196 directory in addition to the default ones.
1197 .
1198 See
1199 .BR @g@troff (@MAN1EXT@)
1200 and
1201 .BR \%groff_font (@MAN5EXT@)
1202 for more details.
1203 .
1204 .
1205 .TP
1206 .EnvVar GROFF_TMAC_PATH
1207 A list of directories in which to search for macro files in addition to
1208 the default directories.
1209 .
1210 See
1211 .BR @g@troff (@MAN1EXT@)
1212 and
1213 .BR \%groff_tmac (@MAN5EXT@)
1214 for more details.
1215 .
1216 .
1217 .TP
1218 .EnvVar GROFF_TMPDIR
1219 The directory in which temporary files will be created.
1220 .
1221 If this is not set but the environment variable
1222 .EnvVar TMPDIR
1223 instead, temporary files will be created in the directory
1224 .EnvVar $TMPDIR .
1225 .
1226 Otherwise temporary files will be created in
1227 .BR /tmp .
1228 The
1229 .BR \%@g@refer (@MAN1EXT@),
1230 .BR \%groffer (@MAN1EXT@),
1231 .BR \%grohtml (@MAN1EXT@),
1232 and
1233 .BR grops (@MAN1EXT@)
1234 commands use temporary files.
1235 .
1236 .
1237 .TP
1238 .EnvVar GROFF_TYPESETTER
1239 Preset the default device.
1240 .
1241 If this is not set the
1242 .B @DEVICE@
1243 device is used as default.
1244 .
1245 This device name is overwritten by the option
1246 .ShortOpt T .
1247 .
1248 .
1249 .\" --------------------------------------------------------------------
1250 .SH FILES
1251 .\" --------------------------------------------------------------------
1252 .
1253 There are some directories in which
1254 .I groff
1255 installs all of its data files.
1256 .
1257 Due to different installation habits on different operating systems,
1258 their locations are not absolutely fixed, but their function is
1259 clearly defined and coincides on all systems.
1260 .
1261 .
1262 .\" --------------------------------------------------------------------
1263 .SS "groff Macro Directory"
1264 .\" --------------------------------------------------------------------
1265 .
1266 This contains all information related to macro packages.
1267 .
1268 Note that more than a single directory is searched for those files
1269 as documented in
1270 .BR \%groff_tmac (@MAN5EXT@).
1271 .
1272 For the groff installation corresponding to this document, it is
1273 located at
1274 .IR @MACRODIR@ .
1275 .
1276 The following files contained in the
1277 .I groff macro directory
1278 have a special meaning:
1279 .
1280 .
1281 .TP
1282 .B troffrc
1283 Initialization file for troff.
1284 .
1285 This is interpreted by
1286 .B @g@troff
1287 before reading the macro sets and any input.
1288 .
1289 .
1290 .TP
1291 .B troffrc-end
1292 Final startup file for troff, it is parsed after all macro sets have
1293 been read.
1294 .
1295 .
1296 .TP
1297 .IB name .tmac
1298 .TP+
1299 .BI tmac. name
1300 Macro file for macro package
1301 .IR name .
1302 .
1303 .
1304 .\" --------------------------------------------------------------------
1305 .SS "groff Font Directory"
1306 .\" --------------------------------------------------------------------
1307 .
1308 This contains all information related to output devices.
1309 .
1310 Note that more than a single directory is searched for those files; see
1311 .BR @g@troff (@MAN1EXT@).
1312 .
1313 For the groff installation corresponding to this document, it is
1314 located at
1315 .IR @FONTDIR@ .
1316 .
1317 The following files contained in the
1318 .I groff font directory
1319 have a special meaning:
1320 .
1321 .
1322 .TP
1323 .BI dev name /DESC
1324 Device description file for device
1325 .IR name ,
1326 see
1327 .BR \%groff_font (@MAN5EXT@).
1328 .
1329 .
1330 .TP
1331 .BI dev name / F
1332 Font file for font
1333 .I F
1334 of device
1335 .IR name .
1336 .
1337 .
1338 .\" --------------------------------------------------------------------
1339 .SH EXAMPLES
1340 .\" --------------------------------------------------------------------
1341 .
1342 The following example illustrates the power of the
1343 .B groff
1344 program as a wrapper around
1345 .BR @g@troff .
1346 .
1347 .P
1348 To process a roff file using the preprocessors
1349 .B tbl
1350 and
1351 .B pic
1352 and the
1353 .B me
1354 macro set, classical troff had to be called by
1355 .
1356 .P
1357 .ShellCommand pic foo.me | tbl | troff -me -Tlatin1 | grotty
1358 .
1359 .P
1360 Using
1361 .BR groff ,
1362 this pipe can be shortened to the equivalent command
1363 .P
1364 .ShellCommand groff -p -t -me -T latin1 foo.me
1365 .
1366 .P
1367 An even easier way to call this is to use
1368 .BR grog (@MAN1EXT@)
1369 to guess the preprocessor and macro options and execute the generated
1370 command (by specifying shell left quotes)
1371 .P
1372 .ShellCommand `grog -Tlatin1 foo.me`
1373 .
1374 .P
1375 The simplest way is to view the contents in an automated way by
1376 calling
1377 .
1378 .P
1379 .ShellCommand groffer foo.me
1380 .
1381 .
1382 .\" --------------------------------------------------------------------
1383 .SH BUGS
1384 .\" --------------------------------------------------------------------
1385 .
1386 .P
1387 On EBCDIC hosts (e.g. OS/390 Unix), output devices
1388 .B ascii
1389 and
1390 .B latin1
1391 aren't available.
1392 .
1393 Similarly, output for EBCDIC code page
1394 .B cp1047
1395 is not available on ASCII based operating systems.
1396 .
1397 .P
1398 Report bugs to bug-groff@gnu.org.
1399 .
1400 Include a complete, self-contained example that will allow the bug to
1401 be reproduced, and say which version of groff you are using.
1402 .
1403 .
1404 .\" --------------------------------------------------------------------
1405 .SH AVAILABILITY
1406 .\" --------------------------------------------------------------------
1407 .
1408 Information on how to get groff and related information is available
1409 at the
1410 .URL http://\:www.gnu.org/\:software/\:groff "GNU website" .
1411 The most recent released version of groff is available for anonymous
1412 ftp at the
1413 .URL ftp://ftp.ffii.org/\:pub/\:groff/\:devel/\:groff-current.tar.gz \
1414      "groff development site" .
1415 .
1416 .P
1417 Three groff mailing lists are available:
1418 .TP
1419 .MTO bug-groff@gnu.org
1420 for reporting bugs,
1421 .
1422 .TP
1423 .MTO groff@gnu.org
1424 for general discussion of groff,
1425 .
1426 .TP
1427 .MTO groff-commit@ffii.org
1428 a read-only list showing logs of commitments to the CVS repository.
1429 .
1430 .P
1431 Details on CVS access and much more can be found in the file
1432 .B README
1433 at the top directory of the groff source package.
1434 .
1435 .P
1436 There is a free implementation of the
1437 .B grap
1438 preprocessor, written by
1439 .MTO faber@lunabase.org " Ted Faber" .
1440 .
1441 The actual version can be found at the
1442 .
1443 .URL http://\:www.lunabase.org/\:~faber/\:Vault/\:software/\:grap/ \
1444      "grap website" .
1445 This is the only grap version supported by groff.
1446 .
1447 .
1448 .\" --------------------------------------------------------------------
1449 .SH AUTHORS
1450 .\" --------------------------------------------------------------------
1451 .
1452 Copyright \(co 1989, 2002 Free Software Foundation, Inc.
1453 .
1454 .P
1455 This document is distributed under the terms of the FDL (GNU Free
1456 Documentation License) version 1.1 or later.
1457 .
1458 You should have received a copy of the FDL on your system, it is also
1459 available on-line at the
1460 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
1461 .
1462 .P
1463 This document is based on the original groff man page written by
1464 .MTO jjc@jclark.com "James Clark" .
1465 .
1466 It was rewritten, enhanced, and put under the FDL license by
1467 .MTO bwarken@mayn.de "Bernd Warken" .
1468 .
1469 It is maintained by
1470 .MTO wl@gnu.org "Werner Lemberg" .
1471 .
1472 .P
1473 .I groff
1474 is a GNU free software project.
1475 .
1476 All parts of the
1477 .I groff package
1478 are protected by GNU copyleft licenses.
1479 .
1480 The software files are distributed under the terms of the GNU General
1481 Public License (GPL), while the documentation files mostly use the GNU
1482 Free Documentation License (FDL).
1483 .
1484 .
1485 .\" --------------------------------------------------------------------
1486 .SH "SEE ALSO"
1487 .\" --------------------------------------------------------------------
1488 .
1489 The
1490 .IR "groff info file"
1491 contains all information on the groff system within a single document.
1492 .
1493 Beneath the detailed documentation of all aspects, it provides
1494 examples and background information.
1495 .
1496 See
1497 .BR info (1)
1498 on how to read it.
1499 .
1500 .P
1501 Due to its complex structure, the groff system has many man pages.
1502 .
1503 They can be read with
1504 .BR man (1)
1505 or
1506 .BR \%groffer (@MAN1EXT@).
1507 .
1508 .TP
1509 Introduction, history and further readings:
1510 .BR roff (@MAN7EXT@).
1511 .
1512 .TP
1513 Viewer for groff files:
1514 .BR \%groffer (@MAN1EXT@),
1515 .BR \%gxditview (@MAN1EXT@),
1516 .BR \%xditview (1x).
1517 .
1518 .TP
1519 Wrapper programs for formatters:
1520 .BR \%groff (@MAN1EXT@),
1521 .BR \%grog (@MAN1EXT@).
1522 .
1523 .TP
1524 Roff preprocessors:
1525 .BR \%@g@eqn (@MAN1EXT@),
1526 .BR \%@g@grn (@MAN1EXT@),
1527 .BR \%@g@pic (@MAN1EXT@),
1528 .BR \%@g@refer (@MAN1EXT@),
1529 .BR \%@g@soelim (@MAN1EXT@),
1530 .BR \%@g@tbl (@MAN1EXT@),
1531 .BR grap (1).
1532 .
1533 .TP
1534 Roff language with the groff extensions:
1535 .BR \%groff (@MAN7EXT@),
1536 .BR \%groff_char (@MAN7EXT@),
1537 .BR \%groff_diff (@MAN7EXT@),
1538 .BR \%groff_font (@MAN5EXT@).
1539 .
1540 .TP
1541 Roff formatter programs:
1542 .BR \%@g@nroff (@MAN1EXT@),
1543 .BR \%@g@troff (@MAN1EXT@),
1544 .BR ditroff (@MAN7EXT@).
1545 .
1546 .TP
1547 The intermediate output language:
1548 .BR \%groff_out (@MAN7EXT@).
1549 .
1550 .TP
1551 Postprocessors for the output devices:
1552 .BR \%grodvi (@MAN1EXT@),
1553 .BR \%grohtml (@MAN1EXT@),
1554 .BR \%grolbp (@MAN1EXT@),
1555 .BR \%grolj4 (@MAN1EXT@),
1556 .BR \%grops (@MAN1EXT@),
1557 .BR \%grotty (@MAN1EXT@).
1558 .
1559 .TP
1560 Groff macro packages and macro-specific utilities:
1561 .BR \%groff_tmac (@MAN5EXT@),
1562 .BR \%groff_man (@MAN7EXT@),
1563 .BR \%groff_mdoc (@MAN7EXT@),
1564 .BR \%groff_me (@MAN7EXT@),
1565 .BR \%groff_mm (@MAN7EXT@),
1566 .BR \%groff_mmse (@MAN7EXT@),
1567 .BR \%groff_mom (@MAN7EXT@),
1568 .BR \%groff_ms (@MAN7EXT@),
1569 .BR \%groff_www (@MAN7EXT@),
1570 .BR \%mmroff (@MAN7EXT@).
1571 .
1572 .TP
1573 The following utilities are available:
1574 .BR \%addftinfo (@MAN1EXT@),
1575 .BR \%afmtodit (@MAN1EXT@),
1576 .BR \%eqn2graph (@MAN1EXT@),
1577 .BR \%groffer (@MAN1EXT@),
1578 .BR \%gxditview (@MAN1EXT@),
1579 .BR \%hpftodit (@MAN1EXT@),
1580 .BR \%@g@indxbib (@MAN1EXT@),
1581 .BR \%@g@lookbib (@MAN1EXT@),
1582 .BR \%pfbtops (@MAN1EXT@),
1583 .BR \%pic2graph (@MAN1EXT@),
1584 .BR \%tfmtodit (@MAN1EXT@).
1585 .
1586 .
1587 .\" --------------------------------------------------------------------
1588 .\" Emacs setup
1589 .\" --------------------------------------------------------------------
1590 .
1591 .\" Local Variables:
1592 .\" mode: nroff
1593 .\" End: