GROFFER

NAME

SYNOPSIS

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.

[t_[alt] - Q -- source] [t_[alt] - T -- device device] [t_[alt] -- auto-modes mode1,mode2,Ellipsis]] [t_[alt] -- debug] [t_[alt] -- default] [t_[alt] -- dvi] [t_[alt] -- dvi-viewer prog] [t_[alt] -- groff] [t_[alt] -- location] [t_[alt] -- mode display_mode] [t_[alt] -- pager program] [t_[alt] -- pdf] [t_[alt] -- pdf-viewer prog] [t_[alt] -- ps] [t_[alt] -- ps-viewer prog] [t_[alt] -- tty] [t_[alt] -- www] [t_[alt] -- www-viewer prog] [t_[alt] -- x] [t_[alt] -- x-viewer prog] The following long options were adapted from the corresponding X Toolkit options with a single leading minus; see X(1). [t_[alt] -- bd] [t_[alt] -- bg -- background] [t_[alt] -- bw] [t_[alt] -- display] [t_[alt] -- fg -- foreground] [t_[alt] -- ft -- font] [t_[alt] -- geometry size_pos] [t_[alt] -- resolution value] [t_[alt] -- rv] [t_[alt] -- title string] [t_[alt] -- 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 [t_short V,] [t_short X,] and [t_short 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 options include [t_short m] (to add macro files that cannot be recognized by grog), and [t_short 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 program.

[t_[alt] -- all] [t_[alt] -- ascii] [t_[alt] -- apropos] [t_[alt] -- ditroff] [t_[alt] -- extension suffix] [t_[alt] -- locale language] [t_[alt] -- local-file] [t_[alt] -- man] [t_[alt] -- manpath dir1:dir2:Ellipsis]] [t_[alt] -- no-location] [t_[alt] -- no-man] [t_[alt] -- sections sec1:sec2:Ellipsis]] [t_[alt] -- systems sys1,sys2,Ellipsis]] [t_[alt] -- troff-device device] [t_[alt] -- whatis] The GNU man long options that are not mentioned are recognized, but they are just ignored because of alternative implementations. 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

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.

[t_short]

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

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', Ellipsis], `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

OPTIONS

Option Parsing

single character options are always preceded by a single minus character, for example, [t_short c]

the argument for a single character option is the next command line argument, for example, [t_alt - o~ arg] or can be appended to the option character within the same argument [t_alt - o arg]

clusters of such single character options without an argument, eventually terminated by a single character option with an argument; for example, [t_alt - abo arg] is equivalent to [t_short a~][t_short b~][t_short o~]arg .

Long options, that means option with names longer than one character are always prededed by a double minus; an option argument can either go to the next command line argument or be appended with an equal sign to the argument; for example, [t_alt -- long= arg] is equivalent to [t_alt -- long~ arg]

An argument of [t_--] ends option parsing; all further command line arguments are interpreted as filespec arguments.

By default, all command line arguments that are neither options nor option arguments are interpreted as filespec parameters and stored until option parsing has finished. For example, the command line

ell_cmd groffer file1 -a -o arg file 2

ell_cmd groffer -a -o arg -- file1 file 2

This behavior can be changed by setting the environment variable to a non-empty value; in this case, option processing is stopped as soon as the first non-option argument is found. For example, in posixly correct mode, the command line

ell_cmd groffer file1 -a -o arg file 2

ell_cmd groffer -- file1 -a -o arg file 2

Compatibility with Options from other Programs

Native groffer Options

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 specified with

dvi

Display formatted input in a dvi viewer program; equivalent to [t_long dvi]

pdf

Display formatted input in a PDF (Portable Document Format) viewer program; equivalent to [t_long pdf]

ps

Display formatted input in a Postscript viewer program; equivalent to [t_long ps]

tty

Display formatted input in a text terminal; equivalent to [t_long tty]

www

Display formatted input in a internet browser program; equivalent to [t_long www]

x

Display formatted input in a native roff viewer such as gxditview(1);equivalentto [t_long 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_short T] the groff default ps is assumed.

source

Display source code; same as [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.

OUTPUT MODES

graphically display the formatted input with an X window program, including

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

in a dvi viewer program (dvi mode),

in a Postscript viewer (ps mode),

in a PDF viewer (pdf mode),

in a web browser (www mode),

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

run groffer like groff, but with decompression and man~page searching (groff mode); this includes things like generating the groff intermediate output.

stream the unformatted source code of the input onto standard output (source mode), By default, groffer first tries whether x mode is possible, then ps mode, and finally tty mode. This mode testing sequence for default mode can be changed by specifying a comma separated list of modes with the option [t_long default-modes.] The searching for man~pages and the decompression of the input are active in every mode.

Graphical Display Modes

Displaying on a tty

Non-displaying Modes

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 [t_short Q] or [t_long 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 details. This mode is activated automatically by the three groff options [t_short V] (print roff pipe, no formatting), [t_short X] (display with gxditview in groff's native way, using [t_short P] for customization), and [t_short Z] (disable post-processing, thus producing the groff intermediate output).

FILE PARAMETERS

Filespecs

[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. 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 corresponding command with the man program would be

ell_cmd man~ name

name.section

the man~page name in section. The corresponding command with the man program would be

ell_cmd man~ section~name

name

if name is not an existing file search for the man~page name in the lowest section just like

ell_cmd man~ name

section name

Even this curious construct known from the various man programs is handled. For example,

ell_cmd groffer 7 groff

ell_cmd man 7 groff

Man~Page Searching

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, the manpath(1) program for determining a path of man directories is tried.

If this does not work a reasonable default path is searched for man~pages. After this, the path elements for the language (locale) and operating system specific man~pages are added to the man~path; their sequence is determined automatically. For example, both /usr/share/man/linux/fr and /usr/share/man/fr/linux for french linux man~pages are found. The language and operating system names are determined from both 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 a filespec, 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).

Decompression

ENVIRONMENT

Native groffer Variables

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

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

ell_cmd DISPLAY=:0.1~groffer~ what.ever

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 setlocale(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

ell_cmd PAGER=cat~groffer~ anything

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 for option processing, that means that option processing will be finished as soon as a non-option argument is found. Usually, you do not want to set this environment variable.

Groff Variables

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

Man Variables

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.

FILES

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. It makes sense to use these configuration files for the following tasks:

Preset environment variables recognized by groffer; preferably a variable should only be set when it is unset in order not to override a user-provided value.

Preset command line options by prepending them to prepending should be preferred to appending and setting in order not to delete the environment variable provided by the

Write functions for calling viewer programs in a special way and feed them into the [t_long I]*]-viewer] options. 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.

#! /bin/sh
# ~/.groff/groffer.conf
if test "$DISPLAY" = ""; then
  DISPLAY='localhost:0.0';
fi;
GROFF_OPT="--resolution=100 $GROFF_OPT";
gxditview()
{
  /usr/local/bin/gxditview --fg DarkBlue "$@";
}

This has the following effects:

allows to start groffer in a graphical mode even from a text terminal;

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

the gxditview(1) program is told to use DarkBlue as the text color. These configurations can be overridden by command line options and by environment variable

EXAMPLES

ell_cmd groffer~/usr/local/share/doc/groff/meintro.ms.gz