# phpman > man > groffer(1) [GROFFER(1)](https://www.chedong.com/phpMan.php/man/GROFFER/1/markdown) General Commands Manual [GROFFER(1)](https://www.chedong.com/phpMan.php/man/GROFFER/1/markdown) ## NAME groffer - display groff files and man pages on X and tty ## SYNOPSIS **groffer** [_mode-option_ ...] [_groff-option_ ...] [_man-option_ ...] [_X-option_ ...] [**--**] [_filespec_ ...] ### groffer -h ### groffer --help ### groffer -v ### groffer --version ## DESCRIPTION The **groffer** program is the easiest way to use [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). It can display arbitrary documents written in the _groff_ language, see [**groff**(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown), or other _roff_ languages, see [**roff**(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown), that are compatible to the original _troff_ language. It finds and runs all necessary _groff_ preproces‐ sors, such as **chem**. The **groffer** program also includes many of the features for finding and displaying the Unix manual pages (_man_ _pages_), such that it can be used as a replacement for a [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) program. Moreover, compressed files that can be handled by [**gzip**(1)](https://www.chedong.com/phpMan.php/man/gzip/1/markdown) or [**bzip2**(1)](https://www.chedong.com/phpMan.php/man/bzip2/1/markdown) are decompressed on- the-fly. The normal usage is quite simple by supplying a file name or name of a _man_ _page_ without fur‐ ther 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 X Window System-based _groff_ program [**gxditview**(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown), each _PostScript_, _PDF_, or _DVI_ display program, a web browser by generating _HTML_ or _XHTML_ in _www_ _mode_, or several _text_ _modes_ in text terminals. Most of the options that must be named when running **groff** directly are determined automati‐ cally for **groffer**, due to the internal usage of the [**grog**(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) 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 GNU style. Options and file names can be mixed freely. The op‐ tion “**--**” closes the option handling, all following arguments are treated as file names. Long options can be abbreviated in several ways. ## OPTION OVERVIEW _breaking_ _options_ [**-h** | **--help**] [**-v** | **--version**] _groffer_ _mode_ _options_ [**--auto**] [**--default**] [**--default-modes** _mode1,mode2,..._] [**--dvi**] [**--groff**] [**--html**] [**--latin1**] [**--mode** _display_mode_] [**--pdf**] [**--pdf2**] [**--ps**] [**--source**] [**--text**] [**--to-stdout**] [**--tty**] [**--utf8**] [**--viewer** _prog_] [**--www**] [**--xhtml**] [**--x** | **--X**] _options_ _related_ _to_ _groff_ [**-T** | **--device** _device_] [**-Z** | **--intermediate-output** | **--ditroff**] All further **groff** short options are accepted. _options_ _for_ _man_ _pages_ [**--apropos**] [**--apropos-data**] [**--apropos-devel**] [**--apropos-progs**] [**--man**] [**--no-man**] [**--no-special**] [**--whatis**] _long_ _options_ _taken_ _over_ _from_ _GNU_ _man_ [**--all**] [**--ascii**] [**--ditroff**] [**--extension** _suffix_] [**--locale** _language_] [**--local-file**] [**--location** | **--where**] [**--manpath** _dir1:dir2:..._] [**--no-location**] [**--pager** _program_] [**--sections** _sec1:sec2:..._] [**--systems** _sys1,sys2,..._] [**--troff-device** _device_] Further long options of GNU **man** are accepted as well. _options_ _mapped_ _to_ _X_ _Window_ _System_ _Toolkit_ _Intrinsics_ _options_ [**--bd** | **--bordercolor** _pixels_] [**--bg** | **--background** _color_] [**--bw** | **--borderwidth** _pixels_] [**--display** _X-display_] [**--fg** | **--foreground** _color_] [**--fn** | **--ft** | **--font** _font_name_] [**--geometry** _size_pos_] [**--resolution** _value_] [**--rv**] [**--title** _string_] [**--xrm** _X-resource_] _options_ _for_ _development_ [**--debug**] [**--debug-filenames**] [**--debug-grog**] [**--debug-keep**] [**--debug-params**] [**--debug-tmpdir**] [**--do-nothing**] [**--print** _text_] [**-V**] _filespec_ _arguments_ The _filespec_ parameters are all arguments that are neither an option nor an option ar‐ gument. They usually mean a file name or a _man_ _page_ searching scheme. In the following, the term _section_extension_ is used. It means a word that consists of a _man_ _section_ that is optionally followed by an _extension_. The name of a _man_ _sec__‐ _tion_ is a single character from **[1**––**9on]**, the _extension_ is some word. The _extension_ is mostly lacking. No _filespec_ parameters means standard input. **-** stands for standard input (can occur several times). _filename_ the path name of an existing file. **man:**_name_**(**_section_extension_**)** **man:**_name_**.**_section_extension_ _name_**(**_section_extension_**)** _name_**.**_section_extension_ _section_extension_ _name_ search the man page _name_ in the section with optional extension _section_ex__‐ _tension_. **man:**_name_ man page in the lowest _man_ _section_ that has _name_. _name_ if _name_ is not an existing file search for the man page _name_ in the lowest man section. ## OPTION DETAILS The **groffer** program can usually be run with very few options. But for special purposes, it supports many options. These can be classified in 5 option classes. All short options of **groffer** are compatible with the short options of [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). All long op‐ tions of **groffer** are compatible with the long options of [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown). Arguments for long option names can be abbreviated in several ways. First, the argument is checked whether it can be prolonged as is. Furthermore, each minus sign **-** is considered as a starting point for a new abbreviation. This leads to a set of multiple abbreviations for a single argument. For example, **--de-n-f** can be used as an abbreviation for **--debug-not-func**, but **--de-n** works as well. If the abbreviation of the argument leads to several resulting op‐ tions an error is raised. These abbreviations are only allowed in the environment variable _GROFFER_OPT_, but not in the configuration files. In configuration, all long options must be exact. ### groffer breaking Options As soon as one of these options is found on the command line it is executed, printed to stan‐ dard output, and the running **groffer** is terminated thereafter. All other arguments are ig‐ nored. ### -h --help Print help information with a short explanation of options to standard output. ### -v --version Print version information to standard output. ### groffer Mode Options 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 automati‐ cally. The default modes are _mode_ _pdf_, _mode_ _ps_, _mode_ _html_, _mode_ _xhtml_, _mode_ _x_, and _mode_ _dvi_ in the X Window System with different viewers and _mode_ _tty_ with device _utf8_ under **less** on a terminal; other modes are tested if the programs for the main default mode do not exist. In the X Window System, many programs create their own window when called. **groffer** can run these viewers as an independent program in the background. As this does not work in text mode on a terminal (tty) there must be a way to know which viewers are X Window System-based graphical programs. The **groffer** script has a small amount of information on some viewer names. If a viewer argument of the command-line chooses an element that is recognized as an X Window System-based program in this list, it is treated as a viewer that can run in the background. Unrecognized viewers are not run in the background. For each mode, you are free to choose whatever viewer you want. That need not be some graph‐ ical viewer suitable for this mode. There is a chance to view the output source; for exam‐ ple, the combination of the options **--mode=ps** and **--viewer=less** shows the content of the _PostScript_ output, the source code, with the pager **less**. **--auto** Equivalent to **--mode=auto**. ### --default Reset all configuration from previously processed command-line options to the default values. This is useful to wipe out all former options of the configuration, in _GROFFER_OPT_, and restart option processing using only the rest of the command line. **--default-modes** _mode1,mode2,..._ Set the sequence of modes for _auto_ _mode_ to the comma separated list given in the argu‐ ment. See **--mode** for details on modes. Display in the default manner; actually, this means to try the modes _x_, _ps_, and _tty_ in this sequence. **--dvi** Equivalent to **--mode=dvi**. Known _DVI_ viewers for the X Window System include [**xdvi**(1)](https://www.chedong.com/phpMan.php/man/xdvi/1/markdown) and [**dvilx**(1)](https://www.chedong.com/phpMan.php/man/dvilx/1/markdown). ### --groff Equivalent to **--mode=groff**. **--html** Equivalent to **--mode=html**. **--mode** _value_ Set the display mode. The following mode values are recognized: **auto** Select the automatic determination of the display mode. The sequence of modes that are tried can be set with the **--default-modes** option. Useful for restor‐ ing the _default_ _mode_ when a different mode was specified before. **dvi** Display formatted input in a _DVI_ viewer program. By default, the formatted in‐ put is displayed with the [**xdvi**(1)](https://www.chedong.com/phpMan.php/man/xdvi/1/markdown) program. **groff** After the file determination, switch **groffer** to process the input like [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) would do. This disables the _groffer_ viewing features. **html** Translate the input into HTML format and display the result in a web browser program. By default, the existence of a sequence of standard web browsers is tested, starting with [**konqueror**(1)](https://www.chedong.com/phpMan.php/man/konqueror/1/markdown) and [**mozilla**(1)](https://www.chedong.com/phpMan.php/man/mozilla/1/markdown). The text HTML viewer is [**lynx**(1)](https://www.chedong.com/phpMan.php/man/lynx/1/markdown). By default, the existence of a sequence of standard web browsers is tested, starting with [**konqueror**(1)](https://www.chedong.com/phpMan.php/man/konqueror/1/markdown) and [**mozilla**(1)](https://www.chedong.com/phpMan.php/man/mozilla/1/markdown). The text HTML viewer is [**lynx**(1)](https://www.chedong.com/phpMan.php/man/lynx/1/markdown). **pdf** Transform _roff_ _input_ _files_ into a _PDF_ _file_ by using the **groff** **(1)** device **-Tpdf**. This is the default **PDF** generator. The generated _PDF_ _file_ is displayed with suitable viewer programs, such as [**okular**(1)](https://www.chedong.com/phpMan.php/man/okular/1/markdown). **pdf2** This is the traditional _pdf_ _mode_. Sometimes this mode produces more correct output than the default **PDF** **mode**. By default, the input is formatted by **groff** using the PostScript device, then it is transformed into the PDF file format using [**gs**(1)](https://www.chedong.com/phpMan.php/man/gs/1/markdown), or [**ps2pdf**(1)](https://www.chedong.com/phpMan.php/man/ps2pdf/1/markdown). If that's not possible, the _PostScript_ _mode_ _(ps)_ is used instead. Finally it is displayed using different viewer programs. **ps** Display formatted input in a PostScript viewer program. By default, the for‐ matted input is displayed in one of many viewer programs. **text** Format in a _groff_ _text_ _mode_ and write the result to standard output without a pager or viewer program. The text device, _latin1_ by default, can be chosen with option **-T**. **tty** Format in a _groff_ _text_ _mode_ and write the result to standard output using a text pager program, even when in the X Window System. **www** Equivalent to **--mode=html**. **x** Display the formatted input in a native _roff_ viewer. By default, the formatted input is displayed with the [**gxditview**(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown) program being distributed together with **groff**. But the legacy X Window System application [**xditview**(1)](https://www.chedong.com/phpMan.php/man/xditview/1/markdown) can also be chosen with the option **--viewer**. The default resolution is **75dpi**, but **100dpi** are also possible. The default _groff_ device for the resolution of **75dpi** is **X75-12**, for **100dpi** it is **X100**. The corresponding _groff_ _intermediate_ _output_ for the actual device is generated and the result is displayed. For a resolution of **100dpi**, the default width of the geometry of the display program is chosen to **850dpi**. **X** Equivalent to **--mode=x**. **xhtml** Translate the input into _XHTML_ format, which is an _XML_ version of _HTML_. Then display the result in a web browser program, mostly the known _HTML_ _viewers_. The following modes do not use the _groffer_ viewing features. They are only interest‐ ing for advanced applications. **groff** Generate device output with plain _groff_ without using the special viewing fea‐ tures of _groffer_. If no device was specified by option **-T** the _groff_ default **ps** is assumed. **source** Output the roff source code of the input files without further processing. **--pdf** Equivalent to **--mode=pdf**. **--pdf2** Equivalent to **--mode=pdf2**. **--ps** Equivalent to **--mode=ps**. Common PostScript viewers include [**okular**(1)](https://www.chedong.com/phpMan.php/man/okular/1/markdown), [**evince**(1)](https://www.chedong.com/phpMan.php/man/evince/1/markdown), [**gv**(1)](https://www.chedong.com/phpMan.php/man/gv/1/markdown), [**ghostview**(1)](https://www.chedong.com/phpMan.php/man/ghostview/1/markdown), and [**gs**(1)](https://www.chedong.com/phpMan.php/man/gs/1/markdown), In each case, arguments can be provided additionally. ### --source Equivalent to **--mode=source**. **--text** Equivalent to **--mode=text**. ### --to-stdout The file for the chosen mode is generated and its content is printed to standard out‐ put. It will not be displayed in graphical mode. **--tty** Equivalent to **--mode=tty**. The standard pager is [**less**(1)](https://www.chedong.com/phpMan.php/man/less/1/markdown). This option is equivalent to _man_ option **--pager=**_prog_. The option argument can be a file name or a program to be searched in _$PATH_; arguments can be provided additionally. **--viewer** _prog_ Choose a viewer program for actual device or mode. This can be a file name or a pro‐ gram to be searched in _$PATH_; arguments can be provided additionally. **--www** Equivalent to **--mode=html**. **--X** | **--x** Equivalent to **--mode=x**. Suitable viewer programs are [**gxditview**(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown) which is the de‐ fault and [**xditview**(1)](https://www.chedong.com/phpMan.php/man/xditview/1/markdown). **--** 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**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) 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. ### Options related to groff All short options of **groffer** are compatible with the short options of [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). The follow‐ ing 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 **-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. **--a** This generates an ASCII approximation of output in the _text_ _modes_. That could be im‐ portant when the text pager has problems with control sequences in _tty_ _mode_. **--m** _file_ Add _file_ as a _groff_ macro file. This is useful in case it cannot be recognized auto‐ matically. **--P** _opt_or_arg_ Send the argument _opt_or_arg_ as an option or option argument to the actual **groff** post‐ processor. **--T** _devname_ | **--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**, **utf8**, 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** **--mode=**_devname_ option: **dvi**, **html**, **xhtml**, and **ps**. All **X*** arguments are mapped to _mode_ _x_. Each other _devname_ argu‐ ment switches to _mode_ _groff_ using this device. **--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 **--X** instead because the _x_ _mode_ uses an _X_* device for a better display. ### -Z --intermediate-output --ditroff Switch into _groff_ _mode_ and format the input with the _groff_ _intermediate_ _output_ without postprocessing; see **groff**___**[out**(5)](https://www.chedong.com/phpMan.php/man/out/5/markdown). This is equivalent to option **--ditroff** of _man_, which can be used as well. All other **groff** options are supported by **groffer**, but they are just transparently transferred to **groff** without any intervention. The options that are not explicitly handled by **groffer** are transparently passed to **groff**. Therefore these transparent options are not documented here, but in [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown). Due to the automatism in **groffer**, none of these **groff** options should be needed, except for advanced usage. ### Options for man pages ### --apropos Start the [**apropos**(1)](https://www.chedong.com/phpMan.php/man/apropos/1/markdown) command or facility of [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) for searching the _filespec_ argu‐ ments 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 _language_ locale is handled only when the called programs do support this; the GNU **apropos** and **man** **-k** do not. The display differs from the **apropos** program by the following concepts: * Construct a _groff_ frame similar to a _man_ _page_ to the output of **apropos**, * each _filespec_ argument is searched on its own. * The restriction by **--sections** is handled as well, * wildcard characters are allowed and handled without a further option. ### --apropos-data Show only the **apropos** descriptions for data documents, these are the [**man**(7)](https://www.chedong.com/phpMan.php/man/man/7/markdown) _sec__‐ _tions_ _4_, _5_, and _7_. Direct _section_ declarations are ignored, wildcards are accepted. ### --apropos-devel Show only the **apropos** descriptions for development documents, these are the [**man**(7)](https://www.chedong.com/phpMan.php/man/man/7/markdown) _sections_ _2_, _3_, and _9_. Direct _section_ declarations are ignored, wildcards are ac‐ cepted. ### --apropos-progs Show only the **apropos** descriptions for documents on programs, these are the [**man**(7)](https://www.chedong.com/phpMan.php/man/man/7/markdown) _sections_ _1_, _6_, and _8_. Direct _section_ declarations are ignored, wildcards are ac‐ cepted. ### --whatis For each _filespec_ argument search all _man_ _pages_ and display their description — or say that it is not a _man_ _page_. This is written from anew, so it differs from _man_'s **whatis** output by the following concepts * each retrieved file name is added, * local files are handled as well, * the _language_ and _system_ locale is supported, * the display is framed by a _groff_ output format similar to a _man_ _page_, * wildcard characters are allowed without a further option. The following 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. **--man** Check the non-option command-line arguments (_filespecs_) first on being _man_ _pages_, then whether they represent an existing file. By default, a _filespec_ is first tested whether it is an existing file. **--no-man** | **--local-file** Do not check for _man_ _pages_. **--local-file** is the corresponding **man** option. ### --no-special Disable former calls of **--all**, **--apropos***, and **--whatis**. ### Long options taken over from GNU man The long options of **groffer** were synchronized with the long options of GNU **man**. All long op‐ tions of GNU **man** are recognized, but not all of these options are important to **groffer**, so most of them are just ignored. These ignored **man** options are **--catman**, **--troff**, and **--up**‐‐ **date**. In the following, the **man** options that have a special meaning for **groffer** are documented. If your system has GNU **man** installed the full set of long and short options of the GNU **man** program can be passed via the environment variable _MANOPT_; see [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown). **--all** In searching _man_ _pages_, retrieve all suitable documents instead of only one. ### -7 --ascii In _text_ _modes_, display ASCII translation of special characters for critical environ‐ ment. This is equivalent to **groff** **-mtty**___**char**; see **groff**___**[tmac**(5)](https://www.chedong.com/phpMan.php/man/tmac/5/markdown). ### --ditroff Produce _groff_ _intermediate_ _output_. This is equivalent to **groffer** **-Z**. **--extension** _suffix_ Restrict _man_ _page_ search to file names that have _suffix_ appended to their section ele‐ ment. For example, in the file name _/usr/share/man/man3/terminfo.3ncurses.gz_ the _man_ _page_ extension is _ncurses_. **--locale** _language_ Set the language for _man_ _pages_. This has the same effect, but overwrites _$LANG_. ### --location Print the location of the retrieved files to standard error. ### --no-location Do not display the location of retrieved files; this resets a former call to **--loca**‐‐ **tion**. This was added by **groffer**. **--manpath** _'dir1:dir2:...'_ Use the specified search path for retrieving _man_ _pages_ instead of the program de‐ faults. If the argument is set to the empty string "" the search for _man_ _page_ is dis‐ abled. ### --pager Set the pager program in _tty_ _mode_; default is **less**. This can be set with **--viewer**. **--sections** _sec1:sec2:..._ Restrict searching for _man_ _pages_ to the given _sections_, a colon-separated list. **--systems** _sys1,sys2,..._ Search for _man_ _pages_ for the given operating systems; the argument _systems_ is a comma- separated list. ### --where Equivalent to **--location**. ### X Window System Toolkit Intrinsics Options The following long options were adapted from the corresponding X Window System Toolkit In‐ trinsics options. **groffer** will pass them to the actual viewer program if it is an X Window System 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 ex‐ ample, **groffer** uses the option **--font** for the X Window System Toolkit Intrinsics option ### -font See [**X**(7)](https://www.chedong.com/phpMan.php/man/X/7/markdown) and the manual _X_ _Toolkit_ _Intrinsics_ _– _C_ _Language_ _Interface_ for more details on these options and their arguments. **--background** _color_ Set the background color of the viewer window. **--bd** _pixels_ This is equivalent to **--bordercolor**. **--bg** _color_ This is equivalent to **--background**. **--bw** _pixels_ This is equivalent to **--borderwidth**. **--bordercolor** _pixels_ Specifies the color of the border surrounding the viewer window. **--borderwidth** _pixels_ Specifies the width in pixels of the border surrounding the viewer window. **--display** _X-display_ Set the X Window System display on which the viewer program shall be started. See section “Display Names” in [**X**(7)](https://www.chedong.com/phpMan.php/man/X/7/markdown) for the syntax of the argument. **--foreground** _color_ Set the foreground color of the viewer window. **--fg** _color_ This is equivalent to **--foreground**. **--fn** _font_name_ This is equivalent to **--font**. **--font** _font_name_ Set the font used by the viewer window. The argument is an X Window System font name. **--ft** _font_name_ This is equivalent to **--font**. **--geometry** _size_pos_ Set the geometry of the display window, that means its size and its starting position. See section “Geometry Specifications” in [**X**(7)](https://www.chedong.com/phpMan.php/man/X/7/markdown) for the syntax of the argument. **--resolution** _value_ Set X Window System 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 **75dpi**. The resolution also sets the default device in _mode_ _x_. **--rv** Reverse foreground and background color of the viewer window. **--title** _'some_ _text'_ Set the title for the viewer window. **--xrm** _'resource'_ Set the X Window System server resource to the given value. ### Options for Development ### --debug Enable all debugging options **--debug-**_type_. The temporary files are kept and not deleted, the **grog** output is printed, the name of the temporary directory is printed, the displayed file names are printed, and the parameters are printed. ### --debug-filenames Print the names of the files and _man_ _pages_ that are displayed by **groffer**. ### --debug-grog Print the output of all **grog** commands. ### --debug-keep Enable two debugging informations. Print the name of the temporary directory and keep the temporary files, do not delete them during the run of **groffer**. ### --debug-params Print the parameters, as obtained from the configuration files, from _GROFFER_OPT_, and the command-line arguments. ### --debug-tmpdir Print the name of the temporary directory. ### --do-nothing This is like **--version**, but without the output; no viewer is started. This makes only sense in development. **--print=**_text_ Just print the argument to standard error. This is good for parameter check. ### -V input, a lot of _groffer_ specific information is printed to standard output: * the output file name in the temporary directory, * the display mode of the actual **groffer** run, * the display program for viewing the output with its arguments, * the active parameters from the config files, the arguments in _GROFFER_OPT_, and the arguments of the command line, * the pipeline that would be run by the **groff** program, but without executing it. Other useful debugging options are the **groff** option **-Z** and **--mode=groff**. ### Filespec Arguments A _filespec_ parameter is an argument that is not an option or option argument. 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 POSIX behavior to regard all arguments behind the first non-option argument as _filespec_ arguments is ignored. The GNU behavior to recognize options even when mixed with _filespec_ arguments is used throughout. But, as usual, the double minus argument **--** ends the option handling and interprets all following arguments as _filespec_ arguments; so the POSIX behavior can be easily adopted. The options **--apropos*** have a special handling of _filespec_ arguments. Each argument is taken as a search scheme of its own. Also a regexp (regular expression) can be used in the file‐ spec. For example, **groffer** **--apropos** **'^gro.f$'** searches **groff** in the _man_ _page_ name, while **groffer** **--apropos** **groff** searches **groff** somewhere in the name or description of the _man_ _pages_. All other parts of _groffer_, such as the normal display or the output with **--whatis** have a different scheme for _filespecs_. No regular expressions are used for the arguments. The _filespec_ arguments are handled by the following scheme. It is necessary to know that on each system the _man_ _pages_ are sorted according to their con‐ tent 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**. This can optionally be followed by a string, the so-called _extension_. The _extension_ allows the storage of several _man_ _pages_ with the same name in the same _section_. But the _extension_ is only rarely used; usually it is omitted. Then the _extensions_ are searched automatically by alphabet. In the following, we use the name _section_extension_ for a word that consists of a single character _section_ name or a _section_ character that is followed by an _extension_. Each _filespec_ parameter can have one of the following forms in decreasing sequence. * No _filespec_ parameters means that **groffer** waits for standard input. The minus option **-** al‐ ways stands for standard input; it can occur several times. If you want to look up a _man_ _page_ called **-** use the argument **man:-**. * 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_. * **man:**_name_**(**_section_extension_**)**_,_ **man:**_name_**.**_section_extension,_ _name_**(**_section_extension_**)**_,_ or _name_**.**_section_extension_ search the man page _name_ in man section and possibly extension of _section_extension_. * Now **man:**_name_ searches for a _man_ _page_ in the lowest _man_ _section_ that has a document called _name_. * _section_extension_ _name_ is a pattern of 2 arguments that originates from a strange argument parsing of the **man** program. Again, this searches the man page _name_ with _section_extension_, a combination of a _section_ character optionally followed by an _extension_. * We are left with the argument _name_ which is not an existing file. So this searches for the _man_ _page_ called _name_ in the lowest _man_ _section_ that has a document for this name. Several file name arguments can be supplied. They are mixed by **groff** into a single document. Note that the set of option arguments must fit to all of these file arguments. So they should have at least the same style of the _groff_ language. ## OUTPUT MODES By default, the **groffer** program collects all input into a single file, formats it with the **groff** program for a certain device, and then 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 **--mode=**_anymode_. Additionally, each of this argument can be specified as an option of its own, such as **anymode**. Most of these modes have a viewer program, which can be chosen by the option **--viewer**. Several different modes are offered: graphical modes for the X Window System, _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 sep‐ arated list of modes with the option **--default-modes.** The searching for _man_ _pages_ and the decompression of the input are active in every mode. ### Graphical Display Modes The graphical display modes work mostly in the X Window System environment (or similar imple‐ mentations within other windowing environments). The environment variable _DISPLAY_ and the option **--display** are used for specifying the X Window System display to be used. If this en‐ vironment variable is empty, **groffer** assumes that the X Window System is not running and changes to a _text_ _mode_. You can change this automatic behavior by the option **--de**‐‐ **fault-modes**. Known viewers for the graphical display modes and their standard X Window System viewer pro‐ grams are * in a PDF viewer (_pdf_ _mode_) * in a web browser (_html_, (_xhtml_, or _www_ _mode_) * in a PostScript viewer (_ps_ _mode_) * X Window System _roff_ viewers such as [**gxditview**(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown) or [**xditview**(1)](https://www.chedong.com/phpMan.php/man/xditview/1/markdown) (in _x_ _mode_) * in a DVI viewer program (_dvi_ _mode_) The _pdf_ _mode_ has a major advantage — it is the only graphical display mode that allows searching 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 X Window System Toolkit Intrin‐ sics. But the **groffer** options use a leading double minus instead of the single minus used by the X Window System Toolkit Intrinsics. ### Text modes 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 _DISPLAY_ is not set or empty, **groffer** assumes that it should use _tty_ _mode_. In the actual implementation, the _groff_ output device _latin1_ is chosen for _text_ _modes_. This can be changed by specifying option **-T** or **--device**. The pager to be used can be specified by one of the options **--pager** and **--viewer**, or by the environment variable _PAGER_. If all of this is not used the [**less**(1)](https://www.chedong.com/phpMan.php/man/less/1/markdown) program with the option ### -r ### Special Modes for Debugging and Development These modes use the _groffer_ file determination and decompression. This is combined into a single input file that is fed directly into **groff** with different strategy without the _groffer_ viewing facilities. These modes are regarded as advanced, they are useful for debugging and development purposes. The _source_ _mode_ with option **--source** just displays the decompressed input. Option **--to-stdout** does not display in a graphical mode. It just generates the file for the chosen mode and then prints its content to standard output. 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 an‐ other program. In _groff_ _mode_, the option **-Z** disables post-processing, thus producing the _groff_ _intermediate_ _output_. In this mode, the input is formatted, but not postprocessed; see **groff**___**[out**(5)](https://www.chedong.com/phpMan.php/man/out/5/markdown) for details. All **groff** short options are supported by **groffer**. ## MAN PAGE SEARCHING The default behavior of **groffer** is to first test whether a file parameter represents a local file; if it is not an existing file name, it is assumed to represent the name of a _man_ _page_. The following options can be used to determine whether the arguments should be handled as file name or _man_ _page_ arguments. **--man** forces to interpret all file parameters as _filespecs_ for searching _man_ _pages_. ### --no-man ### --local-file disable the _man_ searching; so only local files are displayed. If neither a local file nor a _man_ _page_ was retrieved for some file parameter a warning is is‐ sued on standard error, but processing is continued. ### Search Algorithm Let us now assume that a _man_ _page_ should be searched. The **groffer** program provides a search facility for _man_ _pages_. All long options, all environment variables, and most of the func‐ tionality of the GNU [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) program were implemented. The search algorithm shall determine which file is displayed for a given _man_ _page_. The process can be modified by options and en‐ vironment variables. The only _man_ action that is omitted in **groffer** are the preformatted _man_ _pages_, also called _cat_ _pages_. With the excellent performance of the actual computers, the preformatted _man_ _pages_ aren't necessary any longer. Additionally, **groffer** is a _roff_ program; it wants to read _roff_ source files and format them itself. The algorithm for retrieving the file for a _man_ _page_ needs first a set of directories. This set starts with the so-called _man_ _path_ that is modified later on by adding names of _operating_ _system_ and _language_. This arising set is used for adding the section directories which con‐ tain the _man_ _page_ files. The _man_ _path_ is a list of directories that are separated by colon. It is generated by the following methods. * The environment variable _MANPATH_ can be set. * It can be read from the arguments of the environment variable _MANOPT_. * The _man_ _path_ can be manually specified by using the option **--manpath**. An empty argument disables the _man_ _page_ searching. * When no _man_ _path_ was set the [**manpath**(1)](https://www.chedong.com/phpMan.php/man/manpath/1/markdown) program is tried to determine one. * If this does not work a reasonable default path from _$PATH_ is determined. We now have a starting set of directories. The first way to change this set is by adding names of _operating_ _systems_. This assumes that _man_ _pages_ for several _operating_ _systems_ are installed. This is not always true. The names of such _operating_ _systems_ can be provided by 3 methods. * The environment variable _SYSTEM_ has the lowest precedence. * This can be overridden by an option in _MANOPT_. * This again is overridden by the command-line option **--systems**. Several names of _operating_ _systems_ can be given by appending their names, separated by a com‐ ma. The _man_ _path_ is changed by appending each _system_ name as subdirectory at the end of each di‐ rectory of the set. No directory of the _man_ _path_ set is kept. But if no _system_ name is specified the _man_ _path_ is left unchanged. After this, the actual set of directories can be changed by _language_ information. This as‐ sumes that there exist _man_ _pages_ in different languages. The wanted _language_ can be chosen by several methods. * Environment variable _LANG_. * This is overridden by _LC_MESSAGES_. * This is overridden by _LC_ALL_. * This can be overridden by providing an option in _MANOPT_. * All these environment variables are overridden by the command-line option **--locale**. The _default_ _language_ can be specified by specifying one of the pseudo-language parameters C or POSIX. This is like deleting a formerly given _language_ information. The _man_ _pages_ in the _default_ _language_ are usually in English. Of course, the _language_ name is determined by **man**. In GNU **man**, it is specified in the POSIX 1003.1 based format: __[___[**.**__[**,**__]]], but the two-letter code in __ is sufficient for most purposes. If for a complicated _language_ formulation no _man_ _pages_ are found **groffer** searches the country part consisting of these first two characters as well. The actual directory set is copied thrice. The _language_ name is appended as subdirectory to each directory in the first copy of the actual directory set (this is only done when a lan‐ guage information is given). Then the 2-letter abbreviation of the _language_ name is appended as subdirectories to the second copy of the directory set (this is only done when the given language name has more than 2 letters). The third copy of the directory set is kept un‐ changed (if no _language_ information is given this is the kept directory set). These maximal‐ ly 3 copies are appended to get the new directory set. We now have a complete set of directories to work with. In each of these directories, the _man_ files are separated in _sections_. The name of a _section_ is represented by a single char‐ acter, a digit between _1_ and _9_, or the character _o_ or _n_, in this order. For each available _section_, a subdirectory **man**_
_ exists containing all _man_ files for this _section_, where _
_ is a single character as described before. Each _man_ file in a _section_ directory has the form **man**_
_**/**__**.**_
[][_**.**_]_, where __ and __ are optional. __ is the name of the _man_ _page_ that is also specified as filespec argument on the command line. The _extension_ is an addition to the section. This postfix acts like a subsection. An _exten__‐ _sion_ occurs only in the file name, not in name of the _section_ subdirectory. It can be speci‐ fied on the command line. On the other hand, the _compression_ is just an information on how the file is compressed. This is not important for the user, such that it cannot be specified on the command line. There are 4 methods to specify a _section_ on the command line: * Environment variable _MANSECT_ * Command line option **--sections** * Appendix to the _name_ argument in the form _.
_ * Preargument before the _name_ argument in the form _
_ __ It is also possible to specify several _sections_ by appending the single characters separated by colons. One can imagine that this means to restrict the _man_ _page_ search to only some _sec__‐ _tions_. The multiple _sections_ are only possible for _MANSECT_ and **--sections**. If no _section_ is specified all _sections_ are searched one after the other in the given order, starting with _section_ _1_, until a suitable file is found. There are 4 methods to specify an _extension_ on the command line. But it is not necessary to provide the whole extension name, some abbreviation is good enough in most cases. * Environment variable _EXTENSION_ * Command line option **--extension** * Appendix to the _.
_ argument in the form _.
_ * Preargument before the _name_ argument in the form _
_ __ For further details on _man_ _page_ searching, see [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown). ### Examples of man files ### /usr/share/man/man1/groff.1 This is an uncompressed file for the _man_ _page_ groff in _section_ _1_. It can be called by _sh#_ groffer groff No _section_ is specified here, so all _sections_ should be searched, but as _section_ _1_ is searched first this file will be found first. The file name is composed of the fol‐ lowing components. **/usr/share/man/** must be part of the _man_ _path_; the subdirectory **man1/** and the part **.1** stand for the _section_; **groff** is the name of the _man_ _page_. ### /usr/local/share/man/man7/groff.7.gz The file name is composed of the following components. **/usr/local/share/man** must be part of the _man_ _path_; the subdirectory **man7/** and the part **.7** stand for the _section_; **groff** is the name of the _man_ _page_; the final part **.gz** stands for a compression with [**gzip**(1)](https://www.chedong.com/phpMan.php/man/gzip/1/markdown). As the _section_ is not the first one it must be specified as well. This can be done by one of the following commands. _sh#_ groffer groff.7 _sh#_ groffer 7 groff _sh#_ groffer --sections=7 groff ### /usr/local/man/man1/ctags.1emacs21.bz2 Here **/usr/local/man** must be in _man_ _path_; the subdirectory **man1/** and the file name part **.1** stand for _section_ _1_; the name of the _man_ _page_ is **ctags**; the section has an exten‐ sion **emacs21**; and the file is compressed as **.bz2** with [**bzip2**(1)](https://www.chedong.com/phpMan.php/man/bzip2/1/markdown). The file can be viewed with one of the following commands _sh#_ groffer ctags.1e _sh#_ groffer 1e ctags _sh#_ groffer --extension=e --sections=1 ctags where e works as an abbreviation for the extension emacs21. ### /usr/man/linux/de/man7/man.7.Z The directory **/usr/man** is now part of the _man_ _path_; then there is a subdirectory for an _operating_ _system_ name **linux/**; next comes a subdirectory **de/** for the German _lan__‐ _guage_; the _section_ names **man7** and **.7** are known so far; **man** is the name of the _man_ _page_; and **.Z** signifies the compression that can be handled by [**gzip**(1)](https://www.chedong.com/phpMan.php/man/gzip/1/markdown). We want now show how to provide several values for some options. That is possible for _sec__‐ _tions_ and _operating_ _system_ names. So we use as _sections_ _5_ and _7_ and as _system_ names _linux_ and _aix_. The command is then _sh#_ groffer --locale=de --sections=5:7 --systems=linux,aix man _sh#_ LANG=de MANSECT=5:7 SYSTEM=linux,aix groffer man ## DECOMPRESSION The program has a decompression facility. If standard input or a file that was retrieved from the command line parameters is compressed with a format that is supported by either [**gzip**(1)](https://www.chedong.com/phpMan.php/man/gzip/1/markdown) or [**bzip2**(1)](https://www.chedong.com/phpMan.php/man/bzip2/1/markdown) it is decompressed on-the-fly. This includes the GNU **.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. ## ENVIRONMENT The **groffer** program supports many system variables, most of them by courtesy of other pro‐ grams. All environment variables of [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) and GNU [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) and some standard system vari‐ ables are honored. ### Native groffer Variables _GROFFER_OPT_ Store options for a run of **groffer**. The options specified in this variable are over‐ ridden by the options given on the command line. The content of this variable is run through the shell builtin “eval”, so arguments containing whitespace or special shell characters should be quoted. Do not forget to export this variable, otherwise it does not exist during the run of **groffer**. ### System Variables The following variables have a special meaning for **groffer**. _DISPLAY_ If set, this variable 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 graphi‐ cal **groffer** on a remote X Window System terminal. For example, depending on your sys‐ tem, **groffer** can be started on the second monitor by the command _sh#_ DISPLAY=:0.1 groffer what.ever & _LC_ALL_ _LC_MESSAGES_ _LANG_ If one of these variables is set (in the above sequence), its content is interpreted as the locale, the language to be used, especially when retrieving _man_ _pages_. A lo‐ cale 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)](https://www.chedong.com/phpMan.php/man/setlocale/3/markdown). 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 vari‐ ables are unset. _PAGER_ This variable can be used to set the pager for the tty output. For example, to dis‐ able the use of a pager completely set this variable to the [**cat**(1)](https://www.chedong.com/phpMan.php/man/cat/1/markdown) program _sh#_ PAGER=cat groffer anything _PATH_ All programs within the **groffer** script are called without a fixed path. Thus this en‐ vironment variable determines the set of programs used within the run of **groffer**. ### Groff Variables The **groffer** program internally calls **groff**, so all environment variables documented in [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) are internally used within **groffer** as well. The following variable has a direct meaning for the **groffer** program. _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. See the [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown) man page for more details on the location of temporary files. ### Man Variables Parts of the functionality of the **man** program were implemented in **groffer**; support for all environment variables documented in [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) 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 _MANOPT_, which in turn is overwritten by the command line. _EXTENSION_ Restrict the search for _man_ _pages_ to files having this extension. This is overridden by option **--extension**; see there for details. _MANOPT_ This variable contains options as a preset for [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown). As not all of these are rele‐ vant 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. _MANPATH_ If set, this variable contains the directories in which the _man_ _page_ trees are stored. This is overridden by option **--manpath**. _MANSECT_ If this is a colon separated list of section names, the search for _man_ _pages_ is re‐ stricted to those manual sections in that order. This is overridden by option **--sec**‐‐ **tions**. _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 **--systems**; see there for details. The environment variable _MANROFFSEQ_ is ignored by **groffer** because the necessary preprocessors are determined automatically. ## CONFIGURATION FILES The **groffer** program can be preconfigured by two configuration files. ### /etc/groff/groffer.conf System-wide configuration file for **groffer**. ### $HOME/.groff/groffer.conf User-specific configuration file for **groffer**, where _$HOME_ denotes the user's home di‐ rectory. This file is called after the system-wide configuration file to enable over‐ riding by the user. Both files are handled for the configuration, but the configuration file in **/etc** comes first; it is overwritten by the configuration file in the home directory; both configuration files are overwritten by the environment variable _GROFFER_OPT_; everything is overwritten by the command line arguments. The configuration files contain options that should be called as default for every **groffer** run. These options are written in lines such that each contains either a long option, a short option, or a short option cluster; each with or without an argument. So each line with configuration information starts with a minus character “**-**”; a line with a long option starts with two minus characters “**--**”, a line with a short option or short option cluster starts with a single minus “**-**”. The option names in the configuration files may not be abbreviated, they must be exact. The argument for a long option can be separated from the option name either by an equal sign “**=**” or by whitespace, i.e. one or several space or tab characters. An argument for a short option or short option cluster can be directly appended to the option name or separated by whitespace. The end of an argument is the end of the line. It is not allowed to use a shell environment variable in an option name or argument. It is not necessary to use quotes in an option or argument, except for empty arguments. An empty argument can be provided by appending a pair of quotes to the separating equal sign or whitespace; with a short option, the separator can be omitted as well. For a long option with a separating equal sign “**=**”, the pair of quotes can be omitted, thus ending the line with the separating equal sign. All other quote characters are cancelled internally. In the configuration files, arbitrary whitespace is allowed at the beginning of each line, it is just ignored. Each whitespace within a line is replaced by a single space character “ ” internally. All lines of the configuration lines that do not start with a minus character are ignored, such that comments starting with “**#**” are possible. So there are no shell commands in the configuration files. As an example, consider the following configuration file that can be used either in **/etc/groff/groffer.conf** or **~/.groff/groffer.conf** **.** # groffer configuration file # # groffer options that are used in each call of groffer --foreground=DarkBlue --resolution=100 --viewer=gxditview -geometry 900x1200 The lines starting with **#** are just ignored, so they act as command lines. This configuration sets four **groffer** options (the lines starting with “**-**”). This has the following effects: * Use a text color of **DarkBlue** in all viewers that support this, such as **gxditview**. * Use a resolution of **100dpi** in all viewers that support this, such as **gxditview**. By this, the default device in _x_ _mode_ is set to **X100**. * Force [**gxditview**(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown) as the _x-mode_ viewer using the geometry option for setting the width to **900px** and the height to **1200px**. This geometry is suitable for a resolution of **100dpi**. * Use [**xpdf**(1)](https://www.chedong.com/phpMan.php/man/xpdf/1/markdown) as the _pdf-mode_ viewer with the argument **-Z** **150**. ## EXAMPLES The usage of **groffer** is very easy. Usually, it is just called with a file name or _man_ _page_. The following examples, however, show that **groffer** has much more fancy capabilities. _sh#_ groffer /usr/local/share/doc/groff/meintro.ms.gz Decompress, format and display the compressed file **meintro.ms.gz** in the directory **/usr/lo**‐‐ **cal/share/doc/groff**, using the standard viewer **gxditview** as graphical viewer when in the X Window System, or the [**less**(1)](https://www.chedong.com/phpMan.php/man/less/1/markdown) pager program otherwise. _sh#_ groffer groff If the file **./groff** exists use it as input. Otherwise interpret the argument as a search for the _man_ _page_ named **groff** in the smallest possible _man_ _section_, being section 1 in this case. _sh#_ groffer man:groff search for the _man_ _page_ of **groff** even when the file **./groff** exists. _sh#_ groffer groff.7 _sh#_ groffer 7 groff search the _man_ _page_ of **groff** in _man_ _section_ **7**. This section search works only for a digit or a single character from a small set. _sh#_ groffer fb.modes If the file **./fb.modes** does not exist interpret this as a search for the _man_ _page_ of **fb.modes**. As the extension _modes_ is not a single character in classical section style the argument is not split to a search for **fb**. _sh#_ groffer groff ’[troff(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)’ man:roff The arguments that are not existing files are looked-up as the following _man_ _pages_: **groff** (automatic search, should be found in _man_ section 1), **troff** (in section 1), and **roff** (in the section with the lowest number, being 7 in this case). The quotes around _’[_troff(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown)__’ are nec‐ essary because the parentheses are special shell characters; escaping them with a backslash character _\(_ and _\)_ would be possible, too. The formatted files are concatenated and dis‐ played in one piece. _sh#_ LANG=de groffer --man --viewer=galeon ls Retrieve the German _man_ _page_ (language _de_) for the **ls** program, decompress it, format it to _html_ or _xhtml_ format (_www_ _mode_) and view the result in the web browser **galeon**. The option **--man** guarantees that the _man_ _page_ is retrieved, even when a local file **ls** exists in the ac‐ tual directory. _sh#_ groffer --source 'man:[roff(7)](https://www.chedong.com/phpMan.php/man/roff/7/markdown)' Get the _man_ _page_ called _roff_ in _man_ section 7, decompress it, and print its unformatted con‐ tent, its source code. _sh#_ groffer --de-p --in --ap This is a set of abbreviated arguments, it is determined as _sh#_ groffer --debug-params --intermediate-output --apropos _sh#_ cat file.gz | groffer -Z -mfoo The file **file.gz** is sent to standard input, this is decompressed, and then this is trans‐ ported to the _groff_ _intermediate_ _output_ _mode_ without post-processing (**groff** option **-Z**), using macro package _foo_ (**groff** option **-m**). _sh#_ echo '\f(CBWOW!' | > groffer --x --bg red --fg yellow --geometry 200x100 - Display the word **WOW!** in a small window in constant-width bold font, using color yellow on red background. ## COMPATIBILITY The **groffer** program is written in Perl, the Perl version during writing was v5.8.8. **groffer** provides its own parser for command-line arguments that is compatible to both POSIX [**getopts**(1)](https://www.chedong.com/phpMan.php/man/getopts/1/markdown) and GNU [**getopt**(1)](https://www.chedong.com/phpMan.php/man/getopt/1/markdown). 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. * The option consisting of a single minus **-** refers to standard input. * A single minus followed by characters refers to a single character option or a combination thereof; for example, the **groffer** short option combination **-Qmfoo** is equivalent to **-Q** **-m** **foo**. * 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, **--long=arg** is equivalent to **--long** **arg**. * An argument of **--** ends option parsing; all further command-line arguments are interpreted as _filespec_ parameters, i.e. file names or constructs for searching _man_ _pages_). * All command-line arguments that are neither options nor option arguments are interpreted as _filespec_ parameters and stored until option parsing has finished. For example, the command line _sh#_ groffer file1 -a -o arg file2 is equivalent to _sh#_ 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 POSIX 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 op‐ tion “**--**” anyway. ## AUTHORS **groffer** was written by Bernd Warken ⟨⟩. ## SEE ALSO [**groff**(1)](https://www.chedong.com/phpMan.php/man/groff/1/markdown), [**troff**(1)](https://www.chedong.com/phpMan.php/man/troff/1/markdown) Details on the options and environment variables available in **groff**; all of them can be used with **groffer**. [**grog**(1)](https://www.chedong.com/phpMan.php/man/grog/1/markdown) This program tries to guess the necessary **groff** command-line options from the input and the **groffer** options. [**groff**(7)](https://www.chedong.com/phpMan.php/man/groff/7/markdown) Documentation of the _groff_ language. **groff**___**[char**(7)](https://www.chedong.com/phpMan.php/man/char/7/markdown) Documentation on the _groff_ characters, special characters, and glyphs.. **groff**___**[tmac**(5)](https://www.chedong.com/phpMan.php/man/tmac/5/markdown) Documentation on the _groff_ macro files. **groff**___**[out**(5)](https://www.chedong.com/phpMan.php/man/out/5/markdown) Documentation on the _groff_ _intermediate_ _output_ before the run of a _postprocessor_. (_ditroff_ output). This can be run by the **groff** or **groffer** option **-Z**. [**man**(1)](https://www.chedong.com/phpMan.php/man/man/1/markdown) 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**. [**gxditview**(1)](https://www.chedong.com/phpMan.php/man/gxditview/1/markdown) [**xditview**(1x)](https://www.chedong.com/phpMan.php/man/xditview/1x/markdown) Viewers for **groffer**'s _x_ _mode_. [**kpdf**(1)](https://www.chedong.com/phpMan.php/man/kpdf/1/markdown) [**kghostview**(1)](https://www.chedong.com/phpMan.php/man/kghostview/1/markdown) [**evince**(1)](https://www.chedong.com/phpMan.php/man/evince/1/markdown) [**ggv**(1)](https://www.chedong.com/phpMan.php/man/ggv/1/markdown) [**gv**(1)](https://www.chedong.com/phpMan.php/man/gv/1/markdown) [**ghostview**(1)](https://www.chedong.com/phpMan.php/man/ghostview/1/markdown) [**gs**(1)](https://www.chedong.com/phpMan.php/man/gs/1/markdown) Viewers for **groffer**'s _ps_ _mode_. [**kpdf**(1)](https://www.chedong.com/phpMan.php/man/kpdf/1/markdown) [**acroread**(1)](https://www.chedong.com/phpMan.php/man/acroread/1/markdown) [**evince**(1)](https://www.chedong.com/phpMan.php/man/evince/1/markdown) [**xpdf**(1)](https://www.chedong.com/phpMan.php/man/xpdf/1/markdown) [**gpdf**(1)](https://www.chedong.com/phpMan.php/man/gpdf/1/markdown) [**kghostview**(1)](https://www.chedong.com/phpMan.php/man/kghostview/1/markdown) [**ggv**(1)](https://www.chedong.com/phpMan.php/man/ggv/1/markdown) Viewers for **groffer**'s _pdf_ _mode_. [**kdvi**(1)](https://www.chedong.com/phpMan.php/man/kdvi/1/markdown), [**xdvi**(1)](https://www.chedong.com/phpMan.php/man/xdvi/1/markdown), [**dvilx**(1)](https://www.chedong.com/phpMan.php/man/dvilx/1/markdown) Viewers for **groffer**'s _dvi_ _mode_. [**konqueror**(1)](https://www.chedong.com/phpMan.php/man/konqueror/1/markdown) [**epiphany**(1)](https://www.chedong.com/phpMan.php/man/epiphany/1/markdown) [**firefox**(1)](https://www.chedong.com/phpMan.php/man/firefox/1/markdown) [**mozilla**(1)](https://www.chedong.com/phpMan.php/man/mozilla/1/markdown) [**netscape**(1)](https://www.chedong.com/phpMan.php/man/netscape/1/markdown) [**lynx**(1)](https://www.chedong.com/phpMan.php/man/lynx/1/markdown) Web-browsers for **groffer**'s _html_, _xhtml_, or _www_ _mode_. [**less**(1)](https://www.chedong.com/phpMan.php/man/less/1/markdown) [**more**(1)](https://www.chedong.com/phpMan.php/man/more/1/markdown) Standard pager program for the _tty_ _mode_. [**gzip**(1)](https://www.chedong.com/phpMan.php/man/gzip/1/markdown) [**bzip2**(1)](https://www.chedong.com/phpMan.php/man/bzip2/1/markdown) [**xz**(1)](https://www.chedong.com/phpMan.php/man/xz/1/markdown) The decompression programs supported by **groffer**. groff 1.22.4 23 March 2022 [GROFFER(1)](https://www.chedong.com/phpMan.php/man/GROFFER/1/markdown)