groffer - display groff files and man\~pages on X and tty . The .SH was moved to this place in order to appease `apropos'.
. --------------------------------------------------------------------
Legalize
--------------------------------------------------------------------
. groffer.1 - man page for groffer (section 1). Source file position: <groff_source_top>/contrib/groffer/groffer.man Installed position: $prefix/share/man/man1/groffer.1 Last update: 22 August 2005 Source file position: <groff-source>/contrib/groffer/groffer.man .. This file was written by .MTO "" "Bernd Warken" . .. Copyright (C) 2001,2002,2004,2005 Free Software Foundation, Inc. .

This file is part of \%groffer , which is part of \%groff , a free software project. . You can redistribute 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 \f[CR]GNU General Public License\f[] along with groff , see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] 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, 51 Franklin St - Fifth Floor, Boston, "MA 02110-1301, USA" . .. . --------------------------------------------------------------------
Setup
--------------------------------------------------------------------
. .mso www.tmac . . mso tty-char.tmac . ftr CR R . ftr CI I . ftr CB B .\} . . ftr CB CW .\} . . --------------------------------------------------------------------
setup for the macro definitions below

naming: namespace:cathegory_macro.variable_name (experimental)
. --------------------------------------------------------------------
configuration of prompt for `.Shell_cmd'* macros
. automatically determine setup from the configuration above
.als @f groffer:Shell_cmd_base.prompt_font\" .als @t groffer:Shell_cmd.prompt_text\" .als @t+ groffer:Shell_cmd+.prompt_text\" .nr @w \w'\*[groffer:Shell_cmd.prompt]'\" .nr @w+ \w'\*[groffer:Shell_cmd+.prompt]'\" Full prompt width is maximum of texts plus 1m
.nr groffer:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed .rr @w .rr @w+ . --------------------------------------------------------------------
static register for inter-macro communication in `.Synopsis'*
.nr groffer:Synopsis.level 0 . --------------------------------------------------------------------
static registers for inter-macro communication in `.TP'*
.nr groffer:TP.level 0 .rr groffer:TP_header.flag .rr groffer:TP_body.flag .rr groffer:TP.indent . . --------------------------------------------------------------------
Macro definitions
. Ignore all arguments like a comment, even after a .eo call.
.. .c -------------------------------------------------------------------- .c .CB (<text>...) .c .c Print in constant-width bold font. .c . ft CB . Text \\$* . ft .. .c -------------------------------------------------------------------- .c .CI (<text>...) .c .c Print in constant-width italic font. .c . ft CI . Text \\$* . ft .. .c -------------------------------------------------------------------- .c .CR (<text>...) .c .c Print in constant-width roman font. .c . ft CR . Text \\$* . ft .. .c -------------------------------------------------------------------- .c .Error (<text>...) .c .c Print error message to terminal and abort. .c . tm \\$* . ab .. .c -------------------------------------------------------------------- .c .Env_var (<env_var_name> [<punct>]) .c .c Display an environment variable, with optional punctuation. .c . nh . SM . Text \f[CB]\\$1\f[]\\$2 . hy .. .c -------------------------------------------------------------------- .c .File_name (<path_name>) .c .c Display a file or directory name in CB font. .c . Header_CB \\$@ .. .c -------------------------------------------------------------------- .c .Header_CB (<path_name>) .c .c Display a line in CB font, for example after .TP .c . nh . Text \f[CB]\\$1\f[]\\$2 . hy .. .c -------------------------------------------------------------------- .c .Opt_- ([<punct>]) .c .c Print `-' (minus sign); optional punctuation. .c . ie (\\n[.$] == 0) \ . Opt_alt - "" . el \ . Opt_alt - "" "\\$1" .. .c -------------------------------------------------------------------- .c .Opt_[-] ([<punct>]) .c .c Print `Opt_[-]' (minus sign in brackets); optional punctuation. .c . ie (\\n[.$] == 0) \ . Opt_[alt] - "" . el \ . Opt_[alt] - "" "\\$1" .. .c -------------------------------------------------------------------- .c .Opt_-- ([<punct>]) .c .c Print `--' (double minus); optional punctuation. .c . ie (\\n[.$] == 0) \ . Opt_alt -- "" . el \ . Opt_alt -- "" "\\$1" .. .c -------------------------------------------------------------------- .c .Opt_[--] ([<punct>]) .c .c Print `Opt_[--]' (double minus in brackets); optional punctuation. .c . ie (\\n[.$] == 0) \ . Opt_[alt] -- "" . el \ . Opt_[alt] -- "" "\\$1" .. .c -------------------------------------------------------------------- .c .Opt_alt ([<minus> <opt>]... [<arg> [<punct>]]) .c .c Alternate options separated by a vertical bar. .c .c Arguments: .c minus: either `-' or `--' (font CB). .c opt: a name for an option, empty allowed (font CB). .c arg: optionally, the argument to the option (font I). .c punct: optional punctuation (in the starting font). .c Result: .c The minus/opt argument pairs, each .c separated by a vertical bar `|', optionally add 'arg', separated .c a space character ` '. .c .c Example: .c .Opt_alt - T -- device -- device-troff device . .c results in .c -T|--device|--device-troff device. .c . Opt_alt_base "" | "" \\$@ .. .c -------------------------------------------------------------------- .c .Opt_[alt] ([<minus> <opt>]... [<arg> [<punct>]]) .c .c Alternate options in brackets for section SYNOPSIS. .c .c Arguments: .c minus: either `-' or `--' (font CB). .c opt: a name for an option, empty allowed (font CB). .c arg: optionally, the argument to the option (font I). .c punct: optional punctuation (in the starting font). .c Global strings written to: .c `@oa_prefix': left enclosing character (`[') .c `@oa_sep': separator (`|') .c `@oa_postfix': right enclosing character (`]') .c Result: .c The minus/opt argument pairs, each separated by a vertical .c bar `|', optionally add 'arg', separated by a space character ` '. .c .c Example: .c .Opt_[alt] - T -- device -- device-troff device . .c results in .c [-T|--device|--device-troff device]. .c . Opt_alt_base [ | ] \\$@ .. .c -------------------------------------------------------------------- .c .Opt_alt_base (<pre> <sep> <post> [<minus> <opt>]... [arg [punct]]) .c .c Alternating options; base macro for many others; do not use directly. .c .c Arguments: .c <pre>: prefix, result is preceded by this. .c <sep>: separator between minus/opt pairs. .c <post>: postfix, is appended to the result. .c <minus>: either `-' or `--' (font CB). .c <opt>: a name for an option, empty allowed (font CB). .c <arg>: optionally, the argument to the option (font I). .c <punct>: optional punctuation (in the starting font). .c Result: .c String `<pre>' followed by the <minus>/<opt> argument pairs, each .c separated by string `<sep>', optionally add '<arg>', separated by .c a single space ` ', followed by the string `<post>'. Terminated .c by the optional punctuation <punct>. .c . nr @font \\n[.f]\" . if (\\n[.$] < 3) \ . Error .\\0: not enough arguments. . ds @pre \)\\$1\)\" prefix . ds @sep \)\\$2\)\" separator . ds @post \)\\$3\)\" postfix . shift 3 . nr @count 0 . ds @res \f[CR]\\*[@pre]\" . while (\\n[.$] >= 2) \{\ . c do the pairs, break on no `-' . if !'\\$1'-' \{\ . if !'\\$1'--' \ . break . \} . c separator . if (\\n[@count] > 0) \ . as @res \f[CR]\\*[@sep]\:\" . nr @count +1 . c combine minus with option name . as @res \f[CB]\-\" . if '\\$1'--' \ . as @res \-\" . as @res \\$2\" . shift 2 . \} . if (\\n[.$] >= 3) \ . Error .\\0: wrong arguments: \\$@ . c all pairs are done . ie (\\n[.$] == 0) \ . as @res \f[CR]\\*[@post]\" . el \{\ . c optional option argument . if !'\\$1'' \ . as @res \f[CR] \,\f[I]\\$1\" . shift . c postfix . as @res \\f[CR]\\*[@post]\" . if (\\n[.$] >= 1) \{\ . c add punctuation . as @res \f[\\n[@font]]\\$1\" . \} . \} . nh . Text \\*[@res] . hy . ft \\n[@font] . rr @count . rr @font . rm @pre . rm @post . rm @sep . rm @res .. .c -------------------------------------------------------------------- .c .Opt_def ([<minus> <opt>]... [<arg> [<punct>]]) .c .c Definitions of options in section OPTIONS. .c .c Arguments: .c minus: either `-' or `--' (font CB). .c opt: a name for an option, empty allowed (font CB). .c arg: optionally, the argument to the option (font I). .c punct: optional punctuation (in the starting font). .c Result: .c The header for an indented paragraph, consisting of .c minus/opt argument pairs, each, separated by a space .c character ` ', optionally add 'arg', separated a space .c character ` '. .c .c Example: .c .Opt_def - T -- device -- device-troff device . .c results in .c -T --device --device-troff device. .c as the header of for indented paragraph. .c . TP . Opt_alt_base "" "\~|\~" "" \\$@ .. .c -------------------------------------------------------------------- .c .Opt_element ([<minus> <opt>]... [<arg> [<punct>]]) .c .c Definitions of options in section OPTIONS. .c .c Arguments: .c minus: either `-' or `--' (font CB). .c opt: a name for an option, empty allowed (font CB). .c arg: optionally, the argument to the option (font I). .c punct: optional punctuation (in the starting font). .c Result: .c The minus/opt argument pairs, each, separated by a space .c character ` ', optionally add 'arg', separated a space .c character ` '. .c .c Example: .c .Opt_element - T -- device -- device-troff device . .c results in .c -T --device --device-troff device. .c . Opt_alt_base "" "\~" "" \\$@ .. .c -------------------------------------------------------------------- .als Opt_list Opt_element . .c -------------------------------------------------------------------- .c .Opt_long ([<name> [<punct>]]) .c .c Print `--name' somewhere in the text; optional punctuation. .c . Opt_alt -- "\\$1" "" "\\$2" .. .c -------------------------------------------------------------------- .c .Opt_long_arg ([<name> <arg> [<punct>]]) .c .c Print `--name=arg' somewhere in the text; optional punctuation. .c . Opt_alt -- "\\$1=\\$2" "" "\\$3" .. .c -------------------------------------------------------------------- .c .Opt_[long] ([<name> [<punct>]]) .c .c Print `--name' somewhere in the text; optional punctuation. .c . Opt_[alt] -- "\\$1" "" "\\$2" .. .c -------------------------------------------------------------------- .c .Opt_short ([<name> [<punct>]]) .c .c Print `-name' somewhere in the Text; optional punctuation. .c . Opt_alt - "\\$1" "" "\\$2" .. .c -------------------------------------------------------------------- .c .Opt_[short] ([name [punct]]) .c .c Print `[-name]' somewhere in the Text; optional punctuation. .c . Opt_[alt] - "\\$1" "" "\\$2" .. .c -------------------------------------------------------------------- .c .Shell_cmd (<CR> [<CI>] ...) .c .c A shell command line; display args alternating in fonts CR and CI. .c .c Examples: .c .Shell_cmd "groffer --dpi 100 file" .c result: `sh# groffer --dpi 100 file' .c with 'sh#' in font I, the rest in CR .c .c .Shell_cmd groffer\~--dpi\~100\~file .c result: the same as above .c .c .Shell_cmd "groffer --dpi=" value " file" .c result: sh# groffer --dpi=value file .c with `groffer --dpi=' and `file' in CR; `value' in CI .c .c .Shell_cmd groffer\~--dpi= value \~file .c result: the same as the previous example .c . groffer:Shell_cmd_base "\*[groffer:Shell_cmd.prompt]" \\$@ .. .c -------------------------------------------------------------------- .c .Shell_cmd+ (<CR> [<CI>] ...) .c .c A continuation line for .Shell_cmd. .c . groffer:Shell_cmd_base "\*[groffer:Shell_cmd+.prompt]" \\$@ .. .c -------------------------------------------------------------------- .c .Shell_cmd_base (<prompt> [<CR> [<CI>] ...]) .c .c A shell command line; display args alternating in fonts CR and CI. .c Internal, do not use directly. .c .c Globals: read-only register @.Shell_cmd_width .c . if (\\n[.$] <= 0) \ . return . nr @+font \\n[.f]\" . ds @prompt \\$1\" . ft CR . c gap between prompt and command . nr @+gap \\n[groffer:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\" . ds @res \\*[@prompt]\h'\\n[@+gap]u'\" . shift . ds @cf CR\" . while (\\n[.$] > 0) \{\ . as @res \\f[\\*[@cf]]\\$1\" . shift . ie '\\*[@cf]'CR' \ . ds @cf I\" . el \ . ds @cf CR\" . \} . br . ad l . nh . nf . Text \\*[@res]\" . fi . hy . ad . br . ft \\n[@+font] . rr @+font . rr @+gap . rm @cf . rm @res .. .c -------------------------------------------------------------------- .c .Synopsis () .c .c Begin a synopsis section, to be ended by a ./Synopsis macro. .c . if (\\n[groffer:Synopsis.level] > 0) \ . Error .\\$0: previous .Synopsis was not closed by ./Synopsis. . nh . ds @1 \\$1\" . nr @old_indent \\n(.i . ad l . in +\w'\\*[@1]\0'u . ti \\n[@old_indent]u . B \\*[@1]\0\c . rr @old_indent . rm @1 . nr groffer:Synopsis.level +1\" marker for ./Synopsis .. .c -------------------------------------------------------------------- .c ./Synopsis () .c .c Close a synopsis section opened by the previous .Synopsis macro. .c . if (\\n[groffer:Synopsis.level] <= 0) \ . Error .\\$0: no previous call of .Synopsis . br . ad . in . hy . nr groffer:Synopsis.level -1 .. .c -------------------------------------------------------------------- .c .Text (<text>...) .c .c Treat the arguments as text, no matter how they look. .c . if (\\n[.$] == 0) \ . return . nh . nop \)\\$*\) . hy .. .c -------------------------------------------------------------------- .c .Topic ([<indent>]) .c .c A bulleted paragraph .c . ie (\\n[.$] = 0) \ . ds @indent 2m\" . el \ . ds @indent \\$1\" . TP \\*[@indent] . Text \[bu] . rm @indent .. .c -------------------------------------------------------------------- .c .TP+ () .c .c Continuation line for .TP header. .c . br . ns . TP \\$1 .. .c -------------------------------------------------------------------- .c .TP_header ([<indent>]) .c .c Start a multi-line header for a .TP-like paragraph .c . if (\\n[groffer:TP.level] < 0) \ . Error .\\$0: wrong level. . nr groffer:TP.level +1 . P . ie (\\n[.$] == 0) \ . rr groffer:TP.indent . el \ . nr groffer:TP.indent \\$1 . nr groffer:TP_header.flag 1 .. .c -------------------------------------------------------------------- .c .TP_body ([<indent>]) .c .c End a previous .TP-header and beging the body of the paragraph. .c . if !rgroffer:TP_header.flag \ . Error .\\$0: no previous call of .TP_header . if (\\n[groffer:TP.level] <= 0) \ . Error .\\$0: wrong level. . br . ie (\\n[.$] == 0) \{\ . ie rgroffer:TP.indent \{\ . RS \\n[groffer:TP.indent]u . \} . el \ . RS . \} . el \ . RS \\$1u . rr groffer:TP.indent . rr groffer:TP_header.flag . nr groffer:TP_body.flag 1 .. .c -------------------------------------------------------------------- .c TP_end () .c .c End of former .TP_body paragraph. .c . if !rgroffer:TP_body.flag \ . Error .\\$0: no previous .TP_body. . if (\\n[groffer:TP.level] <= 0) \ . Error TP_end: wrong level. . nr groffer:TP.level -1 . rr grogger:TP.indent . rr groffer:TP_header.flag . rr groffer:TP_body.flag . br . RE .. . End of macro definitions
. . --------------------------------------------------------------------
SH "SYNOPSIS"
--------------------------------------------------------------------
. .Synopsis groffer [ option... ] .Opt_[--] [ "\%filespec" "\*[Ellipsis]]" ./Synopsis . .Synopsis groffer .Opt_alt - h -- help ./Synopsis . .Synopsis groffer .Opt_alt - v -- version ./Synopsis . . --------------------------------------------------------------------

--------------------------------------------------------------------
. The \%groffer program is the easiest way to use \%groff (@MAN1EXT@). It can display arbitrary documents written in the \%groff language, see \%groff (@MAN7EXT@), or other \%roff languages, see \%roff (@MAN7EXT@), that are compatible to the original \%troff language. . The \%groffer program also includes many of the features for finding and displaying the \%\f[CR]Unix\f[] 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 either 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 \%\f[CR]X\~Window\f[] viewer \%gxditview (@MAN1EXT@), each \%Postcript , \%pdf , 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 (@MAN1EXT@) 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 handling is done in \f[CR]GNU\f[] style. . Options and file names can be mixed freely. . The option ` -- ' closes the option handling, all following arguments are treated as file names. . Long options can be abbreviated. . . --------------------------------------------------------------------

--------------------------------------------------------------------
.

breaking options

. .

\%groffer mode options

. .

development options

. .

options related to \%groff

. .

options for man\~pages .Opt_[alt] -- apropos .Opt_[alt] -- apropos-data .Opt_[alt] -- apropos-devel .Opt_[alt] -- apropos-progs .Opt_[alt] -- whatis .Opt_[alt] -- man .Opt_[alt] -- no-man .Opt_[alt] -- no-special . .

long options taken over from GNU man

. .

X Window Toolkit options

. .

\%filespec arguments

. . --------------------------------------------------------------------
--------------------------------------------------------------------
. 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 (@MAN1EXT@). . All long options of \%groffer are compatible with the long options of \%man (1). . . --------------------------------------------------------------------

--------------------------------------------------------------------
. As soon as one of these options is found on the command line it is executed, printed to standard output, and the running \%groffer is terminated thereafter. . All other arguments are ignored. . . .Opt_def - h -- help Print a helping information with a short explanation of option sto standard output. . . .Opt_def - v -- version Print version information to standard output. . . --------------------------------------------------------------------
--------------------------------------------------------------------
. The display mode and the viewer programs are determined by these options. . If none of these mode and viewer options is specified \%groffer tries to find a suitable display mode automatically. . The default modes are mode x with gxditview in \%\f[CR]X\~Window\f[] and mode tty with device latin1 under less on a terminal. . .

There are two kinds of options for viewers. .Opt_long mode-viewer chooses the normal viewer programs that run on their own in \%\f[CR]X\~Window\f[], while .Opt_long mode-viewer-tty chooses programs that run on the terminal (on tty). . Most graphical viewers are programs running in \%\f[CR]X\~Window\f[], so there aren't many opportunities to call the tty viewers. . But they give the chance to view the output source; for example, .Opt_long ps-viewer-tty=less shows the content of the Postscript output with the pager less . . .

The \%\f[CR]X\~Window\f[] viewers are not critical, you can use both .Opt_long *-viewer and .Opt_long *-viewer-tty for them; with .Opt_long *-viewer-tty the viewer program will not become independently, it just stays coupled with groffer . But the program will not run if you specify a terminal program with .Opt_long *-viewer because this viewer will stay in background without a chance to reach it. . So you really need .Opt_long *-viewer-tty for viewers that run on tty. . . .Opt_def -- auto Equivalent to .Opt_long_arg mode auto . . . .Opt_def -- 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 .Env_var $GROFFER_OPT , and restart option processing using only the rest of the command line. . . .Opt_def -- default-modes mode1,mode2,\*[Ellipsis] Set the sequence of modes for \%auto\~mode to the comma separated list given in the argument. . See .Opt_long mode for details on modes. Display in the default manner; actually, this means to try the modes x , ps , and \%tty in this sequence. . . . .Opt_def -- dvi Equivalent to .Opt_long_arg mode \%dvi . . . .Opt_def -- dvi-viewer prog Choose an \%\f[CR]X\~Window\f[] viewer program for \%dvi\~mode . . This can be a file name or a program to be searched in .Env_var $PATH . . Known \%\f[CR]X\~Window\f[] \%dvi viewers include \%xdvi (1) and \%dvilx (1) . In each case, arguments can be provided additionally. . . .Opt_def -- dvi-viewer-tty prog Choose a program running on the terminal for viewing the output of \%dvi\~mode . . This can be a file name or a program to be searched in .Env_var $PATH ; arguments can be provided additionally. . . .Opt_def -- groff Equivalent to .Opt_long_arg mode groff . . . .Opt_def -- html Equivalent to .Opt_long_arg mode html . . . .Opt_def -- html-viewer Choose an \%\f[CR]X\~Window\f[] web browser program for viewing in \%html\~mode . . It can be the path name of an executable file or a program in .Env_var $PATH . . In each case, arguments can be provided additionally. . . .Opt_def -- html-viewer-tty Choose a terminal program for viewing the output of \%html\~mode . . It can be the path name of an executable file or a program in .Env_var $PATH ; arguments can be provided additionally. . . .Opt_def -- mode value . Set the display mode. . The following mode values are recognized: .

. . .Opt_def -- pdf Equivalent to .Opt_long_arg mode pdf . . . .Opt_def -- pdf-viewer prog Choose an \%\f[CR]X\~Window\f[] viewer program for \%pdf\~mode . . This can be a file name or a program to be searched in .Env_var $PATH ; arguments can be provided additionally. . . .Opt_def -- pdf-viewer-tty prog Choose a terminal viewer program for \%pdf\~mode . . This can be a file name or a program to be searched in .Env_var $PATH ; arguments can be provided additionally. . . .Opt_def -- ps Equivalent to .Opt_long_arg mode ps . . . .Opt_def -- ps-viewer prog Choose an \%\f[CR]X\~Window\f[] viewer program for \%ps\~mode . . This can be a file name or a program to be searched in .Env_var $PATH . . Common Postscript viewers inlude \%gv (1), \%ghostview (1), and \%gs (1), . In each case, arguments can be provided additionally. . . .Opt_def -- ps-viewer-tty prog Choose a terminal viewer program for \%ps\~mode . . This can be a file name or a program to be searched in .Env_var $PATH ; arguments can be provided additionally. . . .Opt_def -- text Equivalent to .Opt_long_arg mode text . . . .Opt_def -- tty Equivalent to .Opt_long_arg mode tty . . . .Opt_def -- tty-viewer prog Choose a text pager for mode tty . The standard pager is less (1). This option is eqivalent to man option .Opt_long_arg pager prog . The option argument can be a file name or a program to be searched in .Env_var $PATH ; arguments can be provided additionally. . . .Opt_def -- tty-viewer-tty prog This is equivalent to .Opt_long tty-viewer because the programs for tty mode run on a terminal anyway. . . .Opt_def -- www Equivalent to .Opt_long_arg mode html . . . .Opt_def -- www-viewer prog Equivalent to .Opt_long html-viewer . . . .Opt_def -- www-viewer-tty prog Equivalent to .Opt_long html-viewer-tty . . . .Opt_def -- X -- x Equivalent to .Opt_long_arg mode x . . . .Opt_def -- X-viewer -- x-viewer prog Choose an \%\f[CR]X\~Window\f[] viewer program for \%x\~mode . Suitable viewer programs are \%gxditview (@MAN1EXT@) which is the default and \%xditview (1). The argument can be any executable file or a program in .Env_var $PATH ; arguments can be provided additionally. . . .Opt_def -- X-viewer-tty -- x-viewer-tty prog Choose a terminal viewer program for \%x\~mode . The argument can be any executable file or a program in .Env_var $PATH ; arguments can be provided additionally. . .

.Opt_-- Signals the end of option processing; all remaining arguments are interpreted as \%filespec parameters. . .

Besides these, \%groffer accepts all short options that are valid for the \%groff (@MAN1EXT@) program. . All \%non- groffer options are sent unmodified via \%grog to \%groff . . So postprocessors, macro packages, compatibility with classical \%troff , and much more can be manually specified. . . --------------------------------------------------------------------

--------------------------------------------------------------------
. .Opt_def -- debug Enable five debugging informations. . The temporary files are kept and not deleted, the name of the temporary directory and the shell name for .File_name groffer2.sh are printed, the parameters are printed at several steps of development, and a function stack is output with function \f[CR]error_user()\f[] as well. . Neither the function call stack that is printed at each opening and closing of a function call nor the landmark information that is printed to determine how far the program is running are used. . This seems to be the most useful among all debugging options. . . .Opt_def -- debug-all Enable all seven debugging informations including the function call stack and the landmark information. . . .Opt_def -- debug-keep Enable two debugging information, the printing of the name of the temporary directory and the keeping of the temporary files. . . .Opt_def -- debug-lm Enable one debugging information, the landmark information. . . .Opt_def -- debug-params Enable one debugging information, the parameters at several steps. . . .Opt_def -- debug-shell Enable one debugging information, the shell name for .File_name groffer2.sh . . . .Opt_def -- debug-stacks Enable one debugging information, the function call stack. . . .Opt_def -- debug-tmpdir Enable one debugging information, the name of the temporary directory. . . .Opt_def -- debug-user Enable one debugging information, the function stack with \f[CR]error_user()\f[]. . . .Opt_def -- do-nothing This is like .Opt_long version , but without the output; no viewer is started. . This makes only sense in development. . . .Opt_def -- print=text Just print the argument to standard error. . This is good for parameter check. . . .Opt_def -- shell "shell_program" Specify the shell under which the .File_name \%groffer2.sh script should be run. . This option overwrites the automatic shell determination of the program. . If the argument shell_program is empty a former shell option and the automatic shell determination is cancelled and the default shell is restored. . Some shells run considerably faster than the standard shell. . . .Opt_def - Q -- source Output the roff source code of the input files without further processing. . This is the equivalent .Opt_long_arg mode source . . . .Opt_def - V This is an advanced option for debugging only. . Instead of displaying the formatted input, a lot of \%groffer specific information is printed to standard output: . . .

Other useful debugging options are the \%groff option .Opt_short Z and .Opt_long_arg mode groff . . . --------------------------------------------------------------------

--------------------------------------------------------------------
. All short options of \%groffer are compatible with the short options of \%groff (@MAN1EXT@). . 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 option .Opt_short Z \%groffer was designed to be switched into \%groff\~mode ; the \%groffer viewing features are disabled there. . The other \%groff options do not switch the mode, but allow to customize the formatting process. . . .Opt_def - a This generates an ascii approximation of output in the \%text\~modes . . That could be important when the text pager has problems with control sequences in "tty mode" . . . .Opt_def - m file Add \%file as a \%groff macro file. . This is useful in case it cannot be recognized automatically. . . .Opt_def - P opt_or_arg Send the argument \%opt_or_arg as an option or option argument to the actual \%groff postprocessor. . . .Opt_def - T -- device devname . This option determines \%groff 's output device. . The most important devices are the text output devices for referring to the different character sets, such as \%ascii , \%utf8 , \%latin1 , and others. . 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 corresponding \%groffer .Opt_long_arg 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. . . .Opt_def - X is equivalent to "groff -X" . It displays the groff intermediate output with gxditview . As the quality is relatively bad this option is deprecated; use .Opt_long X instead because the \%x\~mode uses an X * device for a better display. . . .Opt_def - Z -- intermediate-output -- ditroff Switch into \%groff\~mode and format the input with the \%groff intermediate output without postprocessing; see \%groff_out (@MAN5EXT@). This is equivalent to option .Opt_long 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 options that are not explicitly handled by \%groffer are transparently passed to \%groff . . Therefore these transparent options are not documented here, but in \%groff (@MAN1EXT@). Due to the automatism in \%groffer , none of these \%groff options should be needed, except for advanced usage. . . --------------------------------------------------------------------

--------------------------------------------------------------------
. .Opt_def -- apropos Start the \%apropos (1) command or facility of \%man (1) for searching the \%filespec arguments within all \%man\~page descriptions. . Each \%filespec argument is taken for search as it is; section specific parts are not handled, such that 7 groff searches for the two arguments 7 and groff with a large result; for the \%filespec groff.7 nothing will be found. . The display differs from the \%apropos program by the following concepts: . . .Opt_def -- apropos-data Show only the \%apropos descriptions for data documents, these are the \%man (7) sections 4, 5, and 7. . Direct section declarations are ignored, wildcards are accepted. . . .Opt_def -- apropos-devel Show only the \%apropos descriptions for development documents, these are the man (7) sections 2, 3, and 9. . Direct section declarations are ignored, wildcards are accepted. . . .Opt_def -- apropos-progs Show only the \%apropos descriptions for documents on programs, these are the \%man (7) sections 1, 6, and 8. . Direct section declarations are ignored, wildcards are accepted. . . .Opt_def -- whatis For each \%filespec argument search all \%man\~pages and display their description \[em] or say that it is not a \%man\~page . This differs from man 's whatis output by the following concepts . .

The following two options were added to \%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. . . .Opt_def -- 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. . . .Opt_def -- no-man -- local-file Do not check for \%man\~pages . . .Opt_long local-file is the corresponding man option. . . .Opt_def -- no-special Disable former calls of .Opt_long all , .Opt_long apropos* , and .Opt_long whatis . . . --------------------------------------------------------------------

--------------------------------------------------------------------
. The long options of \%groffer were synchronized with the long options of \f[CR]GNU\f[] man . . All long options of \f[CR]GNU\f[] man are recognized, but not all of these options are important to \%groffer , so most of them are just ignored. . .

In the following, the man options that have a special meaning for \%groffer are documented. . .

The full set of long and short options of the \f[CR]GNU\f[] man program can be passed via the environment variable .Env_var $MANOPT ; see \%man (1) if your system has \f[CR]GNU\f[] man installed. . . .Opt_def -- all In searching \%man\~pages , retrieve all suitable documents instead of only one. . . .Opt_def - 7 -- ascii In \%text\~modes , display ASCII translation of special characters for critical environment. . This is equivalent to "groff -mtty_char" ; see groff_tmac (@MAN5EXT@). . . .Opt_def -- ditroff Eqivalent to \%groffer .Opt_short Z . . . .Opt_def -- 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 . . . .Opt_def -- locale language . Set the language for \%man\~pages . . This has the same effect, but overwrites .Env_var $LANG . . .Opt_def -- location Print the location of the retrieved files to standard error. . . .Opt_def -- no-location Do not display the location of retrieved files; this resets a former call to .Opt_long location . . This was added by \%groffer . . . .Opt_def -- manpath "'dir1:dir2:\*[Ellipsis]'" 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. . . .Opt_def -- pager Set the pager program in \%tty\~mode ; default is \%less . This is equivalent to .Opt_long tty-viewer . . . .Opt_def -- sections "'sec1:sec2:\*[Ellipsis]'" Restrict searching for \%man\~pages to the given sections , a colon-separated list. . . .Opt_def -- systems "'sys1,sys2,\*[Ellipsis]'" Search for \%man\~pages for the given operating systems; the argument \%systems is a comma-separated list. . . .Opt_def -- where Eqivalent to .Opt_long location . . . --------------------------------------------------------------------

--------------------------------------------------------------------
. The following long options were adapted from the corresponding \%\f[CR]X\~\Window\~Toolkit\f[] options. . \%groffer will pass them to the actual viewer program if it is an \%\f[CR]X\~Window\f[] 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 .Opt_long font for the \%\f[CR]X\~Window\f[] option .Opt_short font . . .

See \%X (1), \%X (7), and the documentation on the \%\f[CR]X\~Window\~Toolkit\f[] options for more details on these options and their arguments. . . .Opt_def -- background color Set the background color of the viewer window. . . .Opt_def -- bd pixels Specifies the color of the border surrounding the viewer window. . . .Opt_def -- bg color This is equivalent to .Opt_long background . . . .Opt_def -- bw pixels Specifies the width in pixels of the border surrounding the viewer window. . . .Opt_def -- display X-display Set the \%\f[CR]X\~Window\f[] display on which the viewer program shall be started, see the \%\f[CR]X\~Window\f[] documentation for the syntax of the argument. . . .Opt_def -- foreground color Set the foreground color of the viewer window. . . .Opt_def -- fg color This is equivalent to .Opt_short foreground . . . .Opt_def -- font font_name Set the font used by the viewer window. . The argument is an \%\f[CR]X\~Window\f[] font name. . . .Opt_def -- ft font_name This is equivalent to .Opt_long ft . . . .Opt_def -- 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. . . .Opt_def -- resolution value Set \%\f[CR]X\~Window\f[] resolution in dpi (dots per inch) in some viewer programs. . The only supported dpi values are 75 and 100 . . Actually, the default resolution for \%groffer is set to 75\~dpi . The resolution also sets the default device in "mode x" . . . .Opt_def -- rv Reverse foreground and background color of the viewer window. . . .Opt_def -- title "'some text'" Set the title for the viewer window. . . .Opt_def -- xrm "'resource'" Set \f[CR]\%X\~Window\f[] resource. . . --------------------------------------------------------------------

--------------------------------------------------------------------
. A \%filespec parameter is an argument that is not an option or option argument. . It means an input source. . In \%groffer , \%filespec parameters are a file name or a template for searching \%man\~pages . . These input sources are collected and composed into a single output file such as \%groff does. . .

The strange \%\f[CR]POSIX\f[] behavior to regard all arguments behind the first non-option argument as \%filespec arguments is ignored. . The \f[CR]GNU\f[] behavior to recognize options even when mixed with \%filespec arguments is used througout. . But, as usual, the double minus argument .Opt_long ends the option handling and interprets all following arguments as \%filespec arguments; so the \%\f[CR]POSIX\f[] behavior can be easily adopted. . .

For the following, it is necessary to know that 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 a digit from 1 to 9 or one of the characters n or o . . In the following, a stand-alone character s stands for a "classical man section" . 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. . .

Each \%filespec parameter can have one of the following forms in decreasing sequence. . . .Topic No \%filespec parameters means that \%groffer waits for standard input. . The minus option .Opt_short "" stands for standard input, too; it can occur several times. . . .Topic Next a \%filespec is tested whether it is the path name of an existing file. . Otherwise it is assumed to be a searching pattern for a \%man\~page . . . .Topic \%man: name ( section ) and \%name ( section ) search the \%man\~page \%name in \%man\~section\~\c \%section , where \%section can be any string, but it must exist in the \%man system. . . .Topic Next some patterns based on the classical man sections are checked. . \%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 a \%man\~page named \%name.s is searched in the lowest man\~section . . . .Topic Now \%man: name searches for a \%man\~page in the lowest \%man\~section that has a document called \%name . . . .Topic 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 both s and \%name as two independent \%filespec arguments. . . .Topic 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. . .

Wildcards in \%filespec arguments are only accepted for .Opt_long apropos* and .Opt_long whatis ; for normal display, they are interpreted as characters. . .

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

--------------------------------------------------------------------
. By default, the \%groffer program collects all input into a single file, formats it with the \%groff program for a certain device, and then chooses 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 .Opt_long_arg mode anymode . Additionally, each of this argument can be specified as an option of its own, such as .Opt_long anymode . Most of these modes have a viewer program, which can be chosen by an option that is constructed like .Opt_long anymode-viewer . . .

Several different modes are offered, graphical modes for \f[CR]\%X\~Window\f[], \%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 .Opt_long default-modes. . .

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

--------------------------------------------------------------------
. The graphical display modes work mostly in the \%\f[CR]X\~Window\f[] environment (or similar implementations within other windowing environments). . The environment variable .Env_var $DISPLAY and the option .Opt_long display are used for specifying the \%\f[CR]X\~Window\f[] display to be used. . If this environment variable is empty \%groffer assumes that no \%\f[CR]X\~Window\f[] is running and changes to a \%text\~mode . . You can change this automatic behavior by the option .Opt_long default-modes . . .

Known viewers for the graphical display modes and their standard \%\f[CR]X\~Window\f[] viewer progams are . .Topic \%\f[CR]X\~Window\f[] roff viewers such as \%gxditview (@MAN1EXT@) or \%xditview (1) (in \%x\~mode ), . .Topic in a Postscript viewer ( \%ps\~mode ), . .Topic in a dvi viewer program ( \%dvi\~mode ), . .Topic in a PDF viewer ( \%pdf\~mode ), . .Topic in a web browser ( html or \%www\~mode ).

. .

The \%pdf\~mode has a major advantage \[em] 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 transform 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 \%\f[CR]X\~Window\~Toolkit\f[]. . But the \%groffer options use a leading double minus instead of the single minus used by the \%\f[CR]X\~Window\~Toolkit\f[]. . . --------------------------------------------------------------------

--------------------------------------------------------------------
. There are two 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 .Env_var \%$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 .Opt_short T or .Opt_long device . . .

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

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

The \%source\~mode with option .Opt_short Q and .Opt_long source just displays the decompressed 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 .Opt_short Z disables post-processing, thus producing the groff intermediate output . . In this mode, the input is formatted, but not postprocessed; see \%groff_out (@MAN5EXT@) for details. . .

All \%groff short options are supported by \%groffer . . . --------------------------------------------------------------------

--------------------------------------------------------------------
. The default behavior of \%groffer is to first test whether a file parameter 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 modified by the following options. . .

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

.Opt_long no-man

+ .Opt_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 \f[CR]GNU\f[] \%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 .File_name /usr/share/man/man7/groff.7.gz , where .File_name /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 \I \%man\~pages uses five search methods. . They are successively tried until a method works. . . .Topic The search path can be manually specified by using the option .Opt_long manpath . An empty argument disables the \%man\~page searching. . This overwrites the other methods. . . .Topic If this is not available the environment variable .Env_var $MANPATH is searched. . . .Topic If this is empty, the program tries to read it from the environment variable .Env_var $MANOPT . . . .Topic If this does not work a reasonable default path from .Env_var $PATH is searched for \%man\~pages . . . .Topic 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 .File_name /usr/share/man/linux/fr and .File_name /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 \f[CR]GNU\f[] man , that is from highest to lowest precedence: .Topic .Opt_long locale . .Topic .Env_var $GROFFER_OPT . .Topic .Env_var $MANOPT . .Topic .Env_var $LCALL . .Topic .Env_var $LC_MESSAGES . .Topic .Env_var $LANG . . .

The language locale is usually specified in the \%\f[CR]POSIX\~1003.1\f[] based format:

\f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\f[]\ \f[I]<character-set>\f[][\f[CB],\f[]\f[I]<version>\f[]]]],

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 `\f[CB]_\f[]', `\f[CB].\f[]', and `\f[CB],\f[]' 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 \f[CR]C\f[] or \f[CR]\%POSIX\f[]. . 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 .Env_var $SYSTEM or by the command line option .Opt_long systems . The precedence is similar to the locale case above from highest to lowest precedence: . Topic .Opt_long systems . .Topic .Env_var $GROFFER_OPT . .Topic .Env_var $MANOPT . .Topic .Env_var $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 sections. . A single section can be specified within each \%filespec argument, several sections as a colon-separated list in command line option .Opt_long sections or environment variable .Env_var $MANSECT . . When no section was specified a set of standard sections is searched until a suitable \%man\~page was found. . .

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

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

--------------------------------------------------------------------
. 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 decompressed on-the-fly. . This includes the \f[CR]GNU\f[] \%.gz , \%.bz2 , and the traditional \%.Z compression. . The program displays the concatenation of all decompressed input in the sequence that was specified on the command line. . . --------------------------------------------------------------------
--------------------------------------------------------------------
. The \%groffer program supports many system variables, most of them by courtesy of other programs. . All environment variables of \%groff (@MAN1EXT@) and \f[CR]GNU\f[] \%man (1) and some standard system variables are honored. . . --------------------------------------------------------------------
--------------------------------------------------------------------
.

.Env_var $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. . Do not forget to export this variable, otherwise it does not exist during the run of groffer . . . --------------------------------------------------------------------

--------------------------------------------------------------------
. The \%groffer program is a shell script that is run through .File_name /bin/sh , which can be internally linked to programs like \%bash (1). The corresponding system environment is automatically effective. . The following variables have a special meaning for \%groffer . . .

.Env_var $DISPLAY If this variable is set this indicates that the \%\f[CR]X\~Window\f[] 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 \%\f[CR]X\~Window\f[] terminal. . For example, depending on your system, \%groffer can be started on the second monitor by the command .Shell_cmd DISPLAY=:0.1\~groffer\~ what.ever & . .

.Env_var $LC_ALL

+ .Env_var $LC_MESSAGES

+ .Env_var $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 \IR \%man\~pages . . A locale name is typically of the form language [\c _\c territory [\c .\c codeset [\c @\c 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 \f[CR]C\f[] and \%\f[CR]POSIX\f[] 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. . .

.Env_var $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 .Shell_cmd PAGER=cat\~groffer\~ anything . .

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

--------------------------------------------------------------------
. The \%groffer program internally calls \%groff , so all environment variables documented in \%groff (@MAN1EXT@) are internally used within \%groffer as well. . The following variable has a direct meaning for the \%groffer program. .

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

--------------------------------------------------------------------
. Parts of the functionality of the man program were implemented in \%groffer ; support for all environment variables documented in \%man (1) was added to \%groffer , but the meaning was slightly modified due to the different approach in \%groffer ; but the user interface is the same. . The man environment variables can be overwritten by options provided with .Env_var $MANOPT , which in turn is overwritten by the command line. . .

.Env_var $EXTENSION Restrict the search for \%man\~pages to files having this extension. . This is overridden by option .Opt_long extension ; see there for details. . .

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

.Env_var $MANPATH If set, this variable contains the directories in which the \%man\~page trees are stored. . This is overridden by option .Opt_long manpath . . .

.Env_var $MANSECT 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 .Opt_long sections . . .

.Env_var $SYSTEM 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 .Opt_long systems ; see there for details. . .

The environment variable .Env_var $MANROFFSEQ is ignored by \%groffer because the necessary preprocessors are determined automatically. . . --------------------------------------------------------------------

--------------------------------------------------------------------
. The \%groffer program can be preconfigured by two configuration files. . .

.File_name /etc/groff/groffer.conf System-wide configuration file for \%groffer . . .

.File_name $HOME/.groff/groffer.conf User-specific configuration file for \%groffer , where .Env_var $HOME denotes the user's home directory. . This file is called after the system-wide configuration file to enable overriding by the user. . .

The precedence of option delivery is given in the following. . The configuration file in .File_name /etc has the lowest precedence; it is overwritten by the configuration file in the home directory; both configuration files are overwritten by the environment variable .Env_var $GROFFER_OPT ; everything is overwritten by the command line. . .

In the configuration files, arbitrary spaces are allowed at the beginning of each line, they are just ignored. . Apart from that, the lines of the configuration lines either start with a minus character, all other lines are interpreted as shell commands. . .

The lines with the beginning minus are interpreted as groffer options. . This easily allows to set general \%groffer options that should be used with any call of \%groffer . . Each line can represent a single short option, a short option cluster, or a long option with two minus signs, eventually with an argument. . The argument can be appended either after a space character or an equal sign ` = '. The argument can be surrounded by quotes, but this is not necessary. . The options from these lines are collected and prepended to the existing value of .Env_var $GROFFER_OPT at the end of each configuration file. . .

After the transformation of the minus lines, the configuration files have been transferred into a shell script that is called within \%groffer using the `\c .CB \.\~\c \%filename ' shell syntax. . .

It makes sense to use these configuration files for the following tasks: . .Topic Preset command line options, such as choosing a \%mode or a viewer. . These are written into lines starting with a single or double minus sign, followed by the option name. . .Topic Preset environment variables recognized by \%groffer ; but do not forget to export them. . .Topic You can also write a shell function for calling, for example a viewer program for some \%mode . Such a function can be fed into a corresponding .Opt_long \f[I]mode\f[]-viewer option. . .Topic Enter .Opt_long shell to specify a shell for the run of .File_name groffer2.sh . Some shells run much faster than the standard shell. . .

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

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

. .

The lines starting with # are command lines. . This configuration sets four \%groffer options (the lines starting with `-') and runs two shell commands (the rest of the script). . This has the following effects: . . .Topic Use ksh as the shell to run the \%groffer script; if it works it should be faster than the usual sh . . . .Topic Use a text color of \%DarkBlue in all viewers that support this, such as \%gxditview . . . .Topic Use a resolution of 100\~dpi in all viewers that support this, such as \%gxditview . . By this, the default device in x mode is set to X100 . . . .Topic Force \%gxditview (@MAN1EXT@) as the \%x-mode viewer using the geometry option for setting the width to 900\~dpi and the height to 1200\~dpi . This geometry is suitable for a resolution of 100\~dpi . . . .Topic If the environment variable .Env_var $DISPLAY is empty set it to localhost:0.0 . . That allows to start \%groffer in the standard \%\f[CR]X\~Window\f[] display, even when the program is called from a text console. . . .Topic Just for fun, the date of each \%groffer start is written to the file .File_name mygroffer.log in the home directory. . . --------------------------------------------------------------------

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

.Shell_cmd "groffer\~/usr/local/share/doc/groff/meintro.ms.gz" Decompress, format and display the compressed file .File_name meintro.ms.gz in the directory .File_name /usr/local/share/doc/groff , using the standard viewer \%gxditview as graphical viewer when in \%\f[CR]X\~Window\f[], or the \%less (1) pager program when not in \%\f[CR]X\~Window\f[]. . .

.Shell_cmd "groffer\~groff" If the file .File_name \%./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 section 1 in this case. . .

.Shell_cmd "groffer\~man:groff" search for the \%man\~page of \%groff even when the file .File_name ./groff exists. . .

.Shell_cmd "groffer\~groff.7"

+ .Shell_cmd "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. . .

.Shell_cmd "groffer\~fb.modes" If the file .File_name ./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 . . .

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

.Shell_cmd "LANG=de\~groffer\~--man\~--www\~--www-viever=galeon\~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 .Opt_long man guarantees that the \%man\~page is retrieved, even when a local file .File_name \%ls exists in the actual directory. . .

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

.Shell_cmd "cat\~file.gz\~|\~groffer\~-Z\~-mfoo" . Decompress the standard input, send this to \%groff intermediate output mode without post-processing ( groff option .Opt_short Z ), using macro package by \%foo ( groff option .Opt_short m ) . . .

.Shell_cmd "echo\~'\[rs]f[CB]WOW!'\~|"

+ .Shell_cmd+ "groffer --x --bg red --fg yellow --geometry 200x100 -" . Display the word \f[CB]WOW!\f[] in a small window in constant-width bold font, using color yellow on red background. . . --------------------------------------------------------------------

--------------------------------------------------------------------
. The \%groffer program consists of two shell scripts. . .

The starting script is the file .File_name \%groffer that is installed in a .File_name bin directory. . It is generated from the source file .File_name \%groffer.sh . . It is just a short starting script without any functions such that it can run on very poor shells. . .

The main part of the \%groffer program is the file .File_name groffer2.sh that is installed in the groff library directory. . This script can be run under a different shell by using the \%groffer option .Opt_long shell . . .

Both scripts are compatible with both \f[CR]GNU\f[] and \%\f[CR]POSIX\f[]. . \%\f[CR]POSIX\f[] compatibility refers to \%\f[CR]IEEE\~P1003.2/D11.2\f[] of September 1991, a very early version of the \%\f[CR]POSIX\f[] standard that is still freely available in the internet at RL http://\:www.funet.fi/\:pub/\:doc/\:posix/\:p1003.2/\:d11.2/\:all \ "\%POSIX\~P1003.2\~draft\~11.2" . . .

Only a restricted set of shell language elements and shell builtins is used to achieve even compatibility with some Bourne shells that are not fully \%\f[CR]POSIX\f[] compatible. . The \%groffer shell scripts were tested on many shells, including the following Bourne shells: \%ash (1), \%bash (1), \%dash (1), \%ksh (1), \%pdksh (1), \%posh (1), and \%zsh (1). So it should work on most actual free and commercial operating systems. . .

The shell for the run of .File_name groffer2.sh can be chosen by the option .Opt_long shell on the command line or the environment variable .Env_var $GROFF_OPT . If you want to add it to one of the \%groffer configuration files you must write a line starting with .Opt_long shell . . .

The \%groffer program provides its own parser for command line arguments that is compatible to both \%\f[CR]POSIX\f[] \%getopts (1) and \%\f[CR]GNU\f[] \%getopt (1). It can handle option arguments and file names containing white space and a large set of special characters. . The following standard types of options are supported. . . .Topic The option consisiting of a single minus .Opt_short refers to standard input. . . .Topic A single minus followed by characters refers to a single character option or a combination thereof; for example, the \%groffer short option combination .Opt_short Qmfoo is equivalent to .Opt_short Q\~-m\~foo . . . .Topic Long options are options with names longer than one character; they are always preceded 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, .Opt_alt -- long=arg is equivalent to .Opt_alt -- long\~arg . . . .Topic An argument of .Opt_-- ends option parsing; all further command line arguments are interpreted as \%filespec parameters, i.e. file names or constructs for searching \%man\~pages ). . . .Topic 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 .Shell_cmd "groffer file1 -a -o arg file2" is equivalent to .Shell_cmd "groffer -a -o arg -- file1 file2" . .

The free mixing of options and \%filespec parameters follows the GNU principle. . That does not fulfill the strange option behavior of \%\f[CR]POSIX\f[] that ends option processing as soon as the first non-option argument has been reached. . The end of option processing can be forced by the option ` -- ' anyway. . . --------------------------------------------------------------------

--------------------------------------------------------------------
. Report bugs to the .MTO bug-groff@gnu.org "bug-groff mailing list" . . Include a complete, self-contained example that will allow the bug to be reproduced, and say which version of \%groffer you are using. . .

You can also use the .MTO groff@gnu.org "groff mailing list" , but you must first subscribe to this list. . You can do that by visiting the RL http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff \ "groff mailing list web page" . . .

See \%groff (@MAN1EXT@) for information on availability. . . --------------------------------------------------------------------

--------------------------------------------------------------------
.

\%groff (@MAN1EXT@), \%@g@troff (@MAN1EXT@)

. .

\%groff (@MAN7EXT@) Documentation of the \%groff language. . .

\%grog (@MAN1EXT@) Internally, \%groffer tries to guess the \%groff command line options from the input using this program. . .

groff_out (@MAN5EXT@) Documentation on the \%groff intermediate output ( ditroff output). . .

groff_tmac (@MAN5EXT@) Documentation on the \%groff macro files. . .

\%man (1) The standard program to display \%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 . . .

\%ash (1), \%bash (1), \%dash (1), \%ksh (1), \%pdksh (1), \%posh (1), \%sh (1), \%zsh (1)

. .

\%gxditview (@MAN1EXT@), \%xditview (1x)

. .

\%kghostview (1), \%ggv (1), \%gv (1), \%ghostview (1), \%gs (1)

. .

\%kghostview (1), \%ggv (1), \%xpdf (1), \%acroread (1), \%kpdf (1)

. .

\%kdvi (1), \%xdvi (1), \%dvilx (1)

. .

\%konqueror (1), \%mozilla (1), \%lynx (1)

. .

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

\%gzip (1), \%bzip2 (1)

. . --------------------------------------------------------------------
--------------------------------------------------------------------
.author . . --------------------------------------------------------------------
--------------------------------------------------------------------
.copyleft . . --------------------------------------------------------------------
Emacs settings
--------------------------------------------------------------------
. Local Variables:
mode: nroff
End: