groffer

GROFFER(1)                  General Commands Manual                 GROFFER(1)



NAME
       groffer - display groff files and man pages on X and tty

SYNOPSIS
       groffer [option...]  [--] [filespec...]
       groffer --apropos|--apropos-data|--apropos-devel|--apropos-progs name
       groffer -h|--help
       groffer -v|--version

DESCRIPTION
       The groffer program is the easiest way to use groff(1).  It can display
       arbitrary documents written in the groff(7) language or other roff(7)
       languages that are compatible to the original troff language.  The
       groffer program also includes many of the features for finding and
       displaying the UNIX manual pages (man pages), such that it can be used
       as a replacement for a man(1) program.  Moreover, compressed files that
       can be handled by gzip(1) or bzip2(1) are decompressed on-the-fly.

       The normal usage is quite simple by supplying a file name or name of a
       man page without further options.  But the option handling has many
       possibilities for creating special behaviors.  This can be done in
       configuration files, with the shell environment variable $GROFFER_OPT,
       or on the command line.

       The output can be generated and viewed in several different ways
       available for groff.  This includes the groff native X viewer
       gxditview(1), each Postcript or dvi display program, a web browser by
       generating html in www-mode, or several text modes in text terminals.

       Most of the options that must be named when running groff directly are
       determined automatically for groffer, due to the internal usage of the
       grog(1) program.  But all parts can also be controlled manually by
       arguments.

       Several file names can be specified on the command line arguments.
       They are transformed into a single document in the normal way of groff.

OPTION OVERVIEW
       breaking options

              [--apropos name] [--apropos-data name] [--apropos-devel name]
              [--apropos-progs name] [-h|--help] [-v|--version]

       groffer mode options

              [--auto] [--default] [--default-modes mode1,mode2,...]  [--dvi]
              [--dvi-viewer prog] [--groff] [--html] [--html-viewer prog]
              [--man] [--mode display_mode] [--no-man] [--pdf] [--pdf-viewer
              prog] [--ps] [--ps-viewer prog] [--text] [--tty] [--tty-viewer
              prog] [--www] [--www-viewer prog] [--x|--X] [--x-viewer|--X-
              viewer prog]

       development options

              [--debug] [--shell]

       options related to groff

              [-P|--postproc-arg opt_or_arg] [-Q|--source] [-T|--device
              device] [-Z|--intermediate-output|--ditroff]

              All further groff short options are accepted.

       X Window toolkit options

              [--bd pixels] [--bg|--background color] [--bw pixels] [--display
              X-display] [--fg|--foreground color] [--ft|--font font_name]
              [--geometry size_pos] [--resolution value] [--rv] [--title
              string] [--xrm X_resource]

       options from man

              [--all] [--ascii] [--ditroff] [--extension suffix] [--locale
              language] [--local-file] [--manpath dir1:dir2:...]  [--pager
              program] [--sections sec1:sec2:...]  [--systems sys1,sys2,...]
              [--troff-device device] [--whatis]

              Further long options of GNU man are accepted as well.

       filespec argument

              No filespec parameters means standard input.

              -         stands for standard input (can occur several times).

              filename  the path name of an existing file.

              man:name(section)
              name(section)
                        search the man page name in man section section.

              man:name.s
              name.s    if s is a character in [1-9on], search for a man page
                        name in man section s.

              man:name  man page in the lowest man section that has name.

              s name    if s is a character in [1-9on], search for a man page
                        name in man section s.

              name      if name is not an existing file search for the
                        man page name in the lowest man section.

