groffer man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

GROFFER(1)							    GROFFER(1)

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

SYNOPSIS
       groffer [viewing_options] [man_options] [groff_options] [--] [file‐
	       spec...]
       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 automatically.

	      [-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 options 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  formatting process.  Useful groff formatting op‐
	      tions 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 pro‐
	      gram.

	      [--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 implementa‐
	      tions.  The full set of long and short options of	 the  GNU  man
	      program  can be passed via the environment variable $MANOPT; see
	      man(1) if your system has GNU man installed.

       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  sec‐
			tion.

	      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 ar‐
       bitrary documents written in the roff(7) formatting language in several
       different  ways,	 in  an X window viewer 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 functionality of the GNU man program was provided or suitably
       adapted.	  This	makes  the  groffer program 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 decompressed 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 dis‐
       played without formatting.

       The formatting process can be regulated by all options that are	avail‐
       able  groff.  By using the -T option, groffer can be switched to behave
       exactly like groff without using its viewer facilities, but additional‐
       ly 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 preprocessors 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 completeness, 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:

       · single	 character options are always preceded by a single minus char‐
	 acter, for example, -c.

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

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

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

       · An argument of -- ends option parsing; all further command line argu‐
	 ments are interpreted as filespec arguments.

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

       · This  behavior	 can  be  changed  by setting the environment variable
	 $POSIXLY_CORRECT to a non-empty value; in this case, option  process‐
	 ing  is  stopped  as  soon as the first non-option 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 with‐
       in 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 op‐
       tions into groffer.  These options are documented 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	 device	 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	 grof‐
	      fer's  viewer options are not used, but the viewer is configured
	      like in groff with the groff option  -P.	 This  option  is  in‐
	      hereted from groff(1).

       -Z     Switch into groff mode and format the input with groff option -Z
	      ; this produces the groff intermediate output  without  postpro‐
	      cessing;	 see  groff_out(1).   This  an	advanced  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 separat‐
	      ed 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 adaption of the X Toolkit option -bd.  The argument
	      is an X color name, see (1) for details.

       --bg color
	      Set the background color of the viewer window.  This is an adap‐
	      tion  of	the  X Toolkit 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 adap‐
	      tion of the X Toolkit option -bw.

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

       --default
	      Reset  all  configuration from previously processed command line
	      options to the default 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 formatted input is displayed with the xdvi(1)  pro‐
	      gram.

       --dvi-viewer prog
	      Set the viewer program for dvi mode.  This can be a file name or
	      a program to be searched in $PATH.  Known dvi viewers inlude xd‐
	      vi(1) and dvilx(1) In each case, arguments can be provided addi‐
	      tionally.

       --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 adap‐
	      tion of the X Toolkit 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 option -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 position.  See X(1) for details on  the  syntax  of
	      the argument.  If the actual display mode is not X then this op‐
	      tion is ignored.

       --groff
	      Set groff mode.	Switch	groffer	 to  process  the  input  like
	      groff(1).	 This disables the groffer viewing features, all grof‐
	      fer 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	defaults.  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 different mode  was	speci‐
		     fied with $GROFFER_OPT.

	      dvi    Display  formatted input in a dvi viewer program; equiva‐
		     lent to --dvi.

	      pdf    Display formatted input in a PDF (Portable Document  For‐
		     mat) 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);equivalentto --x.

	      The  following  modes  do	 not use the groffer viewing features.
	      They are only interesting for advanced applications.

	      groff  Generate device output with plain groff without using the
		     special  viewing  features	 of groffer.  If no device was
		     specified by option -T the groff default ps is assumed.

	      source Display 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 in‐
	      put 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  dis‐
	      played  graphically  and	is  searchable	nevertheless;  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 device that is compatible to
	      this mode is ps, which is also the default  when	no  device  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 supported dpi values are 75 and 100.  This is an adap‐
	      tion 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 option); if so, the script is
	      rerun under the shell program specified with  the	 option	 argu‐
	      ment.

       --source
	      Equivalent to -Q.

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

       --title 'some text'
	      Set the title for the viewer window.  This feature is not avail‐
	      able 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; eqivalent 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  ex‐
	      istence of a sequence of standard web browsers is tested, start‐
	      ing with mozilla(1) and netscape(1)

       --www-viewer prog
	      Set the web browser program for viewing in www mode.  Each  pro‐
	      gram  that  accepts  html	 input	and  allows  the file://local‐
	      host/dir/file syntax on the command line is suitable; 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  format‐
	      ted input is displayed with the gxditview(1) program, being dis‐
	      tributed together with groff, or with xditview(1), which is dis‐
	      tributed	as a standard X tool.  This can be configured with op‐
	      tion --x-viewer.	The only devices (option -T) that are compati‐
	      ble  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 exe‐
	      cutable file or a program in $PATH.  In each case, arguments can
	      be provided additionally.

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

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

