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 [option...]  [--] [filespec...]
       groffer --apropos|--apropos-data|--apropos-devel|--apropos-progs	name
       groffer -h|--help
       groffer -v|--version

DESCRIPTION
       The groffer program is the easiest way to use groff(1).	It can display
       arbitrary documents written in the groff(7) language or	other  roff(7)
       languages  that	are  compatible	 to  the original troff	language.  The
       groffer program also includes many of the features for finding and dis-
       playing	the UNIX manual	pages (man pages), such	that it	can be used as
       a replacement for a man(1) program.  Moreover,  compressed  files  that
       can be handled by gzip(1) or bzip2(1) are decompressed on-the-fly.

       The  normal usage is quite simple by supplying a	file name or name of a
       man page	without	further	options.  But the  option  handling  has  many
       possibilities for creating special behaviors.  This can be done in con-
       figuration files, with the shell	environment variable $GROFFER_OPT,  or
       on the command line.

       The output can be generated and viewed in several different ways	avail-
       able for	groff.	This includes the groff	native X viewer	 gxditview(1),
       each Postcript or dvi display program, a	web browser by generating html
       in www-mode, or several text modes in text terminals.

       Most of the options that	must be	named when running groff directly  are
       determined  automatically for groffer, due to the internal usage	of the
       grog(1) program.	 But all parts can also	be controlled manually by  ar-
       guments.

       Several	file  names  can  be  specified	on the command line arguments.
       They are	transformed into a single document in the normal way of	groff.

OPTION OVERVIEW
       breaking	options

	      [--apropos name]	[--apropos-data	name]	[--apropos-devel name]
	      [--apropos-progs name] [-h|--help] [-v|--version]

       groffer mode options

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

       development options

	      [--debug]	[--shell]

       options related to groff

	      [-P|--postproc-arg opt_or_arg]	[-Q|--source]	  [-T|--device
	      device] [-Z|--intermediate-output|--ditroff]

	      All further groff	short options are accepted.

       X Window	toolkit	options

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

       options from man

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

	      Further long options of GNU man are accepted as well.

       filespec	argument

	      No filespec parameters means standard input.

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

	      filename	the path name of an existing file.

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

	      man:name.s
	      name.s	if  s is a character in	[1-9on], search	for a man page
			name in	man section s.

	      man:name	man page in the	lowest man section that	has name.

	      s	name	if s is	a character in [1-9on],	search for a man  page
			name in	man section s.

	      name	if  name  is  not  an  existing	 file  search  for the
			man page name in the lowest man	section.