OPTION DETAILS
       The groffer program can usually be run with very few options.  But for
       special purposes, it supports many options.  These can be classified in
       5 option classes.

       All short options of groffer are compatible with the short options of
       groff(1).  All long options of groffer are compatible with the long
       options of man(1).

   groffer breaking Options
       As soon as one of these options is found on the command line it is
       executed, printed to standard output, and the running groffer is
       terminated thereafter.  All other arguments are ignored.

       --apropos name
              Start the apropos(1) command for searching within man page
              descriptions.  That slightly differs from the strange behavior
              of the --apropos program of man(1), which has no argument of its
              own, but takes the file arguments instead.  Practically both
              concepts are compatible.

       --apropos-data name
              Show only the apropos(1) descriptions for data documents, in the
              man(7) sections 4, 5, and 7.

       --apropos-devel name
              Show only the apropos(1) descriptions for development documents,
              in the man(7) sections 2, 3, and 9.

       --apropos-progs name
              Show only the apropos(1) descriptions for documents on programs,
              in the man(7) sections 1, 6, and 8.

       -h | --help
              Print a helping information with a short explanation of option
              sto standard output.

       -v | --version
              Print version information to standard output.

   groffer Mode Options
       The display mode and the viewer programs are determined by these
       options.  If none of these mode and viewer options is specified groffer
       tries to find a suitable display mode automatically.

       --auto Equivalent to --mode=auto.

       --default
              Reset all configuration from previously processed command line
              options to the default values.  This is useful to wipe out all
              former options of the configuration, in $GROFFER_OPT, and
              restart option processing using only the rest of the command
              line.

       --default-modes mode1,mode2,...
              Set the sequence of modes for auto mode to the comma separated
              list given in the argument.  See --mode for details on modes.
              Display in the default manner; actually, this means to try the
              modes x, ps, and tty in this sequence.

       --dvi  Equivalent to --mode=dvi.

       --dvi-viewer prog
              Set the viewer program for dvi mode.  This can be a file name or
              a program to be searched in $PATH.  Known dvi viewers inlude
              xdvi(1) and dvilx(1) In each case, arguments can be provided
              additionally.

       --groff
              Equivalent to --mode=groff.

       --html Equivalent to --mode=html.

       --html-viewer
              Equivalent to --www-viewer.

       --mode value
              Set the display mode.  The following mode values are recognized:

              auto   Select the automatic determination of the display mode.
                     The sequence of modes that are tried can be set with the
                     --default-modes option.  Useful for restoring the default
                     mode when a different mode was specified before.

              dvi    Display formatted input in a dvi viewer program.  By
                     default, the formatted input is displayed with the
                     xdvi(1) program.  --dvi.

              groff  After the file determination, switch groffer to process
                     the input like groff(1) would do .  This disables the
                     groffer viewing features.

              html   Translate the input into html format and display the
                     result in a web browser program.  By default, the
                     existence of a sequence of standard web browsers is
                     tested, starting with konqueror(1) and mozilla(1).  The
                     text html viewer is lynx(1).

              pdf    Display formatted input in a PDF (Portable Document
                     Format) viewer program.  By default, the input is
                     formatted by groff using the Postscript device, then it
                     is transformed into the PDF file format using gs(1), and
                     finally displayed either with the xpdf(1) or the
                     acroread(1) program.  PDF has a big advantage because the
                     text is displayed graphically and is searchable as well.
                     But as the transformation takes a considerable amount of
                     time, this mode is not suitable as a default device for
                     the auto mode.

              ps     Display formatted input in a Postscript viewer program.
                     By default, the formatted input is displayed with the
                     ghostview(1) program.

              text   Format in a groff text mode and write the result to
                     standard output without a pager or viewer program.  The
                     text device, latin1 by default, can be chosen with option
                     -T.

              tty    Format in a groff text mode and write the result to
                     standard output using a text pager program, even when in
                     X Window.

              www    Equivalent to --www.

              X      Display formatted input in a native roff viewer.  By
                     default, the formatted input is displayed with the
                     gxditview(1) program, being distributed together with
                     groff, or with xditview(1), which is distributed as a
                     standard X tool.

              x      Equivalent to --mode=X.

              The following modes do not use the groffer viewing features.
              They are only interesting for advanced applications.

              groff  Generate device output with plain groff without using the
                     special viewing features of groffer.  If no device was
                     specified by option -T the groff default ps is assumed.

              source Display the source code of the input without formatting;
                     equivalent to -Q.

       --pdf  Equivalent to --mode=pdf.

       --pdf-viewer prog
              Set the viewer program for pdf mode.  This can be a file name or
              a program to be searched in $PATH.  In each case, arguments can
              be provided additionally.

       --ps   Equivalent to --mode=ps.

       --ps-viewer prog
              Set the viewer program for ps mode.  This can be a file name or
              a program to be searched in $PATH.  Common Postscript viewers
              inlude gv(1), ghostview(1), and gs(1), In each case, arguments
              can be provided additionally.

       --text Equivalent to --mode=text.

       --tty  Equivalent to --mode=tty.

       --tty-viewer
              Choose tty display mode, that means displaying in a text pager
              even when in X; eqivalent to --mode=tty.

       --www  Equivalent to --mode=www.

       --www-viewer prog
              Set the web browser program for viewing in www mode.  Each
              program that accepts html input and allows the
              file://localhost/dir/file syntax on the command line is suitable
              as viewer program; it can be the path name of an executable file
              or a program in $PATH.  In each case, arguments can be provided
              additionally.

       -X | --X | --x
              Equivalent to --mode=X.

       --X-viewer | --x-viewer prog
              Set the viewer program for x mode.  Suitable viewer programs are
              gxditview(1) and xditview(1).  But the argument can be any
              executable file or a program in $PATH.  In each case, arguments
              can be provided additionally.

       --     Signals the end of option processing; all remaining arguments
              are interpreted as filespec parameters.

       Besides these, groffer accepts all arguments that are valid for the
       groff(1) program.  All non-groffer options are sent unmodified via grog
       to groff.  Postprocessors, macro packages, compatibility with classical
       troff, and much more can be manually specified.

