Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for groffer (opendarwin section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


GROFFER(1)									       GROFFER(1)

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

SYNOPSIS
       groffer [viewing_options] [man_options] [groff_options] [--] [filespec...]
       groffer -h|--help
       groffer -v|--version

       viewing_options
	      These  options  determine  and  configure the display mode.  They were synchronized
	      with the options of both groff(1) and GNU man(1).  As groff uses almost any  letter
	      in its option set, only long option names are available for most features.  If none
	      of these options is used groffer tries to find a suitable display mode automatical-
	      ly.

	      [-Q|--source]    [-T|--device device]   [--auto-modes mode1,mode2,...]	[--debug]
	      [--default]   [--dvi]   [--dvi-viewer prog]    [--groff]	  [--location]	  [--mode
	      display_mode]  [--pager program]	[--pdf]  [--pdf-viewer prog]  [--ps] [--ps-viewer
	      prog] [--shell] [--tty] [--www] [--www-viewer prog] [--x] [--x-viewer prog]

	      The following long options were adapted from the corresponding  X  Toolkit  options
	      with a single leading minus; see X(1).

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

       groff_options
	      Any  combination	of (short) options from the groff(1) program is accepted; the op-
	      tions that are not explicitly handled by groffer are transparently passed to groff.
	      Due  to the automatism in groffer, none of these groff options should be necessary,
	      except for advanced usage.

	      Because of the special outputting behavior of the groff options  -V,  -X,  and  -Z,
	      groffer  was  designed  to be switched into groff mode by each of these options; in
	      this mode, the groffer viewing features are disabled.

	      The other groff options do not switch the mode, but allow to customize the  format-
	      ting  process.  Useful groff formatting options include -m (to add macro files that
	      cannot be recognized by grog), and -T (to specify an  alternative  device  for  the
	      modes tty and x).

       man_options
	      These options regulate whether and how man pages are searched.  They are compatible
	      with the long options of the GNU man program.

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

	      The  GNU	man long options that are not mentioned are recognized, but they are just
	      ignored because of alternative implementations.  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) if your system has GNU man installed.

       filespec
	      is a sequence of file names or templates for searching man pages,  see  man(1).	A
	      filespec can have one of the following forms.

	      filename	the path name of an existing file.

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

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

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

	      man:name	search the man page name in the lowest available section.

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

	      name.section
			search the man page name in section section.

	      standard_section
			if  this  is `1', ..., `9', `o', or `n' try to retrieve the next argument
			as a man page in this section.

	      name	search for the man page name in the lowest available section.

	      No filespec parameters means standard input.

       For details on the options, see section OPTIONS.

DESCRIPTION
       The groffer program is part of groff(7).  It can be used to  display  arbitrary	documents
       written in the roff(7) formatting language in several different ways, in an X window view-
       er program or in a text terminal.  The viewer programs can be chosen as the  groff  native
       viewer gxditview(1), a Postcript or dvi display program, or a web browser.

       A search facility for manual pages ( man pages) is provided.  Almost the whole functional-
       ity of the GNU man program was provided or suitably adapted.  This makes the groffer  pro-
       gram a valuable tool on systems with a poor man system.

       The  program  always  concatenates all input specified by the non-option parameters of the
       calling command line or standard input.	Compressed standard input  or  files  are  decom-
       pressed on-the-fly.

       Normally, the input is run through the groff(1) text processor before being displayed.  By
       using the option -Q, the roff source code is displayed without formatting.

       The formatting process can be regulated by all options that are available groff.  By using
       the  -T	option,  groffer  can  be switched to behave exactly like groff without using its
       viewer facilities, but additionally with the search and decompression features.

       All necessary options can be determined automatically.  For example, the  groffer  program
       internally  uses the grog(1) program to determine from the unformatted document which pre-
       processors should be run and which macro files should be included.  But all parts  of  the
       program can be controlled manually by suitable options.

OPTIONS
       The groffer program provides its own parser for command line options that is compatible to
       both POSIX getopts(1) and GNU getopt(1).  The command line behaves as usually.	For  com-
       pleteness, the details are provided here.

   Option Parsing
       The  following types of options are supported, equally on all systems that are able to run
       the groffer program:

       o single character options are always preceded by a single minus character,  for  example,
	 -c.

       o the  argument for a single character option is the next command line argument, for exam-
	 ple, -o  arg, or can be appended to the option character within  the  same  argument  -o
	 arg.

       o clusters  of such single character options without an argument, eventually terminated by
	 a single character option with an argument;  for  example,  -abo arg  is  equivalent  to
	 -a -b -o arg .

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

       o An argument of -- ends option parsing; all further command line arguments are interpret-
	 ed as filespec arguments.

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

       o This  behavior  can be changed by setting the environment variable $POSIXLY_CORRECT to a
	 non-empty value; in this case, option processing is stopped as soon as the first non-op-
	 tion argument is found.  For example, in posixly correct mode, the command line
	 sh# groffer file1 -a -o arg file 2
	 is equivalent to
	 sh# groffer -- file1 -a -o arg file 2
	 As  this  leads  to  unwanted	behavior  in  most  cases, most people do not want to set
	 $POSIXLY_CORRECT.

   Compatibility with Options from other Programs
       All short options of groffer are compatible with the short options of groff(1).	 Some  of
       the  groff  options  were given a special meaning within groffer.  All other groff options
       are supported by groffer, but they are just transparently transferred to groff without any
       intervention.   Therefore  these  transparent  options  are  not  documented  here, but in
       groff(1).

       All long options of groffer are compatible with the long options of man(1).  Most  of  the
       man long options were implemented as native options into groffer.  These options are docu-
       mented in the following; the other man options are recognized, but ignored.

   Native groffer Options
       -h     Print usage message to standard error and exit.

       -Q     Output the roff source code of the input files unprocessed.  This is the equivalent
	      --mode source.

       -T devname
	      Switch to --mode device, thus disabling the groffer viewing.  Instead, the input is
	      formatted and postprocessed using plain groff with devname as  the  output  device.
	      The  allowed device names are listed in groff(1).  Note that this forces all device
	      names that begin with the letter X to be displayed with gxditview(1); all other de-
	      vice  names generate output for the specified device; this is printed onto standard
	      output without a pager.

       -v     Print version information onto standard error.

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

       -X     Switch into groff mode and format the input with groff option  -X;  actually,  this
	      formats  the  input and displays it with gxditview(1).  This differs from groffer's
	      mode x because groffer's viewer options are not used, but the viewer is  configured
	      like in groff with the groff option -P.  This option is inhereted from groff(1).

       -Z     Switch into groff mode and format the input with groff option -Z; this produces the
	      groff intermediate output without postprocessing; see groff_out(1).   This  an  ad-
	      vanced option from groff(1), useful for debugging.

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

       --apropos
	      Instead  of  displaying,	start the `apropos' command for searching within man page
	      descriptions; only kept for compatibility with `man'.

       --auto-modes mode1,mode2,...
	      Set the sequence of modes for default mode to the comma separated list given in the
	      argument.

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

       --bd pixels
	      Specifies  the color of the border surrounding the viewer window.  This is an adap-
	      tion of the X Toolkit option -bd.  The argument is an X color name, see(1) for de-
	      tails.

       --bg color
	      Set  the background color of the viewer window.  This is an adaption of the X Tool-
	      kit option -bg.  The argument is an X color name, see(1) for details.

       --bw pixels
	      Specifies the width in pixels of the border  surrounding	the  viewer  window  (not
	      available for all viewers).  This is an adaption of the X Toolkit option -bw.

       --debug
	      Print  debugging information.  Actually, a function call stack is printed if an er-
	      ror occurs.

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

       --device
	      Eqivalent to -T.

       --display X-display
	      Set the X display on which the viewer program shall be started, see  X(1)  for  the
	      syntax of the argument.

       --ditroff
	      Eqivalent to -Z.	This is kept for compatibiliy with GNU man(1).

       --dvi  Choose  dvi mode; the formatted input is displayed with the by default, the format-
	      ted input is displayed with the xdvi(1) program.

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

       --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.  Originates from GNU man.

       --foreground color
	      This is equivalent to -fg.

       --fg color
	      Set the foreground color of the viewer window.  This is an adaption of the X  Tool-
	      kit option -bg.  The argument is an X color name, see(1) for details.

       --font font_name
	      This is equivalent to -ft.

       --ft font_name
	      Set  the	font used by the viewer window.  This is an adaption of the X Toolkit op-
	      tion -ft.  The argument is an X font name, see(1) for details.

       --geometry size_pos
	      Set the geometry of the display window, that means its size and its starting  posi-
	      tion.   See  X(1) for details on the syntax of the argument.  If the actual display
	      mode is not X then this option is ignored.

       --groff
	      Set groff mode.  Switch groffer to process the input like groff(1).  This  disables
	      the groffer viewing features, all groffer viewing options are ignored.

       --help Eqivalent to -h.

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

       --locale language
	      Set the language for man pages.  This option originates from GNU man(1).

       --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 if it is an existing file.

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

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

	      auto   Display  in  the default manner; this actually means to try the modes ps, x,
		     and tty in this sequence.	Useful for restoring default mode when a  differ-
		     ent mode was specified with $GROFFER_OPT.

	      dvi    Display formatted input in a dvi viewer program; equivalent to --dvi.

	      pdf    Display  formatted input in a PDF (Portable Document Format) viewer program;
		     equivalent to --pdf.

	      ps     Display formatted input in a Postscript viewer program; equivalent to --ps.

	      tty    Display formatted input in a text terminal; equivalent to --tty.

	      www    Display formatted input in a internet browser program; equivalent to --www.

	      x      Display formatted input in a native roff viewer such as gxditview(1);equiva-
		     lentto --x.

	      The  following modes do not use the groffer viewing features.  They are only inter-
	      esting 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 de-
		     fault ps is assumed.

	      source Display source code; same as -Q.

       --no-location
	      Do not display the location of retireved	files;	this  resets  a  former  call  to
	      --location.

       --no-man
	      Do not check for man pages.

       --pager
	      Set the pager program in tty mode; default is less.

       --pdf  Choose  pdf mode (Portable Document Format).  By default, the input is formatted by
	      groff using the Postscript device, then it is transformed into the PDF file  format
	      using  gs(1) (this is quite slow), and finally displayed either with the xpdf(1) or
	      the acroread(1) program; this can be configured with option --viewer-pdf.  PDF  has
	      a  big advantage because the text is displayed graphically and is searchable never-
	      theless; but as thtransformation into pdf takes a considerable amount of time,  the
	      pdf  mode  is  not suitable as a default device for the auto mode.  The only device
	      that is compatible to this mode is ps, which is also the default when no device  is
	      specified.

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

       --ps   Choose ps mode (Postscript).  By default, the formatted input is displayed with the
	      ghostview(1) program; this can be configured with option --viewer-ps.  The only de-
	      vice that is compatible to this mode is ps, which is also the default when  no  de-
	      vice is specified.

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

       --resolution value
	      Set X resolution in dpi (dots per inch) in some viewer programs.	The only support-
	      ed dpi values are 75 and 100.   This  is	an  adaption  of  the  X  Toolkit  option
	      -resolution.

       --rv   Reverse  foreground and background color of the viewer window.  This is an adaption
	      of the X Toolkit option -rv.  This feature is not available in all viewer programs.

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

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

       --source
	      Equivalent to -Q.

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

       --title 'some text'
	      Set the title for the viewer window.  This feature is not available in  all  viewer
	      programs.

       --to-postproc opt_or_arg
	      Eqivalent to -P.

       --troff-device
	      Eqivalent to -T.	This option is only kept for compatibility with GNU man(1).

       --tty  Choose tty display mode, that means displaying in a text pager even when in X; eqi-
	      valent to --mode tty.

       --version
	      Eqivalent to -v.

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

       --where
	      Eqivalent to --location.

       --www  Choose  www  mode  (html), display in a web browser program, which can be specified
	      with option --www-viewer.  By default, the existence of a sequence of standard  web
	      browsers is tested, starting with mozilla(1) and netscape(1)

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

       --x    Choose x mode (view in X roff viewer).  By default, the  formatted  input  is  dis-
	      played  with  the  gxditview(1)  program, being distributed together with groff, or
	      with xditview(1), which is distributed as a standard X tool.  This can  be  config-
	      ured with option --x-viewer.  The only devices (option -T) that are compatible with
	      this mode are X75, X100, X75-12, X100-12, and ps (the default device).

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

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

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

OUTPUT MODES
       By  default,  the groffer program formats the input and then automatically chooses a suit-
       able display mode, but the user can also choose between the following modes:

       o graphically display the formatted input with an X window program, including

	 o with X window roff viewers such as gxditview(1) (x mode),

	 o in a dvi viewer program (dvi mode),

	 o in a Postscript viewer (ps mode),

	 o in a PDF viewer (pdf mode),

	 o in a web browser (www mode),

       o display formatted input in a pager on the text terminal (tty mode),

       o run groffer like groff, but with decompression and man page searching (groff mode); this
	 includes things like generating the groff intermediate output.

       o stream the unformatted source code of the input onto standard output (source mode),

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

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

   Graphical Display Modes
       The  graphical display modes work only in the X window environment (or similar implementa-
       tions within other windowing environments).  The environment variable $DISPLAY or the  op-
       tion  --display are used for specifying the X display to be used; if neither is specified,
       groffer assumes that no X is running.

       A certain graphical display mode can be selected by one of the options --dvi, --pdf, --ps,
       -X,  and --www.	By default, some graphical modes are tried first.  If none succeeds grof-
       fer switches to tty mode.

       The graphical modes can be customized by options that were named according to the resource
       options	in  the X(1) Toolkit but using a leading double minus instead of the single minus
       used by X.  These include --background, --foreground, --geometry,  --resolution,  --title,
       --xrm, etc.

       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  a long time to transform the input into the PDF format, so it was not chosen as
       the major mode.	You can change this by the options --pdf and --auto-modes.

   Displaying on a tty
       If the variable $DISPLAY is not set or empty, groffer assumes that it should produce  out-
       put on a text terminal.	This mode can also be forced by option --tty.

       In  the	actual implementation, the groff output device latin1 is chosen and the processed
       output is piped into a pager program.  This can be changed  by  specifying  option  --tty-
       device.

       The  pager  to  be  used  can  be  specified by option --pager by the environment variable
       $PAGER.	If this is not set or empty the less(1) program is used as the default pager.

   Non-displaying Modes
       There are some special modes that do not display the formatted output in a viewer program.
       These modes are regarded as advanced, they are useful for debugging purposes.

       source mode
	      Instead  of  displaying  the formatted output, it is also possible to have the roff
	      source code streamed onto the standard output.  This mode must be requested by  one
	      of the options -Q or --source.

       groff mode
	      This  mode  disables the groffer viewing facilities.  The input is handled as usual
	      with decompression and man page searching, but then it is passed to groff using on-
	      ly the options provided by groff.  This enables the user to save the generated out-
	      put into a file or pipe it into another program.	In this mode, the input  is  for-
	      matted, but not postprocessed; see groff_out(5) for details.  This mode is activat-
	      ed automatically by the three groff options -V (print roff pipe, no formatting), -X
	      (display	with gxditview in groff's native way, using -P for customization), and -Z
	      (disable post-processing, thus producing the groff intermediate output).

FILE PARAMETERS
       The non-option command line parameters determine which files should be displayed.

   Filespecs
       The default behavior of groffer is to first test whether the file parameter is  represents
       a  local  file;	if  not,  it is assumed to represent a filespec for searching one or more
       man page.  This behavior can be modified by options.

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

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

       The following parameter formats are recognized to represent a wanted man page.

       man:name(section)
	      the quasi-URL notation used in many Desktop systems to represent the man page  name
	      in section.

       man:name
	      search the man page name in the lowest section.  The corresponding command with the
	      man program would be
	      sh# man name

       name.section
	      the man page name in section.  The corresponding command with the man program would
	      be
	      sh# man section name

       name   if  name is not an existing file search for the man page name in the lowest section
	      just like
	      sh# man name

       section name
	      Even this curious construct known from the various man programs  is  handled.   For
	      example,
	      sh# groffer 7 groff
	      was modelled according to
	      sh# man 7 groff
	      retrieves the man page named groff in section 7.	Only a few standard section names
	      are accepted, being actually the number sections 1, 2, 3, 4, 5, 6, 7, 8, and 9, and
	      the lower case letters `o' and `n'.

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

   Man Page Searching
       The groffer program provides a search facility for system manual pages (man  pages).   All
       long  options,  all environment variables, and most of the functionality of the GNU man(1)
       program were implemented.

       Preformatted man pages (cat pages) are intentionally  excluded  from  the  search  because
       groffer is a roff program that wants to format by its own, not spit out stuff that was di-
       gested previously by someone else.  With the excellent performance of the  actual  comput-
       ers,  the preformatted man pages aren't necessary any longer.  Due to their inflexible na-
       ture, they tend to provoke some trouble with changing line lengths and different  environ-
       ments in networks.

       The  algorithm  for  retrieving 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 argu-
	 ment 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, the manpath(1) program for determining a path of man directories
	 is tried.

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

       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 ex-
       ample, both /usr/share/man/linux/fr and /usr/share/man/fr/linux for french linux man pages
       are  found.   The language and operating system names are determined from both environment
       variables and command line options.

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

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

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

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

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

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

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

       o $GROFFER_OPT

       o $MANOPT

       o $SYSTEM.

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

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

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

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

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

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

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

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

       $DISPLAY
	      If  this variable is set this indicates that the X window system is running.  Test-
	      ing this variable decides on whether graphical or text output is	generated.   This
	      variable	should not be changed by the user carelessly, but it can be used to start
	      the graphical groffer on a remote X terminal.  For example, depending on your  sys-
	      tem, 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 interpret-
	      ed as the locale, the language to be used, especially when retrieving man pages.	A
	      locale  name  is	typically  of the form language[_territory[.codeset[@modifier]]],
	      where language is an ISO 639 language code, territory is an ISO 3166 country  code,
	      and codeset is a character set or encoding identifier like ISO-8859-1 or UTF-8; see
	      setlocale(3).  The locale values C and  POSIX  stand  for  the  default,	i.e.  the
	      man  page directories without a language prefix.	This is the same behavior as when
	      all 3 variables are unset.

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

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

       $POSIXLY_CORRECT
	      If set to a non-empty value this chooses the POSIX mode for option processing, that
	      means that option processing will be finished as soon as a non-option  argument  is
	      found.  Usually, you do not want to set this environment variable.

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

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

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

       $EXTENSION
	      Restrict the search for man pages to files having this extension.  This is overrid-
	      den 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  op-
	      tions  specified	in  this  variable  overwrite the values of the other environment
	      variables taht are specific to man.  All options specified  in  this  variable  are
	      overridden by the options given on the command line.

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

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

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

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