OPTION DETAILS
       The groffer program can usually be run with very	few options.  But  for
       special purposes, it supports many options.  These can be classified in
       5 option	classes.

       All short options of groffer are	compatible with	the short  options  of
       groff(1).  All long options of groffer are compatible with the long op-
       tions of	man(1).

   groffer breaking Options
       As soon as one of these options is found	on the command line it is exe-
       cuted, printed to standard output, and the running groffer is terminat-
       ed thereafter.  All other arguments are ignored.

       --apropos name
	      Start the	apropos(1) command for searching within	man  page  de-
	      scriptions.   That slightly differs from the strange behavior of
	      the --apropos program of man(1), which has no  argument  of  its
	      own,  but	 takes	the  file arguments instead.  Practically both
	      concepts are compatible.

       --apropos-data name
	      Show only	the apropos(1) descriptions for	data documents,	in the
	      man(7) sections 4, 5, and	7.

       --apropos-devel name
	      Show only	the apropos(1) descriptions for	development documents,
	      in the man(7) sections 2,	3, and 9.

       --apropos-progs name
	      Show only	the apropos(1) descriptions for	documents on programs,
	      in the man(7) sections 1,	6, and 8.

       -h | --help
	      Print  a	helping	information with a short explanation of	option
	      sto standard output.

       -v | --version
	      Print version information	to standard output.

   groffer Mode	Options
       The display mode	and the	viewer programs	are determined	by  these  op-
       tions.	If  none of these mode and viewer options is specified groffer
       tries to	find a suitable	display	mode automatically.

       --auto Equivalent to --mode=auto.

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

       --default-modes mode1,mode2,...
	      Set the sequence of modes	for auto mode to the  comma  separated
	      list  given  in  the argument.  See --mode for details on	modes.
	      Display in the default manner; actually, this means to  try  the
	      modes x, ps, and tty in this sequence.

       --dvi  Equivalent to --mode=dvi.

       --dvi-viewer prog
	      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.

       --groff
	      Equivalent to --mode=groff.

       --html Equivalent to --mode=html.

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

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

	      auto   Select the	automatic determination	of the	display	 mode.
		     The  sequence of modes that are tried can be set with the
		     --default-modes option.  Useful for restoring the default
		     mode when a different mode	was specified before.

	      dvi    Display  formatted	input in a dvi viewer program.	By de-
		     fault, the	formatted input	is displayed with the  xdvi(1)
		     program.  --dvi.

	      groff  After  the	 file determination, switch groffer to process
		     the input like groff(1) would do  .   This	 disables  the
		     groffer viewing features.

	      html   Translate	the input into html format and display the re-
		     sult in a web browser program.  By	default, the existence
		     of	 a sequence of standard	web browsers is	tested,	start-
		     ing with konqueror(1)  and	 mozilla(1).   The  text  html
		     viewer is lynx(1).

	      pdf    Display  formatted	input in a PDF (Portable Document For-
		     mat) viewer program.  By default, the input is  formatted
		     by	 groff	using the Postscript device, then it is	trans-
		     formed into the PDF file format using gs(1), and  finally
		     displayed either with the xpdf(1) or the acroread(1) pro-
		     gram.  PDF	has a big advantage because the	text  is  dis-
		     played graphically	and is searchable as well.  But	as the
		     transformation takes a considerable amount	of time,  this
		     mode  is  not  suitable  as a default device for the auto
		     mode.

	      ps     Display formatted input in	a Postscript  viewer  program.
		     By	 default,  the	formatted  input is displayed with the
		     ghostview(1) program.

	      text   Format in a groff text mode and write the result to stan-
		     dard  output without a pager or viewer program.  The text
		     device, latin1 by default,	can be chosen with option -T.

	      tty    Format in a groff text mode and write the result to stan-
		     dard  output  using  a text pager program,	even when in X
		     Window.

	      www    Equivalent	to --www.

	      X	     Display formatted input in	a native roff viewer.  By  de-
		     fault,   the   formatted  input  is  displayed  with  the
		     gxditview(1) program,  being  distributed	together  with
		     groff,  or	 with  xditview(1),  which is distributed as a
		     standard X	tool.

	      x	     Equivalent	to --mode=X.

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

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

	      source Display  the source code of the input without formatting;
		     equivalent	to -Q.

       --pdf  Equivalent to --mode=pdf.

       --pdf-viewer prog
	      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   Equivalent to --mode=ps.

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

       --text Equivalent to --mode=text.

       --tty  Equivalent to --mode=tty.

       --tty-viewer
	      Choose  tty  display mode, that means displaying in a text pager
	      even when	in X; eqivalent	to --mode=tty.

       --www  Equivalent to --mode=www.

       --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  as	viewer
	      program; it can be the path name of an executable	file or	a pro-
	      gram in $PATH.  In each case, arguments can  be  provided	 addi-
	      tionally.

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

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

Options	for Development
       --debug
	      Print debugging information for development only.	  Actually,  a
	      function call stack is printed if	an error occurs.

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

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

       Other useful debugging options are the groff options -V and -Z and  op-
       tion --mode=groff.

