manpagez: man pages & more
man groffer(1)
Home | html | info | man
groffer(1)                                                          groffer(1)




NAME

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


SYNOPSIS

       groffer [option...]  [--] [filespec...]
       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  language,  see  groff(7),  or
       other  roff languages, see roff(7), 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,  com-
       pressed  files  that  can  be handled by gzip(1) or bzip2(1) are decom-
       pressed 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  either
       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 avail-
       able  for  groff.   This  includes  the  groff  native  X Window viewer
       gxditview(1), each Postcript, pdf, or dvi display program, a web brows-
       er by generating html in www mode, or several text modes in text termi-
       nals.

       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  handling  is  done in GNU style.  Options and file names can be
       mixed freely.  The option `--' closes the option handling, all  follow-
       ing  arguments are treated as file names.  Long options can be abbrevi-
       ated.


OPTION OVERVIEW

       breaking options

              [-h|--help] [-v|--version]

       groffer mode options

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

       development options

              [--debug] [--do-nothing] [--shell prog] [-Q|--source] [-V]

       options related to groff

              [-T|--device device] [-Z|--intermediate-output|--ditroff]

              All further groff short options are accepted.

       options for man pages
              [--apropos] [--apropos-data] [--apropos-devel] [--apropos-progs]
              [--whatis] [--man] [--no-man] [--no-special]

       long options taken over from GNU man

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

              Further long options of GNU man are accepted as well.

       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]

       filespec arguments

              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.

       -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.  The default modes
       are  mode  x with gxditview in X Window and mode tty with device latin1
       under less on a terminal.

       There are two kinds of options for viewers.  --mode-viewer chooses  the
       normal viewer programs that run on their own in X Window, while --mode-
       viewer-tty chooses programs that run on the terminal  (on  tty).   Most
       graphical  viewers  are  programs  running in X Window, so there aren't
       many opportunities to call the tty viewers.  But they give  the  chance
       to  view the output source; for example, --ps-viewer-tty=less shows the
       content of the Postscript output with the pager less.

       The X Window viewers are not critical, you can use both --*-viewer  and
       --*-viewer-tty  for  them;  with --*-viewer-tty the viewer program will
       not become independently, it just stays coupled with groffer.  But  the
       program  will not run if you specify a terminal program with --*-viewer
       because this viewer will stay in background without a chance  to  reach
       it.  So you really need --*-viewer-tty for viewers that run on tty.

       --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
              Choose an X Window viewer program for dvi mode.  This can  be  a
              file  name or a program to be searched in $PATH.  Known X Window
              dvi viewers include xdvi(1) and dvilx(1) In each case, arguments
              can be provided additionally.

       --dvi-viewer-tty prog
              Choose  a program running on the terminal for viewing the output
              of dvi mode.  This can be  a  file  name  or  a  program  to  be
              searched in $PATH; arguments can be provided additionally.

       --groff
              Equivalent to --mode=groff.

       --html Equivalent to --mode=html.

       --html-viewer
              Choose  an X Window web browser program for viewing in html mode
              .  It can be the path name of an executable file or a program in
              $PATH.  In each case, arguments can be provided additionally.

       --html-viewer-tty
              Choose  a terminal program for viewing the output of html mode .
              It can be the path name of an executable file or  a  program  in
              $PATH; arguments can be provided additionally.

       --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 --mode=html.

              x      Display the formatted input in a native roff viewer.   By
                     default,  the  formatted  input  is  displayed  with  the
                     gxditview(1)  program  being  distributed  together  with
                     groff.   But  the  standard X Window tool xditview(1) can
                     also be chosen with the option --x-viewer.   The  default
                     resolution is 75 dpi, but 100 dpi are also possible.  The
                     default groff device for the  resolution  of  75  dpi  is
                     X75-12,  for 100 dpi it is X100.  The corresponding groff
                     intermediate output for the actual  device  is  generated
                     and  the  result  is  displayed.   For  a  resolution  of
                     100 dpi, the default width of the geometry of the display
                     program is chosen to 850 dpi.

              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
              Choose  an  X Window viewer program for pdf mode.  This can be a
              file name or a program to be searched in $PATH; arguments can be
              provided additionally.

       --pdf-viewer-tty prog
              Choose  a  terminal  viewer program for pdf mode.  This can be a
              file name or a program to be searched in $PATH; arguments can be
              provided additionally.

       --ps   Equivalent to --mode=ps.

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

       --ps-viewer-tty prog
              Choose a terminal viewer program for ps mode.   This  can  be  a
              file name or a program to be searched in $PATH; arguments can be
              provided additionally.

       --text Equivalent to --mode=text.

       --tty  Equivalent to --mode=tty.

       --tty-viewer prog
              Choose a text  pager  for  mode  tty.   The  standard  pager  is
              less(1).   This  option is eqivalent to man option --pager=prog.
              The option argument can be a  file  name  or  a  program  to  be
              searched in $PATH; arguments can be provided additionally.

       --tty-viewer-tty prog
              This  is equivalent to --tty-viewer because the programs for tty
              mode run on a terminal anyway.

       --www  Equivalent to --mode=html.

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

       --www-viewer-tty prog
              Equivalent to --html-viewer-tty.

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

       --X-viewer | --x-viewer prog
              Choose an X Window viewer program for x mode.   Suitable  viewer
              programs  are gxditview(1) which is the default and xditview(1).
              The argument can be any executable file or a program  in  $PATH;
              arguments can be provided additionally.

       --X-viewer-tty | --x-viewer-tty prog
              Choose  a  terminal viewer program for x mode.  The argument can
              be any executable file or a program in $PATH; arguments  can  be
              provided additionally.

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

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


Options for Development

       --debug
              Enable  five  debugging  informations.   The temporary files are
              kept and not deleted, the name of the  temporary  directory  and
              the  shell  name for groffer2.sh are printed, the parameters are
              printed at several steps of development, and a function stack is
              output with function error_user() as well.  Neither the function
              call stack that is printed at each  opening  and  closing  of  a
              function  call  nor  the landmark information that is printed to
              determine how far the program is running are used.   This  seems
              to be the most useful among all debugging options.

       --debug-all
              Enable  all  seven debugging informations including the function
              call stack and the landmark information.

       --debug-keep
              Enable two debugging information, the printing of  the  name  of
              the  temporary directory and the keeping of the temporary files.

       --debug-lm
              Enable one debugging information, the landmark information.

       --debug-params
              Enable one debugging  information,  the  parameters  at  several
              steps.

       --debug-shell
              Enable   one   debugging   information,   the   shell  name  for
              groffer2.sh.

       --debug-stacks
              Enable one debugging information, the function call stack.

       --debug-tmpdir
              Enable one debugging information, the name of the temporary  di-
              rectory.

       --debug-user
              Enable  one  debugging  information, the function stack with er-
              ror_user().

       --do-nothing
              This is like --version, but without the  output;  no  viewer  is
              started.  This makes only sense in development.

       --print=text
              Just print the argument to standard error.  This is good for pa-
              rameter check.

       --shell shell_program
              Specify the shell under which the groffer2.sh script  should  be
              run.   This  option overwrites the automatic shell determination
              of the program.  If the argument shell_program is empty a former
              shell  option and the automatic shell determination is cancelled
              and the default shell is restored.  Some shells run considerably
              faster than the standard shell.

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

       -V     This is an advanced option for debugging only.  Instead of  dis-
              playing  the formatted input, a lot of groffer specific informa-
              tion is printed to standard output:

              o the output file name in the temporary directory,

              o the display mode of the actual groffer run,

              o the display program for viewing the output with its arguments,

              o the  active parameters from the config files, the arguments in
                $GROFFER_OPT, and the arguments of the command line,

              o the pipeline that would be run by the groff program, but with-
                out executing it.

       Other   useful   debugging   options   are  the  groff  option  -Z  and
       --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  option  -Z
       groffer was designed to be switched into groff mode ; the groffer view-
       ing 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  the
              text modes.  That could be important when  the  text  pager  has
              problems with control sequences in tty mode.

       -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
              corresponding  groffer --mode=devname option: dvi, html, and ps.
              All X* arguments are mapped to mode x.  Each other devname argu-
              ment switches to mode groff using this device.

       -X     is  equivalent  to groff -X.  It displays the groff intermediate
              output with gxditview.  As the quality is  relatively  bad  this
              option is deprecated; use --X instead because the x mode uses an
              X* device for a better display.

       -Z | --intermediate-output | --ditroff
              Switch into groff mode and format the input with the  groff  in-
              termediate  output  without  postprocessing;  see  groff_out(5).
              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.

   Options for man pages
       --apropos
              Start the apropos(1) command or facility of man(1) for searching
              the  filespec  arguments within all man page descriptions.  Each
              filespec argument is taken for search as it is; section specific
              parts  are  not  handled, such that 7 groff searches for the two
              arguments 7 and groff with a  large  result;  for  the  filespec
              groff.7  nothing  will  be  found.  The display differs from the
              apropos program by the following concepts:

              o construct a groff frame to the output of apropos,

              o each filespec argument is searched on its own.

              o the restriction by --sections is handled as well,

              o wildcard characters are allowed and handled without a  further
                option.

       --apropos-data
              Show only the apropos descriptions for data documents, these are
              the man(7) sections 4, 5, and 7.   Direct  section  declarations
              are ignored, wildcards are accepted.

       --apropos-devel
              Show  only  the  apropos descriptions for development documents,
              these are the man(7) sections 2, 3, and 9.  Direct section  dec-
              larations are ignored, wildcards are accepted.

       --apropos-progs
              Show  only  the  apropos descriptions for documents on programs,
              these are the man(7) sections 1, 6, and 8.  Direct section  dec-
              larations are ignored, wildcards are accepted.

       --whatis
              For  each  filespec  argument  search  all man pages and display
              their description -- or say that it is not  a  man  page.   This
              differs from man's whatis output by the following concepts

              o each retrieved file name is added,

              o local files are handled as well,

              o the display is framed by a groff output format,

              o wildcard characters are allowed without a further option.

       The  following  two  options were added to 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.

       --no-special
              Disable former calls of --all, --apropos*, and --whatis.

   Long options taken over from GNU man
       The long options of groffer were synchronized with the long options  of
       GNU  man.   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.

       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
              for critical environment.  This  is  equivalent  to  groff  -mt-
              ty_char; see groff_tmac(5).

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

       --where
              Eqivalent to --location.

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

       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 Window option -font.

       See  X(1),  X(7), and the documentation on the X Window 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 Window 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 Window 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  Window  resolution in dpi (dots per inch) in some viewer
              programs.  The only supported dpi values are 75 and 100.   Actu-
              ally,  the default resolution for groffer is set to 75 dpi.  The
              resolution also sets the default device in mode x.

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

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

       --xrm 'resource'
              Set X Window resource.

   Filespec Arguments
       A filespec parameter is an argument that is not an option or option ar-
       gument.  It means an input source.  In groffer, filespec parameters are
       a file name or a 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 to regard all  arguments  behind  the  first
       non-option argument as 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 -- ends the option
       handling and interprets all following arguments as filespec  arguments;
       so the POSIX behavior can be easily adopted.

       For  the  following,  it  is  necessary to know that 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 a digit
       from 1 to 9 or one of the characters n  or  o.   In  the  following,  a
       stand-alone character s stands for a classical man section.  The inter-
       nal precedence of man for searching man pages with the same name within
       several  sections  goes according to the classical single-character se-
       quence.  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.

       Each filespec parameter can have one of the following forms in decreas-
       ing sequence.

       o No  filespec  parameters means that groffer waits for standard input.
         The minus option - stands for standard input, too; it can occur  sev-
         eral times.

       o Next  a filespec is tested whether it is the path name of an existing
         file.  Otherwise it is assumed  to  be  a  searching  pattern  for  a
         man page.

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

       o Next  some  patterns based on the classical man sections are checked.
         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 a man page
         named name.s is searched in the lowest man section .

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

       o 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 inter-
         pret both s and name as two independent filespec arguments.

       o 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.

       Wildcards in filespec arguments are only accepted  for  --apropos*  and
       --whatis; for normal display, they are interpreted as characters.

       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 modes for X Window,
       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 mostly 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 Window display to be used.  If this  environment  variable
       is  empty  groffer assumes that no X Window is running and changes to a
       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

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

       o in a Postscript viewer (ps mode),

       o in a dvi viewer program (dvi mode),

       o in a PDF viewer (pdf mode),

       o 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 modes
       There are two 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 option -Q and --source just displays the decom-
       pressed input.

       The groff mode passes the input to groff using only some  suitable  op-
       tions 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 I man  pages  uses  five  search  methods.
       They are successively tried until a method works.

       o 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.

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

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

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

       o 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:

       o --locale

       o $GROFFER_OPT

       o $MANOPT

       o $LCALL

       o $LC_MESSAGES

       o $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

       o $GROFFER_OPT

       o $MANOPT

       o $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 program 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.  Do not forget to export this
              variable, otherwise it does not exist during the run of groffer.

   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 Window 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 IR man pages .  A locale name is typ-
              ically 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 lo-
              cale values C and POSIX stand for the default, i.e. the man page
              directories  without a language prefix.  This is the same behav-
              ior 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.

   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 variable has a direct meaning for the groffer pro-
       gram.

       $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
       groffer; 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
              that 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.

       /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 file is called after  the
              system-wide configuration file to enable overriding by the user.

       The precedence of option delivery is given in the following.  The  con-
       figuration file in /etc has the lowest precedence; it is overwritten by
       the configuration file in the home directory; both configuration  files
       are overwritten by the environment variable $GROFFER_OPT; everything is
       overwritten by the command line.

       In the configuration files, arbitrary spaces are allowed at the  begin-
       ning  of  each line, they are just ignored.  Apart from that, the lines
       of the configuration lines either start with  a  minus  character,  all
       other lines are interpreted as shell commands.

       The  lines with the beginning minus are interpreted as groffer options.
       This easily allows to set general groffer options that should  be  used
       with  any  call of groffer.  Each line can represent a single short op-
       tion, a short option cluster, or a long option with  two  minus  signs,
       eventually with an argument.  The argument can be appended either after
       a space character or an equal sign `='.  The argument can be surrounded
       by quotes, but this is not necessary.  The options from these lines are
       collected and prepended to the existing value of  $GROFFER_OPT  at  the
       end of each configuration file.

       After  the  transformation  of the minus lines, the configuration files
       have been transferred into a shell script that is called within groffer
       using the `. filename' shell syntax.

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

       o Preset command line options, such as choosing a  mode  or  a  viewer.
         These  are  written into lines starting with a single or double minus
         sign, followed by the option name.

       o Preset environment variables recognized by groffer; but do not forget
         to export them.

       o You can also write a shell function for calling, for example a viewer
         program for some mode.  Such a function can be fed into a correspond-
         ing --mode-viewer option.

       o Enter  --shell  to  specify a shell for the run of groffer2.sh.  Some
         shells run much faster than the standard shell.

       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=ksh
       --foreground=DarkBlue
       --resolution=100
       --x-viewer='gxditview -geometry 900x1200'
       #
       # some shell commands
       if test "$DISPLAY" = ""; then
         export DISPLAY='localhost:0.0'
       fi
       date >>~/mygroffer.log

       The  lines  starting with # are command lines.  This configuration sets
       four groffer options (the lines starting with `-') and runs  two  shell
       commands (the rest of the script).  This has the following effects:

       o Use ksh as the shell to run the groffer script; if it works it should
         be faster than the usual sh.

       o Use a text color of DarkBlue in all viewers that support  this,  such
         as gxditview.

       o Use a resolution of 100 dpi in all viewers that support this, such as
         gxditview.  By this, the default device in x mode is set to X100.

       o Force gxditview(1) as the x-mode viewer using the geometry option for
         setting the width to 900 dpi and the height to 1200 dpi.  This geome-
         try is suitable for a resolution of 100 dpi.

       o If the environment variable  $DISPLAY  is  empty  set  it  to  local-
         host:0.0.  That allows to start groffer in the standard X Window dis-
         play, even when the program is called from a text console.

       o 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 the  standard
              viewer  gxditview  as  graphical viewer when in X Window, or the
              less(1) pager program when not in X Window.

       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 section 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=galeon 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
              output  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 program consists of two shell scripts.

       The  starting script is the file groffer that is installed in a bin di-
       rectory.  It is generated from the source file groffer.sh.  It is  just
       a  short  starting script without any functions such that it can run on
       very poor shells.

       The main part of the groffer program is the file  groffer2.sh  that  is
       installed in the groff library directory.  This script can be run under
       a different shell by using the groffer option --shell.

       Both scripts are compatible with both GNU and POSIX.  POSIX compatibil-
       ity  refers  to IEEE P1003.2/D11.2 of September 1991, a very early ver-
       sion of the POSIX standard that is still freely available in the inter-
       net at POSIX P1003.2 draft 11.2 <http://www.funet.fi/pub/doc/posix/
       p1003.2/d11.2/all>.

       Only a restricted set of shell language elements and shell builtins  is
       used to achieve even compatibility with some Bourne shells that are not
       fully POSIX compatible.  The groffer shell scripts were tested on  many
       shells,   including  the  following  Bourne  shells:  ash(1),  bash(1),
       dash(1), ksh(1), pdksh(1), posh(1), and zsh(1).  So it should  work  on
       most actual free and commercial operating systems.

       The  shell  for  the  run  of  groffer2.sh  can be chosen by the option
       --shell on the command line or the environment variable $GROFF_OPT.  If
       you  want  to add it to one of the groffer configuration files you must
       write 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).  It can
       handle option arguments and file names containing  white  space  and  a
       large  set  of special characters.  The following standard types of op-
       tions are supported.

       o The option consisiting of a single minus - refers to standard  input.

       o A  single  minus  followed by characters refers to a single character
         option or a combination thereof; for example, the groffer  short  op-
         tion combination -Qmfoo is equivalent to -Q -m foo.

       o Long  options  are options with names longer than one character; they
         are always preceded 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 .

       o An argument of -- ends option parsing; all further command line argu-
         ments are interpreted as filespec parameters, i.e. file names or con-
         structs for searching man pages).

       o All  command line arguments that are neither options nor option argu-
         ments 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 equivalent to
         sh# groffer -a -o arg -- file1 file2

       The  free  mixing  of  options  and filespec parameters follows the GNU
       principle.  That does not fulfill the strange option behavior of  POSIX
       that  ends  option  processing as soon as the first non-option argument
       has been reached.  The end of option processing can be  forced  by  the
       option `--' anyway.


BUGS

       Report bugs to the

       bug-groff  mailing list <bug-groff@gnu.org>.  Include a complete, self-
       contained example that will allow the bug to  be  reproduced,  and  say
       which version of groffer you are using.

       You can also use the

       groff  mailing  list  <groff@gnu.org>,  but you must first subscribe to
       this list.  You can do that by visiting the groff mailing list web page
       <http://lists.gnu.org/mailman/listinfo/groff>.

       See groff(1) for information on availability.


SEE ALSO

       groff(1), troff(1)
              Details  on  the  options and environment variables available in
              groff; all of them can be used with 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).

       groff_tmac(5)
              Documentation on the groff macro files.

       man(1) The standard program to  display  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  sup-
              ported by groffer.

       ash(1), bash(1), dash(1), ksh(1), pdksh(1), posh(1), sh(1), zsh(1)
              Bourne shells that were tested with groffer.

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

       kghostview(1), ggv(1), gv(1), ghostview(1), gs(1)
              Viewers for groffer's ps mode.

       kghostview(1), ggv(1), xpdf(1), acroread(1), kpdf(1)
              Viewers for groffer's pdf mode.

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

       konqueror(1), mozilla(1), lynx(1)
              Web-browsers for groffer's html or www mode.

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

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


AUTHOR

       This file was written by Bernd Warken.


COPYING

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

       This  file  is part of groffer, which 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, 51 Franklin St - Fifth Floor,
       Boston, MA 02110-1301, USA.



Groff Version 1.19.2            22 August 2005                      groffer(1)

Mac OS X 10.6 - Generated Thu Sep 17 20:07:46 CDT 2009
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.