Options for Development
       --debug
              Print debugging information for development only.  Actually, a
              function call stack is printed if an error occurs.

       --shell shell_program
              Specify the shell under which the groffer script should be run.
              The script first tests whether this option is set (either by
              configuration, within $GROFF_OPT or as a command line option);
              if so, the script is rerun under the shell program specified
              with the option argument.

       -Q | --source
              Output the roff source code of the input files without further
              processing.  This is the equivalent --mode=source.

       Other useful debugging options are the groff options -V and -Z and
       option --mode=groff.

Options related to groff
       All short options of groffer are compatible with the short options of
       groff(1).  The following of groff options have either an additional
       special meaning within groffer or make sense for normal usage.

       Because of the special outputting behavior of the groff options -V and
       -Z groffer was designed to be switched into groff mode by these; the
       groffer viewing features are disabled there.  The other groff options
       do not switch the mode, but allow to customize the formatting process.

       -a     This generates an ascii approximation of output in text modes.
              That could be important when the text pager has problems with
              control sequences.

       -m file
              Add file as a groff macro file.  This is useful in case it
              cannot be recognized automatically.

       -P opt_or_arg
              Send the argument opt_or_arg as an option or option argument to
              the actual groff postprocessor.

       -T | --device devname
              This option determines groff's output device.  The most
              important devices are the text output devices for referring to
              the different character sets, such as ascii, utf8, latin1, and
              others.  Each of these arguments switches groffer into a text
              mode using this device, to mode tty if the actual mode is not a
              text mode.  The following devname arguments are mapped to the
              corresponding groffer --mode=devname option: dvi, html, and ps.
              All X* arguments are mapped to mode X.  Each other devname
              argument switches to mode groff using this device.

       -V     Switch into groff mode and show only the groff calling pipe
              without formatting the input.  This an advanced option from
              groff(1), only useful for debugging.

       -X     was made equivalent to --mode=x; this slightly enhances the
              facility of groff's option.

       -Z | --intermediate-output | --ditroff
              Switch into groff mode and format the input with groff
              intermediate output without postprocessing; see groff_out(1).
              This is equivalent to option --ditroff of man, which can be used
              as well.

       All other groff options are supported by groffer, but they are just
       transparently transferred to groff without any intervention.  The
       options that are not explicitly handled by groffer are transparently
       passed to groff.  Therefore these transparent options are not
       documented here, but in groff(1).  Due to the automatism in groffer,
       none of these groff options should be needed, except for advanced
       usage.

   X Window toolkit Options
       The following long options were adapted from the corresponding X
       Toolkit options.  groffer will pass them to the actual viewer program
       if it is an X Window program.  Otherwise these options are ignored.

       Unfortunately these options use the old style of a single minus for
       long options.  For groffer that was changed to the standard with using
       a double minus for long options, for example, groffer uses the option
       --font for the X option -font.

       See X(1), X(7), and the documentation on the X toolkit options for more
       details on these options and their arguments.

       --background color
              Set the background color of the viewer window.

       --bd pixels
              Specifies the color of the border surrounding the viewer window.

       --bg color
              This is equivalent to --background.

       --bw pixels
              Specifies the width in pixels of the border surrounding the
              viewer window.

       --display X-display
              Set the X display on which the viewer program shall be started,
              see the X Window documentation for the syntax of the argument.

       --foreground color
              Set the foreground color of the viewer window.

       --fg color
              This is equivalent to -foreground.

       --font font_name
              Set the font used by the viewer window.  The argument is an X
              font name.

       --ft font_name
              This is equivalent to --ft.

       --geometry size_pos
              Set the geometry of the display window, that means its size and
              its starting position.  See X(7) for the syntax of the argument.

       --resolution value
              Set X resolution in dpi (dots per inch) in some viewer programs.
              The only supported dpi values are 75 and 100.  Actually, the
              default resolution for groffer is set to 75.

       --rv   Reverse foreground and background color of the viewer window.

       --title 'some text'
              Set the title for the viewer window.

       --xrm 'resource'
              Set X resource.

   Options from man
       The long options of groffer were synchronized with the long options of
       GNUman.  All long options of GNU man are recognized, but not all of
       these options are important to groffer, so most of them are just
       ignored.

       The following two options were added by groffer for choosing whether
       the file name arguments are interpreted as names for local files or as
       a search pattern for man pages.  The default is looking up for local
       files.

       --man  Check the non-option command line arguments (filespecs) first on
              being man pages, then whether they represent an existing file.
              By default, a filespec is first tested whether it is an existing
              file.

       --no-man | --local-file
              Do not check for man pages.  --local-file is the corresponding
              man option.

       In the following, the man options that have a special meaning for
       groffer are documented.

       The full set of long and short options of the GNU man program can be
       passed via the environment variable $MANOPT; see man(1) if your system
       has GNU man installed.

       --all  In searching man pages, retrieve all suitable documents instead
              of only one.

       -7 | --ascii
              In text modes, display ASCII translation of special characters.

       --ditroff
              Eqivalent to groffer -Z.

       --extension suffix
              Restrict man page search to file names that have suffix appended
              to their section element.  For example, in the file name
              /usr/share/man/man3/terminfo.3ncurses.gz the man page extension
              is ncurses.

       --locale language
              Set the language for man pages.  This has the same effect, but
              overwrites $LANG

       --location
              Print the location of the retrieved files to standard error.

       --no-location
              Do not display the location of retrieved files; this resets a
              former call to --location.  This was added by groffer.

       --manpath 'dir1:dir2:...'
              Use the specified search path for retrieving man pages instead
              of the program defaults.  If the argument is set to the empty
              string "" the search for man page is disabled.

       --pager
              Set the pager program in tty mode; default is less.  This is
              equivalent to --tty-viewer.

       --sections 'sec1:sec2:...'
              Restrict searching for man pages to the given sections, a colon-
              separated list.

       --systems 'sys1,sys2,...'
              Search for man pages for the given operating systems; the
              argument systems is a comma-separated list.

       --whatis
              Instead of displaying the content, get the one-liner description
              from the retrieved man page files — or say that it is not a
              man page.

       --where
              Eqivalent to --location.

       Additionally, the following short option of man is supported as well.

   Filespec Arguments
       A filespec parameter is an argument meaning an input source, such as a
       file name or template for searching man pages.  These input sources are
       collected and composed into a single output file such as groff does.

       The strange POSIX behavior that maps all arguments behind the first
       non-option argument into filespec arguments is ignored.  The GNU
       behavior to recognize options even when mixed with filespec arguments
       is used througout.  But, as usual, the double minus argument -- still
       takes all following arguments as filespecs.

       Each filespec parameters can have one of the following forms.

       No filespec parameters means that groffer waits for standard input.
       The minus option - stands for standard input, too, but can occur
       several times.  Next filespec is tested whether it is the path name of
       an existing file.  Otherwise it is assumed as a searching pattern for a
       man page.

       On each system, the man pages are sorted according to their content
       into several sections.  The classical man sections have a single-
       character name, either are a digit from 1 to 9 or one of the characters
       n or o.  In the following, a stand-alone character s means this scheme.

       The internal precedence of man for searching man pages with the same
       name within several sections goes according to the classical single-
       character sequence.  On some systems, this single character can be
       extended by a following string.  But the special groffer man page
       facility is based on the classical single character sections.

       man:name(section) and name(section) search the man page name in
       man section section, where section can be any string, but it must exist
       in the man system.

       Next some patterns based on the classical man sections were
       constructed.  man:name.s and name.s search for a man page name in
       man section s if s is a classical man section mentioned above.
       Otherwise search for a man page named name.s in the lowest man section.

       Now man:name searches for a man page in the lowest man section that has
       a document called name.

       The pattern s name originates from a strange argument parsing of the
       man program.  If s is a classical man section interpret it as a search
       for a man page called name in man section s, otherwise interpret s as a
       file argument and name as another filespec argument.

       We are left with the argument name which is not an existing file.  So
       this searches for the man page called name in the lowest man section
       that has a document for this name.

       Several file name arguments can be supplied.  They are mixed by groff
       into a single document.  Note that the set of option arguments must fit
       to all of these file arguments.  So they should have at least the same
       style of the groff language.