Options	related	to groff
       All  short  options of groffer are compatible with the short options of
       groff(1).  The following	of groff options  have	either	an  additional
       special meaning within groffer or make sense for	normal usage.

       Because	of the special outputting behavior of the groff	options	-V and
       -Z groffer was designed to be switched into groff mode  by  these;  the
       groffer	viewing	 features are disabled there.  The other groff options
       do not switch the mode, but allow to customize the formatting process.

       -a     This generates an	ascii approximation of output in  text	modes.
	      That  could  be  important when the text pager has problems with
	      control sequences.

       -m file
	      Add file as a groff macro	file.  This is useful in case it  can-
	      not be recognized	automatically.

       -P opt_or_arg
	      Send  the	argument opt_or_arg as an option or option argument to
	      the actual groff postprocessor.

       -T | --device devname
	      This option determines groff's output device.  The  most	impor-
	      tant  devices  are  the text output devices for referring	to the
	      different	character sets,	such as	ascii, utf8, latin1, and  oth-
	      ers.   Each of these arguments switches groffer into a text mode
	      using this device, to mode tty if	the actual mode	is not a  text
	      mode.   The following devname arguments are mapped to the	corre-
	      sponding groffer --mode=devname option: dvi, html, and ps.   All
	      X*  arguments are	mapped to mode X.  Each	other devname argument
	      switches to mode groff using this	device.

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

       -X     was made equivalent to --mode=x; this slightly enhances the  fa-
	      cility of	groff's	option.

       -Z | --intermediate-output | --ditroff
	      Switch  into groff mode and format the input with	groff interme-
	      diate output without postprocessing; see groff_out(1).  This  is
	      equivalent  to  option  --ditroff	 of  man, which	can be used as
	      well.

       All other groff options are supported by	groffer,  but  they  are  just
       transparently  transferred  to groff without any	intervention.  The op-
       tions that are not explicitly  handled  by  groffer  are	 transparently
       passed to groff.	 Therefore these transparent options are not document-
       ed here,	but in groff(1).  Due to the automatism	in  groffer,  none  of
       these groff options should be needed, except for	advanced usage.

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

       Unfortunately  these  options  use  the old style of a single minus for
       long options.  For groffer that was changed to the standard with	 using
       a  double  minus	for long options, for example, groffer uses the	option
       --font for the X	option -font.

       See X(1), X(7), and the documentation on	the X toolkit options for more
       details on these	options	and their arguments.

       --background color
	      Set the background color of the viewer window.

       --bd pixels
	      Specifies	the color of the border	surrounding the	viewer window.

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

       --bw pixels
	      Specifies	 the  width  in	 pixels	 of the	border surrounding the
	      viewer window.

       --display X-display
	      Set the X	display	on which the viewer program shall be  started,
	      see the X	Window documentation for the syntax of the argument.

       --foreground color
	      Set the foreground color of the viewer window.

       --fg color
	      This is equivalent to -foreground.

       --font font_name
	      Set  the	font  used by the viewer window.  The argument is an X
	      font name.

       --ft font_name
	      This is equivalent to --ft.

       --geometry size_pos
	      Set the geometry of the display window, that means its size  and
	      its starting position.  See X(7) for the syntax of the argument.

       --resolution value
	      Set X resolution in dpi (dots per	inch) in some viewer programs.
	      The only supported dpi values are	75 and 100.  Actually, the de-
	      fault resolution for groffer is set to 75.

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

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

       --xrm 'resource'
	      Set X resource.

   Options from	man
       The  long options of groffer were synchronized with the long options of
       GNUman.	All long options of GNU	man are	recognized,  but  not  all  of
       these  options  are  important to groffer, so most of them are just ig-
       nored.

       The following two options were added by groffer	for  choosing  whether
       the  file name arguments	are interpreted	as names for local files or as
       a search	pattern	for man	pages.	The default is looking	up  for	 local
       files.

       --man  Check the	non-option command line	arguments (filespecs) first on
	      being man	pages, then whether they represent an  existing	 file.
	      By default, a filespec is	first tested whether it	is an existing
	      file.

       --no-man	| --local-file
	      Do not check for man pages.  --local-file	is  the	 corresponding
	      man option.

       In the following, the man options that have a special meaning for grof-
       fer are documented.

       The full	set of long and	short options of the GNU man  program  can  be
       passed  via the environment variable $MANOPT; see man(1)	if your	system
       has GNU man installed.

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

       -7 | --ascii
	      In text modes, display ASCII translation of special characters.

       --ditroff
	      Eqivalent	to groffer -Z.

       --extension suffix
	      Restrict man page	search to file names that have suffix appended
	      to their	section	 element.   For	 example,  in  the  file  name
	      /usr/share/man/man3/terminfo.3ncurses.gz	the man	page extension
	      is ncurses.

       --locale	language
	      Set the language for man pages.  This has	the same  effect,  but
	      overwrites $LANG

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

       --no-location
	      Do  not  display	the location of	retrieved files; this resets a
	      former call to --location.  This was added by groffer.

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

       --pager
	      Set the pager program in tty mode; default  is  less.   This  is
	      equivalent to --tty-viewer.

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

       --systems 'sys1,sys2,...'
	      Search for man pages for the given operating systems; the	 argu-
	      ment systems is a	comma-separated	list.

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

       Additionally, the following short option	of man is supported as well.

   Filespec Arguments
       A  filespec parameter is	an argument meaning an input source, such as a
       file name or template for searching man pages.  These input sources are
       collected and composed into a single output file	such as	groff does.

       The  strange  POSIX  behavior  that maps	all arguments behind the first
       non-option argument into	filespec arguments is ignored.	The GNU	behav-
       ior  to	recognize  options  even when mixed with filespec arguments is
       used througout.	But, as	usual, the  double  minus  argument  --	 still
       takes all following arguments as	filespecs.

       Each filespec parameters	can have one of	the following forms.

       No  filespec  parameters	 means	that groffer waits for standard	input.
       The minus option	- stands for standard input, too, but can occur	sever-
       al  times.   Next  filespec is tested whether it	is the path name of an
       existing	file.  Otherwise it is assumed as a searching  pattern	for  a
       man page.

       On each system, the man pages are sorted	according to their content in-
       to several sections.  The classical man sections	have a	single-charac-
       ter  name, either are a digit from 1 to 9 or one	of the characters n or
       o.  In the following, a stand-alone character s means this scheme.

       The internal precedence of man for searching man	pages  with  the  same
       name  within  several  sections goes according to the classical single-
       character sequence.  On some systems, this single character can be  ex-
       tended by a following string.  But the special groffer man page facili-
       ty is based on the classical single character sections.

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

       Next some patterns based	on the classical man sections  were  construc-
       ted.  man:name.s	and name.s search for a	man page name in man section s
       if s is a classical man section mentioned above.	 Otherwise search  for
       a man page named	name.s in the lowest man section.

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

       The pattern s name originates from a strange argument  parsing  of  the
       man  program.  If s is a	classical man section interpret	it as a	search
       for a man page called name in man section s, otherwise interpret	s as a
       file argument and name as another filespec argument.

       We  are	left with the argument name which is not an existing file.  So
       this searches for the man page called name in the  lowest  man  section
       that has	a document for this name.

       Several	file  name arguments can be supplied.  They are	mixed by groff
       into a single document.	Note that the set of option arguments must fit
       to  all of these	file arguments.	 So they should	have at	least the same
       style of	the groff language.