FILES
       The  groffer  program  can  be preconfigured by two configuration files.  Both of them are
       shell scripts that are called at the beginning of groffer using the `. filename' syntax.

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

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

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

       o Preset environment variables recognized by groffer; preferably a variable should only be
	 set when it is unset in order not to override a user-provided value.

       o Preset  command  line	options  by prepending them to $GROFFER_OPT; prepending should be
	 preferred to appending and setting in order not to delete the environment variable  pro-
	 vided by the

       o Write	functions  for	calling  viewer  programs in a special way and feed them into the
	 --*-viewer options.  Note that the name of such a function must coincide with	some  ex-
	 isting program in the system path $PATH in order to be recognized by groffer.

       As an example, consider the following configuration file.

       #! /bin/sh
       # ~/.groff/groffer.conf
       if test "$DISPLAY" = ""; then
	 DISPLAY='localhost:0.0';
       fi;
       GROFF_OPT="--resolution=100 $GROFF_OPT";
       gxditview()
       {
	 /usr/local/bin/gxditview --fg DarkBlue "$@";
       }

       This has the following effects:

       o allows to start groffer in a graphical mode even from a text terminal;

       o all graphical modes use a resolution of 100 dpi where applicable;

       o the  gxditview(1)  program  is told to use DarkBlue as the text color.  These configura-
	 tions	can  be  overridden  by  command  line	options  and  by   environment	 variable
	 $GROFFER_OPT.

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

       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 a default graphical viewer when in X  window,  or
	      the less(1) pager program when not in X.

       sh# groffer groff.7 groff 'troff(1)' man:roff
	      The arguments that are not existing files are looked-up as the following man pages:
	      groff (in section 7), groff (automatic search, should be found in 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 concatenated and displayed in one piece.

       sh# LANG=de groffer --man --www --www-viever=netscape ls
	      Retrieve the German man page for the ls program (or the English one if there  is	a
	      German  version), decompress it, format it into the html format and view the result
	      in the default web browser  netscape  .	The  option  --man  guarantees	that  the
	      man page is retrieved, even when a local file ls exists in the actual directory.

       sh# groffer -Q 'man:roff(7)'
	      Print  the unformatted content of the man page called roff in section 7 on standard
	      output.

       sh# groffer -Z -mfoo
	      Decompress the standard input, switch to groff mode, format the  input  with  groff
	      using  the macro package foo, but do not postprocess the result, thus producing the
	      intermediate output.

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

COMPATIBILITY
       The  groffer shell script is compatible to both POSIX and GNU.  POSIX compatibility refers
       to IEEE P1003.2/D11.2 of September 1991, a very	early  version	of  this  standard.   The
       script  uses  only  a  quite restricted set of shell language elements and shell builtins,
       common to all POSIX versions; the only external program used is `sed', again only the most
       basic  POSIX  features  of  `sed' are used.  The groffer script should work on most actual
       free and commercial operating systems.

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

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

       The best performance was obtained with the ash shell; so groffer tries to  run  under  ash
       whenever  possible.  The procedure to determine the shell to run groffer was programmed to
       be as follows:

       o the argument of the command line option --shell; if not set

       o the argument of the option --shell in the environment variable $GROFF_OPT; if not set

       o try ash; if not available

       o continue with the shell under which the script was started in the first place.

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

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

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

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

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

       xpdf(1)
	      Viewers for pdf files.

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

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

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

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

       This document is distributed under the terms of the FDL (GNU Free  Documentation  License)
       version	1.1  or  later.  You should have received a copy of the FDL on your system, it is
       also available on-line at the GNU copyleft site <http://www.gnu.org/copyleft/fdl.html>.

       This document is part of groff, the GNU roff distribution.  It was written by Bernd Warken
       <bwarken@mayn.de>.

Groff Version 1.18.1			    Nov  2003				       GROFFER(1)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 02:37 PM.