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