OUTPUT MODES
       By default, the groffer program collects	all input into a single	 file,
       formats it with the groff program for a certain device, and then	choos-
       es a suitable viewer program.  The device and viewer process in groffer
       is  called a mode.  The mode and	viewer of a running groffer program is
       selected	automatically, but the user can	also choose it	with  options.
       The  modes are selected by option the arguments of --mode=anymode.  Ad-
       ditionally, each	of this	argument can be	specified as an	option of  its
       own,  such  as  --anymode.   Most of these modes	have a viewer program,
       which can be chosen by an option	that is	 constructed  like  --anymode-
       viewer.

       Several different modes are offered, graphical X	modes, text modes, and
       some direct groff modes for debugging and development.

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

       The  searching for man pages and	the decompression of the input are ac-
       tive in every mode.

   Graphical Display Modes
       The graphical display modes work	only in	the X Window  environment  (or
       similar	implementations	within other windowing environments).  The en-
       vironment variable $DISPLAY and the option --display are	used for spec-
       ifying  the X display to	be used.  If neither is	given, groffer assumes
       that no X and changes to	one text mode.	You can	change this  automatic
       behavior	by the option --default-modes.

       Known viewers for the graphical display modes and their standard	X Win-
       dow viewer progams are

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

       o in a Postscript viewer	(ps mode),

       o in a dvi viewer program (dvi mode),

       o in a PDF viewer (pdf mode),

       o in a web browser (html	or www mode),

       The  pdf	 mode has a major advantage -- it is the only graphical	diplay
       mode that allows	to search for text within the viewer; this  can	 be  a
       really  important feature.  Unfortunately, it takes some	time to	trans-
       form the	input into the PDF format, so it was not chosen	as  the	 major
       mode.

       These  graphical	 viewers  can be customized by options of the X	Window
       Toolkit.	 But the groffer options use a leading double minus instead of
       the single minus	used by	the X Window Toolkit.

   Text	mode
       There  are to modes for text output, mode text for plain	output without
       a pager and mode	tty for	a text output on a text	 terminal  using  some
       pager program.

       If  the	variable $DISPLAY is not set or	empty, groffer assumes that it
       should use tty mode.

       In the actual implementation, the groff output device latin1 is	chosen
       for  text  modes.   This	 can  be  changed  by  specifying option -T or
       --device.

       The pager to be used can	be specified by	one of the options --pager and
       --tty-viewer, or	by the environment variable $PAGER.  If	all of this is
       not used	the less(1) program with the option -r for correctly  display-
       ing control sequences is	used as	the default pager.

   Special Modes for Debugging and Development
       These modes use the groffer file	determination and decompression.  This
       is combined into	a single input file that is fed	 directly  into	 groff
       with  different strategy	without	the groffer viewing facilities.	 These
       modes are regarded as advanced, they are	useful for debugging  and  de-
       velopment purposes.

       The source mode with just displays the generated	input.	The groff mode
       passes the input	to groff using only some suitable options provided  to
       groffer.	  This	enables	 the  user to save the generated output	into a
       file or pipe it into another program.

       In groff	mode, the option -Z disables post-processing,  thus  producing
       the  groff  intermediate	output.	 In this mode, the input is formatted,
       but not postprocessed; see groff_out(5) for details.

       All groff short options are supported by	groffer.

