LinuxGuruz
  • Last 5 Forum Topics
    Replies
    Views
    Last post


The Web Only This Site
  • BOOKMARK

  • ADD TO FAVORITES

  • REFERENCES


  • MARC

    Mailing list ARChives
    - Search by -
     Subjects
     Authors
     Bodies





    FOLDOC

    Computing Dictionary




  • Text Link Ads






  • LINUX man pages
  • Linux Man Page Viewer


    The following form allows you to view linux man pages.

    Command:

    groffer

    
    
    

    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 in several ways.
    
    
    

    OPTION OVERVIEW

           breaking options
    
                  [-h|--help] [-v|--version]
    
           groffer mode options
    
                  [--auto] [--default] [--default-modes mode1,mode2,...]   [--dvi]
                  [--dvi-viewer  prog]  [--groff]  [--html]  [--html-viewer  prog]
                  [--mode  display_mode]  [--pdf]   [--pdf-viewer   prog]   [--ps]
                  [--ps-viewer  prog]  [--source]  [--text]  [--to-stdout] [--tty]
                  [--tty-viewer  prog]  [--www]  [--www-viewer   prog]   [--x|--X]
                  [--all] [--ascii]  [--ditroff]  [--extension  suffix]  [--locale
                  language]    [--local-file]    [--location|--where]   [--manpath
                  dir1:dir2:...]  [--no-location]  [--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|--bordercolor  pixels]  [--bg|--background  color]  [--bw|
                  --borderwidth  pixels]  [--display X-display] [--fg|--foreground
                  color]  [--fn|--ft|--font   font_name]   [--geometry   size_pos]
                  [--resolution value] [--rv] [--title string] [--xrm X-resource]
    
           options for development
    
                  [--debug]   [--debug-all]   [--debug-filenames]   [--debug-func]
                  [--debug-keep]  [--debug-lm]  [--debug-params]   [--debug-shell]
                  [--debug-stacks]  [--debug-tmpdir] [--debug-user] [--do-nothing]
                  [--print text] [--shell prog] [-V]
    
           filespec arguments
    
                  The filespec parameters are all arguments that  are  neither  an
                  option nor an option argument.  They usually mean a file name or
                  a man page searching scheme.
    
                  In the following, the term section_extension is used.  It  means
                  a  word  that  consists of a man section that is optionally fol-
                  lowed by an extension.  The name of a man section  is  a  single
                  character  from [1-9on], the extension is some word.  The exten-
                  sion is mostly lacking.
    
                  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_extension)
                  man:name.section_extension
                  name(section_extension)
                  name.section_extension
                  section_extension name
                            search the man page name in the section with  optional
                            extension section_extension.
    
                  man:name  man page in the lowest man section that has name.
    
                  name      if  name  is  not  an  existing  file  search  for the
                            man page name in the lowest man section.
    
           gle argument.  For example, --de-n-f can be used as an abbreviation for
           --debug-not-func, but --de-n works as well.  If the abbreviation of the
           argument leads to several resulting options an error is raised.
    
       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 pdf, mode ps, mode html, mode x, and mode dvi in X Window with
           different  viewers and mode tty with device latin1 under less on a ter-
           minal; other modes are tested if the programs for the main default mode
           do not exist.
    
           In  X  Window,  many  programs  create  their  own  window when called.
           groffer can run these viewers as an independent program  in  the  back-
           ground.   As  this does not work in text mode on a terminal (tty) there
           must be a way to know which viewers are X  Window  graphical  programs.
           The groffer script has a small set of information on some viewer names.
           If a viewer argument of the command-line chooses  an  element  that  is
           kept  as  X  Window program in this list it is treated as a viewer that
           can run in the background.  All other, unknown viewer calls are not run
           in the background.
    
           For  each  mode, you are free to choose whatever viewer you want.  That
           need not be some graphical viewer suitable for this mode.  There  is  a
           chance  to  view the output source; for example, the combination of the
           options  --mode=ps  and  --ps-viewer=less  shows  the  content  of  the
           Postscript output, the source code, with the pager less.
    
           --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
    
           --html Equivalent to --mode=html.
    
           --html-viewer
                  Choose  a  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.
    
           --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),  or
                         ps2pdf(1).  If that's not possible, the  Postscript  mode
                         (ps) is used instead.  Finally it is displayed using dif-
                         ferent viewer programs.  pdf has a big advantage  because
                         the  text  is  displayed graphically and is searchable as
                         well.
    
                  ps     Display formatted input in a Postscript  viewer  program.
                         By  default,  the  formatted input is displayed in one of
                         many viewer programs.
    
                  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.
    
    
                  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 Output  the  roff  source code of the input files without
                         further processing.
    
           --pdf  Equivalent to --mode=pdf.
    
           --pdf-viewer prog
                  Choose a 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 a 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.
    
           --source
                  Equivalent --mode=source.
    
           --text Equivalent to --mode=text.
    
           --to-stdout
                  The  file  for  the  chosen mode is generated and its content is
                  printed to standard output.  It will not be displayed in graphi-
                  cal mode.
    
           --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.
    
           --www  Equivalent to --mode=html.
    
           --www-viewer prog
                  Equivalent to --html-viewer.
    
           --X | --x
           sical troff, and much more can be manually specified.
    
       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.
                    apropos,
    
                  ? each filespec argument is searched on its own.
    
                  ? The restriction by --sections is handled as well,
    
                  ? 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  is
                  written from anew, so it differs from man's whatis output by the
                  following concepts
    
                  ? each retrieved file name is added,
    
                  ? local files are handled as well,
    
                  ? the language and system locale is supported,
    
                  ? the display is framed by a groff output format  similar  to  a
                    man page,
    
                  ? wildcard characters are allowed without a further option.
    
           The  following  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
    
           If your system has GNU man installed the full set of long and short op-
           tions of the GNU man program can be passed via the environment variable
           $MANOPT; see man(1).
    
           --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
                  Produce  groff  intermediate  output.   This  is  equivalent  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
           for more details on these options and their arguments.
    
           --background color
                  Set the background color of the viewer window.
    
           --bd pixels
                  This is equivalent to --bordercolor.
    
           --bg color
                  This is equivalent to --background.
    
           --bw pixels
                  This is equivalent to --borderwidth.
    
           --bordercolor pixels
                  Specifies the color of the border surrounding the viewer window.
    
           --borderwidth 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.
    
           --fn font_name
                  This is equivalent to --font.
    
           --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 --font.
    
           --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.
    
                  of development, and a function stack is output with function er-
                  ror_user()  as  well.   Neither  the  function call stack at the
                  opening and closing of each function call nor the  landmark  in-
                  formation to determine how far the program is running are print-
                  ed.  These seem to be the most useful parts among all  debugging
                  options.
    
           --debug-all
                  Enable  all  nine  debugging informations including the function
                  call stack and the landmark information.
    
           --debug-filenames
                  Print the names of the files and man pages that are displayed by
                  groffer.
    
           --debug-func
                  Enable  the  basic  debugging information for checking the func-
                  tions on the beginning  and  end  of  each  call.   The  options
                  --debug-stacks  and --debug-user enable this option automatical-
                  ly.  This option is important for the development,  but  it  de-
                  creases the speed of groffer by large amounts.
    
           --debug-keep
                  Enable  two  debugging informations, 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.
    
                  tion is printed to standard output:
    
                  ? the output file name in the temporary directory,
    
                  ? the display mode of the actual groffer run,
    
                  ? the display program for viewing the output with its arguments,
    
                  ? the  active parameters from the config files, the arguments in
                    $GROFFER_OPT, and the arguments of the command line,
    
                  ? 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.
    
       Filespec Arguments
           A filespec parameter is an argument that is not an option or option ar-
           gument.   In groffer, filespec parameters are a file name or a template
           for searching man pages.  These input sources are  collected  and  com-
           posed 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.
    
           The options have a special handling of filespec arguments.  Each  argu-
           ment  is  taken  as a search scheme of its own.  Also a regexp (regular
           expression) can be used in the filespec.  For example, groffer  --apro-
           pos  '^gro.f$'  searches  groff  in  the  man  page name, while groffer
           --apropos groff searches groff somewhere in the name or description  of
           the man pages.
    
           All  other  parts  of groffer, such as the normal display or the output
           with have a different scheme for filespecs.  No regular expressions are
           used for the arguments.  The filespec arguments are handled by the fol-
           lowing scheme.
    
           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.
    
           This  can  optionally be followed by a string, the so-called extension.
           The extension allows to store several man pages with the same  name  in
           the same section.  But the extension is only rarely used, usually it is
           omitted.  Then the extensions are searched automatically by alphabet.
    
           ? man:name(section_extension),              man:name.section_extension,
             name(section_extension),   or   name.section_extension   search   the
             man  page  name  in   man   section   and   possibly   extension   of
             section_extension.
    
           ? Now  man:name  searches for a man page in the lowest man section that
             has a document called name.
    
           ? section_extension name is a pattern of 2  arguments  that  originates
             from  a  strange  argument  parsing  of the man program.  Again, this
             searches the man page name with section_extension, a combination of a
             section character optionally followed by an extension.
    
           ? 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 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
           ? in a dvi viewer program (dvi 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 --source just displays the decompressed in-
           put.
    
           Otion --to-stdout does not display in a graphical mode.  It just gener-
           ates  the file for the chosen mode and then prints its content to stan-
           dard output.
    
           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.
    
           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.
    
       Search Algoritm
           Let us now assume that a man page should be searched.  The groffer pro-
           gram 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.  The search algorithm shall  determine  which
           file is displayed for a given man page.  The process can be modified by
           options and environment variables.
    
           The only man action that is omitted in  groffer  are  the  preformatted
           man  pages,  also  called cat pages.  With the excellent performance of
           the actual computers, the preformatted man pages aren't  necessary  any
           longer.  Additionally, groffer is a roff program; it wants to read roff
           source files and format them itself.
    
           The algorithm for retrieving the file for a man page needs first a  set
           of  directories.   This  set starts with the so-called man path that is
           modified later on by adding names of  operating  system  and  language.
           This  arising set is used for adding the section directories which con-
           tain the man page files.
    
           The man path is a list of directories that are separated by colon.   It
           is generated by the following methods.
    
           ? The environment variable $MANPATH can be set.
    
           ? It  can  be  read  from  the  arguments  of  the environment variable
             $MANOPT.
    
           ? The man path can be manually specified by using the option --manpath.
             An empty argument disables the man page searching.
    
           ? When no man path was set the manpath(1) program is tried to determine
             one.
    
           ? If this does not work a reasonable default path from $PATH is  deter-
             mined.
    
           We  now  have  a  starting set of directories.  The first way to change
           this set is by adding names of operating systems.   This  assumes  that
           man pages for several operating systems are installed.  This is not al-
           ways true.  The names of such operating systems can be  provided  by  3
           methods.
    
           ? The environment variable $SYSTEM has the lowest precedence.
    
           ? This can be overridden by an option in $MANOPT.
    
           ? Enviroment variable $LANG.
    
           ? This is overridden by $LC_MESSAGES.
    
           ? This is overridden by $LC_ALL.
    
           ? This can be overridden by providing an option in $MANOPT.
    
           ? All  these  environment  variables are overridden by the command line
             option --locale.
    
           The default language can be specified by specifying one of the  pseudo-
           language parameters C or POSIX.  This is like deleting a formerly given
           language information.  The man pages in the default language are usual-
           ly in English.
    
           Of  course,  the language name is determined by man.  In GNU man, it is
           specified in the POSIX 1003.1 based format:
    
           <language>[_<territory>[.<character-set>[,<version>]]],
    
           but the two-letter code in <language> is sufficient for most  purposes.
           If  for  a  complicated  language  formulation  no  man pages are found
           groffer searches the country part consisting of these first two charac-
           ters as well.
    
           The  actual  directory  set is copied thrice.  The language name is ap-
           pended as subdirectory to each directory in the first copy of the actu-
           al directory set (this is only done when a language information is giv-
           en).  Then the 2-letter abbreviation of the language name  is  appended
           as subdirectories to the second copy of the directory set (this is only
           done when the given language name has more than 2 letters).  The  third
           copy of the directory set is kept unchanged (if no language information
           is given this is the kept directory set).  These maximally 3 copies are
           appended to get the new directory set.
    
           We  now  have  a  complete set of directories to work with.  In each of
           these directories, the man files are separated in sections.   The  name
           of  a  section  is represented by a single character, a digit between 1
           and 9, or the character o or n, in this order.
    
           For each available section, a subdirectory man<section> exists contain-
           ing all man files for this section, where <section> is a single charac-
           ter as described before.  Each man file in a section directory has  the
           form  man<section>/<name>.<section>[<extension>][.<compression>], where
           <extension> and <compression> are optional.  <name> is the name of  the
           man  page  that  is  also specified as filespec argument on the command
           line.
    
           The extension is an addition to the section.  This postfix acts like  a
           subsection.   An extension occurs only in the file name, not in name of
           the section subdirectory.  It can be specified on the command line.
    
           It is also possible to specify several sections by appending the single
           characters separated by colons.  One can imagine that this means to re-
           strict the man page search to only some sections.   The  multiple  sec-
           tions are only possible for $MANSECT and --sections.
    
           If no section is specified all sections are searched one after the oth-
           er in the given order, starting with section 1, until a  suitable  file
           is found.
    
           There  are  4 methods to specify an extension on the command line.  But
           it is not necessary to provide the whole extension name, some abbrevia-
           tion is good enough in most cases.
    
           ? Environment variable $EXTENSION
    
           ? Command line option --extension
    
           ? Appendix  to  the  <name>.<section> argument in the form <name>.<sec-
             tion><extension>
    
           ? Preargument before the name argument in the form <section><extension>
             <name>
    
           For further details on man page searching, see man(1).
    
       Examples of man files
           /usr/share/man/man1/groff.1
                  This  is  an  uncompressed  file  for the man page groff in sec-
                  tion 1.  It can be called by
                  sh# groffer groff
                  No  section  is  specified  here,  so  all  sections  should  be
                  searched,  but  as section 1 is searched first this file will be
                  found first.  The file name is composed of the following  compo-
                  nents.   /usr/share/man must be part of the man path; the subdi-
                  rectory man1/ and the part .1 stand for the  section;  groff  is
                  the name of the man page.
    
           /usr/local/share/man/man7/groff.7.gz
                  The   file   name  is  composed  of  the  following  components.
                  /usr/local/share/man must be part of the man path; the subdirec-
                  tory  man7/  and the part .7 stand for the section; groff is the
                  name of the man page; the final part .gz stands for  a  compres-
                  sion  with gzip(1).  As the section is not the first one it must
                  be specified as well.  This can be done by one of the  following
                  commands.
                  sh# groffer groff.7
                  sh# groffer 7 groff
                  sh# groffer --sections=7 groff
    
           /usr/local/man/man1/ctags.1emacs21.bz2
                  Here  /usr/local/man must be in man path; the subdirectory man1/
                  man  page;  and .Z signifies the compression that can be handled
                  by gzip(1).  We want now show how to provide several values  for
                  some  options.  That is possible for sections and operating sys-
                  tem names.  So we use as sections 5 and 7 and  as  system  names
                  linux and aix.  The command is then
                  sh# groffer --locale=de --sections=5:7 --systems=linux,aix man
                  sh# LANG=de MANSECT=5:7 SYSTEM=linux,aix groffer man
    
    
    

    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-
                  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
           file in /etc comes first; 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 arguments.
    
           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.
    
           If a lines starts with a double minus it represents a groffer long  op-
           tion;  everything behind the first equal sign '=' or space character up
           to the end of the line is interpreted as its argument.  A line starting
           with  a single minus represents a short options cluster with or without
           a final argument.  It is not necessary to use quotes  in  these  lines;
           quotes are just ignored.
    
           The  lines  starting with a minus are changed into a prepend to the ex-
           isting value of $GROFFER_OPT.   So  the  configuration  files  will  be
           transferred into a shell script that is called within groffer.
    
           It  makes  sense  to  use  these  configuration files for the following
           tasks:
    
           ? 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.
    
           ? Preset environment variables recognized by groffer; but do not forget
             to export them.
    
           ? 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.
    
           ? 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
           ? Use a text color of DarkBlue in all viewers that support  this,  such
             as gxditview.
    
           ? 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.
    
           ? 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.
    
           ? 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.
    
           ? 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
    
           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# groffer --de-p --in --ap
                  This is a set of abbreviated arguments, it is determined as
                  sh# groffer --debug-params --intermediate-output --apropos
    
           sh# cat file.gz | groffer -Z -mfoo
                  The file file.gz is sent  to  standard  input,  this  is  decom-
                  pressed,  and then this is transported to the groff intermediate
                  output mode without post-processing  (groff  option  -Z),  using
                  macro package 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
    
           ? 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).
    
           ? 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 repro-
           duced, 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.
    
                  Viewers for groffer's dvi mode.
    
           konqueror(1), epiphany(1), firefox(1), mozilla(1), netscape(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,2006 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.18.1.4 05 October 2006 GROFFER(1)

    
    
  • MORE RESOURCE


  • Linux

    The Distributions





    Linux

    The Software





    Linux

    The News



  • MARKETING






  • Toll Free

webmaster@linuxguruz.com
Copyright © 1999 - 2016 by LinuxGuruz