groffer - Unix, Linux Command

NAME

SYNOPSIS

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 configuration files, with the shell environment variable $GROFFER_OPT, or on the command line.

The output can be generated and viewed in several different ways available 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 arguments.

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

OPTION DETAILS

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

groffer breaking Options

groffer Mode Options

Options for Development

Because of the special outputting behavior of the groff options and 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.

X Window toolkit Options

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 for the X option

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

Options from man

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.

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

Filespec Arguments

The strange POSIX behavior that maps all arguments behind the first non-option argument into filespec arguments is ignored. The GNU behavior 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 several 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 into several sections. The classical man sections have a single-character 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 extended by a following string. But the special groffer man page facility 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 constructed. 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

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

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

Graphical Display Modes

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 locale (language) is determined like in GNU man, that is from highest to lowest precedence:

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 The precedence is similar to the locale case above from highest to lowest precedence: Topic

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 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 or environment variable

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

DECOMPRESSION

ENVIRONMENT

Native groffer Variables

System Variables

Groff Variables

Man Variables

CONFIGURATION FILES

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

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

EXAMPLES

COMPATIBILITY

Most GNU shells are compatible with this interpretation of POSIX, but provide much more facilities. Nevertheless this script uses only a restricted set of shell language elements and shell builtins. The groffer script should work on most actual free and commercial operating systems.

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

The groffer shell script was tested with the following common implementations of the GNU shells: POSIX sh(1), bash(1), and others. Free POSIX compatible shells and shell utilities for most operating systems are available at the

The shell can be chosen by the option This option can also be given to the environment variable If you want to write it to one of the groffer configuration files you must use the single option style, a line starting with

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.