MAN PAGE SEARCHING
       The default behavior of groffer is to first test	whether	a file parame-
       ter  represents a local file; if	it is not an existing file name, it is
       assumed to represent a name of a	man page.  This	behavior can be	 modi-
       fied by the following options.

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

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

       If neither a local file nor a man page was retrieved for	some file  pa-
       rameter	a  warning is issued on	standard error,	but processing is con-
       tinued.

       The groffer program provides a search facility for man pages.  All long
       options,	 all  environment  variables, and most of the functionality of
       the GNU man(1) program were implemented.	  This	inludes	 the  extended
       file names of man pages,	for example, the man page of groff in man sec-
       tion  7	may  be	 stored	 under	/usr/share/man/man7/groff.7.gz,	 where
       /usr/share/man/	is part	of the man path, the subdirectory man7 and the
       file extension .7 refer to the man section 7; .gz shows the compression
       of the file.

       The  cat	pages (preformatted man	pages) are intentionally excluded from
       the search because groffer is a roff program that wants	to  format  by
       its  own.   With	the excellent performance of the actual	computers, the
       preformatted man	pages aren't necessary any longer.

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

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

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

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

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

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

       After  this,  the path elements for the language	(locale) and operating
       system specific man pages are added to the man path; their sequence  is
       determined  automatically.   For	 example, both /usr/share/man/linux/fr
       and /usr/share/man/fr/linux for french linux man	pages are found.   The
       language	 and  operating	system names are determined from both environ-
       ment variables and command line options.

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

       o --locale

       o $GROFFER_OPT

       o $MANOPT

       o $LCALL

       o $LC_MESSAGES

       o $LANG.

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

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

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

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

       If still	not found the corresponding man	page in	the  default  language
       is  used	 instead.  As usual, this default can be specified by one of C
       or POSIX.  The man pages	in the default language	are  usually  in  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 each	filespec argu-
       ment, several sections as a colon-separated list	in command line	option
       --sections or environment variable $MANSECT.  When no section was spec-
       ified a set of standard sections	is searched until a suitable man  page
       was found.

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

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

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