OUTPUT MODES
       By default, the groffer program collects all input into a single file,
       formats it with the groff program for a certain device, and then
       chooses a suitable viewer program.  The device and viewer process in
       groffer is called a mode.  The mode and viewer of a running groffer
       program is selected automatically, but the user can also choose it with
       options.  The modes are selected by option the arguments of
       --mode=anymode.  Additionally, each of this argument can be specified
       as an option of its own, such as --anymode.  Most of these modes have a
       viewer program, which can be chosen by an option that is constructed
       like --anymode-viewer.

       Several different modes are offered, graphical X modes, text modes, and
       some direct groff modes for debugging and development.

       By default, groffer first tries whether x mode is possible, then ps
       mode, and finally tty mode.  This mode testing sequence for auto mode
       can be changed by specifying a comma separated list of modes with the
       option --default-modes.

       The searching for man pages and the decompression of the input are
       active in every mode.

   Graphical Display Modes
       The graphical display modes work only in the X Window environment (or
       similar implementations within other windowing environments).  The
       environment variable $DISPLAY and the option --display are used for
       specifying the X display to be used.  If neither is given, groffer
       assumes that no X and changes to one text mode.  You can change this
       automatic behavior by the option --default-modes.

       Known viewers for the graphical display modes and their standard X
       Window viewer progams are

       · X Window roff viewers such as gxditview(1) or xditview(1) (in x or X
         mode),

       · in a Postscript viewer (ps mode),

       · in a dvi viewer program (dvi mode),

       · in a PDF viewer (pdf mode),

       · in a web browser (html or www mode),

       The pdf mode has a major advantage — it is the only graphical diplay
       mode that allows to search for text within the viewer; this can be a
       really important feature.  Unfortunately, it takes some time to
       transform the input into the PDF format, so it was not chosen as the
       major mode.

       These graphical viewers can be customized by options of the X Window
       Toolkit.  But the groffer options use a leading double minus instead of
       the single minus used by the X Window Toolkit.

   Text mode
       There are to modes for text output, mode text for plain output without
       a pager and mode tty for a text output on a text terminal using some
       pager program.

       If the variable $DISPLAY is not set or empty, groffer assumes that it
       should use tty mode.

       In the actual implementation, the groff output device latin1 is chosen
       for text modes.  This can be changed by specifying option -T or
       --device.

       The pager to be used can be specified by one of the options --pager and
       --tty-viewer, or by the environment variable $PAGER.  If all of this is
       not used the less(1) program with the option -r for correctly
       displaying control sequences is used as the default pager.

   Special Modes for Debugging and Development
       These modes use the groffer file determination and decompression.  This
       is combined into a single input file that is fed directly into groff
       with different strategy without the groffer viewing facilities.  These
       modes are regarded as advanced, they are useful for debugging and
       development purposes.

       The source mode with just displays the generated input.  The groff mode
       passes the input to groff using only some suitable options provided to
       groffer.  This enables the user to save the generated output into a
       file or pipe it into another program.

       In groff mode, the option -Z disables post-processing, thus producing
       the groff intermediate output.  In this mode, the input is formatted,
       but not postprocessed; see groff_out(5) for details.

       All groff short options are supported by groffer.

