groffer



GROFFER(1)                                                          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 dis-
       playing  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 con-
       figuration files, with the shell environment variable $GROFFER_OPT,  or
       on the command line.

       The output can be generated and viewed in several different ways avail-
       able 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  ar-
       guments.

       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 op-
       tions of man(1).

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

       --apropos name
              Start  the  apropos(1) command for searching within man page de-
              scriptions.  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 op-
       tions.  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 xd-
              vi(1) and dvilx(1) In each case, arguments can be provided addi-
              tionally.

       --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 de-
                     fault, 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 re-
                     sult in a web browser program.  By default, the existence
                     of  a sequence of standard web browsers is tested, start-
                     ing with konqueror(1)  and  mozilla(1).   The  text  html
                     viewer is lynx(1).

              pdf    Display  formatted input in a PDF (Portable Document For-
                     mat) viewer program.  By default, the input is  formatted
                     by  groff  using the Postscript device, then it is trans-
                     formed into the PDF file format using gs(1), and  finally
                     displayed either with the xpdf(1) or the acroread(1) pro-
                     gram.  PDF has a big advantage because the text  is  dis-
                     played 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 stan-
                     dard  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 stan-
                     dard 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 de-
                     fault,  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 pro-
              gram that  accepts  html  input  and  allows  the  file://local-
              host/dir/file  syntax  on the command line is suitable as viewer
              program; it can be the path name of an executable file or a pro-
              gram  in  $PATH.   In each case, arguments can be provided addi-
              tionally.

       -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 exe-
              cutable 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 op-
       tion --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  can-
              not 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  impor-
              tant  devices  are  the text output devices for referring to the
              different character sets, such as ascii, utf8, latin1, and  oth-
              ers.   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 corre-
              sponding 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  fa-
              cility of groff’s option.

       -Z | --intermediate-output | --ditroff
              Switch  into groff mode and format the input with groff interme-
              diate 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 op-
       tions that are not explicitly  handled  by  groffer  are  transparently
       passed to groff.  Therefore these transparent options are not document-
       ed 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 Toolk-
       it 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 de-
              fault 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 ig-
       nored.

       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 grof-
       fer 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 argu-
              ment 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 behav-
       ior 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 sever-
       al 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 in-
       to  several sections.  The classical man sections have a single-charac-
       ter 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 ex-
       tended by a following string.  But the special groffer man page facili-
       ty 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 construct-
       ed.  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 choos-
       es 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.   Ad-
       ditionally,  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  ac-
       tive 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  en-
       vironment variable $DISPLAY and the option --display are used for spec-
       ifying 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 Win-
       dow 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  trans-
       form  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 display-
       ing 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 de-
       velopment 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 parame-
       ter 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 modi-
       fied by the following options.

       --man  forces to interpret all file parameters as filespecs for search-
              ing 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 pa-
       rameter a warning is issued on standard error, but processing  is  con-
       tinued.

       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 sec-
       tion  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  environ-
       ment variables and command line options.

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

       · --locale

       · $GROFFER_OPT

       · $MANOPT

       · $LCALL

       · $LC_MESSAGES

       · $LANG.

       The language locale is usually specified in the POSIX 1003.1 based for-
       mat:

       <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  En-
       glish.

       Several  operating systems can be given by appending their names, sepa-
       rated 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  sec-
       tions.   A  single  section can be specified within each filespec argu-
       ment, several sections as a colon-separated list in command line option
       --sections or environment variable $MANSECT.  When no section was spec-
       ified 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 decom-
       pressed on-the-fly.  This includes the GNU .gz, .bz2,  and  the  tradi-
       tional  .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  corre-
       sponding  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,  depend-
              ing 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 typical-
              ly  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 identi-
              fier 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 di-
              rectories 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 vari-
       ables 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  directo-
              ry,  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 grof-
       fer;  support  for  all  environment variables documented in man(1) was
       added to groffer, but the meaning was slightly modified due to the dif-
       ferent  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 exten-
              sion.  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 vari-
              able overwrite the values of  the  other  environment  variables
              taht  are  specific to man.  All options specified in this vari-
              able 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 or-
              der.  This is overridden by option --sections.

       $SYSTEM
              If this is set to a comma separated list of names these are  in-
              terpreted  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  de-
              notes  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 ear-
       ly stage before the whole syntax of the  configuration  can  be  trans-
       formed.

       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  grof-
         fer.

       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  com-
       mands.  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 ex-
              ists.

       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 spe-
              cial shell characters; escaping them with a backslash  character
              \(  and \) would be possible, too.  The formatted files are con-
              catenated 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 re-
       stricted  set of shell language elements and shell builtins.  The grof-
       fer 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 implemen-
       tations 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 op-
       tion 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 combina-
         tion 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 argu-
         ments 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-op-
       tion 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  com-
       mand 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 docu-
              ments  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  op-
              tions 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  redis-
       tribute  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)

Man(1) output converted with man2html