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

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