Provided by: groff_1.18.1.1-22build1_i386 bug

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.