Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
GROFFER(1)		    General Commands Manual		    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:

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

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

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

       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 argu-
	 ments are interpreted 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  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:

       o graphically display the formatted input with an X window program, in-
	 cluding

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

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

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

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

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

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

       o --locale

       o $GROFFER_OPT

       o $MANOPT

       o $LCALL

       o $LC_MESSAGES

       o $LANG.

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

       _language_[__territory_[._character-set_[,_version_]]],

       but the two-letter code in _language_ is	sufficient for most purposes.

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

       If still	not found the corresponding man	page in	the  default  language
       is  used	 instead.  As usual, this default can be specified by one of C
       or POSIX.  The man pages	in the default language	are  usually  in  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

       o $GROFFER_OPT

       o $MANOPT

       o $SYSTEM.

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

       The search can further be restricted by limiting	 it  to	 certain  sec-
       tions.	A  single  section can be specified within 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:

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

       o allows	 to  start groffer in a	graphical mode even from a text	termi-
	 nal;

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

       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  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						    GROFFER(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | OUTPUT MODES | FILE PARAMETERS | ENVIRONMENT | FILES | EXAMPLES | COMPATIBILITY | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=groffer&sektion=1&manpath=FreeBSD+5.4-RELEASE+and+Ports>

home | help