OUTPUT MODES
       By default, the groffer program formats the input and then automatical‐
       ly chooses a suitable display mode, but the user can  also  choose  be‐
       tween the following modes:

       · graphically display the formatted input with an X window program, in‐
	 cluding

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

	 · in a dvi viewer program (dvi mode),

	 · in a Postscript viewer (ps mode),

	 · in a PDF viewer (pdf mode),

	 · in a web browser (www mode),

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

       · run groffer like groff, but with decompression and man page searching
	 (groff mode); this includes things like generating the groff interme‐
	 diate output.

       · 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  ac‐
       tive in every mode.

   Graphical Display Modes
       The  graphical  display modes work only in the X window environment (or
       similar implementations within other windowing environments).  The  en‐
       vironment variable $DISPLAY or the option --display are used for speci‐
       fying the X display to be used; if neither is  specified,  groffer  as‐
       sumes 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 groffer switches to tty mode.

       The  graphical  modes  can be customized by options that were named ac‐
       cording 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 output 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 environ‐
       ment 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 only the	 options  provided  by
	      groff.   This enables the user to save the generated output into
	      a file or pipe it into another program.  In this mode, the input
	      is  formatted,  but  not postprocessed; see groff_out(5) for de‐
	      tails.  This mode is activated 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 inter‐
	      mediate 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 pa‐
       rameter 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 search‐
	      ing 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 correspond‐
	      ing 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 let‐
	      ters `o' and `n'.

       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.

   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 digested previously by	someone	 else.
       With  the excellent performance of the actual computers, the preformat‐
       ted 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 environments in networks.

       The algorithm for retrieving man pages uses five search methods.	  They
       are successively tried until a method works.

       · The  search  path  can	 be  manually  specified  by  using the option
	 --manpath.  An empty argument disables the man page searching.	  This
	 overwrites the other methods.

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

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

       · If  this does not work, the manpath(1) program for determining a path
	 of man directories is tried.

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

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

       · --locale

       · $GROFFER_OPT

       · $MANOPT

       · $LCALL

       · $LC_MESSAGES

       · $LANG.

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

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

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

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

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

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

       · $GROFFER_OPT

       · $MANOPT

       · $SYSTEM.

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

       The search can further be restricted by limiting	 it  to	 certain  sec‐
       tions.	A  single  section can be specified within 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	decom‐
       pressed	on-the-fly.   This  includes the GNU .gz, .bz2, and the tradi‐
       tional .Z compression.  The program displays the concatenation  of  all
       decompressed  input  in	the sequence that was specified on the command
       line.

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

   Native groffer Variables
       $GROFFER_OPT
	      Store options for a run of groffer.  The	options	 specified  in
	      this variable are overridden by the options given on the command
	      line.  The content of this variable is  run  through  the	 shell
	      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 corre‐
       sponding system environment is automatically effective.	The  following
       variables have a special meaning for groffer.

       $DISPLAY
	      If  this variable is set this indicates that the X window system
	      is running.  Testing this variable decides on whether  graphical
	      or  text	output	is  generated.	 This  variable	 should not be
	      changed by the user carelessly, but it can be used to start  the
	      graphical	 groffer on a remote X terminal.  For example, depend‐
	      ing on your system, groffer can be started on the second monitor
	      by the command
	      sh# DISPLAY=:0.1 groffer what.ever&

       $LC_ALL
       $LC_MESSAGES
       $LANG  If  one  of  these variables is set (in the above sequence), its
	      content is interpreted as the locale, the language to  be	 used,
	      especially when retrieving man pages.  A locale name is typical‐
	      ly of the form language[_territory[.codeset[@modifier]]],	 where
	      language	is  an ISO 639 language code, territory is an ISO 3166
	      country code, and codeset is a character set or encoding identi‐
	      fier  like  ISO-8859-1  or  UTF-8; see setlocale(3).  The locale
	      values C and POSIX stand for the default, i.e. the man page  di‐
	      rectories	 without a language prefix.  This is the same behavior
	      as when all 3 variables are unset.

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

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

       $POSIXLY_CORRECT
	      If set to a non-empty value this chooses the POSIX mode for  op‐
	      tion  processing, that means that option processing will be fin‐
	      ished 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 vari‐
       ables 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  directo‐
	      ry,  groffer  uses  it  for storing its temporary files, just as
	      groff does.

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

       $EXTENSION
	      Restrict	the  search  for man pages to files having this exten‐
	      sion.  This is overridden by option --extension; see  there  for
	      details.

       $MANOPT
	      This  variable  contains options as a preset for man(1).	As not
	      all of these are relevant for groffer only the  essential	 parts
	      of its value are extracted.  The options specified in this vari‐
	      able overwrite the values of  the	 other	environment  variables
	      taht  are	 specific to man.  All options specified in this vari‐
	      able are overridden by the options given on the command line.

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

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

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

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

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  de‐
	      notes  the  user's  home directory.  This script is called after
	      the system-wide configuration file to enable overriding  by  the
	      user.

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

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

       · 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 provided by the

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

       As an example, consider the following configuration file.

       #! /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:

       · allows	 to  start groffer in a graphical mode even from a text termi‐
	 nal;

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

       · the gxditview(1) program is told to use DarkBlue as the  text	color.
	 These configurations 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 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 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 special shell characters; escaping them  with  a
	      backslash	 character \( and \) would be possible, too.  The for‐
	      matted 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 re‐
	      trieved, even when a local file ls exists in the actual directo‐
	      ry.

       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 post‐
	      process 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,  us‐
	      ing 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 restrict‐
       ed 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 implemen‐
       tations 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:

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

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

       · try ash; if not available

       · 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  op‐
	      tions 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 docu‐
	      ments  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 Docu‐
       mentation  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)
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net