MAN PAGE SEARCHING
       The default behavior of groffer is to first test whether a file
       parameter represents a local file; if it is not an existing file name,
       it is assumed to represent a name of a man page.  This behavior can be
       modified by the following options.

       --man  forces to interpret all file parameters as filespecs for
              searching man pages.

       --no-man
       --local-file
              disable the man searching; so only local files are displayed.

       If neither a local file nor a man page was retrieved for some file
       parameter a warning is issued on standard error, but processing is
       continued.

       The groffer program provides a search facility for man pages.  All long
       options, all environment variables, and most of the functionality of
       the GNU man(1) program were implemented.  This inludes the extended
       file names of man pages, for example, the man page of groff in
       man section 7 may be stored under /usr/share/man/man7/groff.7.gz, where
       /usr/share/man/ is part of the man path, the subdirectory man7 and the
       file extension .7 refer to the man section 7; .gz shows the compression
       of the file.

       The cat pages (preformatted man pages) are intentionally excluded from
       the search because groffer is a roff program that wants to format by
       its own.  With the excellent performance of the actual computers, the
       preformatted man pages aren't necessary any longer.

       The algorithm for retrieving man pages uses five search methods.  They
       are successively tried until a method works.

       · The search path can be manually specified by using the option
         --manpath.  An empty argument disables the man page searching.  This
         overwrites the other methods.

       · If this is not available the environment variable $MANPATH is
         searched.

       · If this is empty, the program tries to read it from the environment
         variable $MANOPT.

       · If this does not work a reasonable default path from $PATH is
         searched for man pages.

       · If this does not work, the manpath(1) program for determining a path
         of man directories is tried.

       After this, the path elements for the language (locale) and operating
       system specific man pages are added to the man path; their sequence is
       determined automatically.  For example, both /usr/share/man/linux/fr
       and /usr/share/man/fr/linux for french linux man pages are found.  The
       language and operating system names are determined from both
       environment variables and command line options.

       The locale (language) is determined like in GNU man, that is from
       highest to lowest precedence:

       · --locale

       · $GROFFER_OPT

       · $MANOPT

       · $LCALL

       · $LC_MESSAGES

       · $LANG.

       The language locale is usually specified in the POSIX 1003.1 based
       format:

       <language>[_<territory>[.<character-set>[,<version>]]],

       but the two-letter code in <language> is sufficient for most purposes.

       If no man pages for a complicated locale are found the country part
       consisting of the first two characters (without the `_', `.', and `,',
       parts) of the locale is searched as well.

       If still not found the corresponding man page in the default language
       is used instead.  As usual, this default can be specified by one of C
       or POSIX.  The man pages in the default language are usually in
       English.

       Several operating systems can be given by appending their names,
       separated by a comma.  This is then specified by the environment
       variable $SYSTEM or by the command line option --systems.  The
       precedence is similar to the locale case above from highest to lowest
       precedence: Topic --systems

       · $GROFFER_OPT

       · $MANOPT

       · $SYSTEM.

       When searching for man pages this man path with the additional language
       and system specific directories is used.

       The search can further be restricted by limiting it to certain
       sections.  A single section can be specified within each filespec
       argument, several sections as a colon-separated list in command line
       option --sections or environment variable $MANSECT.  When no section
       was specified a set of standard sections is searched until a suitable
       man page was found.

       Finally, the search can be restricted to a so-called extension.  This
       is a postfix that acts like a subsection.  It can be specified by
       --extension or environment variable $EXTENSION.

       For further details on man page searching, see man(1).

