No filespec parameters means standard input.

[t_short ]

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.

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

Display formatted input in a dvi viewer program. By default, the formatted input is displayed with the xdvi(1) program. [t_long dvi]

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

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

Display formatted input in a PDF (Portable Document Format) viewer program. By default, the input is formatted by groff using the Postscript device, then it is transformed into the PDF file format using gs(1), and finally displayed either with the xpdf(1) or the acroread(1) program. PDF has a big advantage because the text is displayed 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.

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

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

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

Equivalent to [t_long www]

Display formatted input in a native roff viewer. By default, 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.

Equivalent to [t_long_arg mode X] The following modes do not use the groffer viewing features. They are only interesting for advanced applications.

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

Display the source code of the input without formatting; equivalent to [t_short Q]

[t_--]

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.

[t_long man]

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

[t_long no-man]

[t_long 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 parameter a warning is issued on standard error, but processing is continued. 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~section 7 may be stored under where 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. The search path can be manually specified by using the option [t_long manpath] An empty argument disables the man~page searching. This overwrites the other methods. If this is not available the environment variable is searched. If this is empty, the program tries to read it from the environment variable If this does not work a reasonable default path from is searched for man~pages. 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 environment variables and command line options. The locale (language) is determined like in GNU man, that is from highest to lowest precedence: [t_long locale] The language locale is usually specified in the POSIX 1003.1 based format: I]<language>][CB]_]I]<territory>][CB].]I]<character-set>][CB],]I]<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 `CB]_]', `CB].]', and `CB],]', 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 CR]C] or CR]POSIX]. The man~pages in the default language are usually in English. Several operating systems can be given by appending their names, separated by a comma. This is then specified by the environment variable or by the command line option [t_long systems] The precedence is similar to the locale case above from highest to lowest precedence: Topic [t_long systems] 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 sections. A single section can be specified within each filespec argument, several sections as a colon-separated list in command line option [t_long sections] or environment variable 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 [t_long extension] or environment variable For further details on man~page searching, see man(1).

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.

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, depending on your system, groffer can be started on the second monitor by the command

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 typically of the form language[_territory[.codeset[@ modifier]]], where language is an ISO 639 language code, territory is an ISO 3166 country code, and codeset is a character set or encoding identifier like ISO-8859-1 or UTF-8; see (3). The locale values~C and POSIX stand for the default, i.e. the man~page directories without a language prefix. This is the same behavior as when all 3~variables are unset.

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

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.

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.

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

Restrict the search for man~pages to files having this extension. This is overridden by option [t_long extension] see there for details.

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 variable overwrite the values of the other environment variables taht are specific to man. All options specified in this variable are overridden by the options given on the command line.

If set, this variable contains the directories in which the man~page trees are stored. This is overridden by option [t_long manpath]

If this is a colon separated list of section names, the search for man~pages is restricted to those manual sections in that order. This is overridden by option [t_long sections]

If this is set to a comma separated list of names these are interpreted as man~page trees for different operating systems. This variable can be overwritten by option [t_long systems] see there for details. The environment variable is ignored by groffer because the necessary preprocessors are determined automatically.

System-wide configuration file for groffer.

User-specific configuration file for groffer, where denotes 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 [t_long shell] The reason is that its argument must be called at a very early stage before the whole syntax of the configuration can be transformed. It makes sense to use these configuration files for the following tasks: Preset command line options by writing them into lines starting with a minus sign. Preset environment variables recognized by groffer. Write a function for calling a viewer program for a special mode and feed this name into its corresponding [t_long I]mode]-viewer] option. Note that the name of such a function must coincide with some existing program in the system path in order to be recognized by groffer. 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 commands. This has the following effects: Lines starting with a # character are Use /bin/bash as the shell to run the groffer script. Take a resolution of 100 dpi and a text color of DarkBlue in all viewers that support this. 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. The variable 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. Just for fun, the date of each groffer start is written to the file mygroffer.log in the home directory.

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.

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.

search for the man~page of groff even when the file ./groff exists.

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.

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.

ell_cmd groffer~groff~[cq]troff(1)[cq]~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 [cq]troff(1)[cq] are necessary because the paranthesis are special shell characters; escaping them with a backslash character [rs]( and [rs]) would be possible, too. The formatted files are concatenated and displayed in one piece.

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 [t_long man] guarantees that the man~page is retrieved, even when a local file ls exists in the actual directory.

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

Decompress the standard input, send this to groff intermediate mode without post-processing (groff option [t_short Z ),] using macro package by foo (groff option [t_short m )]

Display the word CB]WOW!] in a small window in constant-width bold font, using color yellow on red background.

COMPATIBILITY

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 documents 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 options from the input using this program.

(5)

Documentation on the groff intermediate output (ditroff output).