ENVIRONMENT
       The  groffer  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
	      builtin `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.  This
	      is done internally by some  shells.   groffer  ignores  the  bad
	      POSIX  behavior  for  option  processing,	that means that	option
	      processing will be finished as soon as a non-option argument  is
	      found.   Instead	the  GNU behavior of freely mixing options and
	      filespec arguments is used in any	case.	Usually,  you  do  not
	      want to set this environment variable externally.

   Groff Variables
       The  groffer  program  internally calls groff, so all environment vari-
       ables documented	in groff(1) are	 internally  used  within  groffer  as
       well.   The  following  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.

CONFIGURATION FILES
       The groffer program can be preconfigured	by  two	 configuration	files.
       This  configuration  can	be overridden at each program start by command
       line options or by the environment variable $GROFFER_OPT.

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

       Their  lines either start with a	minus character	or are shell commands.
       Arbitrary spaces	are allowed at the beginning, they are	just  ignored.
       The  lines  with	the beginning minus are	appended to the	existing value
       of $GROFFER_OPT.	 This easily allows to	set  general  groffer  options
       that are	used with any call of groffer.

       After  the transformation of the	minus lines the	emerging shell scripts
       that are	called by groffer using	the `. filename' syntax.

       The only	option that needs a minus line in the configuration  files  is
       --shell.	 The reason is that its	argument must be called	at a very ear-
       ly stage	before the whole syntax	of the	configuration  can  be	trans-
       formed.

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

       o Preset	command	line options by	writing	them into lines	starting  with
	 a minus sign.

       o Preset	environment variables recognized by groffer.

       o Write	a function for calling a viewer	program	for a special mode and
	 feed this name	into its  corresponding	 --mode-viewer	option.	  Note
	 that  the  name  of  such a function must coincide with some existing
	 program in the	system path $PATH in order to be recognized  by	 grof-
	 fer.

       As   an	 example,   consider   the  following  configuration  file  in
       ~/.groff/groffer.conf, say.

       # groffer configuration file
       #
       # groffer options that are used in each call of groffer
       --shell=/bin/bash
       --resolution=100
       --foreground=DarkBlue
       --x-viewer='gxditview -geometry 850x800'
       #
       # some shell commands
       if test "$DISPLAY" = "";	then
	 DISPLAY='localhost:0.0'
       fi
       date >>~/mygroffer.log

       This configuration sets four groffer options and	runs  two  shell  com-
       mands.  This has	the following effects:

       o Lines starting	with a # character are

       o Use /bin/bash as the shell to run the groffer script.

       o Take  a  resolution  of  100  dpi and a text color of DarkBlue	in all
	 viewers that support this.

       o Force gxditview(1) as the X-mode viewer using the geometry option for
	 setting the width to 850 dpi and the height to	800 dpi.

       o The  variable	$DISPLAY is set	to localhost:0.0 which allows to start
	 groffer in the	standard X display, even when the  program  is	called
	 from a	text console.

       o Just  for  fun, the date of each groffer start	is written to the file
	 mygroffer.log in the home directory.

EXAMPLES
       The usage of groffer is very easy.  Usually, it is just called  with  a
       file  name  or  man  page.   The	following examples, however, show that
       groffer has much	more fancy capabilities.

       sh# groffer /usr/local/share/doc/groff/meintro.ms.gz
	      Decompress, format and display the compressed file meintro.ms.gz
	      in  the directory	/usr/local/share/doc/groff, using gxditview as
	      graphical	viewer when in X Window, or the	less(1)	pager  program
	      when not in X.

       sh# groffer groff
	      If the file ./groff exists use it	as input.  Otherwise interpret
	      the argument as a	search for the man page	 named	groff  in  the
	      smallest possible	man section, being secion 1 in this case.

       sh# groffer man:groff
	      search  for the man page of groff	even when the file ./groff ex-
	      ists.

       sh# groffer groff.7
       sh# groffer 7 groff
	      search the man page of groff in man  section  7.	 This  section
	      search works only	for a digit or a single	character from a small
	      set.

       sh# groffer fb.modes
	      If the file ./fb.modes does not exist interpret this as a	search
	      for  the	man page of fb.modes.  As the extension	modes is not a
	      single character in classical section style the argument is  not
	      split to a search	for fb.

       sh# groffer groff 'troff(1)' man:roff
	      The  arguments  that are not existing files are looked-up	as the
	      following	man pages: groff (automatic search, should be found in
	      man  section  1),	troff (in section 1), and roff (in the section
	      with the lowest number, being  7	in  this  case).   The	quotes
	      around 'troff(1)'	are necessary because the paranthesis are spe-
	      cial shell characters; escaping them with	a backslash  character
	      \(  and \) would be possible, too.  The formatted	files are con-
	      catenated	and displayed in one piece.

       sh# LANG=de groffer --man --www --www-viever=mozilla ls
	      Retrieve the German man page (language de) for the  ls  program,
	      decompress  it, format it	to html	format (www mode) and view the
	      result in	the web	browser	galeon .  The option --man  guarantees
	      that the man page	is retrieved, even when	a local	file ls	exists
	      in the actual directory.

       sh# groffer --source 'man:roff(7)'
	      Get the man page called roff in man section  7,  decompress  it,
	      and print	its unformatted	content, its source code.

       sh# cat file.gz | groffer -Z -mfoo
	      Decompress  the  standard	input, send this to groff intermediate
	      mode without post-processing  (groff  option  -Z),  using	 macro
	      package by foo (groff option -m)

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