DECOMPRESSION
       The program has a decompression facility.  If standard input or a file
       that was retrieved from the command line parameters is compressed with
       a format that is supported by either gzip(1) or bzip2(1) it is
       decompressed on-the-fly.  This includes the GNU .gz, .bz2, and the
       traditional .Z compression.  The program displays the concatenation of
       all decompressed input in the sequence that was specified on the
       command line.

ENVIRONMENT
       The groffer programs supports many system variables, most of them by
       courtesy of other programs.  All environment variables of groff(1) and
       GNU man(1) and some standard system variables are honored.

   Native groffer Variables
       $GROFFER_OPT
              Store options for a run of groffer.  The options specified in
              this variable are overridden by the options given on the command
              line.  The content of this variable is run through the shell
              builtin `eval'; so arguments containing white-space or special
              shell characters should be quoted.

   System Variables
       The groffer program is a shell script that is run through /bin/sh,
       which can be internally linked to programs like bash(1).  The
       corresponding system environment is automatically effective.  The
       following variables have a special meaning for groffer.

       $DISPLAY
              If this variable is set this indicates that the X Window system
              is running.  Testing this variable decides on whether graphical
              or text output is generated.  This variable should not be
              changed by the user carelessly, but it can be used to start the
              graphical groffer on a remote X terminal.  For example,
              depending on your system, groffer can be started on the second
              monitor by the command
              sh# DISPLAY=:0.1 groffer what.ever&

       $LC_ALL
       $LC_MESSAGES
       $LANG  If one of these variables is set (in the above sequence), its
              content is interpreted as the locale, the language to be used,
              especially when retrieving man pages.  A locale name is
              typically of the form language[_territory[.codeset[@modifier]]],
              where language is an ISO 639 language code, territory is an ISO
              3166 country code, and codeset is a character set or encoding
              identifier like ISO-8859-1 or UTF-8; see setlocale(3).  The
              locale values C and POSIX stand for the default, i.e. the
              man page directories without a language prefix.  This is the
              same behavior as when all 3 variables are unset.

       $PAGER This variable can be used to set the pager for the tty output.
              For example, to disable the use of a pager completely set this
              variable to the cat(1) program
              sh# PAGER=cat groffer anything

       $PATH  All programs within the groffer shell script are called without
              a fixed path.  Thus this environment variable determines the set
              of programs used within the run of groffer.

       $POSIXLY_CORRECT
              If set to a non-empty value this chooses the POSIX mode.  This
              is done internally by some shells.  groffer ignores the bad
              POSIX behavior for option processing, that means that option
              processing will be finished as soon as a non-option argument is
              found.  Instead the GNU behavior of freely mixing options and
              filespec arguments is used in any case.  Usually, you do not
              want to set this environment variable externally.

   Groff Variables
       The groffer program internally calls groff, so all environment
       variables documented in groff(1) are internally used within groffer as
       well.  The following variables have a direct meaning for the groffer
       program.

       $GROFF_TMPDIR
              If the value of this variable is an existing, writable
              directory, groffer uses it for storing its temporary files, just
              as groff does.

   Man Variables
       Parts of the functionality of the man program were implemented in
       groffer; support for all environment variables documented in man(1) was
       added to groffer, but the meaning was slightly modified due to the
       different approach in groffer; but the user interface is the same.  The
       man environment variables can be overwritten by options provided with
       $MANOPT, which in turn is overwritten by the command line.

       $EXTENSION
              Restrict the search for man pages to files having this
              extension.  This is overridden by option --extension; see there
              for details.

       $MANOPT
              This variable contains options as a preset for man(1).  As not
              all of these are relevant for groffer only the essential parts
              of its value are extracted.  The options specified in this
              variable overwrite the values of the other environment variables
              taht are specific to man.  All options specified in this
              variable are overridden by the options given on the command
              line.

       $MANPATH
              If set, this variable contains the directories in which the
              man page trees are stored.  This is overridden by option
              --manpath.

       $MANSECT
              If this is a colon separated list of section names, the search
              for man pages is restricted to those manual sections in that
              order.  This is overridden by option --sections.

       $SYSTEM
              If this is set to a comma separated list of names these are
              interpreted as man page trees for different operating systems.
              This variable can be overwritten by option --systems; see there
              for details.

       The environment variable $MANROFFSEQ is ignored by groffer because the
       necessary preprocessors are determined automatically.

CONFIGURATION FILES
       The groffer program can be preconfigured by two configuration files.
       This configuration can be overridden at each program start by command
       line options or by the environment variable $GROFFER_OPT.

       /etc/groff/groffer.conf
              System-wide configuration file for groffer.

       $HOME/.groff/groffer.conf
              User-specific configuration file for groffer, where $HOME
              denotes the user's home directory.  This script is called after
              the system-wide configuration file to enable overriding by the
              user.

       Their lines either start with a minus character or are shell commands.
       Arbitrary spaces are allowed at the beginning, they are just ignored.
       The lines with the beginning minus are appended to the existing value
       of $GROFFER_OPT.  This easily allows to set general groffer options
       that are used with any call of groffer.

       After the transformation of the minus lines the emerging shell scripts
       that are called by groffer using the `. filename' syntax.

       The only option that needs a minus line in the configuration files is
       --shell.  The reason is that its argument must be called at a very
       early stage before the whole syntax of the configuration can be
       transformed.

       It makes sense to use these configuration files for the following
       tasks:

       · Preset command line options by writing them into lines starting with
         a minus sign.

       · Preset environment variables recognized by groffer.

       · Write a function for calling a viewer program for a special mode and
         feed this name into its corresponding --mode-viewer option.  Note
         that the name of such a function must coincide with some existing
         program in the system path $PATH in order to be recognized by
         groffer.

       As an example, consider the following configuration file in
       ~/.groff/groffer.conf, say.

       # groffer configuration file
       #
       # groffer options that are used in each call of groffer
       --shell=/bin/bash
       --resolution=100
       --foreground=DarkBlue
       --x-viewer='gxditview -geometry 850x800'
       #
       # some shell commands
       if test "$DISPLAY" = ""; then
         DISPLAY='localhost:0.0'
       fi
       date >>~/mygroffer.log

       This configuration sets four groffer options and runs two shell
       commands.  This has the following effects:

       · Lines starting with a # character are

       · Use /bin/bash as the shell to run the groffer script.

       · Take a resolution of 100 dpi and a text color of DarkBlue in all
         viewers that support this.

       · Force gxditview(1) as the X-mode viewer using the geometry option for
         setting the width to 850 dpi and the height to 800 dpi.

       · The variable $DISPLAY is set to localhost:0.0 which allows to start
         groffer in the standard X display, even when the program is called
         from a text console.

       · Just for fun, the date of each groffer start is written to the file
         mygroffer.log in the home directory.

