1 .TH GROFFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
3 groffer \- display groff files and man\~pages on X and tty
5 .\" The .SH was moved to this place in order to appease `apropos'.
7 .\" --------------------------------------------------------------------
9 .\" --------------------------------------------------------------------
12 Copyright \[co] 2001-2014 Free Software Foundation, Inc.
14 This file is part of groffer, which is part of groff, a free software
17 You can redistribute it and/or modify it under the terms of the GNU
18 General Public License version 2 as published by the Free Software
21 The license text is available in the internet at
22 .UR http://www.gnu.org/licenses/gpl-2.0.html
27 This file was written by
28 .MT groff-bernd.warken-72@web.de
33 .\" --------------------------------------------------------------------
35 .\" --------------------------------------------------------------------
38 .ie t .ds EL \fS\N'188'\fP
39 .el .ds EL \&.\|.\|.\&\
45 .\" used in `.IP \*(BU 2m' (former .Topic)
48 .\" --------------------------------------------------------------------
50 .\" --------------------------------------------------------------------
59 .OP groff-options \*(EL
67 .BR \-h " | " \-\-help
71 .BR \-v " | " \-\-version
75 .\" --------------------------------------------------------------------
77 .\" --------------------------------------------------------------------
81 program is the easiest way to use
82 .BR \%groff (@MAN1EXT@).
83 It can display arbitrary documents written in the
86 .BR \%groff (@MAN7EXT@),
90 .BR \%roff (@MAN7EXT@),
91 that are compatible to the original
95 It finds and runs all necessary
97 preprocessors, such as
104 program also includes many of the features for finding and displaying
105 the \%\f[CR]Unix\f[] manual pages
109 such that it can be used as a replacement for a
113 Moreover, compressed files that can be handled by
117 are decompressed on-the-fly.
121 The normal usage is quite simple by supplying a file name or name of a
123 without further options.
125 But the option handling has many possibilities for creating special
128 This can be done either in configuration files, with the shell
132 or on the command line.
136 The output can be generated and viewed in several different ways
142 native \%\f[CR]X\~Window\f[] viewer
143 .BR \%gxditview (@MAN1EXT@),
149 display program, a web browser by generating
159 Most of the options that must be named when running
161 directly are determined automatically for
163 due to the internal usage of the
164 .BR \%grog (@MAN1EXT@)
167 But all parts can also be controlled manually by arguments.
171 Several file names can be specified on the command line arguments.
173 They are transformed into a single document in the normal way of
178 Option handling is done in \f[CR]GNU\f[] style.
180 Options and file names can be mixed freely.
184 closes the option handling, all following arguments are treated as
187 Long options can be abbreviated in several ways.
190 .\" --------------------------------------------------------------------
191 .SH "OPTION OVERVIEW"
192 .\" --------------------------------------------------------------------
199 .OP \-h\~\fR|\fB\~\-\-help
200 .OP \-v\~\fR|\fB\~\-\-version
206 .I \%groffer mode options
212 .OP \-\-default\-modes mode1,mode2,\*(EL
217 .OP \-\-mode display_mode
228 .OP \-\-x\~\fR|\fB\~\-\-X
234 Replace these options by --viewer
235 .OP \-\-dvi\-viewer prog
236 .OP \-\-html\-viewer prog
237 .OP \-\-pdf\-viewer prog
238 .OP \-\-ps\-viewer prog
239 .OP \-\-tty\-viewer prog
240 .OP \-\-www\-viewer prog
241 .OP \-\-x\-viewer\~\fR|\fB\~\-\-X\-viewer prog
246 .I options related to \%groff
250 .OP \-T\~\fR|\fB\~\-\-device device
251 .OP \-Z\~\fR|\fB\~\-\-intermediate\-output\~\fR|\fB\~\-\-ditroff
256 short options are accepted.
261 .I options for man\~pages
266 .OP \-\-apropos\-data
267 .OP \-\-apropos\-devel
268 .OP \-\-apropos\-progs
278 .I long options taken over from GNU man
285 .OP \-\-extension suffix
286 .OP \-\-locale language
288 .OP \-\-location\~\fR|\fB\~\-\-where
289 .OP \-\-manpath dir1:dir2:\*(EL
291 .OP \-\-pager program
292 .OP \-\-sections sec1:sec2:\*(EL
293 .OP \-\-systems sys1,sys2,\*(EL
294 .OP \-\-troff\-device device
297 Further long options of \f[CR]GNU\f[]
299 are accepted as well.
304 .I X Window Toolkit options
308 .OP \-\-bd\~\fR|\fB\~\-\-bordercolor pixels
309 .OP \-\-bg\~\fR|\fB\~\-\-background color
310 .OP \-\-bw\~\fR|\fB\~\-\-borderwidth pixels
311 .OP \-\-display X-display
312 .OP \-\-fg\~\fR|\fB\~\-\-foreground color
313 .OP \-\-fn\~\fR|\fB\~\-\-ft\~\fR|\fB\~\-\-font font_name
314 .OP \-\-geometry size_pos
315 .OP \-\-resolution value
318 .OP \-\-xrm X\-resource
324 .I options for development
329 .OP \-\-debug\-filenames
332 .OP \-\-debug\-params
333 .OP \-\-debug\-tmpdir
342 .I \%filespec arguments
347 parameters are all arguments that are neither an option nor an option
350 They usually mean a file name or a
356 In the following, the term
360 It means a word that consists of a
362 that is optionally followed by an
367 is a single character from
381 parameters means standard input.
386 stands for standard input (can occur several times).
391 the path name of an existing file.
395 .BI man: name ( section_extension )
397 .BI man: name . section_extension
399 .IB name ( section_extension )
401 .IB name . section_extension
403 .I "section_extension name"
404 search the \%man\~page
406 in the section with optional extension
407 .IR section_extension .
412 \%man\~page in the lowest
422 is not an existing file search for the man\~page
424 in the lowest man\~section.
429 .\" --------------------------------------------------------------------
431 .\" --------------------------------------------------------------------
435 program can usually be run with very few options.
437 But for special purposes, it supports many options.
439 These can be classified in 5 option classes.
445 are compatible with the short options of
446 .BR \%groff (@MAN1EXT@).
450 are compatible with the long options of
455 Arguments for long option names can be abbreviated in several ways.
457 First, the argument is checked whether it can be prolonged as is.
459 Furthermore, each minus sign
461 is considered as a starting point for a new abbreviation.
463 This leads to a set of multiple abbreviations for a single argument.
467 can be used as an abbreviation for
468 .BR \-\-debug\-not\-func ,
473 If the abbreviation of the argument leads to several resulting options
478 These abbreviations are only allowed in the environment variable
481 but not in the configuration files.
483 In configuration, all long options must be exact.
486 .\" --------------------------------------------------------------------
487 .SS "groffer breaking Options"
488 .\" --------------------------------------------------------------------
490 As soon as one of these options is found on the command line it is
491 executed, printed to standard output, and the running
493 is terminated thereafter.
495 All other arguments are ignored.
499 .B \-h\~\fR|\fB\~\-\-help
500 Print help information with a short explanation of options to
505 .B \-v\~\fR|\fB\~\-\-version
506 Print version information to standard output.
509 .\" --------------------------------------------------------------------
510 .SS "groffer Mode Options"
511 .\" --------------------------------------------------------------------
513 The display mode and the viewer programs are determined by these
516 If none of these mode and viewer options is specified
518 tries to find a suitable display mode automatically.
520 The default modes are
527 in \%\f[CR]X\~Window\f[] with different viewers and
533 on a terminal; other modes are tested if the programs for the main
534 default mode do not exist.
538 In \%\f[CR]X\~Window\f[], many programs create their own window when
542 can run these viewers as an independent program in the background.
544 As this does not work in text mode on a terminal (tty) there must be a
545 way to know which viewers are \%\f[CR]X\~Window\f[] graphical
550 script has a small set of information on some viewer names.
552 If a viewer argument of the command\-line chooses an element that is
553 kept as \%\f[CR]X\~Window\f[] program in this list it is treated as a
554 viewer that can run in the background.
556 All other, unknown viewer calls are not run in the background.
560 For each mode, you are free to choose whatever viewer you want.
562 That need not be some graphical viewer suitable for this mode.
564 There is a chance to view the output source; for example, the
565 combination of the options
569 shows the content of the
571 output, the source code, with the pager
583 Reset all configuration from previously processed command line options
584 to the default values.
586 This is useful to wipe out all former options of the configuration, in
589 and restart option processing using only the rest of the command line.
593 .BI \-\-default\-modes \ mode1,mode2,\*(EL
594 Set the sequence of modes for
596 to the comma separated list given in the argument.
600 for details on modes. Display in the default manner; actually, this
601 means to try the modes
615 .BI \-\-viewer \ prog
616 Choose a viewer program for
619 This can be a file name or a program to be searched in
623 Known \%\f[CR]X\~Window\f[]
630 In each case, arguments can be provided additionally.
645 Choose a web browser program for viewing in
648 It can be the path name of an executable file or a program in
651 In each case, arguments can be provided additionally.
657 Set the display mode.
659 The following mode values are recognized:
665 Select the automatic determination of the display mode.
667 The sequence of modes that are tried can be set with the
668 .B \-\-default\-modes
671 Useful for restoring the
673 when a different mode was specified before.
678 Display formatted input in a
682 By default, the formatted input is displayed with the
689 After the file determination, switch
691 to process the input like
692 .BR \%groff (@MAN1EXT@)
702 Translate the input into html format and display the result in a web
705 By default, the existence of a sequence of standard web browsers is
706 tested, starting with
710 The text html viewer is
731 is displayed with suitable viewer programs, such as
737 This is the traditional
740 Sometimes this mode produces more correct output than the default
743 By default, the input is formatted by
745 using the Postscript device, then it is transformed into the PDF file
751 If that's not possible, the
752 .I Postscript mode (ps)
755 Finally it is displayed using different viewer programs.
760 Display formatted input in a Postscript viewer program.
762 By default, the formatted input is displayed in one of many viewer
769 .I \%groff\~text\~mode
770 and write the result to standard output without a pager or viewer
775 by default, can be chosen with option
782 .I \%groff\~text\~mode
783 and write the result to standard output using a text pager program,
784 even when in \%\f[CR]X\~Window\f[].
795 Display the formatted input in a native
799 By default, the formatted input is displayed with the
800 .BR \%gxditview (@MAN1EXT@)
801 program being distributed together with
803 But the standard \%\f[CR]X\~Window\f[] tool
805 can also be chosen with the option
807 The default resolution is
816 for the resolution of
826 .I "groff intermediate output"
827 for the actual device is generated and the result is displayed.
831 the default width of the geometry of the display program is chosen to
842 The following modes do not use the
846 They are only interesting for advanced applications.
851 Generate device output with plain
853 without using the special viewing features of
855 If no device was specified by option
866 Output the roff source code of the input files without further
882 .BI \-\-viewer \ prog
883 Choose a viewer program for
886 This can be a file name or a program to be searched in
889 arguments can be provided additionally.
897 .BI \-\-viewer \ prog
898 Choose a viewer program for
901 This can be a file name or a program to be searched in
905 Common Postscript viewers include
913 In each case, arguments can be provided additionally.
919 .BR \-\-mode=source .
930 The file for the chosen mode is generated and its content is printed
933 It will not be displayed in graphical mode.
941 .BI \-\-viewer \ prog
942 Choose a text pager for mode
944 The standard pager is
946 This option is equivalent to
949 .BR \-\-pager=\,\fIprog\fP .
950 The option argument can be a file name or a program to be searched in
953 arguments can be provided additionally.
966 .B \-\-X\~\fR|\fB\~\-\-x
970 .BI \-\-viewer " prog"
971 Choose a viewer program for
973 Suitable viewer programs are
974 .BR \%gxditview (@MAN1EXT@)
975 which is the default and
977 The argument can be any executable file or a program in
980 arguments can be provided additionally.
985 Signals the end of option processing; all remaining arguments are
994 accepts all short options that are valid for the
995 .BR \%groff (@MAN1EXT@)
1000 options are sent unmodified via
1005 So postprocessors, macro packages, compatibility with
1008 and much more can be manually specified.
1011 .\" --------------------------------------------------------------------
1012 .SS "Options related to groff"
1013 .\" --------------------------------------------------------------------
1015 All short options of
1017 are compatible with the short options of
1018 .BR \%groff (@MAN1EXT@).
1022 options have either an additional special meaning within
1024 or make sense for normal usage.
1028 Because of the special outputting behavior of the
1033 was designed to be switched into
1037 viewing features are disabled there.
1041 options do not switch the mode, but allow to customize the formatting
1047 This generates an ascii approximation of output in the
1050 That could be important when the text pager has problems with control
1063 This is useful in case it cannot be recognized automatically.
1067 .BI \-\-P \ opt_or_arg
1070 as an option or option argument to the actual
1076 .B \-\-T \fIdevname\fR\~\fR|\fB\~\-\-device \fIdevname\fR
1078 This option determines
1082 The most important devices are the text output devices for referring
1083 to the different character sets, such as
1090 Each of these arguments switches
1094 using this device, to
1096 if the actual mode is not a
1101 arguments are mapped to the corresponding
1103 .B \-\-mode=\,\fIdevname\fR
1111 arguments are mapped to
1115 argument switches to
1125 .I groff intermediate output
1128 As the quality is relatively bad this option is deprecated; use
1134 device for a better display.
1138 .B \-Z\~\fR|\fB\~\-\-intermediate-output\~\fR|\fB\~\-\-ditroff
1141 and format the input with the
1142 .I \%groff intermediate output
1143 without postprocessing; see
1144 .BR \%groff_out (@MAN5EXT@).
1145 This is equivalent to option
1149 which can be used as well.
1155 options are supported by
1157 but they are just transparently transferred to
1159 without any intervention.
1161 The options that are not explicitly handled by
1163 are transparently passed to
1166 Therefore these transparent options are not documented here, but in
1167 .BR \%groff (@MAN1EXT@).
1168 Due to the automatism in
1172 options should be needed, except for advanced usage.
1175 .\" --------------------------------------------------------------------
1176 .SS "Options for man\~pages"
1177 .\" --------------------------------------------------------------------
1183 command or facility of
1187 arguments within all
1193 argument is taken for search as it is;
1195 specific parts are not handled, such that
1197 searches for the two arguments
1201 with a large result; for the
1204 nothing will be found.
1208 locale is handled only when the called programs do support this; the
1215 The display differs from the
1217 program by the following concepts:
1229 argument is searched on its own.
1235 wildcard characters are allowed and handled without a further option.
1240 .B \-\-apropos\-data
1243 descriptions for data documents, these are the
1245 .IR sections\~4 ", " 5 ", and " 7 .
1249 declarations are ignored, wildcards are accepted.
1253 .B \-\-apropos\-devel
1256 descriptions for development documents, these are the
1258 .IR sections\~2 ", " 3 ", and " 9 .
1262 declarations are ignored, wildcards are accepted.
1266 .B \-\-apropos\-progs
1269 descriptions for documents on programs, these are the
1271 .IR sections\~1 ", " 6 ", and " 8 .
1275 declarations are ignored, wildcards are accepted.
1284 and display their description \[em] or say that it is not a
1286 This is written from anew, so it differs from
1289 output by the following concepts
1292 each retrieved file name is added,
1294 local files are handled as well,
1296 the \fIlanguage\fP and \fIsystem\fP locale is supported,
1298 the display is framed by a
1300 output format similar to a
1303 wildcard characters are allowed without a further option.
1308 The following options were added to
1310 for choosing whether the file name arguments are interpreted as names
1311 for local files or as a search pattern for
1314 The default is looking up for local files.
1319 Check the non-option command line arguments
1325 then whether they represent an existing file.
1329 is first tested whether it is an existing file.
1333 .B \-\-no-man\~\fR|\fB\~\-\-local-file
1338 is the corresponding
1345 Disable former calls of
1352 .\" --------------------------------------------------------------------
1353 .SS "Long options taken over from GNU man"
1354 .\" --------------------------------------------------------------------
1358 were synchronized with the long options of \f[CR]GNU\f[]
1361 All long options of \f[CR]GNU\f[]
1363 are recognized, but not all of these options are important to
1365 so most of them are just ignored.
1377 In the following, the
1379 options that have a special meaning for
1385 If your system has \f[CR]GNU\f[]
1387 installed the full set of long and short options of the \f[CR]GNU\f[]
1389 program can be passed via the environment variable
1400 retrieve all suitable documents instead of only one.
1404 .B \-7\~\fR|\fB\~\-\-ascii
1407 display ASCII translation of special characters for critical environment.
1409 This is equivalent to
1410 .BR "groff \%\-mtty_char" ;
1412 .BR groff_tmac (@MAN5EXT@).
1418 .IR "groff intermediate output" .
1419 This is equivalent to
1425 .BI \-\-extension \ suffix
1428 search to file names that have
1430 appended to their section element.
1432 For example, in the file name
1433 .I \%/usr/share/man/man3/terminfo.3ncurses.gz
1441 .BI \-\-locale \ language
1443 Set the language for
1446 This has the same effect, but overwrites
1453 Print the location of the retrieved files to standard error.
1458 Do not display the location of retrieved files; this resets a former
1467 .BI \-\-manpath \ 'dir1:dir2:\*(EL'
1468 Use the specified search path for retrieving
1470 instead of the program defaults.
1472 If the argument is set to the empty string "" the search for
1479 Set the pager program in
1484 This can be set with
1489 .BI \-\-sections \ sec1:sec2:\*(EL
1490 Restrict searching for
1494 a colon-separated list.
1498 .BI \-\-systems \ sys1,sys2,\*(EL
1501 for the given operating systems; the argument
1503 is a comma-separated list.
1512 .\" --------------------------------------------------------------------
1513 .SS "X\~\%Window\~\%Toolkit Options"
1514 .\" --------------------------------------------------------------------
1516 The following long options were adapted from the corresponding
1517 \%\f[CR]X\~Window\~Toolkit\f[] options.
1520 will pass them to the actual viewer program if it is an
1521 \%\f[CR]X\~Window\f[] program.
1523 Otherwise these options are ignored.
1527 Unfortunately these options use the old style of a single minus for
1532 that was changed to the standard with using a double minus for long
1533 options, for example,
1537 for the \%\f[CR]X\~Window\f[] option
1544 and the documentation on the \%\f[CR]X\~Window\~Toolkit\f[] options
1545 for more details on these options and their arguments.
1549 .BI \-\-background \ color
1550 Set the background color of the viewer window.
1555 This is equivalent to
1556 .BR \-\-bordercolor .
1561 This is equivalent to
1562 .BR \-\-background .
1567 This is equivalent to
1568 .BR \-\-borderwidth .
1572 .BI \-\-bordercolor \ pixels
1573 Specifies the color of the border surrounding the viewer window.
1577 .BI \-\-borderwidth \ pixels
1578 Specifies the width in pixels of the border surrounding the viewer
1583 .BI \-\-display \ X-display
1584 Set the \%\f[CR]X\~Window\f[] display on which the viewer program
1585 shall be started, see the \%\f[CR]X\~Window\f[] documentation for the
1586 syntax of the argument.
1590 .BI \-\-foreground \ color
1591 Set the foreground color of the viewer window.
1596 This is equivalent to
1597 .BR \-\-foreground .
1601 .BI \-\-fn \ font_name
1602 This is equivalent to
1607 .BI \-\-font \ font_name
1608 Set the font used by the viewer window.
1610 The argument is an \%\f[CR]X\~Window\f[] font name.
1614 .BI \-\-ft \ font_name
1615 This is equivalent to
1620 .BI \-\-geometry \ size_pos
1621 Set the geometry of the display window, that means its size and its
1626 for the syntax of the argument.
1630 .BI \-\-resolution \ value
1631 Set \%\f[CR]X\~Window\f[] resolution in dpi (dots per inch) in some
1634 The only supported dpi values are
1639 Actually, the default resolution for
1643 The resolution also sets the default device in
1649 Reverse foreground and background color of the viewer window.
1653 .BI \-\-title "\ 'some text'"
1654 Set the title for the viewer window.
1658 .BI \-\-xrm \ 'resource'
1659 Set \f[CR]\%X\~Window\f[] resource.
1662 .\" --------------------------------------------------------------------
1663 .SS "Options for Development"
1664 .\" --------------------------------------------------------------------
1668 Enable all debugging options
1669 .BR \-\-debug\-\,\fItype\fP .
1671 The temporary files are kept and not deleted, the
1673 output is printed, the name of the temporary directory is printed, the
1674 displayed file names are printed, and the parameters are printed.
1678 .B \-\-debug\-filenames
1679 Print the names of the files and
1681 that are displayed by
1687 Print the output of all
1694 Enable two debugging informations.
1696 Print the name of the temporary directory and keep the temporary
1697 files, do not delete them during the run of
1702 .B \-\-debug\-params
1703 Print the parameters, as obtained from the configuration files, from
1706 and the command line arguments.
1710 .B \-\-debug\-tmpdir
1711 Print the name of the temporary directory.
1718 but without the output; no viewer is started.
1720 This makes only sense in development.
1724 .B \-\-print=\,\fItext\fR
1725 Just print the argument to standard error.
1727 This is good for parameter check.
1732 This is an advanced option for debugging only.
1734 Instead of displaying the formatted input, a lot of
1736 specific information is printed to standard output:
1740 the output file name in the temporary directory,
1743 the display mode of the actual
1748 the display program for viewing the output with its arguments,
1751 the active parameters from the config files, the arguments in
1753 .BR \%$GROFFER_OPT ,
1754 and the arguments of the command line,
1757 the pipeline that would be run by the
1759 program, but without executing it.
1764 Other useful debugging options are the
1769 .BR \-\-mode=groff .
1772 .\" --------------------------------------------------------------------
1773 .SS "Filespec Arguments"
1774 .\" --------------------------------------------------------------------
1778 parameter is an argument that is not an option or option argument.
1783 parameters are a file name or a template for searching
1786 These input sources are collected and composed into a single output
1793 The strange \%\f[CR]POSIX\f[] behavior to regard all arguments behind
1794 the first non-option argument as
1796 arguments is ignored.
1798 The \f[CR]GNU\f[] behavior to recognize options even when mixed with
1800 arguments is used throughout.
1802 But, as usual, the double minus argument
1804 ends the option handling and interprets all following arguments as
1806 arguments; so the \%\f[CR]POSIX\f[] behavior can be easily adopted.
1812 have a special handling of
1816 Each argument is taken as a search scheme of its own.
1818 Also a regexp (regular expression) can be used in the filespec.
1821 .B groffer \-\-apropos '^gro.f$'
1827 .B groffer \-\-apropos groff
1830 somewhere in the name or description of the
1837 such as the normal display or the output with
1839 have a different scheme for
1841 No regular expressions are used for the arguments.
1845 arguments are handled by the following scheme.
1849 It is necessary to know that on each system the
1851 are sorted according to their content into several sections.
1854 .I classical man sections
1855 have a single-character name, either a digit from
1859 or one of the characters
1866 This can optionally be followed by a string, the so-called
1870 allows to store several
1872 with the same name in the same
1876 is only rarely used, usually it is omitted.
1880 are searched automatically by alphabet.
1884 In the following, we use the name
1885 .I section_extension
1886 for a word that consists of a single character
1890 character that is followed by an
1895 parameter can have one of the following forms in decreasing sequence.
1901 parameters means that
1903 waits for standard input.
1907 always stands for standard input; it can occur several times.
1909 If you want to look up a
1920 is tested whether it is the path name of an existing file.
1922 Otherwise it is assumed to be a searching pattern for a
1927 .BI \%man: name ( section_extension ) ,
1928 .BI \%man: name . section_extension,
1929 .IB \%name ( section_extension ) ,
1931 .IB \%name . section_extension
1932 search the \%man\~page
1934 in \%man\~section and possibly extension of
1935 .IR \%section_extension .
1945 that has a document called
1950 .I \%section_extension\~name
1951 is a pattern of 2 arguments that originates from a strange argument
1956 Again, this searches the man page
1959 .IR \%section_extension ,
1962 character optionally followed by an
1967 We are left with the argument
1969 which is not an existing file.
1971 So this searches for the
1977 that has a document for this name.
1981 Several file name arguments can be supplied.
1985 into a single document.
1987 Note that the set of option arguments must fit to all of these file
1990 So they should have at least the same style of the
1995 .\" --------------------------------------------------------------------
1997 .\" --------------------------------------------------------------------
2001 program collects all input into a single file, formats it with the
2003 program for a certain device, and then chooses a suitable viewer
2006 The device and viewer process in
2011 The mode and viewer of a running
2013 program is selected automatically, but the user can also choose it
2017 The modes are selected by option the arguments of
2018 .BR \-\-mode=\,\fIanymode .
2019 Additionally, each of this argument can be specified as an option of
2022 Most of these modes have a viewer program, which can be chosen by the
2028 Several different modes are offered, graphical modes for
2029 \f[CR]\%X\~Window\f[],
2033 for debugging and development.
2046 This mode testing sequence for
2048 can be changed by specifying a comma separated list of modes with the
2050 .B \-\-default\-modes.
2056 and the decompression of the input are active in every mode.
2059 .\" --------------------------------------------------------------------
2060 .SS "Graphical Display Modes"
2061 .\" --------------------------------------------------------------------
2063 The graphical display modes work mostly in the \%\f[CR]X\~Window\f[]
2064 environment (or similar implementations within other windowing
2067 The environment variable
2072 are used for specifying the \%\f[CR]X\~Window\f[] display to be used.
2074 If this environment variable is empty
2076 assumes that no \%\f[CR]X\~Window\f[] is running and changes to a
2079 You can change this automatic behavior by the option
2080 .BR \-\-default\-modes .
2084 Known viewers for the graphical display modes and their standard
2085 \%\f[CR]X\~Window\f[] viewer programs are
2103 in a Postscript viewer
2109 \%\f[CR]X\~Window\f[]
2112 .BR \%gxditview (@MAN1EXT@)
2119 in a dvi viewer program
2128 has a major advantage \[em] it is the only graphical display mode that
2129 allows to search for text within the viewer; this can be a really
2132 Unfortunately, it takes some time to transform the input into the PDF
2133 format, so it was not chosen as the major mode.
2137 These graphical viewers can be customized by options of the
2138 \%\f[CR]X\~Window\~Toolkit\f[].
2142 options use a leading double minus instead of the single minus used by
2143 the \%\f[CR]X\~Window\~Toolkit\f[].
2146 .\" --------------------------------------------------------------------
2148 .\" --------------------------------------------------------------------
2150 There are two modes for text output,
2152 for plain output without a pager and
2154 for a text output on a text terminal using some pager program.
2161 is not set or empty,
2163 assumes that it should use
2168 In the actual implementation, the
2175 This can be changed by specifying option
2182 The pager to be used can be specified by one of the options
2186 or by the environment variable
2188 If all of this is not used the
2190 program with the option
2192 for correctly displaying control sequences is used as the default
2196 .\" --------------------------------------------------------------------
2197 .SS "Special Modes for Debugging and Development"
2198 .\" --------------------------------------------------------------------
2202 file determination and decompression.
2204 This is combined into a single input file that is fed directly into
2206 with different strategy without the
2210 These modes are regarded as advanced, they are useful for debugging
2211 and development purposes.
2219 just displays the decompressed input.
2225 does not display in a graphical mode.
2227 It just generates the file for the chosen mode and then prints its
2228 content to standard output.
2236 using only some suitable options provided to
2239 This enables the user to save the generated output into a file or pipe
2240 it into another program.
2245 .IR \%groff\~\%mode ,
2248 disables post-processing, thus producing the
2250 .I groff intermediate
2254 In this mode, the input is formatted, but not postprocessed; see
2255 .BR \%groff_out (@MAN5EXT@)
2262 short options are supported by
2266 .\" --------------------------------------------------------------------
2267 .SH "MAN PAGE SEARCHING"
2268 .\" --------------------------------------------------------------------
2270 The default behavior of
2272 is to first test whether a file parameter represents a local file; if
2273 it is not an existing file name, it is assumed to represent the name
2276 The following options can be used to determine whether the arguments
2277 should be handled as file name or
2283 forces to interpret all file parameters as
2294 searching; so only local files are displayed.
2298 If neither a local file nor a
2300 was retrieved for some file parameter a warning is issued on standard
2301 error, but processing is continued.
2304 .\" --------------------------------------------------------------------
2305 .SS "Search Algorithm"
2306 .\" --------------------------------------------------------------------
2308 Let us now assume that a
2314 program provides a search facility for
2317 All long options, all environment variables, and most of the
2318 functionality of the \f[CR]GNU\fP
2320 program were implemented.
2322 The search algorithm shall determine which file is displayed for a given
2324 The process can be modified by options and environment variables.
2330 action that is omitted in
2332 are the preformatted
2337 With the excellent performance of the actual computers, the
2340 aren't necessary any longer.
2346 program; it wants to read
2348 source files and format them itself.
2352 The algorithm for retrieving the file for a
2354 needs first a set of directories.
2356 This set starts with the so-called
2358 that is modified later on by adding names of
2363 This arising set is used for adding the section directories which
2372 is a list of directories that are separated by colon.
2374 It is generated by the following methods.
2377 The environment variable
2383 It can be read from the arguments of the environment variable
2390 can be manually specified by using the option
2392 An empty argument disables the
2401 program is tried to determine one.
2404 If this does not work a reasonable default path from
2411 We now have a starting set of directories.
2413 The first way to change this set is by adding names of
2420 .I operating systems
2423 This is not always true.
2426 .I operating systems
2427 can be provided by 3 methods.
2430 The environment variable
2433 has the lowest precedence.
2436 This can be overridden by an option in
2441 This again is overridden by the command line option
2447 .I operating systems
2448 can be given by appending their names, separated by a comma.
2454 is changed by appending each
2456 name as subdirectory at the end of each directory of the set.
2464 name is specified the
2470 After this, the actual set of directories can be changed by
2474 This assumes that there exist
2476 in different languages.
2480 can be chosen by several methods.
2483 Environment variable
2488 This is overridden by
2490 .BR \%$LC_MESSAGES .
2493 This is overridden by
2498 This can be overridden by providing an option in
2503 All these environment variables are overridden by the command line
2511 can be specified by specifying one of the pseudo-language parameters
2512 \f[CR]C\fP or \f[CR]\%POSIX\fP.
2514 This is like deleting a formerly given
2522 are usually in English.
2528 name is determined by
2532 it is specified in the \%\f[CR]POSIX\~1003.1\fP based format:
2535 \f[I]<language>\/\f[][\f[CB]_\f[]\,\f[I]<territory>\/\f[][\f[CB].\fP\
2536 \f[I]<character-set>\/\f[][\f[CB],\fP\,\f[I]<version>\/\fP]]],
2539 but the two-letter code in
2543 is sufficient for most purposes.
2545 If for a complicated
2551 searches the country part consisting of these first two characters as
2556 The actual directory set is copied thrice.
2560 name is appended as subdirectory to each directory in the first copy
2561 of the actual directory set (this is only done when a language
2562 information is given).
2564 Then the 2-letter abbreviation of the
2566 name is appended as subdirectories to the second copy of the directory
2567 set (this is only done when the given language name has more than 2
2570 The third copy of the directory set is kept unchanged (if no
2572 information is given this is the kept directory set).
2574 These maximally 3 copies are appended to get the new directory set.
2578 We now have a complete set of directories to work with.
2580 In each of these directories, the
2582 files are separated in
2587 is represented by a single character, a digit between
2603 exists containing all
2609 is a single character as described before.
2615 directory has the form
2616 .IR \%\f[CB]man\fP<section>\f[CB]/\fP<name>\f[CB].\fP<section>\
2617 [<extension>][\f[CB].\fP<compression>] ,
2627 that is also specified as filespec argument on the command line.
2633 is an addition to the section.
2635 This postfix acts like a subsection.
2639 occurs only in the file name, not in name of the
2643 It can be specified on the command line.
2647 On the other hand, the
2649 is just an information on how the file is compressed.
2651 This is not important for the user, such that it cannot be specified
2652 on the command line.
2656 There are 4 methods to specify a
2658 on the command line:
2661 Environment variable
2672 argument in the form
2676 Preargument before the
2678 argument in the form
2683 It is also possible to specify several
2685 by appending the single characters separated by colons.
2687 One can imagine that this means to restrict the
2694 are only possible for
2706 are searched one after the other in the given order, starting with
2708 until a suitable file is found.
2712 There are 4 methods to specify an
2714 on the command line.
2716 But it is not necessary to provide the whole extension name, some
2717 abbreviation is good enough in most cases.
2720 Environment variable
2731 argument in the form
2732 .I <name>.<section><extension>
2735 Preargument before the
2737 argument in the form
2738 .I <section><extension> <name>
2742 For further details on
2748 .\" --------------------------------------------------------------------
2749 .SS "Examples of man files"
2750 .\" --------------------------------------------------------------------
2753 .B /usr/share/man/man1/groff.1
2754 This is an uncompressed file for the
2761 \fIsh#\fR groffer\~groff
2765 is specified here, so all
2767 should be searched, but as
2769 is searched first this file will be found first.
2771 The file name is composed of the following components.
2787 .B /usr/local/share/man/man7/groff.7.gz
2788 The file name is composed of the following components.
2789 .B /usr/local/share/man
2803 stands for a compression with
2807 is not the first one it must be specified as well.
2809 This can be done by one of the following commands.
2811 \fIsh#\fR\~groffer\~groff.7
2812 \fIsh#\fR\~groffer\~7\~groff
2813 \fIsh#\fR\~groffer\~\-\-sections=7\~groff
2817 .B /usr/local/man/man1/ctags.1emacs21.bz2
2824 and the file name part
2832 the section has an extension
2834 and the file is compressed as
2838 The file can be viewed with one of the following commands
2840 \fIsh#\fR\~groffer\~ctags.1e
2841 \fIsh#\fR\~groffer\~1e\~ctags
2842 \fIsh#\fR\~groffer\~\-\-extension=e\~\-\-sections=1\~ctags
2844 where \f[CR]e\fP works as an abbreviation for the extension
2849 .B /usr/man/linux/de/man7/man.7.Z
2854 then there is a subdirectory for an
2858 next comes a subdirectory
2874 signifies the compression that can be handled by
2876 We want now show how to provide several values for some options.
2878 That is possible for
2897 \fIsh#\fR groffer\~\-\-locale=de\~\-\-sections=5:7\~\-\-systems=linux,aix\~man
2898 \fIsh#\fR LANG=de\~MANSECT=5:7\~SYSTEM=linux,aix\~groffer\~man
2902 .\" --------------------------------------------------------------------
2904 .\" --------------------------------------------------------------------
2906 The program has a decompression facility.
2908 If standard input or a file that was retrieved from the command line
2909 parameters is compressed with a format that is supported by either
2913 it is decompressed on-the-fly.
2915 This includes the \f[CR]GNU\fP
2922 The program displays the concatenation of all decompressed input in
2923 the sequence that was specified on the command line.
2926 .\" --------------------------------------------------------------------
2928 .\" --------------------------------------------------------------------
2932 program supports many system variables, most of them by courtesy of
2935 All environment variables of
2936 .BR \%groff (@MAN1EXT@)
2939 and some standard system variables are honored.
2942 .\" --------------------------------------------------------------------
2943 .SS "Native groffer Variables"
2944 .\" --------------------------------------------------------------------
2949 Store options for a run of
2952 The options specified in this variable are overridden by the options
2953 given on the command line.
2955 The content of this variable is run through the shell builtin `eval';
2956 so arguments containing white-space or special shell characters should
2959 Do not forget to export this variable, otherwise it does not exist
2964 .\" --------------------------------------------------------------------
2965 .SS "System Variables"
2966 .\" --------------------------------------------------------------------
2968 The following variables have a special meaning for
2975 If this variable is set this indicates that the \%\f[CR]X\~Window\fP
2978 Testing this variable decides on whether graphical or text output is
2981 This variable should not be changed by the user carelessly, but it can
2982 be used to start the graphical
2984 on a remote \%\f[CR]X\~Window\fP terminal.
2986 For example, depending on your system,
2988 can be started on the second monitor by the command
2991 \fIsh#\fR DISPLAY=:0.1\~groffer\~what.ever &
3004 If one of these variables is set (in the above sequence), its content
3005 is interpreted as the locale, the language to be used, especially when
3009 A locale name is typically of the form
3021 is an ISO 639 language code,
3023 is an ISO 3166 country code, and
3025 is a character set or encoding identifier like ISO-8859-1 or UTF-8;
3027 .BR \%setlocale (3).
3029 The locale values \f[CR]C\fP and \%\f[CR]POSIX\fP
3030 stand for the default, i.e.\& the
3032 directories without a language prefix.
3034 This is the same behavior as when all 3\~variables are unset.
3040 This variable can be used to set the pager for the tty output.
3042 For example, to disable the use of a pager completely set this
3048 \fIsh#\fR PAGER=cat\~groffer\~anything
3055 All programs within the
3057 script are called without a fixed path.
3059 Thus this environment variable determines the set of programs used
3064 .\" --------------------------------------------------------------------
3065 .SS "Groff Variables"
3066 .\" --------------------------------------------------------------------
3070 program internally calls
3072 so all environment variables documented in
3073 .BR \%groff (@MAN1EXT@)
3074 are internally used within
3078 The following variable has a direct meaning for the
3085 If the value of this variable is an existing, writable directory,
3087 uses it for storing its temporary files, just as
3092 .BR \%groff (@MAN1EXT@)
3093 man page for more details on the location of temporary files.
3096 .\" --------------------------------------------------------------------
3098 .\" --------------------------------------------------------------------
3100 Parts of the functionality of the
3102 program were implemented in
3104 support for all environment variables documented in
3108 but the meaning was slightly modified due to the different approach in
3110 but the user interface is the same.
3114 environment variables can be overwritten by options provided with
3117 which in turn is overwritten by the command line.
3123 Restrict the search for
3125 to files having this extension.
3127 This is overridden by option
3129 see there for details.
3135 This variable contains options as a preset for
3137 As not all of these are relevant for
3139 only the essential parts of its value are extracted.
3141 The options specified in this variable overwrite the values of the
3142 other environment variables that are specific to
3145 All options specified in this variable are overridden by the options
3146 given on the command line.
3152 If set, this variable contains the directories in which the
3156 This is overridden by option
3163 If this is a colon separated list of section names, the search for
3165 is restricted to those manual sections in that order.
3167 This is overridden by option
3174 If this is set to a comma separated list of names these are interpreted
3177 trees for different operating systems.
3179 This variable can be overwritten by option
3181 see there for details.
3185 The environment variable
3190 because the necessary preprocessors are determined automatically.
3193 .\" --------------------------------------------------------------------
3194 .SH "CONFIGURATION FILES"
3195 .\" --------------------------------------------------------------------
3199 program can be preconfigured by two configuration files.
3203 .B \%/etc/groff/groffer.conf
3204 System-wide configuration file for
3209 .B \%$HOME/.groff/groffer.conf
3210 User-specific configuration file for
3215 denotes the user's home directory.
3217 This file is called after the system-wide configuration file to enable
3218 overriding by the user.
3222 Both files are handled for the configuration, but the configuration
3225 comes first; it is overwritten by the configuration file in the home
3226 directory; both configuration files are overwritten by the environment
3229 .BR \%$GROFFER_OPT ;
3230 everything is overwritten by the command line arguments.
3234 The configuration files contain options that should be called as
3239 These options are written in lines such that each contains either a
3240 long option, a short option, or a short option cluster; each with or
3241 without an argument.
3243 So each line with configuration information starts with a minus
3246 a line with a long option starts with two minus characters
3248 a line with a short option or short option cluster starts with a
3254 The option names in the configuration files may not be abbreviated,
3259 The argument for a long option can be separated from the option name
3260 either by an equal sign
3262 or by whitespace, i.e.\& one or several space or tab characters.
3264 An argument for a short option or short option cluster can be directly
3265 appended to the option name or separated by whitespace.
3267 The end of an argument is the end of the line.
3269 It is not allowed to use a shell environment variable in an option
3274 It is not necessary to use quotes in an option or argument, except for
3277 An empty argument can be provided by appending a pair of quotes to the
3278 separating equal sign or whitespace; with a short option, the
3279 separator can be omitted as well.
3281 For a long option with a separating equal sign
3283 the pair of quotes can be omitted, thus ending the line with the
3284 separating equal sign.
3286 All other quote characters are cancelled internally.
3290 In the configuration files, arbitrary whitespace is allowed at the
3291 beginning of each line, it is just ignored.
3293 Each whitespace within a line is replaced by a single space character
3298 All lines of the configuration lines that do not start
3299 with a minus character are ignored, such that comments starting with
3303 So there are no shell commands in the configuration files.
3307 As an example, consider the following configuration file that can be
3309 .B \%/etc/groff/groffer.conf
3311 .B \%\s+2~\s0/.groff/groffer.conf .
3318 # groffer configuration file
3320 # groffer options that are used in each call of groffer
3321 \-\-foreground=DarkBlue
3323 \-\-viewer=gxditview \-geometry 900x1200
3324 \-\-viewer xpdf \-Z 150
3331 The lines starting with
3333 are just ignored, so they act as command lines.
3335 This configuration sets four
3337 options (the lines starting with
3339 This has the following effects:
3345 in all viewers that support this, such as
3352 in all viewers that support this, such as
3355 By this, the default device in
3363 .BR \%gxditview (@MAN1EXT@)
3366 viewer using the geometry option for setting the width to
3370 This geometry is suitable for a resolution of
3379 viewer with the argument
3384 .\" --------------------------------------------------------------------
3386 .\" --------------------------------------------------------------------
3392 Usually, it is just called with a file name or
3395 The following examples, however, show that
3397 has much more fancy capabilities.
3401 \fIsh#\fR\~groffer\~/usr/local/share/doc/groff/meintro.ms.gz
3404 Decompress, format and display the compressed file
3407 .BR /usr/local/share/doc/groff ,
3408 using the standard viewer
3410 as graphical viewer when in \%\f[CR]X\~Window\fP, or the
3412 pager program when not in \%\f[CR]X\~Window\fP.
3416 \fIsh#\fR\~groffer\~groff
3421 exists use it as input.
3423 Otherwise interpret the argument as a search for the
3427 in the smallest possible
3428 .IR \%man\~section ,
3429 being section 1 in this case.
3433 \fIsh#\fR\~groffer\~man:groff
3446 \fIsh#\fR\~groffer\~groff.7
3447 \fIsh#\fR\~groffer\~7\~groff
3457 This section search works only for a digit or a single character from
3462 \fIsh#\fR\~groffer\~fb.modes
3467 does not exist interpret this as a search for the
3473 is not a single character in classical section style the argument is
3474 not split to a search for
3479 \fIsh#\fR\~groffer\~groff\~\[cq]troff(1)\[cq]\~man:roff
3482 The arguments that are not existing files are looked-up as the
3486 (automatic search, should be found in \fIman\fP\~section\~1),
3491 (in the section with the lowest number, being\~7 in this case).
3495 .I \[cq]troff(1)\[cq]
3497 are necessary because the parentheses are special shell characters;
3498 escaping them with a backslash character
3502 would be possible, too.
3504 The formatted files are concatenated and displayed in one piece.
3508 \fIsh#\fR\~LANG=de\~groffer\~\-\-man\~\-\-viewer=galeon\~ls
3517 program, decompress it, format it to
3523 and view the result in the web browser
3529 is retrieved, even when a local file
3531 exists in the actual directory.
3536 \fIsh#\fR\~groffer\~\-\-source\~'man:roff(7)'
3543 in \fIman\fP\~section 7, decompress it, and print its unformatted
3544 content, its source code.
3549 \fIsh#\fR\~groffer\~\-\-de-p\~\-\-in\~\-\-ap
3552 This is a set of abbreviated arguments, it is determined as
3556 \fIsh#\fR\~groffer\~\-\-debug-params\~\-\-intermediate-output\~\-\-apropos
3562 \fIsh#\fR\~cat\~file.gz\~|\~groffer\~-Z\~-mfoo
3568 is sent to standard input, this is decompressed, and then this is
3570 .I \%groff intermediate output mode
3571 without post-processing
3584 \fIsh#\fR\~echo\~'\[rs]f[CB]WOW!'\~|
3585 > groffer \-\-x \-\-bg red \-\-fg yellow \-\-geometry 200x100 \-
3589 Display the word \f[CB]WOW!\fP in a small window in constant-width
3590 bold font, using color yellow on red background.
3593 .\" --------------------------------------------------------------------
3595 .\" --------------------------------------------------------------------
3599 program is written in Perl, the Perl version during writing was v5.8.8.
3604 provides its own parser for command line arguments that is compatible
3605 to both \%\f[CR]POSIX\fP
3609 It can handle option arguments and file names containing white space
3610 and a large set of special characters.
3612 The following standard types of options are supported.
3616 The option consisting of a single minus
3618 refers to standard input.
3622 A single minus followed by characters refers to a single character
3623 option or a combination thereof; for example, the
3625 short option combination
3632 Long options are options with names longer than one character; they
3633 are always preceded by a double minus.
3635 An option argument can either go to the next command line argument or
3636 be appended with an equal sign to the argument; for example,
3645 ends option parsing; all further command line arguments are
3648 parameters, i.e.\& file names or constructs for searching
3653 All command line arguments that are neither options nor option
3654 arguments are interpreted as
3656 parameters and stored until option parsing has finished.
3658 For example, the command line
3661 \fIsh#\fR\~groffer file1 \-a \-o arg file2
3667 \fIsh#\fR\~groffer \-a \-o arg \-\- file1 file2
3672 The free mixing of options and
3674 parameters follows the GNU principle.
3676 That does not fulfill the strange option behavior of \%\f[CR]POSIX\fP
3677 that ends option processing as soon as the first non-option argument
3680 The end of option processing can be forced by the option
3685 .\" --------------------------------------------------------------------
3687 .\" --------------------------------------------------------------------
3690 .MT bug-groff@gnu.org
3691 bug-groff mailing list
3694 Include a complete, self-contained example that will allow the bug to
3695 be reproduced, and say which version of
3701 You can also use the
3705 but you must first subscribe to this list.
3707 You can do that by visiting the
3708 .UR http://\:lists.gnu.org/\:mailman/\:listinfo/\:groff
3709 groff mailing list web page
3715 .BR \%groff (@MAN1EXT@)
3716 for information on availability.
3719 .\" --------------------------------------------------------------------
3721 .\" --------------------------------------------------------------------
3724 .BR \%groff (@MAN1EXT@),
3725 .BR \%@g@troff (@MAN1EXT@)
3727 Details on the options and environment variables available in
3729 all of them can be used with
3735 .BR \%grog (@MAN1EXT@)
3736 This program tries to guess the necessary
3738 command line options from the input and the
3744 .BR \%groff (@MAN7EXT@)
3745 Documentation of the
3751 .BR groff_char (@MAN7EXT@)
3752 Documentation on the
3754 characters, special characters, and glyphs..
3758 .BR groff_tmac (@MAN5EXT@)
3759 Documentation on the
3765 .BR groff_out (@MAN5EXT@)
3766 Documentation on the
3767 .I \%groff intermediate output
3775 This can be run by the
3785 The standard program to display
3788 The information there is only useful if it is the
3792 Then it documents the options and environment variables that are
3798 .BR \%gxditview (@MAN1EXT@)
3811 .BR \%kghostview (1)
3838 .BR \%kghostview (1)
3880 Standard pager program for the
3890 The decompression programs supported by
3894 .\" --------------------------------------------------------------------
3896 .\" --------------------------------------------------------------------
3898 .\" --------------------------------------------------------------------
3900 .\" --------------------------------------------------------------------
3904 .\" --------------------------------------------------------------------
3906 .\" --------------------------------------------------------------------
3908 .\" Local Variables:
projects / platform / upstream / groff.git / blob