groff: Groff Options

 
 2.1 Options
 ===========
 
 'groff' normally runs the 'gtroff' program and a postprocessor
 appropriate for the selected device.  The default device is 'ps' (but it
 can be changed when 'groff' is configured and built).  It can optionally
 preprocess with any of 'gpic', 'geqn', 'gtbl', 'ggrn', 'grap', 'gchem',
 'grefer', 'gsoelim', or 'preconv'.
 
    This section documents only options to the 'groff' front end.  Many
 of the arguments to 'groff' are passed on to 'gtroff'; therefore, those
 are also included.  Arguments to preprocessors and output drivers can be
 found in the man pages 'gpic(1)', 'geqn(1)', 'gtbl(1)', 'ggrn(1)',
 'grefer(1)', 'gchem(1)', 'gsoelim(1)', 'preconv(1)', 'grotty(1)',
 'grops(1)', 'gropdf(1)', 'grohtml(1)', 'grodvi(1)', 'grolj4(1)',
 'grolbp(1)', and 'gxditview(1)'.
 
    The command-line format for 'groff' is:
 
      groff [ -abceghijklpstvzCEGNRSUVXZ ] [ -dCS ] [ -DARG ]
            [ -fFAM ] [ -FDIR ] [ -IDIR ] [ -KARG ]
            [ -LARG ] [ -mNAME ] [ -MDIR ] [ -nNUM ]
            [ -oLIST ] [ -PARG ] [ -rCN ] [ -TDEV ]
            [ -wNAME ] [ -WNAME ] [ FILES... ]
 
    The command-line format for 'gtroff' is as follows.
 
      gtroff [ -abcivzCERU ] [ -dCS ] [ -fFAM ] [ -FDIR ]
             [ -mNAME ] [ -MDIR ] [ -nNUM ] [ -oLIST ]
             [ -rCN ] [ -TNAME ] [ -wNAME ] [ -WNAME ]
             [ FILES... ]
 
 Obviously, many of the options to 'groff' are actually passed on to
 'gtroff'.
 
    Options without an argument can be grouped behind a single '-'.  A
 filename of '-' denotes the standard input.  Whitespace is permitted
 between an option and its argument.
 
    The 'grog' command can be used to guess the correct 'groff' command
 to format a file.  See its man page 'grog(1)'; type 'man grog' at the
 command line to view it.
 
    'groff''s command-line options are as follows.
 
 '-a'
      Generate a plain text approximation of the typeset output.  The
      read-only register '.A' is set to 1.  ⇒Built-in Registers.
      This option produces a sort of abstract preview of the formatted
      output.
 
         * Page breaks are marked by a phrase in angle brackets; for
           example, '<beginning of page>'.
 
         * Lines are broken where they would be in the formatted output.
 
         * A horizontal motion of any size is represented as one space.
           Adjacent horizontal motions are not combined.  Inter-sentence
           space nodes (those arising from the second argument to the
           'ss' request) are not represented.
 
         * Vertical motions are not represented.
 
         * Special characters are rendered in angle brackets; for
           example, the default soft hyphen character appears as '<hy>'.
 
      The above description should not be considered a specification; the
      details of '-a' output are subject to change.
 
 '-b'
      Write a backtrace reporting the state of 'gtroff''s input parser to
      the standard error stream with each diagnostic message.  The line
      numbers given in the backtrace might not always be correct, because
      'gtroff''s idea of line numbers can be confused by requests that
      append to macros.
 
 '-c'
      Start with color output disabled.
 
 '-C'
      Enable AT&T 'troff' compatibility mode; implies '-c'.  ⇒
      Implementation Differences, for the list of incompatibilities
      between 'groff' and AT&T 'troff'.
 
 '-dCTEXT'
 '-dSTRING=TEXT'
      Define 'roff' string C or STRING as T or TEXT.  C must be one
      character; STRING can be of arbitrary length.  Such string
      assignments happen before any macro file is loaded, including the
      startup file.  Due to 'getopt_long' limitations, C cannot be, and
      STRING cannot contain, an equals sign, even though that is a valid
      character in a 'roff' identifier.
 
 '-DENC'
      Set fallback input encoding used by 'preconv' to ENC; implies '-k'.
 
 '-e'
      Run 'geqn' preprocessor.
 
 '-E'
      Inhibit 'gtroff' error messages.  This option does _not_ suppress
      messages sent to the standard error stream by documents or macro
      packages using 'tm' or related requests.
 
 '-fFAM'
      Use FAM as the default font family.  ⇒Font Families.
 
 '-FDIR'
      Search in directory 'DIR' for the selected output device's
      directory of device and font description files.  See the
      description of 'GROFF_FONT_PATH' in ⇒Environment below for
      the default search locations and ordering.
 
 '-g'
      Run 'ggrn' preprocessor.
 
 '-G'
      Run 'grap' preprocessor; implies '-p'.
 
 '-h'
      Display a usage message and exit.
 
 '-i'
      Read the standard input after all the named input files have been
      processed.
 
 '-IDIR'
      Search the directory DIR for files named in several contexts;
      implies '-g' and '-s'.
 
         * 'gsoelim' replaces 'so' requests with the contents of their
           file name arguments.
 
         * 'gtroff' searches for files named as operands in its command
           line and as arguments to 'psbb', 'so', and 'soquiet' requests.
 
         * Output drivers may search for files; for instance, 'grops'
           looks for files named in '\X'ps: import ...'', '\X'ps: file
           ...'', and '\X'pdf: pdfpic ...'' device control escape
           sequences.
 
      This option may be specified more than once; the directories are
      searched in the order specified.  If you want to search the current
      directory before others, add '-I .' at the desired place.  The
      current working directory is otherwise searched last.  '-I' works
      similarly to, and is named for, the "include" option of Unix C
      compilers.
 
      '-I' options are passed to 'gsoelim', 'gtroff', and output drivers;
      with the flag letter changed to '-M', they are also passed to
      'ggrn'.
 
 '-j'
      Run 'gchem' preprocessor.  Implies '-p'.
 
 '-k'
      Run 'preconv' preprocessor.  Refer to its man page for its behavior
      if neither of 'groff''s '-K' or '-D' options is also specified.
 
 '-KENC'
      Set input encoding used by 'preconv' to ENC; implies '-k'.
 
 '-l'
      Send the output to a spooler for printing.  The 'print' directive
      in the device description file specifies the default command to be
      used; see ⇒Device and Font Description Files.  See options
      '-L' and '-X'.
 
 '-LARG'
      Pass ARG to the print spooler program.  If multiple ARGs are
      required, pass each with a separate '-L' option.  'groff' does not
      prefix an option dash to ARG before passing it to the spooler
      program.
 
 '-mNAME'
      Process the file 'NAME.tmac' prior to any input files.  If not
      found, 'tmac.NAME' is attempted.  NAME (in both arrangements) is
      presumed to be a macro file; see the description of
      'GROFF_TMAC_PATH' in ⇒Environment below for the default
      search locations and ordering.  This option and its argument are
      also passed to 'geqn', 'grap', and 'ggrn'.
 
 '-MDIR'
      Search directory 'DIR' for macro files; see the description of
      'GROFF_TMAC_PATH' in ⇒Environment below for the default
      search locations and ordering.  This option and its argument are
      also passed to 'geqn', 'grap', and 'ggrn'.
 
 '-nNUM'
      Number the first page NUM.
 
 '-N'
      Prohibit newlines between 'eqn' delimiters: pass '-N' to 'geqn'.
 
 '-oLIST'
      Output only pages in LIST, which is a comma-separated list of page
      ranges; 'N' means page N, 'M-N' means every page between M and N,
      '-N' means every page up to N, 'N-' means every page from N on.
      'gtroff' stops processing and exits after formatting the last page
      enumerated in LIST.
 
 '-p'
      Run 'gpic' preprocessor.
 
 '-PARG'
      Pass ARG to the postprocessor.  If multiple ARGs are required, pass
      each with a separate '-P' option.  'groff' does not prefix an
      option dash to ARG before passing it to the postprocessor.
 
 '-rCNUMERIC-EXPRESSION'
 '-rREGISTER=EXPR'
      Set 'roff' register C or REGISTER to the value NUMERIC-EXPRESSION
      (⇒Numeric Expressions).  C must be one character; REGISTER
      can be of arbitrary length.  Such register assignments happen
      before any macro file is loaded, including the startup file.  Due
      to 'getopt_long' limitations, C cannot be, and REGISTER cannot
      contain, an equals sign, even though that is a valid character in a
      'roff' identifier.
 
 '-R'
      Run 'grefer' preprocessor.  No mechanism is provided for passing
      arguments to 'grefer' because most 'grefer' options have equivalent
      language elements that can be specified within the document.
 
      'gtroff' also accepts a '-R' option, which is not accessible via
      'groff'.  This option prevents the loading of the 'troffrc' and
      'troffrc-end' files.
 
 '-s'
      Run 'gsoelim' preprocessor.
 
 '-S'
      Operate in "safer" mode; see '-U' below for its opposite.  For
      security reasons, safer mode is enabled by default.
 
 '-t'
      Run 'gtbl' preprocessor.
 
 '-TDEV'
      Direct 'gtroff' to format the input for the output device DEV.
      'groff' then calls an output driver to convert 'gtroff''s output to
      a form appropriate for DEV.  The following output devices are
      available.
 
      'ps'
           For PostScript printers and previewers.
 
      'pdf'
           For PDF viewers or printers.
 
      'dvi'
           For TeX DVI format.
 
      'X75'
           For a 75dpi X11 previewer.
 
      'X75-12'
           For a 75dpi X11 previewer with a 12-point base font in the
           document.
 
      'X100'
           For a 100dpi X11 previewer.
 
      'X100-12'
           For a 100dpi X11 previewer with a 12-point base font in the
           document.
 
      'ascii'
           For typewriter-like devices using the (7-bit) ASCII (ISO 646)
           character set.
 
      'latin1'
           For typewriter-like devices that support the Latin-1
           (ISO 8859-1) character set.
 
      'utf8'
           For typewriter-like devices that use the Unicode (ISO 10646)
           character set with UTF-8 encoding.
 
      'cp1047'
           For typewriter-like devices that use the EBCDIC encoding IBM
           code page 1047.
 
      'lj4'
           For HP LaserJet4-compatible (or other PCL5-compatible)
           printers.
 
      'lbp'
           For Canon CaPSL printers (LBP-4 and LBP-8 series laser
           printers).
 
      'html'
      'xhtml'
           To produce HTML and XHTML output, respectively.  This driver
           consists of two parts, a preprocessor ('pre-grohtml') and a
           postprocessor ('post-grohtml').
 
      The predefined GNU 'troff' string '.T' contains the name of the
      output device; the read-only register '.T' is set to 1 if this
      option is used (which is always true if 'groff' is used to call GNU
      'troff').  ⇒Built-in Registers.
 
      The postprocessor to be used for a device is specified by the
      'postpro' command in the device description file.  (⇒Device
      and Font Description Files.)  This can be overridden with the
      '-X' option.
 
 '-U'
      Operate in "unsafe mode", which enables the 'open', 'opena', 'pi',
      'pso', and 'sy' requests.  These requests are disabled by default
      because they allow an untrusted input document to write to
      arbitrary file names and run arbitrary commands.  This option also
      adds the current directory to the macro package search path; see
      the '-m' option above.  '-U' is passed to 'gpic' and 'gtroff'.
 
 '-v'
      Write version information for 'groff' and all programs run by it to
      the standard output stream; that is, the given command line is
      processed in the usual way, passing '-v' to the formatter and any
      pre- or postprocessors invoked.
 
 '-V'
      Output the pipeline that would be run by 'groff' (as a wrapper
      program) to the standard output stream, but do not execute it.  If
      given more than once, the pipeline is both written to the standard
      error stream and run.
 
 '-wCATEGORY'
      Enable warnings in CATEGORY.  Categories are listed in ⇒
      Warnings.
 
 '-WCATEGORY'
      Inhibit warnings in CATEGORY.  Categories are listed in ⇒
      Warnings.
 
 '-X'
      Use 'gxditview' instead of the usual postprocessor to (pre)view a
      document on an X11 display.  Combining this option with '-Tps' uses
      the font metrics of the PostScript device, whereas the '-TX75' and
      '-TX100' options use the metrics of X11 fonts.
 
 '-z'
      Suppress formatted output from 'gtroff'.
 
 '-Z'
      Disable postprocessing.  'gtroff' output will appear on the
      standard output stream (unless suppressed with '-z'; see ⇒
      gtroff Output for a description of this format.