EXAMPLES
       The usage of groffer is very easy.  Usually, it is just called with a
       file name or man page.  The following examples, however, show that
       groffer has much more fancy capabilities.

       sh# groffer /usr/local/share/doc/groff/meintro.ms.gz
              Decompress, format and display the compressed file meintro.ms.gz
              in the directory /usr/local/share/doc/groff, using gxditview as
              graphical viewer when in X Window, or the less(1) pager program
              when not in X.

       sh# groffer groff
              If the file ./groff exists use it as input.  Otherwise interpret
              the argument as a search for the man page named groff in the
              smallest possible man section, being secion 1 in this case.

       sh# groffer man:groff
              search for the man page of groff even when the file ./groff
              exists.

       sh# groffer groff.7
       sh# groffer 7 groff
              search the man page of groff in man section 7.  This section
              search works only for a digit or a single character from a small
              set.

       sh# groffer fb.modes
              If the file ./fb.modes does not exist interpret this as a search
              for the man page of fb.modes.  As the extension modes is not a
              single character in classical section style the argument is not
              split to a search for fb.

       sh# groffer groff ’troff(1)’ man:roff
              The arguments that are not existing files are looked-up as the
              following man pages: groff (automatic search, should be found in
              man section 1), troff (in section 1), and roff (in the section
              with the lowest number, being 7 in this case).  The quotes
              around troff(1)are necessary because the paranthesis are
              special shell characters; escaping them with a backslash
              character \( and \) would be possible, too.  The formatted files
              are concatenated and displayed in one piece.

       sh# LANG=de groffer --man --www --www-viever=mozilla ls
              Retrieve the German man page (language de) for the ls program,
              decompress it, format it to html format (www mode) and view the
              result in the web browser galeon .  The option --man guarantees
              that the man page is retrieved, even when a local file ls exists
              in the actual directory.

       sh# groffer --source 'man:roff(7)'
              Get the man page called roff in man section 7, decompress it,
              and print its unformatted content, its source code.

       sh# cat file.gz | groffer -Z -mfoo
              Decompress the standard input, send this to groff intermediate
              mode without post-processing (groff option -Z), using macro
              package by foo (groff option -m)

       sh# echo '\f[CB]WOW!' |
       >   groffer --x --bg red --fg yellow --geometry 200x100 -
              Display the word WOW! in a small window in constant-width bold
              font, using color yellow on red background.

