1 .TH GROFFER @MAN1EXT@ "@MDATE@" "Groff Version @VERSION@"
3 groffer \- display groff files and man\~pages on X and tty
6 .\" The .SH was moved to this place in order to appease `apropos'.
8 .\" --------------------------------------------------------------------
10 .\" --------------------------------------------------------------------
13 groffer.1 - man page for groffer (section 1).
15 Source file position: <groff_source_top>/contrib/groffer/groffer.man
16 Installed position: $prefix/share/man/man1/groffer.1
18 Version : groffer 0.9.7
19 Last update : 03 May 2004
21 Source file position: <groff-source>/contrib/groffer/groffer.man
23 Copyright (C) 2001,2002,2004 Free Software Foundation, Inc.
24 Written by Bernd Warken
26 This file is part of groff version @VERSION@.
28 groff is free software; you can redistribute it and/or modify it
29 under the terms of the GNU General Public License as published by
30 the Free Software Foundation; either version 2, or (at your option)
33 groff is distributed in the hope that it will be useful, but WITHOUT
34 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
35 or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
36 License for more details.
38 You should have received a copy of the GNU General Public License
39 along with groff; see the files COPYING and LICENSE in the top
40 directory of the groff source. If not, write to the Free Software
41 Foundation, 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
44 .\" --------------------------------------------------------------------
46 .\" --------------------------------------------------------------------
64 .ds @b- "\f[CB]-\f[]\""
65 .ds @b-- "\f[CB]--\f[]\""
67 .ds @i- "\f[CI]-\f[]\""
68 .ds @i-- "\f[CI]--\f[]\""
70 .ds Ellipsis ".\|.\|.\""
72 .\" --------------------------------------------------------------------
73 .\" setup for the macro definitions below
75 .\" naming: namespace:cathegory_macro.variable_name (experimental)
77 .\" --------------------------------------------------------------------
78 .\" configuration of prompt for `.Shell_cmd'* macros
79 .ds groffer:Shell_cmd.prompt_text sh#\" prompt for shell commands
80 .ds groffer:Shell_cmd+.prompt_text >\" prompt on continuation lines
81 .ds groffer:Shell_cmd_base.prompt_font I\" font for prompts
83 .\" automatically determine setup from the configuration above
84 .als @f groffer:Shell_cmd_base.prompt_font\"
85 .als @t groffer:Shell_cmd.prompt_text\"
86 .als @t+ groffer:Shell_cmd+.prompt_text\"
87 .ds groffer:Shell_cmd.prompt \f[\*[@f]]\*[@t]\f[]\" needed
88 .ds groffer:Shell_cmd+.prompt \f[\*[@f]]\*[@t+]\f[]\" needed
89 .nr @w \w'\*[groffer:Shell_cmd.prompt]'\"
90 .nr @w+ \w'\*[groffer:Shell_cmd+.prompt]'\"
92 .\" Full prompt width is maximum of texts plus 1m
93 .nr groffer:Shell_cmd_base.prompt_width (\n[@w]>?\n[@w+]+1m)\" needed
102 .\" --------------------------------------------------------------------
103 .\" static register for inter-macro communication in `.Synopsis'*
104 .nr groffer:Synopsis.level 0
106 .\" --------------------------------------------------------------------
107 .\" static registers for inter-macro communication in `.TP'*
108 .nr groffer:TP.level 0
109 .rr groffer:TP_header.flag
110 .rr groffer:TP_body.flag
111 .rr groffer:TP.indent
114 .\" --------------------------------------------------------------------
115 .\" Macro definitions
117 .\" Ignore all arguments like a comment, even after a .eo call.
120 .c --------------------------------------------------------------------
123 .c Print in constant-width bold font.
130 .c --------------------------------------------------------------------
133 .c Print in constant-width italic font.
140 .c --------------------------------------------------------------------
143 .c Print in constant-width roman font.
150 .c --------------------------------------------------------------------
151 .c .Error (<text>...)
153 .c Print error message to terminal and abort.
159 .c --------------------------------------------------------------------
160 .c .Env_var (<env_var_name> [<punct>])
162 .c Display an environment variable, with optional punctuation.
167 . Text \f[CB]\\$1\f[]\\$2
170 .c --------------------------------------------------------------------
171 .c .File_name (<path_name>)
173 .c Display a file or directory name in CB font.
178 .c --------------------------------------------------------------------
179 .c .Header_CB (<path_name>)
181 .c Display a line in CB font, for example after .TP
185 . Text \f[CB]\\$1\f[]\\$2
188 .c --------------------------------------------------------------------
189 .c .Opt_- ([<punct>])
191 .c Print `-' (minus sign); optional punctuation.
194 . ie (\\n[.$] == 0) \
197 . Opt_alt - "" "\\$1"
199 .c --------------------------------------------------------------------
200 .c .Opt_[-] ([<punct>])
202 .c Print `Opt_[-]' (minus sign in brackets); optional punctuation.
205 . ie (\\n[.$] == 0) \
208 . Opt_[alt] - "" "\\$1"
210 .c --------------------------------------------------------------------
211 .c .Opt_-- ([<punct>])
213 .c Print `--' (double minus); optional punctuation.
216 . ie (\\n[.$] == 0) \
219 . Opt_alt -- "" "\\$1"
221 .c --------------------------------------------------------------------
222 .c .Opt_[--] ([<punct>])
224 .c Print `Opt_[--]' (double minus in brackets); optional punctuation.
227 . ie (\\n[.$] == 0) \
230 . Opt_[alt] -- "" "\\$1"
232 .c --------------------------------------------------------------------
233 .c .Opt_alt ([<minus> <opt>]... [<arg> [<punct>]])
235 .c Alternate options separated by a vertical bar.
238 .c minus: either `-' or `--' (font CB).
239 .c opt: a name for an option, empty allowed (font CB).
240 .c arg: optionally, the argument to the option (font I).
241 .c punct: optional punctuation (in the starting font).
243 .c The minus/opt argument pairs, each
244 .c separated by a vertical bar `|', optionally add 'arg', separated
245 .c a space character ` '.
248 .c .Opt_alt - T -- device -- device-troff device .
250 .c -T|--device|--device-troff device.
253 . Opt_alt_base "" | "" \\$@
255 .c --------------------------------------------------------------------
256 .c .Opt_[alt] ([<minus> <opt>]... [<arg> [<punct>]])
258 .c Alternate options in brackets for section SYNOPSIS.
261 .c minus: either `-' or `--' (font CB).
262 .c opt: a name for an option, empty allowed (font CB).
263 .c arg: optionally, the argument to the option (font I).
264 .c punct: optional punctuation (in the starting font).
265 .c Global strings written to:
266 .c `@oa_prefix': left enclosing character (`[')
267 .c `@oa_sep': separator (`|')
268 .c `@oa_postfix': right enclosing character (`]')
270 .c The minus/opt argument pairs, each separated by a vertical
271 .c bar `|', optionally add 'arg', separated by a space character ` '.
274 .c .Opt_[alt] - T -- device -- device-troff device .
276 .c [-T|--device|--device-troff device].
279 . Opt_alt_base [ | ] \\$@
281 .c --------------------------------------------------------------------
282 .c .Opt_alt_base (<pre> <sep> <post> [<minus> <opt>]... [arg [punct]])
284 .c Alternating options; base macro for many others; do not use directly.
287 .c <pre>: prefix, resulted is preceded by this.
288 .c <sep>: separator between minus/opt pairs.
289 .c <post>: postfix, is appended to the result.
290 .c <minus>: either `-' or `--' (font CB).
291 .c <opt>: a name for an option, empty allowed (font CB).
292 .c <arg>: optionally, the argument to the option (font I).
293 .c <punct>: optional punctuation (in the starting font).
295 .c String `<pre>' followed by the <minus>/<opt> argument pairs, each
296 .c separated by string `<sep>', optionally add '<arg>', separated by
297 .c a single space ` ', followed by the string `<post>'.
302 . Error .\\0: not enough arguments.
303 . ds @pre \)\\$1\)\" prefix
304 . ds @sep \)\\$2\)\" separator
305 . ds @post \)\\$3\)\" postfix
308 . ds @res \f[CR]\\*[@pre]\"
309 . while (\\n[.$] >= 2) \{\
310 . c do the pairs, break on no `-'
316 . if (\\n[@count] > 0) \
317 . as @res \f[CR]\\*[@sep]\"
319 . as @res \f[CB]\\$1\\$2\:\" combine minus with option name
322 . if (\\n[.$] >= 3) \
323 . Error .\\0: wrong arguments: \\$@
324 . c all pairs are done
325 . ie (\\n[.$] == 0) \
326 . as @res \f[CR]\\*[@post]\"
328 . c optional option argument
330 . as @res \f[CR] \,\f[I]\\$1\"
333 . as @res \\f[CR]\\*[@post]\"
334 . if (\\n[.$] >= 1) \{\
336 . as @res \f[\\n[@font]]\\$1\"
350 .c --------------------------------------------------------------------
351 .c .Opt_def ([<minus> <opt>]... [<arg> [<punct>]])
353 .c Definitions of options in section OPTIONS.
356 .c minus: either `-' or `--' (font CB).
357 .c opt: a name for an option, empty allowed (font CB).
358 .c arg: optionally, the argument to the option (font I).
359 .c punct: optional punctuation (in the starting font).
361 .c The header for an indented paragraph, consisting of
362 .c minus/opt argument pairs, each, separated by a space
363 .c character ` ', optionally add 'arg', separated a space
367 .c .Opt_def - T -- device -- device-troff device .
369 .c -T --device --device-troff device.
370 .c as the header of for indented paragraph.
374 . Opt_alt_base "" "\~|\~" "" \\$@
376 .c --------------------------------------------------------------------
377 .c .Opt_element ([<minus> <opt>]... [<arg> [<punct>]])
379 .c Definitions of options in section OPTIONS.
382 .c minus: either `-' or `--' (font CB).
383 .c opt: a name for an option, empty allowed (font CB).
384 .c arg: optionally, the argument to the option (font I).
385 .c punct: optional punctuation (in the starting font).
387 .c The minus/opt argument pairs, each, separated by a space
388 .c character ` ', optionally add 'arg', separated a space
392 .c .Opt_element - T -- device -- device-troff device .
394 .c -T --device --device-troff device.
397 . Opt_alt_base "" "\~" "" \\$@
399 .c --------------------------------------------------------------------
400 .als Opt_list Opt_element
402 .c --------------------------------------------------------------------
403 .c .Opt_long ([<name> [<punct>]])
405 .c Print `--name' somewhere in the text; optional punctuation.
408 . Opt_alt -- "\\$1" "" "\\$2"
410 .c --------------------------------------------------------------------
411 .c .Opt_long_arg ([<name> <arg> [<punct>]])
413 .c Print `--name=arg' somewhere in the text; optional punctuation.
416 . Opt_alt -- "\\$1=\\$2" "" "\\$3"
418 .c --------------------------------------------------------------------
419 .c .Opt_[long] ([<name> [<punct>]])
421 .c Print `--name' somewhere in the text; optional punctuation.
424 . Opt_[alt] -- "\\$1" "" "\\$2"
426 .c --------------------------------------------------------------------
427 .c .Opt_short ([<name> [<punct>]])
429 .c Print `-name' somewhere in the Text; optional punctuation.
432 . Opt_alt - "\\$1" "" "\\$2"
434 .c --------------------------------------------------------------------
435 .c .Opt_[short] ([name [punct]])
437 .c Print `[-name]' somewhere in the Text; optional punctuation.
440 . Opt_[alt] - "\\$1" "" "\\$2"
442 .c --------------------------------------------------------------------
443 .c .Shell_cmd (<CR> [<CI>] ...)
445 .c A shell command line; display args alternating in fonts CR and CI.
448 .c .Shell_cmd "groffer --dpi 100 file"
449 .c result: `sh# groffer --dpi 100 file'
450 .c with 'sh#' in font I, the rest in CR
452 .c .Shell_cmd groffer\~--dpi\~100\~file
453 .c result: the same as above
455 .c .Shell_cmd "groffer --dpi=" value " file"
456 .c result: sh# groffer --dpi=value file
457 .c with `groffer --dpi=' and `file' in CR; `value' in CI
459 .c .Shell_cmd groffer\~--dpi= value \~file
460 .c result: the same as the previous example
463 . groffer:Shell_cmd_base "\*[groffer:Shell_cmd.prompt]" \\$@
465 .c --------------------------------------------------------------------
466 .c .Shell_cmd+ (<CR> [<CI>] ...)
468 .c A continuation line for .Shell_cmd.
471 . groffer:Shell_cmd_base "\*[groffer:Shell_cmd+.prompt]" \\$@
473 .c --------------------------------------------------------------------
474 .c .Shell_cmd_base (<prompt> [<CR> [<CI>] ...])
476 .c A shell command line; display args alternating in fonts CR and CI.
477 .c Internal, do not use directly.
479 .c Globals: read-only register @.Shell_cmd_width
481 .de groffer:Shell_cmd_base
482 . if (\\n[.$] <= 0) \
484 . nr @+font \\n[.f]\"
487 . c gap between prompt and command
488 . nr @+gap \\n[groffer:Shell_cmd_base.prompt_width]-\\w'\\*[@prompt]'\"
489 . ds @res \\*[@prompt]\h'\\n[@+gap]u'\"
492 . while (\\n[.$] > 0) \{\
493 . as @res \\f[\\*[@cf]]\\$1\"
515 .c --------------------------------------------------------------------
518 .c Begin a synopsis section, to be ended by a ./Synopsis macro.
521 . if (\\n[groffer:Synopsis.level] > 0) \
522 . Error .\\$0: previous .Synopsis was not closed by ./Synopsis.
525 . nr @old_indent \\n(.i
527 . in +\w'\fB\\*[@1]\0'u
528 . ti \\n[@old_indent]u
532 . nr groffer:Synopsis.level +1\" marker for ./Synopsis
534 .c --------------------------------------------------------------------
537 .c Close a synopsis section opened by the previous .Synopsis macro.
540 . if (\\n[groffer:Synopsis.level] <= 0) \
541 . Error .\\$0: no previous call of .Synopsis
546 . nr groffer:Synopsis.level -1
548 .c --------------------------------------------------------------------
551 .c Treat the arguments as text, no matter how they look.
554 . if (\\n[.$] == 0) \
558 .c --------------------------------------------------------------------
559 .c .Topic ([<indent>])
561 .c A bulleted paragraph
572 .c --------------------------------------------------------------------
575 .c Continuation line for .TP header.
582 .c --------------------------------------------------------------------
583 .c .TP_header ([<indent>])
585 .c Start a multi-line header for a .TP-like paragraph
588 . if (\\n[groffer:TP.level] < 0) \
589 . Error .\\$0: wrong level.
590 . nr groffer:TP.level +1
592 . ie (\\n[.$] == 0) \
593 . rr groffer:TP.indent
595 . nr groffer:TP.indent \\$1
596 . nr groffer:TP_header.flag 1
598 .c --------------------------------------------------------------------
599 .c .TP_body ([<indent>])
601 .c End a previous .TP-header and beging the body of the paragraph.
604 . if !rgroffer:TP_header.flag \
605 . Error .\\$0: no previous call of .TP_header
606 . if (\\n[groffer:TP.level] <= 0) \
607 . Error .\\$0: wrong level.
609 . ie (\\n[.$] == 0) \{\
610 . ie rgroffer:TP.indent \{\
611 . RS \\n[groffer:TP.indent]u
618 . rr groffer:TP.indent
619 . rr groffer:TP_header.flag
620 . nr groffer:TP_body.flag 1
622 .c --------------------------------------------------------------------
625 .c End of former .TP_body paragraph.
628 . if !rgroffer:TP_body.flag \
629 . Error .\\$0: no previous .TP_body.
630 . if (\\n[groffer:TP.level] <= 0) \
631 . Error TP_end: wrong level.
632 . nr groffer:TP.level -1
633 . rr grogger:TP.indent
634 . rr groffer:TP_header.flag
635 . rr groffer:TP_body.flag
640 .\" End of macro definitions
643 .\" --------------------------------------------------------------------
645 .\" --------------------------------------------------------------------
651 .RI [ "filespec" "\*[Ellipsis]]"
655 .Opt_alt -- apropos -- apropos-data -- apropos-devel -- apropos-progs name
663 .Opt_alt - v -- version
667 .\" --------------------------------------------------------------------
669 .\" --------------------------------------------------------------------
673 program is the easiest way to use
674 .BR groff (@MAN1EXT@).
675 It can display arbitrary documents written in the
676 .BR groff (@MAN7EXT@)
679 languages that are compatible to the original troff language.
683 program also includes many of the features for finding and displaying
684 the UNIX manual pages
686 such that it can be used as a replacement for a
690 Moreover, compressed files that can be handled by
694 are decompressed on-the-fly.
698 The normal usage is quite simple by supplying a file name or name of a
699 man\~page without further options.
701 But the option handling has many possibilities for creating special
704 This can be done in configuration files, with the shell environment
707 or on the command line.
711 The output can be generated and viewed in several different ways
715 This includes the groff native X viewer
716 .BR gxditview (@MAN1EXT@),
717 each Postcript or dvi display program, a web browser by generating
718 html in www-mode, or several text modes in text terminals.
722 Most of the options that must be named when running
724 directly are determined automatically for
726 due to the internal usage of the
730 But all parts can also be controlled manually by arguments.
734 Several file names can be specified on the command line arguments.
736 They are transformed into a single document in the normal way of
740 .\" --------------------------------------------------------------------
741 .SH "OPTION OVERVIEW"
742 .\" --------------------------------------------------------------------
748 .Opt_[alt] -- apropos name
749 .Opt_[alt] -- apropos-data name
750 .Opt_[alt] -- apropos-devel name
751 .Opt_[alt] -- apropos-progs name
752 .Opt_[alt] - h -- help
753 .Opt_[alt] - v -- version
758 .I groffer mode options
762 .Opt_[alt] -- default
763 .Opt_[alt] -- default-modes mode1,mode2,\*[Ellipsis]
765 .Opt_[alt] -- dvi-viewer prog
768 .Opt_[alt] -- html-viewer prog
770 .Opt_[alt] -- mode display_mode
773 .Opt_[alt] -- pdf-viewer prog
775 .Opt_[alt] -- ps-viewer prog
778 .Opt_[alt] -- tty-viewer prog
780 .Opt_[alt] -- www-viewer prog
782 .Opt_[alt] -- x-viewer -- X-viewer prog
787 .I development options
796 .I options related to groff
799 .Opt_[alt] - P -- postproc-arg opt_or_arg
800 .Opt_[alt] - Q -- source
801 .Opt_[alt] - T -- device device
802 .Opt_[alt] - Z -- intermediate-output -- ditroff
806 short options are accepted.
811 .I X Window toolkit options
814 .Opt_[alt] -- bd pixels
815 .Opt_[alt] -- bg -- background color
816 .Opt_[alt] -- bw pixels
817 .Opt_[alt] -- display X-display
818 .Opt_[alt] -- fg -- foreground color
819 .Opt_[alt] -- ft -- font font_name
820 .Opt_[alt] -- geometry size_pos
821 .Opt_[alt] -- resolution value
823 .Opt_[alt] -- title string
824 .Opt_[alt] -- xrm X_resource
834 .Opt_[alt] -- ditroff
835 .Opt_[alt] -- extension suffix
836 .Opt_[alt] -- locale language
837 .Opt_[alt] -- local-file
838 .Opt_[alt] -- manpath dir1:dir2:\*[Ellipsis]
839 .Opt_[alt] -- pager program
840 .Opt_[alt] -- sections sec1:sec2:\*[Ellipsis]
841 .Opt_[alt] -- systems sys1,sys2,\*[Ellipsis]
842 .Opt_[alt] -- troff-device device
845 Further long options of GNU
847 are accepted as well.
857 parameters means standard input.
862 stands for standard input (can occur several times).
867 the path name of an existing file.
871 .BI man: name ( section )
888 search for a man\~page
896 man\~page in the lowest man\~section that has
906 search for a man\~page
916 is not an existing file search for the man\~page
918 in the lowest man\~section.
923 .\" --------------------------------------------------------------------
925 .\" --------------------------------------------------------------------
929 program can usually be run with very few options.
931 But for special purposes, it supports many options.
933 These can be classified in 5 option classes.
939 are compatible with the short options of
940 .BR groff (@MAN1EXT@).
944 are compatible with the long options of
948 .\" --------------------------------------------------------------------
949 .SS "groffer breaking Options"
950 .\" --------------------------------------------------------------------
952 As soon as one of these options is found on the command line it is
953 executed, printed to standard output, and the running
955 is terminated thereafter.
957 All other arguments are ignored.
960 .Opt_def -- apropos name
963 command for searching within man page
966 That slightly differs from the strange behavior of the
970 which has no argument of its own, but takes the file arguments
973 Practically both concepts are compatible.
976 .Opt_def -- apropos-data name
979 descriptions for data documents, in the
981 sections 4, 5, and 7.
984 .Opt_def -- apropos-devel name
987 descriptions for development documents, in the
989 sections 2, 3, and 9.
992 .Opt_def -- apropos-progs name
995 descriptions for documents on programs, in the
997 sections 1, 6, and 8.
1000 .Opt_def - h -- help
1001 Print a helping information with a short explanation of option sto
1005 .Opt_def - v -- version
1006 Print version information to standard output.
1009 .\" --------------------------------------------------------------------
1010 .SS "groffer Mode Options"
1011 .\" --------------------------------------------------------------------
1013 The display mode and the viewer programs are determined by these
1016 If none of these mode and viewer options is specified
1018 tries to find a suitable display mode automatically.
1023 .Opt_long_arg mode auto .
1027 Reset all configuration from previously processed command line options
1028 to the default values.
1030 This is useful to wipe out all former options of the configuration, in
1031 .Env_var $GROFFER_OPT ,
1032 and restart option processing using only the rest of the command line.
1035 .Opt_def -- default-modes mode1,mode2,\*[Ellipsis]
1036 Set the sequence of modes for
1038 to the comma separated list given in the argument.
1042 for details on modes. Display in the default manner; actually, this
1043 means to try the modes
1054 .Opt_long_arg mode dvi .
1057 .Opt_def -- dvi-viewer prog
1058 Set the viewer program for dvi mode.
1060 This can be a file name or a program to be searched in
1063 Known dvi viewers inlude
1068 In each case, arguments can be provided additionally.
1073 .Opt_long_arg mode groff .
1078 .Opt_long_arg mode html .
1081 .Opt_def -- html-viewer
1083 .Opt_long www-viewer .
1086 .Opt_def -- mode value
1088 Set the display mode.
1090 The following mode values are recognized:
1096 Select the automatic determination of the display mode.
1098 The sequence of modes that are tried can be set with the
1099 .Opt_long default-modes
1102 Useful for restoring the default mode when a different mode was
1108 Display formatted input in a
1112 By default, the formatted input is displayed with the
1120 After the file determination, switch
1122 to process the input like
1123 .BR groff (@MAN1EXT@)
1133 Translate the input into html format and display the result in a web
1136 By default, the existence of a sequence of standard web browsers is
1137 tested, starting with
1141 The text html viewer is
1147 Display formatted input in a
1149 (Portable Document Format) viewer
1152 By default, the input is formatted by groff using the Postscript
1153 device, then it is transformed into the PDF file format using
1155 and finally displayed either with the
1161 PDF has a big advantage because the text is displayed graphically and
1162 is searchable as well.
1164 But as the transformation takes a considerable amount of time, this
1165 mode is not suitable as a default device for the auto mode.
1170 Display formatted input in a Postscript viewer program.
1172 By default, the formatted input is displayed with the
1173 .BR ghostview (@MAN1EXT@)
1181 text mode and write the result to standard output without a pager or
1186 by default, can be chosen with option
1194 text mode and write the result to standard output using a text pager
1195 program, even when in X Window.
1206 Display formatted input in a native roff viewer.
1208 By default, the formatted input is displayed with the
1209 .BR gxditview (@MAN1EXT@)
1210 program, being distributed together with groff, or with
1212 which is distributed as a standard X tool.
1218 .Opt_long_arg mode X .
1222 The following modes do not use the
1226 They are only interesting for advanced applications.
1231 Generate device output with plain
1233 without using the special viewing features of
1235 If no device was specified by option
1246 Display the source code of the input without formatting; equivalent to
1255 .Opt_long_arg mode pdf .
1258 .Opt_def -- pdf-viewer prog
1259 Set the viewer program for
1263 This can be a file name or a program to be searched in
1266 In each case, arguments can be provided additionally.
1271 .Opt_long_arg mode ps .
1274 .Opt_def -- ps-viewer prog
1275 Set the viewer program for
1279 This can be a file name or a program to be searched in
1282 Common Postscript viewers inlude
1288 In each case, arguments can be provided additionally.
1293 .Opt_long_arg mode text .
1298 .Opt_long_arg mode tty .
1301 .Opt_def -- tty-viewer
1302 Choose tty display mode, that means displaying in a text pager even
1303 when in X; eqivalent to
1304 .Opt_long_arg mode tty .
1309 .Opt_long_arg mode www .
1312 .Opt_def -- www-viewer prog
1313 Set the web browser program for viewing in
1317 Each program that accepts html input and allows the
1318 .BI file://localhost/ dir / file
1319 syntax on the command line is suitable as viewer program; it can be
1320 the path name of an executable file or a program in
1323 In each case, arguments can be provided additionally.
1326 .Opt_def - X -- X -- x
1328 .Opt_long_arg mode X .
1331 .Opt_def -- X-viewer -- x-viewer prog
1332 Set the viewer program for
1336 Suitable viewer programs are
1337 .BR gxditview (@MAN1EXT@)
1341 But the argument can be any executable file or a program in
1344 In each case, arguments can be provided additionally.
1349 Signals the end of option processing; all remaining arguments are
1358 accepts all arguments that are valid for the
1359 .BR groff (@MAN1EXT@)
1362 All non-groffer options are sent unmodified via
1367 Postprocessors, macro packages, compatibility with classical
1369 and much more can be manually specified.
1372 .\" --------------------------------------------------------------------
1373 .SH "Options for Development"
1374 .\" --------------------------------------------------------------------
1377 Print debugging information for development only.
1379 Actually, a function call stack is printed if an error occurs.
1382 .Opt_def -- shell "shell_program"
1383 Specify the shell under which the groffer script should be run.
1385 The script first tests whether this option is set (either by
1386 configuration, within
1388 or as a command line option); if so, the script is rerun under the
1389 shell program specified with the option argument.
1392 .Opt_def - Q -- source
1393 Output the roff source code of the input files without further
1396 This is the equivalent
1397 .Opt_long_arg mode source .
1401 Other useful debugging options are the
1408 .Opt_long_arg mode groff .
1411 .\" --------------------------------------------------------------------
1412 .SH "Options related to groff"
1413 .\" --------------------------------------------------------------------
1415 All short options of
1417 are compatible with the short options of
1418 .BR groff (@MAN1EXT@).
1422 options have either an additional special meaning within
1424 or make sense for normal usage.
1428 Because of the special outputting behavior of the
1435 was designed to be switched into
1439 viewing features are disabled there.
1443 options do not switch the mode, but allow to customize the formatting
1448 This generates an ascii approximation of output in text modes.
1450 That could be important when the text pager has problems with control
1461 This is useful in case it cannot be recognized automatically.
1464 .Opt_def - P opt_or_arg
1467 as an option or option argument to the actual
1472 .Opt_def - T -- device devname
1474 This option determines
1478 The most important devices are the text output devices for referring
1479 to the different character sets, such as
1485 Each of these arguments switches
1487 into a text mode using this device, to
1489 if the actual mode is not a text mode.
1493 arguments are mapped to the corresponding
1495 .Opt_long_arg mode \fIdevname\fR
1503 arguments are mapped to mode
1507 argument switches to
1515 mode and show only the
1517 calling pipe without formatting the input.
1519 This an advanced option from
1520 .BR groff (@MAN1EXT@) ,
1521 only useful for debugging.
1525 was made equivalent to
1526 .Opt_long_arg mode x ;
1527 this slightly enhances the facility of
1532 .Opt_def - Z -- intermediate-output -- ditroff
1535 mode and format the input with
1537 intermediate output without postprocessing; see
1538 .BR groff_out (@MAN1EXT@).
1539 This is equivalent to option
1543 which can be used as well.
1549 options are supported by
1551 but they are just transparently transferred to
1553 without any intervention.
1555 The options that are not explicitly handled by
1557 are transparently passed to
1560 Therefore these transparent options are not documented here, but in
1561 .BR groff (@MAN1EXT@).
1562 Due to the automatism in
1566 options should be needed, except for advanced usage.
1569 .\" --------------------------------------------------------------------
1570 .SS "X Window toolkit Options"
1571 .\" --------------------------------------------------------------------
1573 The following long options were adapted from the corresponding X
1577 will pass them to the actual viewer program if it is an X Window
1580 Otherwise these options are ignored.
1584 Unfortunately these options use the old style of a single minus for
1589 that was changed to the standard with using a double minus for long
1590 options, for example,
1604 and the documentation on the X toolkit options for more details on
1605 these options and their arguments.
1608 .Opt_def -- background color
1609 Set the background color of the viewer window.
1612 .Opt_def -- bd pixels
1613 Specifies the color of the border surrounding the viewer window.
1616 .Opt_def -- bg color
1617 This is equivalent to
1618 .Opt_long background .
1621 .Opt_def -- bw pixels
1622 Specifies the width in pixels of the border surrounding the viewer
1626 .Opt_def -- display X-display
1627 Set the X display on which the viewer program shall be started, see the
1629 documentation for the syntax of the argument.
1632 .Opt_def -- foreground color
1633 Set the foreground color of the viewer window.
1636 .Opt_def -- fg color
1637 This is equivalent to
1638 .Opt_short foreground .
1641 .Opt_def -- font font_name
1642 Set the font used by the viewer window.
1644 The argument is an X font name.
1647 .Opt_def -- ft font_name
1648 This is equivalent to
1652 .Opt_def -- geometry size_pos
1653 Set the geometry of the display window, that means its size and its
1658 for the syntax of the argument.
1661 .Opt_def -- resolution value
1662 Set X resolution in dpi (dots per inch) in some viewer programs.
1664 The only supported dpi values are
1669 Actually, the default resolution for
1676 Reverse foreground and background color of the viewer window.
1679 .Opt_def -- title "'some text'"
1680 Set the title for the viewer window.
1683 .Opt_def -- xrm "'resource'"
1687 .\" --------------------------------------------------------------------
1688 .SS "Options from man"
1689 .\" --------------------------------------------------------------------
1693 were synchronized with the long options of
1698 are recognized, but not all of these options are important to
1700 so most of them are just ignored.
1704 The following two options were added by
1706 for choosing whether the file name arguments are interpreted as names
1707 for local files or as a search pattern for man pages.
1709 The default is looking up for local files.
1713 Check the non-option command line arguments (filespecs) first on being
1714 man\~pages, then whether they represent an existing file.
1716 By default, a filespec is first tested whether it is an existing file.
1719 .Opt_def -- no-man -- local-file
1720 Do not check for man\~pages.
1722 .Opt_long local-file
1723 is the corresponding
1729 In the following, the
1731 options that have a special meaning for
1737 The full set of long and short options of the
1739 program can be passed via the environment variable
1749 In searching man\~pages, retrieve all suitable documents instead of
1753 .Opt_def - 7 -- ascii
1754 In text modes, display ASCII translation of special characters.
1763 .Opt_def -- extension suffix
1764 Restrict man\~page search to file names that have
1766 appended to their section element.
1768 For example, in the file name
1769 .I /usr/share/man/man3/terminfo.3ncurses.gz
1770 the man\~page extension is
1774 .Opt_def -- locale language
1776 Set the language for man pages.
1778 This has the same effect, but overwrites
1782 .Opt_def -- location
1783 Print the location of the retrieved files to standard error.
1786 .Opt_def -- no-location
1787 Do not display the location of retrieved files; this resets a former
1789 .Opt_long location .
1795 .Opt_def -- manpath "'dir1:dir2:\*[Ellipsis]'"
1796 Use the specified search path for retrieving man\~pages instead of the
1799 If the argument is set to the empty string "" the search for man\~page
1804 Set the pager program in tty mode; default is
1806 This is equivalent to
1807 .Opt_long tty-viewer .
1810 .Opt_def -- sections "'sec1:sec2:\*[Ellipsis]'"
1811 Restrict searching for man\~pages to the given
1813 a colon-separated list.
1816 .Opt_def -- systems "'sys1,sys2,\*[Ellipsis]'"
1817 Search for man pages for the given operating systems; the argument
1819 is a comma-separated list.
1823 Instead of displaying the content, get the one-liner description from
1824 the retrieved man\~page files \[em] or say that it is not a man\~page.
1829 .Opt_long location .
1833 Additionally, the following short option of
1835 is supported as well.
1838 .\" --------------------------------------------------------------------
1839 .SS "Filespec Arguments"
1840 .\" --------------------------------------------------------------------
1844 parameter is an argument meaning an input source, such as a file name
1845 or template for searching man\~pages.
1847 These input sources are collected and composed into a single output
1852 parameters can have one of the following forms.
1858 parameters means that
1860 waits for standard input.
1864 stands for standard input, too, but can occur several times.
1868 is tested whether it is the path name of an existing file.
1870 Otherwise it is assumed as a searching pattern for a man\~page.
1874 On each system, the man pages are sorted according to their content
1875 into several sections.
1878 .I classical man sections
1879 have a single-character name, either are a digit from
1883 or one of the characters
1888 In the following, a stand-alone character
1894 The internal precedence of
1896 for searching man pages with the same name within several sections
1897 goes according to the classical single-character sequence.
1899 On some systems, this single character can be extended by a following
1904 man page facility is based on the classical single character sections.
1908 .BI man: name ( section )
1910 .IB name ( section )
1911 search the man\~page
1917 can be any string, but it must exist in the
1923 Next some patterns based on the
1924 .I classical man sections
1930 search for a man\~page
1937 .I classical man section
1940 Otherwise search for a man\~page named
1950 searches for a man\~page in the lowest man\~section that has a
1958 originates from a strange argument parsing of the
1965 .I classical man section
1966 interpret it as a search for a man\~page called
1972 as a file argument and
1980 We are left with the argument
1982 which is not an existing file.
1984 So this searches for the man\~page called
1986 in the lowest man\~section that has a document for this name.
1990 Several file name arguments can be supplied.
1994 into a single document.
1996 Note that the set of option arguments must fit to all of these file
1999 So they should have at least the same style of the
2004 .\" --------------------------------------------------------------------
2006 .\" --------------------------------------------------------------------
2010 program collects all input into a single file, formats it with the
2012 program for a certain device, and then chooses a suitable viewer
2015 The device and viewer process in
2020 The mode and viewer of a running
2022 program is selected automatically, but the user can also choose it
2026 The modes are selected by option the arguments of
2027 .Opt_long_arg mode \fIanymode .
2028 Additionally, each of this argument can be specified as an option of
2030 .Opt_long \fIanymode .
2031 Most of these modes have a viewer program, which can be chosen by an
2032 option that is constructed like
2033 .Opt_long \fIanymode\fR-viewer .
2037 Several different modes are offered, graphical X modes, text modes,
2040 modes for debugging and development.
2048 mode is possible, then
2054 This mode testing sequence for
2056 mode can be changed by specifying a comma separated list of modes
2058 .Opt_long default\-modes.
2062 The searching for man\~pages and the decompression of the input are
2063 active in every mode.
2066 .\" --------------------------------------------------------------------
2067 .SS "Graphical Display Modes"
2068 .\" --------------------------------------------------------------------
2070 The graphical display modes work only in the X Window environment (or
2071 similar implementations within other windowing environments).
2073 The environment variable
2077 are used for specifying the X display to be used.
2079 If neither is given,
2081 assumes that no X and changes to one text mode.
2083 You can change this automatic behavior by the option
2084 .Opt_long default\-modes .
2088 Known viewers for the graphical display modes and their standard X
2089 Window viewer progams are
2092 X Window roff viewers such as
2093 .BR gxditview (@MAN1EXT@)
2102 in a Postscript viewer
2107 in a dvi viewer program
2128 mode has a major advantage \[em] it is the only graphical diplay mode
2129 that 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 X Window
2142 options use a leading double minus instead of the single minus used by
2143 the X Window Toolkit.
2146 .\" --------------------------------------------------------------------
2148 .\" --------------------------------------------------------------------
2150 There are to modes for text output, mode
2152 for plain output without a pager and mode
2154 for a text output on a text terminal using some pager program.
2160 is not set or empty, groffer assumes that it should use
2166 In the actual implementation, the groff output device
2168 is chosen for text modes.
2170 This can be changed by specifying option
2177 The pager to be used can be specified by one of the options
2180 .Opt_long tty-viewer ,
2181 or by the environment variable
2183 If all of this is not used the
2185 program with the option
2187 for correctly displaying control sequences is used as the default
2191 .\" --------------------------------------------------------------------
2192 .SS "Special Modes for Debugging and Development"
2193 .\" --------------------------------------------------------------------
2197 file determination and decompression.
2199 This is combined into a single input file that is fed directly into
2201 with different strategy without the
2205 These modes are regarded as advanced, they are useful for debugging
2206 and development purposes.
2212 mode with just displays the generated input.
2216 mode passes the input to
2218 using only some suitable options provided to
2221 This enables the user to save the generated output into a file or pipe
2222 it into another program.
2230 disables post-processing, thus producing the
2231 .I groff intermediate
2234 In this mode, the input is formatted, but not postprocessed; see
2235 .BR groff_out (@MAN5EXT@)
2242 short options are supported by
2246 .\" --------------------------------------------------------------------
2247 .SH "MAN\~PAGE\~SEARCHING"
2248 .\" --------------------------------------------------------------------
2250 The default behavior of groffer is to first test whether a file
2251 parameter represents a local file; if it is not an existing file name,
2252 it is assumed to represent a name of a man\~page.
2254 This behavior can be modified by the following options.
2259 forces to interpret all file parameters as filespecs for searching
2265 .Opt_long local\-file
2266 disable the man searching; so only local files are displayed.
2270 If neither a local file nor a man\~page was retrieved for some file
2271 parameter a warning is issued on standard error, but processing is
2276 The groffer program provides a search facility for man\~pages.
2278 All long options, all environment variables, and most of the
2279 functionality of the GNU
2281 program were implemented.
2283 This inludes the extended file names of man\~pages, for example,
2286 in man\~section 7 may be stored under
2287 .File_name /usr/share/man/man7/groff.7.gz ,
2289 .File_name /usr/share/man/
2290 is part of the man\~path, the subdirectory
2292 and the file extension
2294 refer to the man\~section 7;
2296 shows the compression of the file.
2302 (preformatted man\~pages) are intentionally excluded from the search
2303 because groffer is a roff program that wants to format by its own.
2305 With the excellent performance of the actual computers, the
2306 preformatted man\~pages aren't necessary any longer.
2310 The algorithm for retrieving man\~pages uses five search methods.
2312 They are successively tried until a method works.
2316 The search path can be manually specified by using the option
2318 An empty argument disables the man\~page searching.
2320 This overwrites the other methods.
2324 If this is not available the environment variable
2330 If this is empty, the program tries to read it from the environment
2336 If this does not work a reasonable default path from
2338 is searched for man\~pages.
2342 If this does not work, the
2344 program for determining a path of man directories is tried.
2348 After this, the path elements for the language (locale) and operating
2349 system specific man\~pages are added to the man\~path; their sequence
2350 is determined automatically.
2353 .I /usr/share/man/linux/fr
2355 .I /usr/share/man/fr/linux
2356 for french linux man\~pages are found.
2358 The language and operating system names are determined from both
2359 environment variables and command line options.
2363 The locale (language) is determined like in GNU man, that is from
2364 highest to lowest precedence:
2369 .Env_var $GROFFER_OPT
2378 .Env_var $LC_MESSAGES
2385 The language locale is usually specified in the POSIX 1003.1 based
2388 \f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\f[]\
2389 \f[I]<character-set>\f[][\f[CB],\f[]\f[I]<version>\f[]]]],
2391 but the two-letter code in
2393 is sufficient for most purposes.
2397 If no man\~pages for a complicated locale are found the country part
2398 consisting of the first two characters (without the `\f[CB]_\f[]',
2399 `\f[CB].\f[]', and `\f[CB],\f[]', parts) of the locale is searched as
2404 If still not found the corresponding man\~page in the default language
2407 As usual, this default can be specified by one of \f[CR]C\f[] or
2410 The man\~pages in the default language are usually in English.
2414 Several operating systems can be given by appending their names,
2415 separated by a comma.
2417 This is then specified by the environment variable
2419 or by the command line option
2421 The precedence is similar to the locale case above from highest to
2428 .Env_var $GROFFER_OPT
2438 When searching for man\~pages this man\~path with the additional
2439 language and system specific directories is used.
2443 The search can further be restricted by limiting it to certain
2446 A single section can be specified within each filespec argument,
2447 several sections as a colon-separated list in command line option
2449 or environment variable
2452 When no section was specified a set of standard sections is searched
2453 until a suitable man\~page was found.
2457 Finally, the search can be restricted to a so-called
2459 This is a postfix that acts like a subsection.
2461 It can be specified by
2463 or environment variable
2464 .Env_var $EXTENSION .
2468 For further details on man\~page searching, see
2472 .\" --------------------------------------------------------------------
2474 .\" --------------------------------------------------------------------
2476 The program has a decompression facility.
2478 If standard input or a file that was retrieved from the command line
2479 parameters is compressed with a format that is supported by either
2483 it is decompressed on-the-fly.
2485 This includes the GNU
2492 The program displays the concatenation of all decompressed input in
2493 the sequence that was specified on the command line.
2496 .\" --------------------------------------------------------------------
2498 .\" --------------------------------------------------------------------
2500 The groffer programs supports many system variables, most of them by
2501 courtesy of other programs.
2503 All environment variables of
2504 .BR groff (@MAN1EXT@)
2507 and some standard system variables are honored.
2510 .\" --------------------------------------------------------------------
2511 .SS "Native groffer Variables"
2512 .\" --------------------------------------------------------------------
2515 .Env_var $GROFFER_OPT
2516 Store options for a run of groffer.
2518 The options specified in this variable are overridden by the options
2519 given on the command line.
2521 The content of this variable is run through the shell builtin `eval';
2522 so arguments containing white-space or special shell characters should
2526 .\" --------------------------------------------------------------------
2527 .SS "System Variables"
2528 .\" --------------------------------------------------------------------
2530 The groffer program is a shell script that is run through
2532 which can be internally linked to programs like
2534 The corresponding system environment is automatically effective.
2536 The following variables have a special meaning for groffer.
2541 If this variable is set this indicates that the X Window system is
2544 Testing this variable decides on whether graphical or text output is
2547 This variable should not be changed by the user carelessly, but it can
2548 be used to start the graphical groffer on a remote X terminal.
2550 For example, depending on your system, groffer can be started on the
2551 second monitor by the command
2552 .Shell_cmd DISPLAY=:0.1\~groffer\~ what.ever &
2558 .Env_var $LC_MESSAGES
2561 If one of these variables is set (in the above sequence), its content
2562 is interpreted as the locale, the language to be used, especially when
2563 retrieving man\~pages.
2565 A locale name is typically of the form
2575 is an ISO 639 language code,
2577 is an ISO 3166 country code, and
2579 is a character set or encoding identifier like ISO-8859-1 or UTF-8;
2583 The locale values\~\c
2587 stand for the default, i.e. the man\~page directories without a
2590 This is the same behavior as when all 3\~variables are unset.
2595 This variable can be used to set the pager for the tty output.
2597 For example, to disable the use of a pager completely set this
2601 .Shell_cmd PAGER=cat\~groffer\~ anything
2606 All programs within the groffer shell script are called without a
2609 Thus this environment variable determines the set of programs used
2610 within the run of groffer.
2614 .Env_var $POSIXLY_CORRECT
2615 If set to a non-empty value this chooses the POSIX mode for option
2616 processing, that means that option processing will be finished as soon
2617 as a non-option argument is found.
2619 Usually, you do not want to set this environment variable.
2622 .\" --------------------------------------------------------------------
2623 .SS "Groff Variables"
2624 .\" --------------------------------------------------------------------
2626 The groffer program internally calls groff, so all environment
2627 variables documented in
2628 .BR groff (@MAN1EXT@)
2629 are internally used within groffer as well.
2631 The following variables have a direct meaning for the groffer program.
2634 .Env_var $GROFF_TMPDIR
2635 If the value of this variable is an existing, writable directory,
2636 groffer uses it for storing its temporary files, just as groff does.
2639 .\" --------------------------------------------------------------------
2641 .\" --------------------------------------------------------------------
2643 Parts of the functionality of the man\~program were implemented in
2644 groffer; support for all environment variables documented in
2646 was added to groffer, but the meaning was slightly modified due to the
2647 different approach in groffer; but the user interface is the same.
2649 The man environment variables can be overwritten by options provided
2652 which in turn is overwritten by the command line.
2657 Restrict the search for man\~pages to files having this extension.
2659 This is overridden by option
2660 .Opt_long extension ;
2661 see there for details.
2666 This variable contains options as a preset for
2668 As not all of these are relevant for groffer only the essential parts
2669 of its value are extracted.
2671 The options specified in this variable overwrite the values of the
2672 other environment variables taht are specific to man.
2674 All options specified in this variable are overridden by the options
2675 given on the command line.
2680 If set, this variable contains the directories in which the man\~page
2683 This is overridden by option
2689 If this is a colon separated list of section names, the search for
2690 man\~pages is restricted to those manual sections in that order.
2692 This is overridden by option
2693 .Opt_long sections .
2698 If this is set to a comma separated list of names these are interpreted
2699 as man\~page trees for different operating systems.
2701 This variable can be overwritten by option
2703 see there for details.
2707 The environment variable
2708 .Env_var $MANROFFSEQ
2709 is ignored by groffer because the necessary preprocessors are
2710 determined automatically.
2713 .\" --------------------------------------------------------------------
2714 .SH "CONFIGURATION FILES"
2715 .\" --------------------------------------------------------------------
2719 program can be preconfigured by two configuration files.
2721 This configuration can be overridden at each program start by command
2722 line options or by the environment variable
2723 .Env_var $GROFFER_OPT .
2727 .File_name /etc/groff/groffer.conf
2728 System-wide configuration file for groffer.
2732 .File_name $HOME/.groff/groffer.conf
2733 User-specific configuration file for groffer, where
2735 denotes the user's home directory.
2737 This script is called after the system-wide configuration file to
2738 enable overriding by the user.
2742 Their lines either start with a minus character or are shell commands.
2744 Arbitrary spaces are allowed at the beginning, they are just ignored.
2746 The lines with the beginning minus are appended to the existing value
2749 This easily allows to set general
2751 options that are used with any call of
2756 After the transformation of the minus lines the emerging shell scripts
2766 It makes sense to use these configuration files for the following
2770 Preset command line options by writing them into lines starting with a
2774 Preset environment variables recognized by groffer.
2777 Write a function for calling a viewer program for a special
2779 and feed this name into its corresponding
2780 .Opt_long \f[I]mode\f[]\-viewer
2783 Note that the name of such a function must coincide with some existing
2784 program in the system path
2786 in order to be recognized by groffer.
2790 As an example, consider the following configuration file in
2791 ~/.groff/groffer.conf, say.
2797 # groffer configuration file
2799 # groffer options that are used in each call of groffer
2801 --foreground=DarkBlue
2802 --x-viewer 'gxditview -geometry 850x800'
2804 # some shell commands
2805 if test "$DISPLAY" = ""; then
2806 DISPLAY='localhost:0.0'
2808 date >>~/mygroffer.log
2815 This configuration sets three
2817 options and runs two shell commands.
2819 This has the following effects:
2823 Lines starting with a
2834 in all viewers that support this.
2839 .BR gxditview (@MAN1EXT@)
2840 as the X-mode viewer using the geometry option for setting the width
2853 which allows to start
2855 in the standard X display, even when the program is called from a text
2860 Just for fun, the date of each
2862 start is written to the file
2864 in the home directory.
2867 .\" --------------------------------------------------------------------
2869 .\" --------------------------------------------------------------------
2871 The usage of groffer is very easy.
2873 Usually, it is just called with a file name or man\~page.
2875 The following examples, however, show that groffer has much more fancy
2880 .Shell_cmd "groffer\~/usr/local/share/doc/groff/meintro.ms.gz"
2881 Decompress, format and display the compressed file
2884 .IR /usr/local/share/doc/groff ,
2887 as graphical viewer when in X Window, or the
2889 pager program when not in X.
2893 .Shell_cmd "groffer\~groff"
2896 exists use it as input.
2898 Otherwise interpret the argument as a search for the man\~page named
2900 in the smallest possible man\~section, being secion 1 in this case.
2904 .Shell_cmd "groffer\~man:groff"
2905 search for the man\~page of
2913 .Shell_cmd "groffer\~groff.7"
2915 .Shell_cmd "groffer\~7\~groff"
2916 search the man\~page of
2920 This section search works only for a digit or a single character from
2925 .Shell_cmd "groffer\~fb.modes"
2928 does not exist interpret this as a search for the man\~page of
2932 is not a single character in classical section style the argument is
2933 not split to a search for
2938 .Shell_cmd "groffer\~groff\~\[cq]troff(1)\[cq]\~man:roff"
2940 The arguments that are not existing files are looked-up as the
2941 following man\~pages:
2943 (automatic search, should be found in man\~section\~1),
2948 (in the section with the lowest number, being\~7 in this case).
2951 .I \[cq]troff(1)\[cq]
2952 are necessary because the paranthesis are special shell characters;
2953 escaping them with a backslash character
2957 would be possible, too.
2959 The formatted files are concatenated and displayed in one piece.
2963 .Shell_cmd "LANG=de\~groffer\~--man\~--www\~--www-viever=mozilla\~ls"
2965 Retrieve the German man\~page (language
2969 program, decompress it, format it to
2973 mode) and view the result in the web browser
2977 guarantees that the man\~page is retrieved, even when a local file
2979 exists in the actual directory.
2983 .Shell_cmd "groffer\~--source\~'man:roff(7)'"
2985 Get the man\~page called
2987 in man\~section 7, decompress it, and print its unformatted content,
2992 .Shell_cmd "cat\~file.gz\~|\~groffer\~-Z\~-mfoo"
2994 Decompress the standard input, send this to
2996 intermediate mode without post-processing (groff option
2998 using macro package by
3005 .Shell_cmd "echo\~'\[rs]f[CB]WOW!'\~|"
3007 .Shell_cmd+ "groffer --x --bg red --fg yellow --geometry 200x100 -"
3009 Display the word \f[CB]WOW!\f[] in a small window in constant-width
3010 bold font, using color yellow on red background.
3013 .\" --------------------------------------------------------------------
3015 .\" --------------------------------------------------------------------
3019 shell script is compatible with both GNU and POSIX.
3021 POSIX compatibility refers to
3022 .B IEEE P1003.2/D11.2
3023 of September 1991, a very early version of the POSIX standard that is
3024 still freely available in the internet.
3026 Unfortunately, this version of the standard has `local' for shell
3027 function variables removed.
3029 As `local' is needed for serious programming this temporary POSIX
3030 deprecation was ignored.
3034 Most GNU shells are compatible with this interpretation of POSIX, but
3035 provide much more facilities.
3037 Nevertheless this script uses only a restricted set of shell language
3038 elements and shell builtins, such that it can be run on `ash', a GNU
3039 shell that is quite fast, but has a slightly limited shell language.
3041 The groffer script should work on most actual free and commercial
3046 The groffer program provides its own parser for command line options;
3047 it can handle option arguments and file names containing white space
3048 and a large set of special characters.
3052 The groffer shell script was tested with the following common
3053 implementations of the GNU shells:
3060 Free POSIX compatible shells and shell utilities for most operating
3061 systems are available at the
3062 .URL http://\:www.gnu.org/software/ "GNU software archive" .
3066 The best performance was obtained with the
3076 is not available the shell under which the script was started in the
3077 first place is used instead.
3079 This can be modified by the option
3084 The groffer program provides its own parser for command line arguments
3085 that is compatible to both POSIX
3089 except for shortcuts of long options.
3091 The following standard types of options are supported.
3095 A single minus always refers to single character option or a
3096 combination thereof, for example, the
3098 short option combination
3101 .Opt_short Q\~\-m\~foo .
3105 Long options are options with names longer than one character; they
3106 are always prededed by a double minus.
3108 An option argument can either go to the next command line argument or
3109 be appended with an equal sign to the argument; for example,
3110 .Opt_alt -- long=arg
3112 .Opt_alt -- long\~arg .
3118 ends option parsing; all further command line arguments are
3119 interpreted as file name arguments.
3123 By default, all command line arguments that are neither options nor
3124 option arguments are interpreted as filespec parameters and stored
3125 until option parsing has finished.
3127 For example, the command line
3128 .Shell_cmd "groffer file1 -a -o arg file2"
3129 is, by default, equivalent to
3130 .Shell_cmd "groffer -a -o arg -- file1 file2"
3134 This behavior can be changed by setting the environment variable
3135 .Env_var $POSIXLY_CORRECT
3136 to a non-empty value.
3138 Then the strange POSIX non-option behavior is adopted, i. e. option
3139 processing is stopped as soon as the first non-option argument is
3140 found and each following argument is taken as a file name.
3142 For example, in posixly correct mode, the command line
3143 .Shell_cmd "groffer file1 -a -o arg file 2"
3145 .Shell_cmd "groffer -- file1 -a -o arg file 2"
3146 As this leads to unwanted behavior in most cases, most people do not
3148 .Env_var $POSIXLY_CORRECT .
3151 .\" --------------------------------------------------------------------
3153 .\" --------------------------------------------------------------------
3156 .BR groff (@MAN1EXT@)
3158 .BR troff (@MAN1EXT@)
3159 Details on the options and environment variables available in
3161 all of them can be used with groffer.
3166 The standard program to diplay man\~pages.
3168 The information there is only useful if it is the man\~page for
3170 Then it documents the options and environment variables that are
3171 supported by groffer.
3175 .BR gxditview (@MAN1EXT@)
3178 Viewers for groffer's
3187 Viewers for groffer's
3214 Viewers for groffer's
3221 Standard pager program for the
3230 The decompression programs supported by groffer.
3234 .BR groff (@MAN7EXT@)
3235 Documentation of the
3241 .BR grog (@MAN1EXT@)
3242 Internally, groffer tries to guess the groff command line options from
3243 the input using this program.
3247 .BR groff_out (@MAN5EXT@)
3248 Documentation on the groff intermediate output (ditroff output).
3251 .\" --------------------------------------------------------------------
3253 .\" --------------------------------------------------------------------
3255 Copyright (C) 2001,2002,2004 Free Software Foundation, Inc.
3258 This document is distributed under the terms of the FDL (GNU Free
3259 Documentation License) version 1.1 or later.
3261 You should have received a copy of the FDL on your system, it is also
3262 available on-line at the
3263 .URL http://\:www.gnu.org/\:copyleft/\:fdl.html "GNU copyleft site" .
3266 This document is part of
3268 the GNU roff distribution.
3270 It was written by Bernd Warken.
3273 \" --------------------------------------------------------------------
3275 .\" --------------------------------------------------------------------
3277 .\" Local Variables: