1 .TH GROFFER @MAN1EXT@ "@MDATE@" "groff @VERSION@"
3 groffer \- display groff files and man pages on X and tty
6 .\"*********************************************************************
8 .\" This man page doesn't use extended groff syntax!
9 .\" XXX: Yes, it does--"\~" is ubiquitous. "\/" and "\," also occur.
10 .\" Formatting it with and without groff's option '-C' should always
11 .\" give the same result.
13 .\"*********************************************************************
16 .\" ====================================================================
18 .\" ====================================================================
20 .\" Copyright (C) 2001-2018 Free Software Foundation, Inc.
22 .\" This file is part of groffer, which is part of groff, a free
25 .\" You can redistribute it and/or modify it under the terms of the GNU
26 .\" General Public License version 2 as published by the Free Software
29 .\" The license text is available in the internet at
30 .\" <http://www.gnu.org/licenses/gpl-2.0.html>.
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 .\" ====================================================================
79 .\" ====================================================================
81 .\" ====================================================================
85 program is the easiest way to use
86 .BR \%groff (@MAN1EXT@).
87 It can display arbitrary documents written in the
90 .BR \%groff (@MAN7EXT@),
94 .BR \%roff (@MAN7EXT@),
95 that are compatible to the original
99 It finds and runs all necessary
101 preprocessors, such as
108 program also includes many of the features for finding and displaying
109 the \%\f(CRUnix\fP manual pages
113 such that it can be used as a replacement for a
117 Moreover, compressed files that can be handled by
121 are decompressed on-the-fly.
125 The normal usage is quite simple by supplying a file name or name of a
127 without further options.
129 But the option handling has many possibilities for creating special
132 This can be done either in configuration files, with the shell
135 or on the command line.
139 The output can be generated and viewed in several different ways
144 X Window System-based
147 .BR \%gxditview (@MAN1EXT@),
153 display program, a web browser by generating
165 Most of the options that must be named when running
167 directly are determined automatically for
169 due to the internal usage of the
170 .BR \%grog (@MAN1EXT@)
173 But all parts can also be controlled manually by arguments.
177 Several file names can be specified on the command-line arguments.
179 They are transformed into a single document in the normal way of
184 Option handling is done in \f(CRGNU\fP style.
186 Options and file names can be mixed freely.
190 closes the option handling, all following arguments are treated as
193 Long options can be abbreviated in several ways.
196 .\" ====================================================================
197 .SH "OPTION OVERVIEW"
198 .\" ====================================================================
205 .OP \-h\~\fR|\fB\~\-\-help
206 .OP \-v\~\fR|\fB\~\-\-version
212 .I \%groffer mode options
218 .OP \-\-default\-modes mode1,mode2,\*(EL
223 .OP \-\-mode display_mode
235 .OP \-\-x\~\fR|\fB\~\-\-X\fP
241 .I options related to \%groff
245 .OP \-T\~\fR|\fB\~\-\-device device
246 .OP \-Z\~\fR|\fB\~\-\-intermediate\-output\~\fR|\fB\~\-\-ditroff
251 short options are accepted.
256 .I options for man\~pages
261 .OP \-\-apropos\-data
262 .OP \-\-apropos\-devel
263 .OP \-\-apropos\-progs
273 .I long options taken over from GNU man
280 .OP \-\-extension suffix
281 .OP \-\-locale language
283 .OP \-\-location\~\fR|\fB\~\-\-where
284 .OP \-\-manpath dir1:dir2:\*(EL
286 .OP \-\-pager program
287 .OP \-\-sections sec1:sec2:\*(EL
288 .OP \-\-systems sys1,sys2,\*(EL
289 .OP \-\-troff\-device device
292 Further long options of \f(CRGNU\fP
294 are accepted as well.
299 .I options mapped to X Window System Toolkit Intrinsics options
303 .OP \-\-bd\~\fR|\fB\~\-\-bordercolor pixels
304 .OP \-\-bg\~\fR|\fB\~\-\-background color
305 .OP \-\-bw\~\fR|\fB\~\-\-borderwidth pixels
306 .OP \-\-display X-display
307 .OP \-\-fg\~\fR|\fB\~\-\-foreground color
308 .OP \-\-fn\~\fR|\fB\~\-\-ft\~\fR|\fB\~\-\-font font_name
309 .OP \-\-geometry size_pos
310 .OP \-\-resolution value
313 .OP \-\-xrm X\-resource
319 .I options for development
324 .OP \-\-debug\-filenames
327 .OP \-\-debug\-params
328 .OP \-\-debug\-tmpdir
337 .I \%filespec arguments
342 parameters are all arguments that are neither an option nor an option
345 They usually mean a file name or a
351 In the following, the term
355 It means a word that consists of a
357 that is optionally followed by an
362 is a single character from
376 parameters means standard input.
381 stands for standard input (can occur several times).
386 the path name of an existing file.
390 .BI man: name ( section_extension )
392 .BI man: name . section_extension
394 .IB name ( section_extension )
396 .IB name . section_extension
398 .I "section_extension name"
399 search the \%man\~page
401 in the section with optional extension
402 .IR section_extension .
407 \%man\~page in the lowest
417 is not an existing file search for the man\~page
419 in the lowest man\~section.
424 .\" ====================================================================
426 .\" ====================================================================
430 program can usually be run with very few options.
432 But for special purposes, it supports many options.
434 These can be classified in 5 option classes.
440 are compatible with the short options of
441 .BR \%groff (@MAN1EXT@).
445 are compatible with the long options of
450 Arguments for long option names can be abbreviated in several ways.
452 First, the argument is checked whether it can be prolonged as is.
454 Furthermore, each minus sign
456 is considered as a starting point for a new abbreviation.
458 This leads to a set of multiple abbreviations for a single argument.
462 can be used as an abbreviation for
463 .BR \-\-debug\-not\-func ,
468 If the abbreviation of the argument leads to several resulting options
473 These abbreviations are only allowed in the environment variable
475 but not in the configuration files.
477 In configuration, all long options must be exact.
480 .\" ====================================================================
481 .SS "groffer breaking Options"
482 .\" ====================================================================
484 As soon as one of these options is found on the command line it is
485 executed, printed to standard output, and the running
487 is terminated thereafter.
489 All other arguments are ignored.
493 .B \-h\~\fR|\fB\~\-\-help
494 Print help information with a short explanation of options to
499 .B \-v\~\fR|\fB\~\-\-version
500 Print version information to standard output.
503 .\" ====================================================================
504 .SS "groffer Mode Options"
505 .\" ====================================================================
507 The display mode and the viewer programs are determined by these
510 If none of these mode and viewer options is specified
512 tries to find a suitable display mode automatically.
514 The default modes are
522 in the X Window System with different viewers and
528 on a terminal; other modes are tested if the programs for the main
529 default mode do not exist.
533 In the X Window System, many programs create their own window when
537 can run these viewers as an independent program in the background.
539 As this does not work in text mode on a terminal (tty) there must be a
540 way to know which viewers are X Window System-based graphical
545 script has a small amount of information on some viewer names.
547 If a viewer argument of the command\-line chooses an element that is
548 recognized as an X Window System-based program in this list, it is
549 treated as a viewer that can run in the background.
551 Unrecognized viewers are not run in the background.
555 For each mode, you are free to choose whatever viewer you want.
557 That need not be some graphical viewer suitable for this mode.
559 There is a chance to view the output source; for example, the
560 combination of the options
564 shows the content of the
566 output, the source code, with the pager
578 Reset all configuration from previously processed command-line options
579 to the default values.
581 This is useful to wipe out all former options of the configuration, in
583 and restart option processing using only the rest of the command line.
587 .BI \-\-default\-modes \ mode1,mode2,\*(EL
588 Set the sequence of modes for
590 to the comma separated list given in the argument.
594 for details on modes.
595 Display in the default manner; actually, this means to try the modes
611 viewers for the X Window System include
632 Set the display mode.
634 The following mode values are recognized:
640 Select the automatic determination of the display mode.
642 The sequence of modes that are tried can be set with the
643 .B \-\-default\-modes
646 Useful for restoring the
648 when a different mode was specified before.
653 Display formatted input in a
657 By default, the formatted input is displayed with the
664 After the file determination, switch
666 to process the input like
667 .BR \%groff (@MAN1EXT@)
677 Translate the input into HTML format and display the result in a web
680 By default, the existence of a sequence of standard web browsers is
681 tested, starting with
685 The text HTML viewer is
688 By default, the existence of a sequence of standard web browsers is
689 tested, starting with
693 The text HTML viewer is
714 is displayed with suitable viewer programs, such as
720 This is the traditional
723 Sometimes this mode produces more correct output than the default
726 By default, the input is formatted by
728 using the PostScript device, then it is transformed into the PDF file
734 If that's not possible, the
735 .I PostScript mode (ps)
738 Finally it is displayed using different viewer programs.
743 Display formatted input in a PostScript viewer program.
745 By default, the formatted input is displayed in one of many viewer
752 .I \%groff\~text\~mode
753 and write the result to standard output without a pager or viewer
758 by default, can be chosen with option
765 .I \%groff\~text\~mode
766 and write the result to standard output using a text pager program,
767 even when in the X Window System.
778 Display the formatted input in a native
782 By default, the formatted input is displayed with the
783 .BR \%gxditview (@MAN1EXT@)
784 program being distributed together with
786 But the legacy X Window System application
788 can also be chosen with the option
790 The default resolution is
799 for the resolution of
809 .I "groff intermediate output"
810 for the actual device is generated and the result is displayed.
814 the default width of the geometry of the display program is chosen to
826 Translate the input into
833 Then display the result in a web browser program, mostly the known
838 The following modes do not use the
842 They are only interesting for advanced applications.
847 Generate device output with plain
849 without using the special viewing features of
851 If no device was specified by option
862 Output the roff source code of the input files without further
884 Common PostScript viewers include
892 In each case, arguments can be provided additionally.
898 .BR \-\-mode=source .
909 The file for the chosen mode is generated and its content is printed
912 It will not be displayed in graphical mode.
919 The standard pager is
921 This option is equivalent to
924 .BR \-\-pager=\,\fIprog\fP .
925 The option argument can be a file name or a program to be searched in
927 arguments can be provided additionally.
931 .BI \-\-viewer \ prog
932 Choose a viewer program for actual device or mode.
934 This can be a file name or a program to be searched in
936 arguments can be provided additionally.
946 .B \-\-X\~\fR|\fB\~\-\-x
949 Suitable viewer programs are
950 .BR \%gxditview (@MAN1EXT@)
951 which is the default and
957 Signals the end of option processing; all remaining arguments are
966 accepts all short options that are valid for the
967 .BR \%groff (@MAN1EXT@)
972 options are sent unmodified via
977 So postprocessors, macro packages, compatibility with
980 and much more can be manually specified.
983 .\" ====================================================================
984 .SS "Options related to groff"
985 .\" ====================================================================
989 are compatible with the short options of
990 .BR \%groff (@MAN1EXT@).
994 options have either an additional special meaning within
996 or make sense for normal usage.
1000 Because of the special outputting behavior of the
1005 was designed to be switched into
1009 viewing features are disabled there.
1013 options do not switch the mode, but allow to customize the formatting
1019 This generates an ASCII approximation of output in the
1022 That could be important when the text pager has problems with control
1035 This is useful in case it cannot be recognized automatically.
1039 .BI \-\-P \ opt_or_arg
1042 as an option or option argument to the actual
1048 .B \-\-T \fIdevname\fR\~\fR|\fB\~\-\-device \fIdevname\fR
1050 This option determines
1054 The most important devices are the text output devices for referring
1055 to the different character sets, such as
1062 Each of these arguments switches
1066 using this device, to
1068 if the actual mode is not a
1073 arguments are mapped to the corresponding
1075 .B \-\-mode=\,\fIdevname\fR
1084 arguments are mapped to
1088 argument switches to
1098 .I groff intermediate output
1101 As the quality is relatively bad this option is deprecated; use
1107 device for a better display.
1111 .B \-Z\~\fR|\fB\~\-\-intermediate-output\~\fR|\fB\~\-\-ditroff
1114 and format the input with the
1115 .I \%groff intermediate output
1116 without postprocessing; see
1117 .BR \%groff_out (@MAN5EXT@).
1118 This is equivalent to option
1122 which can be used as well.
1128 options are supported by
1130 but they are just transparently transferred to
1132 without any intervention.
1134 The options that are not explicitly handled by
1136 are transparently passed to
1139 Therefore these transparent options are not documented here, but in
1140 .BR \%groff (@MAN1EXT@).
1141 Due to the automatism in
1145 options should be needed, except for advanced usage.
1148 .\" ====================================================================
1149 .SS "Options for man\~pages"
1150 .\" ====================================================================
1156 command or facility of
1160 arguments within all
1166 argument is taken for search as it is;
1168 specific parts are not handled, such that
1170 searches for the two arguments
1174 with a large result; for the
1177 nothing will be found.
1181 locale is handled only when the called programs do support this; the
1188 The display differs from the
1190 program by the following concepts:
1202 argument is searched on its own.
1208 wildcard characters are allowed and handled without a further option.
1213 .B \-\-apropos\-data
1216 descriptions for data documents, these are the
1218 .IR sections\~4 ", " 5 ", and " 7 .
1222 declarations are ignored, wildcards are accepted.
1226 .B \-\-apropos\-devel
1229 descriptions for development documents, these are the
1231 .IR sections\~2 ", " 3 ", and " 9 .
1235 declarations are ignored, wildcards are accepted.
1239 .B \-\-apropos\-progs
1242 descriptions for documents on programs, these are the
1244 .IR sections\~1 ", " 6 ", and " 8 .
1248 declarations are ignored, wildcards are accepted.
1257 and display their description \(em or say that it is not a
1259 This is written from anew, so it differs from
1262 output by the following concepts
1265 each retrieved file name is added,
1267 local files are handled as well,
1269 the \fIlanguage\fP and \fIsystem\fP locale is supported,
1271 the display is framed by a
1273 output format similar to a
1276 wildcard characters are allowed without a further option.
1281 The following options were added to
1283 for choosing whether the file name arguments are interpreted as names
1284 for local files or as a search pattern for
1287 The default is looking up for local files.
1292 Check the non-option command-line arguments
1298 then whether they represent an existing file.
1302 is first tested whether it is an existing file.
1306 .B \-\-no-man\~\fR|\fB\~\-\-local-file
1311 is the corresponding
1318 Disable former calls of
1325 .\" ====================================================================
1326 .SS "Long options taken over from GNU man"
1327 .\" ====================================================================
1331 were synchronized with the long options of \f(CRGNU\fP
1334 All long options of \f(CRGNU\fP
1336 are recognized, but not all of these options are important to
1338 so most of them are just ignored.
1350 In the following, the
1352 options that have a special meaning for
1358 If your system has \f(CRGNU\fP
1360 installed the full set of long and short options of the \f(CRGNU\fP
1362 program can be passed via the environment variable
1372 retrieve all suitable documents instead of only one.
1376 .B \-7\~\fR|\fB\~\-\-ascii
1379 display ASCII translation of special characters for critical environment.
1381 This is equivalent to
1382 .BR "groff \%\-mtty_char" ;
1384 .BR groff_tmac (@MAN5EXT@).
1390 .IR "groff intermediate output" .
1391 This is equivalent to
1397 .BI \-\-extension \ suffix
1400 search to file names that have
1402 appended to their section element.
1404 For example, in the file name
1405 .I \%/usr/share/man/man3/terminfo.3ncurses.gz
1413 .BI \-\-locale \ language
1415 Set the language for
1418 This has the same effect, but overwrites
1424 Print the location of the retrieved files to standard error.
1429 Do not display the location of retrieved files; this resets a former
1438 .BI \-\-manpath \ 'dir1:dir2:\*(EL'
1439 Use the specified search path for retrieving
1441 instead of the program defaults.
1443 If the argument is set to the empty string "" the search for
1450 Set the pager program in
1455 This can be set with
1460 .BI \-\-sections \ sec1:sec2:\*(EL
1461 Restrict searching for
1465 a colon-separated list.
1469 .BI \-\-systems \ sys1,sys2,\*(EL
1472 for the given operating systems; the argument
1474 is a comma-separated list.
1483 .\" ====================================================================
1484 .SS "X Window System Toolkit Intrinsics Options"
1485 .\" ====================================================================
1487 The following long options were adapted from the corresponding
1488 X Window System Toolkit Intrinsics options.
1491 will pass them to the actual viewer program if it is an
1492 X Window System program.
1494 Otherwise these options are ignored.
1498 Unfortunately these options use the old style of a single minus for
1503 that was changed to the standard with using a double minus for long
1504 options, for example,
1508 for the X Window System Toolkit Intrinsics option
1516 .I "X Toolkit Intrinsics \(en C Language Interface"
1517 for more details on these options and their arguments.
1521 .BI \-\-background \ color
1522 Set the background color of the viewer window.
1527 This is equivalent to
1528 .BR \-\-bordercolor .
1533 This is equivalent to
1534 .BR \-\-background .
1539 This is equivalent to
1540 .BR \-\-borderwidth .
1544 .BI \-\-bordercolor \ pixels
1545 Specifies the color of the border surrounding the viewer window.
1549 .BI \-\-borderwidth \ pixels
1550 Specifies the width in pixels of the border surrounding the viewer
1555 .BI \-\-display \ X-display
1556 Set the X Window System display on which the viewer program
1559 See section \(lqDisplay Names\(rq in
1561 for the syntax of the argument.
1565 .BI \-\-foreground \ color
1566 Set the foreground color of the viewer window.
1571 This is equivalent to
1572 .BR \-\-foreground .
1576 .BI \-\-fn \ font_name
1577 This is equivalent to
1582 .BI \-\-font \ font_name
1583 Set the font used by the viewer window.
1585 The argument is an X Window System font name.
1589 .BI \-\-ft \ font_name
1590 This is equivalent to
1595 .BI \-\-geometry \ size_pos
1596 Set the geometry of the display window, that means its size and its
1599 See section \(lqGeometry Specifications\(rq in
1601 for the syntax of the argument.
1605 .BI \-\-resolution \ value
1606 Set X Window System resolution in dpi (dots per inch) in some
1609 The only supported dpi values are
1614 Actually, the default resolution for
1618 The resolution also sets the default device in
1624 Reverse foreground and background color of the viewer window.
1628 .BI \-\-title "\ 'some text'"
1629 Set the title for the viewer window.
1633 .BI \-\-xrm \ 'resource'
1634 Set the X Window System server resource to the given value.
1637 .\" ====================================================================
1638 .SS "Options for Development"
1639 .\" ====================================================================
1643 Enable all debugging options
1644 .BR \-\-debug\-\,\fItype\fP .
1646 The temporary files are kept and not deleted, the
1648 output is printed, the name of the temporary directory is printed, the
1649 displayed file names are printed, and the parameters are printed.
1653 .B \-\-debug\-filenames
1654 Print the names of the files and
1656 that are displayed by
1662 Print the output of all
1669 Enable two debugging informations.
1671 Print the name of the temporary directory and keep the temporary
1672 files, do not delete them during the run of
1677 .B \-\-debug\-params
1678 Print the parameters, as obtained from the configuration files, from
1680 and the command-line arguments.
1684 .B \-\-debug\-tmpdir
1685 Print the name of the temporary directory.
1692 but without the output; no viewer is started.
1694 This makes only sense in development.
1698 .B \-\-print=\,\fItext\fR
1699 Just print the argument to standard error.
1701 This is good for parameter check.
1706 This is an advanced option for debugging only.
1708 Instead of displaying the formatted input, a lot of
1710 specific information is printed to standard output:
1714 the output file name in the temporary directory,
1717 the display mode of the actual
1722 the display program for viewing the output with its arguments,
1725 the active parameters from the config files, the arguments in
1727 and the arguments of the command line,
1730 the pipeline that would be run by the
1732 program, but without executing it.
1737 Other useful debugging options are the
1742 .BR \-\-mode=groff .
1745 .\" ====================================================================
1746 .SS "Filespec Arguments"
1747 .\" ====================================================================
1751 parameter is an argument that is not an option or option argument.
1756 parameters are a file name or a template for searching
1759 These input sources are collected and composed into a single output
1766 The strange \%\f(CRPOSIX\fP behavior to regard all arguments behind
1767 the first non-option argument as
1769 arguments is ignored.
1771 The \f(CRGNU\fP behavior to recognize options even when mixed with
1773 arguments is used throughout.
1775 But, as usual, the double minus argument
1777 ends the option handling and interprets all following arguments as
1779 arguments; so the \%\f(CRPOSIX\fP behavior can be easily adopted.
1785 have a special handling of
1789 Each argument is taken as a search scheme of its own.
1791 Also a regexp (regular expression) can be used in the filespec.
1794 .B groffer \-\-apropos '^gro.f$'
1800 .B groffer \-\-apropos groff
1803 somewhere in the name or description of the
1810 such as the normal display or the output with
1812 have a different scheme for
1814 No regular expressions are used for the arguments.
1818 arguments are handled by the following scheme.
1822 It is necessary to know that on each system the
1824 are sorted according to their content into several sections.
1827 .I classical man sections
1828 have a single-character name, either a digit from
1832 or one of the characters
1839 This can optionally be followed by a string, the so-called
1843 allows the storage of several
1845 with the same name in the same
1849 is only rarely used; usually it is omitted.
1853 are searched automatically by alphabet.
1857 In the following, we use the name
1858 .I section_extension
1859 for a word that consists of a single character
1863 character that is followed by an
1868 parameter can have one of the following forms in decreasing sequence.
1874 parameters means that
1876 waits for standard input.
1880 always stands for standard input; it can occur several times.
1882 If you want to look up a
1893 is tested whether it is the path name of an existing file.
1895 Otherwise it is assumed to be a searching pattern for a
1900 .BI \%man: name ( section_extension ) ,
1901 .BI \%man: name . section_extension,
1902 .IB \%name ( section_extension ) ,
1904 .IB \%name . section_extension
1905 search the \%man\~page
1907 in \%man\~section and possibly extension of
1908 .IR \%section_extension .
1918 that has a document called
1923 .I \%section_extension\~name
1924 is a pattern of 2 arguments that originates from a strange argument
1929 Again, this searches the man page
1932 .IR \%section_extension ,
1935 character optionally followed by an
1940 We are left with the argument
1942 which is not an existing file.
1944 So this searches for the
1950 that has a document for this name.
1954 Several file name arguments can be supplied.
1958 into a single document.
1960 Note that the set of option arguments must fit to all of these file
1963 So they should have at least the same style of the
1968 .\" ====================================================================
1970 .\" ====================================================================
1974 program collects all input into a single file, formats it with the
1976 program for a certain device, and then chooses a suitable viewer
1979 The device and viewer process in
1984 The mode and viewer of a running
1986 program is selected automatically, but the user can also choose it
1990 The modes are selected by option the arguments of
1991 .BR \-\-mode=\,\fIanymode .
1992 Additionally, each of this argument can be specified as an option of
1995 Most of these modes have a viewer program, which can be chosen by the
2001 Several different modes are offered: graphical modes for
2002 the X Window System,
2006 for debugging and development.
2019 This mode testing sequence for
2021 can be changed by specifying a comma separated list of modes with the
2023 .B \-\-default\-modes.
2029 and the decompression of the input are active in every mode.
2032 .\" ====================================================================
2033 .SS "Graphical Display Modes"
2034 .\" ====================================================================
2036 The graphical display modes work mostly in the X Window System
2037 environment (or similar implementations within other windowing
2040 The environment variable
2044 are used for specifying the X Window System display to be used.
2046 If this environment variable is empty,
2048 assumes that the X Window System is not running and changes to a
2051 You can change this automatic behavior by the option
2052 .BR \-\-default\-modes .
2056 Known viewers for the graphical display modes and their standard
2057 X Window System viewer programs are
2076 in a PostScript viewer
2085 .BR \%gxditview (@MAN1EXT@)
2092 in a DVI viewer program
2101 has a major advantage \(em it is the only graphical display mode that
2102 allows searching for text within the viewer; this can be a really
2105 Unfortunately, it takes some time to transform the input into the PDF
2106 format, so it was not chosen as the major mode.
2110 These graphical viewers can be customized by options of the
2111 X Window System Toolkit Intrinsics.
2115 options use a leading double minus instead of the single minus used by
2116 the X Window System Toolkit Intrinsics.
2119 .\" ====================================================================
2121 .\" ====================================================================
2123 There are two modes for text output,
2125 for plain output without a pager and
2127 for a text output on a text terminal using some pager program.
2133 is not set or empty,
2135 assumes that it should use
2140 In the actual implementation, the
2147 This can be changed by specifying option
2154 The pager to be used can be specified by one of the options
2158 or by the environment variable
2160 If all of this is not used the
2162 program with the option
2164 for correctly displaying control sequences is used as the default
2168 .\" ====================================================================
2169 .SS "Special Modes for Debugging and Development"
2170 .\" ====================================================================
2174 file determination and decompression.
2176 This is combined into a single input file that is fed directly into
2178 with different strategy without the
2182 These modes are regarded as advanced, they are useful for debugging
2183 and development purposes.
2191 just displays the decompressed input.
2197 does not display in a graphical mode.
2199 It just generates the file for the chosen mode and then prints its
2200 content to standard output.
2208 using only some suitable options provided to
2211 This enables the user to save the generated output into a file or pipe
2212 it into another program.
2217 .IR \%groff\~\%mode ,
2220 disables post-processing, thus producing the
2222 .I groff intermediate
2226 In this mode, the input is formatted, but not postprocessed; see
2227 .BR \%groff_out (@MAN5EXT@)
2234 short options are supported by
2238 .\" ====================================================================
2239 .SH "MAN PAGE SEARCHING"
2240 .\" ====================================================================
2242 The default behavior of
2244 is to first test whether a file parameter represents a local file; if
2245 it is not an existing file name, it is assumed to represent the name
2248 The following options can be used to determine whether the arguments
2249 should be handled as file name or
2255 forces to interpret all file parameters as
2266 searching; so only local files are displayed.
2270 If neither a local file nor a
2272 was retrieved for some file parameter a warning is issued on standard
2273 error, but processing is continued.
2276 .\" ====================================================================
2277 .SS "Search Algorithm"
2278 .\" ====================================================================
2280 Let us now assume that a
2286 program provides a search facility for
2289 All long options, all environment variables, and most of the
2290 functionality of the \f(CRGNU\fP
2292 program were implemented.
2294 The search algorithm shall determine which file is displayed for a given
2296 The process can be modified by options and environment variables.
2302 action that is omitted in
2304 are the preformatted
2309 With the excellent performance of the actual computers, the
2312 aren't necessary any longer.
2318 program; it wants to read
2320 source files and format them itself.
2324 The algorithm for retrieving the file for a
2326 needs first a set of directories.
2328 This set starts with the so-called
2330 that is modified later on by adding names of
2335 This arising set is used for adding the section directories which
2344 is a list of directories that are separated by colon.
2346 It is generated by the following methods.
2349 The environment variable
2354 It can be read from the arguments of the environment variable
2360 can be manually specified by using the option
2362 An empty argument disables the
2371 program is tried to determine one.
2374 If this does not work a reasonable default path from
2380 We now have a starting set of directories.
2382 The first way to change this set is by adding names of
2389 .I operating systems
2392 This is not always true.
2395 .I operating systems
2396 can be provided by 3 methods.
2399 The environment variable
2401 has the lowest precedence.
2404 This can be overridden by an option in
2408 This again is overridden by the command-line option
2414 .I operating systems
2415 can be given by appending their names, separated by a comma.
2421 is changed by appending each
2423 name as subdirectory at the end of each directory of the set.
2431 name is specified the
2437 After this, the actual set of directories can be changed by
2441 This assumes that there exist
2443 in different languages.
2447 can be chosen by several methods.
2450 Environment variable
2454 This is overridden by
2458 This is overridden by
2462 This can be overridden by providing an option in
2466 All these environment variables are overridden by the command-line
2474 can be specified by specifying one of the pseudo-language parameters
2475 \f(CRC\fP or \f(CR\%POSIX\fP.
2477 This is like deleting a formerly given
2485 are usually in English.
2491 name is determined by
2495 it is specified in the \%\f(CRPOSIX\~1003.1\fP based format:
2498 \fI<language>\/\fP[\f(CB_\fP\,\fI<territory>\/\fP[\f(CB.\fP\
2499 \fI<character-set>\/\fP[\f(CB,\fP\,\fI<version>\/\fP]]],
2502 but the two-letter code in
2506 is sufficient for most purposes.
2508 If for a complicated
2514 searches the country part consisting of these first two characters as
2519 The actual directory set is copied thrice.
2523 name is appended as subdirectory to each directory in the first copy
2524 of the actual directory set (this is only done when a language
2525 information is given).
2527 Then the 2-letter abbreviation of the
2529 name is appended as subdirectories to the second copy of the directory
2530 set (this is only done when the given language name has more than 2
2533 The third copy of the directory set is kept unchanged (if no
2535 information is given this is the kept directory set).
2537 These maximally 3 copies are appended to get the new directory set.
2541 We now have a complete set of directories to work with.
2543 In each of these directories, the
2545 files are separated in
2550 is represented by a single character, a digit between
2566 exists containing all
2572 is a single character as described before.
2578 directory has the form
2579 .IR \%\f(CBman\fP<section>\f(CB/\fP<name>\f(CB.\fP<section>\
2580 [<extension>][\f(CB.\fP<compression>] ,
2590 that is also specified as filespec argument on the command line.
2596 is an addition to the section.
2598 This postfix acts like a subsection.
2602 occurs only in the file name, not in name of the
2606 It can be specified on the command line.
2610 On the other hand, the
2612 is just an information on how the file is compressed.
2614 This is not important for the user, such that it cannot be specified
2615 on the command line.
2619 There are 4 methods to specify a
2621 on the command line:
2624 Environment variable
2634 argument in the form
2638 Preargument before the
2640 argument in the form
2645 It is also possible to specify several
2647 by appending the single characters separated by colons.
2649 One can imagine that this means to restrict the
2656 are only possible for
2667 are searched one after the other in the given order, starting with
2669 until a suitable file is found.
2673 There are 4 methods to specify an
2675 on the command line.
2677 But it is not necessary to provide the whole extension name, some
2678 abbreviation is good enough in most cases.
2681 Environment variable
2691 argument in the form
2692 .I <name>.<section><extension>
2695 Preargument before the
2697 argument in the form
2698 .I <section><extension> <name>
2702 For further details on
2708 .\" ====================================================================
2709 .SS "Examples of man files"
2710 .\" ====================================================================
2713 .B /usr/share/man/man1/groff.1
2714 This is an uncompressed file for the
2721 \fIsh#\fR groffer\~groff
2725 is specified here, so all
2727 should be searched, but as
2729 is searched first this file will be found first.
2731 The file name is composed of the following components.
2747 .B /usr/local/share/man/man7/groff.7.gz
2748 The file name is composed of the following components.
2749 .B /usr/local/share/man
2763 stands for a compression with
2767 is not the first one it must be specified as well.
2769 This can be done by one of the following commands.
2771 \fIsh#\fR\~groffer\~groff.7
2772 \fIsh#\fR\~groffer\~7\~groff
2773 \fIsh#\fR\~groffer\~\-\-sections=7\~groff
2777 .B /usr/local/man/man1/ctags.1emacs21.bz2
2784 and the file name part
2792 the section has an extension
2794 and the file is compressed as
2798 The file can be viewed with one of the following commands
2800 \fIsh#\fR\~groffer\~ctags.1e
2801 \fIsh#\fR\~groffer\~1e\~ctags
2802 \fIsh#\fR\~groffer\~\-\-extension=e\~\-\-sections=1\~ctags
2804 where \f(CRe\fP works as an abbreviation for the extension
2809 .B /usr/man/linux/de/man7/man.7.Z
2814 then there is a subdirectory for an
2818 next comes a subdirectory
2834 signifies the compression that can be handled by
2836 We want now show how to provide several values for some options.
2838 That is possible for
2857 \fIsh#\fR groffer\~\-\-locale=de\~\-\-sections=5:7\~\-\-systems=linux,aix\~man
2858 \fIsh#\fR LANG=de\~MANSECT=5:7\~SYSTEM=linux,aix\~groffer\~man
2862 .\" ====================================================================
2864 .\" ====================================================================
2866 The program has a decompression facility.
2868 If standard input or a file that was retrieved from the command line
2869 parameters is compressed with a format that is supported by either
2873 it is decompressed on-the-fly.
2875 This includes the \f(CRGNU\fP
2882 The program displays the concatenation of all decompressed input in
2883 the sequence that was specified on the command line.
2886 .\" ====================================================================
2888 .\" ====================================================================
2892 program supports many system variables, most of them by courtesy of
2895 All environment variables of
2896 .BR \%groff (@MAN1EXT@)
2899 and some standard system variables are honored.
2902 .\" ====================================================================
2903 .SS "Native groffer Variables"
2904 .\" ====================================================================
2908 Store options for a run of
2911 The options specified in this variable are overridden by the options
2912 given on the command line.
2914 The content of this variable is run through the shell builtin
2916 so arguments containing whitespace or special shell characters should
2919 Do not forget to export this variable, otherwise it does not exist
2924 .\" ====================================================================
2925 .SS "System Variables"
2926 .\" ====================================================================
2928 The following variables have a special meaning for
2934 If set, this variable indicates that the X Window System is running.
2936 Testing this variable decides on whether graphical or text output is
2939 This variable should not be changed by the user carelessly, but it can
2940 be used to start the graphical
2942 on a remote X Window System terminal.
2944 For example, depending on your system,
2946 can be started on the second monitor by the command
2949 \fIsh#\fR DISPLAY=:0.1\~groffer\~what.ever &
2959 If one of these variables is set (in the above sequence), its content
2960 is interpreted as the locale, the language to be used, especially when
2964 A locale name is typically of the form
2976 is an ISO 639 language code,
2978 is an ISO 3166 country code, and
2980 is a character set or encoding identifier like ISO-8859-1 or UTF-8;
2982 .BR \%setlocale (3).
2984 The locale values \f(CRC\fP and \%\f(CRPOSIX\fP
2985 stand for the default, i.e.\& the
2987 directories without a language prefix.
2989 This is the same behavior as when all 3\~variables are unset.
2994 This variable can be used to set the pager for the tty output.
2996 For example, to disable the use of a pager completely set this
3002 \fIsh#\fR PAGER=cat\~groffer\~anything
3008 All programs within the
3010 script are called without a fixed path.
3012 Thus this environment variable determines the set of programs used
3017 .\" ====================================================================
3018 .SS "Groff Variables"
3019 .\" ====================================================================
3023 program internally calls
3025 so all environment variables documented in
3026 .BR \%groff (@MAN1EXT@)
3027 are internally used within
3031 The following variable has a direct meaning for the
3037 If the value of this variable is an existing, writable directory,
3039 uses it for storing its temporary files, just as
3044 .BR \%groff (@MAN1EXT@)
3045 man page for more details on the location of temporary files.
3048 .\" ====================================================================
3050 .\" ====================================================================
3052 Parts of the functionality of the
3054 program were implemented in
3056 support for all environment variables documented in
3060 but the meaning was slightly modified due to the different approach in
3062 but the user interface is the same.
3066 environment variables can be overwritten by options provided with
3068 which in turn is overwritten by the command line.
3073 Restrict the search for
3075 to files having this extension.
3077 This is overridden by option
3079 see there for details.
3084 This variable contains options as a preset for
3086 As not all of these are relevant for
3088 only the essential parts of its value are extracted.
3090 The options specified in this variable overwrite the values of the
3091 other environment variables that are specific to
3094 All options specified in this variable are overridden by the options
3095 given on the command line.
3100 If set, this variable contains the directories in which the
3104 This is overridden by option
3110 If this is a colon separated list of section names, the search for
3112 is restricted to those manual sections in that order.
3114 This is overridden by option
3120 If this is set to a comma separated list of names these are interpreted
3123 trees for different operating systems.
3125 This variable can be overwritten by option
3127 see there for details.
3131 The environment variable
3135 because the necessary preprocessors are determined automatically.
3138 .\" ====================================================================
3139 .SH "CONFIGURATION FILES"
3140 .\" ====================================================================
3144 program can be preconfigured by two configuration files.
3148 .B \%/etc/groff/groffer.conf
3149 System-wide configuration file for
3154 .B \%$HOME/.groff/groffer.conf
3155 User-specific configuration file for
3159 denotes the user's home directory.
3161 This file is called after the system-wide configuration file to enable
3162 overriding by the user.
3166 Both files are handled for the configuration, but the configuration
3169 comes first; it is overwritten by the configuration file in the home
3170 directory; both configuration files are overwritten by the environment
3173 everything is overwritten by the command line arguments.
3177 The configuration files contain options that should be called as
3182 These options are written in lines such that each contains either a
3183 long option, a short option, or a short option cluster; each with or
3184 without an argument.
3186 So each line with configuration information starts with a minus
3189 a line with a long option starts with two minus characters
3190 .RB \[lq] \-\- \[rq],
3191 a line with a short option or short option cluster starts with a
3197 The option names in the configuration files may not be abbreviated,
3202 The argument for a long option can be separated from the option name
3203 either by an equal sign
3205 or by whitespace, i.e.\& one or several space or tab characters.
3207 An argument for a short option or short option cluster can be directly
3208 appended to the option name or separated by whitespace.
3210 The end of an argument is the end of the line.
3212 It is not allowed to use a shell environment variable in an option
3217 It is not necessary to use quotes in an option or argument, except for
3220 An empty argument can be provided by appending a pair of quotes to the
3221 separating equal sign or whitespace; with a short option, the
3222 separator can be omitted as well.
3224 For a long option with a separating equal sign
3226 the pair of quotes can be omitted, thus ending the line with the
3227 separating equal sign.
3229 All other quote characters are cancelled internally.
3233 In the configuration files, arbitrary whitespace is allowed at the
3234 beginning of each line, it is just ignored.
3236 Each whitespace within a line is replaced by a single space character
3237 \[lq] \[rq] internally.
3241 All lines of the configuration lines that do not start
3242 with a minus character are ignored, such that comments starting with
3246 So there are no shell commands in the configuration files.
3250 As an example, consider the following configuration file that can be
3252 .B \%/etc/groff/groffer.conf
3254 .B \%\s+2~\s0/.groff/groffer.conf .
3261 # groffer configuration file
3263 # groffer options that are used in each call of groffer
3264 \-\-foreground=DarkBlue
3266 \-\-viewer=gxditview \-geometry 900x1200
3273 The lines starting with
3275 are just ignored, so they act as command lines.
3277 This configuration sets four
3279 options (the lines starting with
3280 .RB \[lq] \- \[rq]).
3281 This has the following effects:
3287 in all viewers that support this, such as
3294 in all viewers that support this, such as
3297 By this, the default device in
3305 .BR \%gxditview (@MAN1EXT@)
3308 viewer using the geometry option for setting the width to
3312 This geometry is suitable for a resolution of
3321 viewer with the argument
3326 .\" ====================================================================
3328 .\" ====================================================================
3334 Usually, it is just called with a file name or
3337 The following examples, however, show that
3339 has much more fancy capabilities.
3343 \fIsh#\fR\~groffer\~/usr/local/share/doc/groff/meintro.ms.gz
3346 Decompress, format and display the compressed file
3349 .BR /usr/local/share/doc/groff ,
3350 using the standard viewer
3352 as graphical viewer when in the X Window System, or the
3354 pager program otherwise.
3358 \fIsh#\fR\~groffer\~groff
3363 exists use it as input.
3365 Otherwise interpret the argument as a search for the
3369 in the smallest possible
3370 .IR \%man\~section ,
3371 being section 1 in this case.
3375 \fIsh#\fR\~groffer\~man:groff
3388 \fIsh#\fR\~groffer\~groff.7
3389 \fIsh#\fR\~groffer\~7\~groff
3399 This section search works only for a digit or a single character from
3404 \fIsh#\fR\~groffer\~fb.modes
3409 does not exist interpret this as a search for the
3415 is not a single character in classical section style the argument is
3416 not split to a search for
3421 \fIsh#\fR\~groffer\~groff\~\(cqtroff(1)\(cq\~man:roff
3424 The arguments that are not existing files are looked-up as the
3428 (automatic search, should be found in \fIman\fP\~section\~1),
3433 (in the section with the lowest number, being\~7 in this case).
3439 are necessary because the parentheses are special shell characters;
3440 escaping them with a backslash character
3444 would be possible, too.
3446 The formatted files are concatenated and displayed in one piece.
3450 \fIsh#\fR\~LANG=de\~groffer\~\-\-man\~\-\-viewer=galeon\~ls
3459 program, decompress it, format it to
3467 and view the result in the web browser
3473 is retrieved, even when a local file
3475 exists in the actual directory.
3480 \fIsh#\fR\~groffer\~\-\-source\~'man:roff(7)'
3487 in \fIman\fP\~section 7, decompress it, and print its unformatted
3488 content, its source code.
3493 \fIsh#\fR\~groffer\~\-\-de-p\~\-\-in\~\-\-ap
3496 This is a set of abbreviated arguments, it is determined as
3500 \fIsh#\fR\~groffer\~\-\-debug-params\~\-\-intermediate-output\~\-\-apropos
3506 \fIsh#\fR\~cat\~file.gz\~|\~groffer\~-Z\~-mfoo
3512 is sent to standard input, this is decompressed, and then this is
3514 .I \%groff intermediate output mode
3515 without post-processing
3528 \fIsh#\fR\~echo\~'\(rsf(CBWOW!'\~|
3529 > groffer \-\-x \-\-bg red \-\-fg yellow \-\-geometry 200x100 \-
3533 Display the word \f(CBWOW!\fP in a small window in constant-width
3534 bold font, using color yellow on red background.
3537 .\" ====================================================================
3539 .\" ====================================================================
3543 program is written in Perl, the Perl version during writing was v5.8.8.
3548 provides its own parser for command-line arguments that is compatible
3549 to both \%\f(CRPOSIX\fP
3553 It can handle option arguments and file names containing white space
3554 and a large set of special characters.
3556 The following standard types of options are supported.
3560 The option consisting of a single minus
3562 refers to standard input.
3566 A single minus followed by characters refers to a single character
3567 option or a combination thereof; for example, the
3569 short option combination
3576 Long options are options with names longer than one character; they
3577 are always preceded by a double minus.
3579 An option argument can either go to the next command-line argument or
3580 be appended with an equal sign to the argument; for example,
3589 ends option parsing; all further command-line arguments are
3592 parameters, i.e.\& file names or constructs for searching
3597 All command-line arguments that are neither options nor option
3598 arguments are interpreted as
3600 parameters and stored until option parsing has finished.
3602 For example, the command line
3605 \fIsh#\fR\~groffer file1 \-a \-o arg file2
3611 \fIsh#\fR\~groffer \-a \-o arg \-\- file1 file2
3616 The free mixing of options and
3618 parameters follows the GNU principle.
3620 That does not fulfill the strange option behavior of \%\f(CRPOSIX\fP
3621 that ends option processing as soon as the first non-option argument
3624 The end of option processing can be forced by the option
3625 .RB \[lq] \-\- \[rq]
3629 .\" ====================================================================
3631 .\" ====================================================================
3634 .MT groff\-bernd.warken\-72@\:web.de
3639 .\" ====================================================================
3641 .\" ====================================================================
3644 .BR \%groff (@MAN1EXT@),
3645 .BR \%@g@troff (@MAN1EXT@)
3647 Details on the options and environment variables available in
3649 all of them can be used with
3655 .BR \%grog (@MAN1EXT@)
3656 This program tries to guess the necessary
3658 command-line options from the input and the
3664 .BR \%groff (@MAN7EXT@)
3665 Documentation of the
3671 .BR groff_char (@MAN7EXT@)
3672 Documentation on the
3674 characters, special characters, and glyphs..
3678 .BR groff_tmac (@MAN5EXT@)
3679 Documentation on the
3685 .BR groff_out (@MAN5EXT@)
3686 Documentation on the
3687 .I \%groff intermediate output
3695 This can be run by the
3705 The standard program to display
3708 The information there is only useful if it is the
3712 Then it documents the options and environment variables that are
3718 .BR \%gxditview (@MAN1EXT@)
3731 .BR \%kghostview (1)
3758 .BR \%kghostview (1)
3801 Standard pager program for the
3811 The decompression programs supported by
3815 .\" ====================================================================
3817 .\" ====================================================================
3819 .\" Local Variables:
3822 .\" vim: set filetype=groff:
projects / platform / upstream / groff.git / blob