COMPATIBILITY
       The groffer shell script is compatible with both GNU and POSIX.  POSIX
       compatibility refers to IEEE P1003.2/D11.2 of September 1991, a very
       early version of the POSIX standard that is still freely available in
       the internet.  Unfortunately, this version of the standard has `local'
       for shell function variables removed.  As `local' is needed for serious
       programming this temporary POSIX deprecation was ignored.

       Most GNU shells are compatible with this interpretation of POSIX, but
       provide much more facilities.  Nevertheless this script uses only a
       restricted set of shell language elements and shell builtins.  The
       groffer script should work on most actual free and commercial operating
       systems.

       The groffer program provides its own parser for command line options;
       it can handle option arguments and file names containing white space
       and a large set of special characters.

       The groffer shell script was tested with the following common
       implementations of the GNU shells: POSIX sh(1), bash(1), and others.
       Free POSIX compatible shells and shell utilities for most operating
       systems are available at the GNU software archive ⟨http://www.gnu.org/
       software/⟩.

       The shell can be chosen by the option --shell.  This option can also be
       given to the environment variable $GROFF_OPT.  If you want to write it
       to one of the groffer configuration files you must use the single
       option style, a line starting with --shell.

       The groffer program provides its own parser for command line arguments
       that is compatible to both POSIX getopts(1) and GNU getopt(1) except
       for shortcuts of long options.  The following standard types of options
       are supported.

       · A single minus always refers to single character option or a
         combination thereof, for example, the groffer short option
         combination -Qmfoo is equivalent to -Q -m foo.

       · Long options are options with names longer than one character; they
         are always prededed by a double minus.  An option argument can either
         go to the next command line argument or be appended with an equal
         sign to the argument; for example, --long=arg is equivalent to
         --long arg .

       · An argument of -- ends option parsing; all further command line
         arguments are interpreted as file name arguments.

       · By default, all command line arguments that are neither options nor
         option arguments are interpreted as filespec parameters and stored
         until option parsing has finished.  For example, the command line
         sh# groffer file1 -a -o arg file2
         is, by default, equivalent to
         sh# groffer -a -o arg -- file1 file2

       This behavior can be changed by setting the environment variable
       $POSIXLY_CORRECT to a non-empty value.  Then the strange POSIX non-
       option behavior is adopted, i. e. option processing is stopped as soon
       as the first non-option argument is found and each following argument
       is taken as a file name.  For example, in posixly correct mode, the
       command line
       sh# groffer file1 -a -o arg file 2
       is equivalent to
       sh# groffer -- file1 -a -o arg file 2
       As this leads to unwanted behavior in most cases, most people do not
       want to set $POSIXLY_CORRECT.

SEE ALSO
       groff(1)
       troff(1)
              Details on the options and environment variables available in
              groff; all of them can be used with groffer.

       man(1) The standard program to diplay man pages.  The information there
              is only useful if it is the man page for GNU man.  Then it
              documents the options and environment variables that are
              supported by groffer.

       gxditview(1)
       xditview(1x)
              Viewers for groffer's x mode.

       gv(1)
       ghostview(1)
              Viewers for groffer's ps mode.
       gs(1)  Transformer from ps to pdf; and a ps viewer.

       xpdf(1)
              Viewers for pdf files.

       xdvi(1)
       dvilx(1)
              Viewers for groffer's dvi mode.

       less(1)
              Standard pager program for the tty mode.

       gzip(1)
       bzip2(1)
              The decompression programs supported by groffer.

       groff(7)
              Documentation of the groff language.

       grog(1)
              Internally, groffer tries to guess the groff command line
              options from the input using this program.

       groff_out(5)
              Documentation on the groff intermediate output (ditroff output).

AUTHOR
       This file was written by Bernd Warken.

COPYING
       Copyright (C) 2001,2002,2004 Free Software Foundation, Inc.

       This file is part of groff, a free software project.  You can
       redistribute it and/or modify it under the terms of the GNU General
       Public License as published by the Free Software Foundation; either
       version 2, or (at your option) any later version.

       You should have received a copy of the GNU General Public License along
       with groff, see the files COPYING and LICENSE in the top directory of
       the groff source package.  Or read the man page gpl(1).  You can also
       write to the Free Software Foundation, 59 Temple Place - Suite 330,
       Boston, MA 02111-1307, USA.




Groff Version 1.18.1.1           02 June 2004                       GROFFER(1)