COMPATIBILITY
       The groffer shell script	is compatible with both	GNU and	POSIX.	 POSIX
       compatibility  refers  to  IEEE P1003.2/D11.2 of	September 1991,	a very
       early version of	the POSIX standard that	is still freely	 available  in
       the  internet.  Unfortunately, this version of the standard has `local'
       for shell function variables removed.  As `local' is needed for serious
       programming this	temporary POSIX	deprecation was	ignored.

       Most  GNU  shells are compatible	with this interpretation of POSIX, but
       provide much more facilities.  Nevertheless this	script uses only a re-
       stricted	 set of	shell language elements	and shell builtins.  The grof-
       fer 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 GNU shells: POSIX	 sh(1),	 bash(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 shell can be	chosen by the option --shell.  This option can also be
       given to	the environment	variable $GROFF_OPT.  If you want to write  it
       to  one	of the groffer configuration files you must use	the single op-
       tion style, a line starting with	--shell.

       The groffer program provides its	own parser for command line  arguments
       that  is	 compatible  to	both POSIX getopts(1) and GNU getopt(1)	except
       for shortcuts of	long options.  The following standard types of options
       are supported.

       o A single minus	always refers to single	character option or a combina-
	 tion thereof, for  example,  the  groffer  short  option  combination
	 -Qmfoo	is equivalent to -Q -m foo.

       o Long  options	are options with names longer than one character; they
	 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 file name 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 file2
	 is, by	default, equivalent to
	 sh# groffer -a	-o arg -- file1	file2

       This behavior can  be  changed  by  setting  the	 environment  variable
       $POSIXLY_CORRECT	 to a non-empty	value.	Then the strange POSIX non-op-
       tion behavior is	adopted, i. e. option processing is stopped as soon as
       the  first  non-option argument is found	and each following argument is
       taken as	a file name.  For example, in posixly correct mode,  the  com-
       mand 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.

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

       gxditview(1)
       xditview(1x)
	      Viewers for groffer's x 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.

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

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

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

       groff(7)
	      Documentation of the groff language.

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

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

AUTHOR
       This file was written by	Bernd Warken.

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

       This  file  is  part of groff, a	free software project.	You can	redis-
       tribute it and/or modify	it under the terms of the GNU  General	Public
       License as published by the Free	Software Foundation; either version 2,
       or (at your option) any later version.

       You should have received	a copy of the GNU General Public License along
       with  groff,  see the files COPYING and LICENSE in the top directory of
       the groff source	package.  Or read the man page gpl(1).	You  can  also
       write  to  the  Free  Software Foundation, 59 Temple Place - Suite 330,
       Boston, MA 02111-1307, USA.

Groff Version 1.18.1		 02 June 2004			    GROFFER(1)

NAME | SYNOPSIS | DESCRIPTION | OPTION OVERVIEW | OPTION DETAILS | Options for Development | Options related to groff | OUTPUT MODES | MAN PAGE SEARCHING | DECOMPRESSION | ENVIRONMENT | CONFIGURATION FILES | EXAMPLES | COMPATIBILITY | SEE ALSO | AUTHOR | COPYING

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

home | help