/[groff]/groff/contrib/groffer/groffer.man
ViewVC logotype

Diff of /groff/contrib/groffer/groffer.man

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.27 by wl, Wed Aug 3 06:32:11 2005 UTC revision 1.28 by wl, Tue Aug 23 09:57:09 2005 UTC
# Line 15  groffer.1 - man page for groffer (sectio Line 15  groffer.1 - man page for groffer (sectio
15  Source file position:  <groff_source_top>/contrib/groffer/groffer.man  Source file position:  <groff_source_top>/contrib/groffer/groffer.man
16  Installed position:    $prefix/share/man/man1/groffer.1  Installed position:    $prefix/share/man/man1/groffer.1
17    
18  Last update : 2 August 2005  Last update: 22 August 2005
19    
20  Source file position: <groff-source>/contrib/groffer/groffer.man  Source file position: <groff-source>/contrib/groffer/groffer.man
21  ..  ..
22  .de author  .de author
23  This file was written by \m[blue]Bernd Warken\m[].  This file was written by
24    .MTO "" "Bernd Warken" .
25  ..  ..
26  .de copyleft  .de copyleft
27  Copyright (C) 2001,2002,2004,2005 Free Software Foundation, Inc.  Copyright (C) 2001,2002,2004,2005 Free Software Foundation, Inc.
# Line 43  as published by the Line 44  as published by the
44  either version 2, or (at your option) any later version.  either version 2, or (at your option) any later version.
45  .  .
46  .P  .P
47  You should have received a copy of the GNU General Public License  You should have received a copy of the \f[CR]GNU General Public
48  along with  License\f[] along with
49  .IR groff ,  .IR groff ,
50  see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top  see the files \%\f[CB]COPYING\f[] and \%\f[CB]LICENSE\f[] in the top
51  directory of the  directory of the
# Line 199  You can also write to the Line 200  You can also write to the
200  .c --------------------------------------------------------------------  .c --------------------------------------------------------------------
201  .c .Opt_-  ([<punct>])  .c .Opt_-  ([<punct>])
202  .c  .c
203  .c Print `-' (minus sign); optional punctuation.  .c Print `-' (minus sign); optional punctuation.
204  .c  .c
205  .de Opt_-  .de Opt_-
206  .  ie (\\n[.$] == 0) \  .  ie (\\n[.$] == 0) \
# Line 210  You can also write to the Line 211  You can also write to the
211  .c --------------------------------------------------------------------  .c --------------------------------------------------------------------
212  .c .Opt_[-]  ([<punct>])  .c .Opt_[-]  ([<punct>])
213  .c  .c
214  .c Print `Opt_[-]' (minus sign in brackets); optional punctuation.  .c Print `Opt_[-]' (minus sign in brackets); optional punctuation.
215  .c  .c
216  .de Opt_[-]  .de Opt_[-]
217  .  ie (\\n[.$] == 0) \  .  ie (\\n[.$] == 0) \
# Line 221  You can also write to the Line 222  You can also write to the
222  .c --------------------------------------------------------------------  .c --------------------------------------------------------------------
223  .c .Opt_--  ([<punct>])  .c .Opt_--  ([<punct>])
224  .c  .c
225  .c Print `--' (double minus); optional punctuation.  .c Print `--' (double minus); optional punctuation.
226  .c  .c
227  .de Opt_--  .de Opt_--
228  .  ie (\\n[.$] == 0) \  .  ie (\\n[.$] == 0) \
# Line 232  You can also write to the Line 233  You can also write to the
233  .c --------------------------------------------------------------------  .c --------------------------------------------------------------------
234  .c .Opt_[--]  ([<punct>])  .c .Opt_[--]  ([<punct>])
235  .c  .c
236  .c Print `Opt_[--]' (double minus in brackets); optional punctuation.  .c Print `Opt_[--]' (double minus in brackets); optional punctuation.
237  .c  .c
238  .de Opt_[--]  .de Opt_[--]
239  .  ie (\\n[.$] == 0) \  .  ie (\\n[.$] == 0) \
# Line 666  You can also write to the Line 667  You can also write to the
667  .Synopsis groffer  .Synopsis groffer
668  .RI [ option... ]  .RI [ option... ]
669  .Opt_[--]  .Opt_[--]
670  .RI [ "filespec" "\*[Ellipsis]]"  .RI [ "\%filespec" "\*[Ellipsis]]"
 ./Synopsis  
 .  
 .Synopsis groffer  
 .Opt_alt -- apropos -- apropos-data -- apropos-devel -- apropos-progs name  
671  ./Synopsis  ./Synopsis
672  .  .
673  .Synopsis groffer  .Synopsis groffer
# Line 691  The Line 688  The
688  program is the easiest way to use  program is the easiest way to use
689  .BR \%groff (@MAN1EXT@).  .BR \%groff (@MAN1EXT@).
690  It can display arbitrary documents written in the  It can display arbitrary documents written in the
691  .BR \%groff (@MAN7EXT@)  .I \%groff
692  language or other  language, see
693  .BR \%roff (@MAN7EXT@)  .BR \%groff (@MAN7EXT@),
694  languages that are compatible to the original  or other
695    .I \%roff
696    languages, see
697    .BR \%roff (@MAN7EXT@),
698    that are compatible to the original
699  .I \%troff  .I \%troff
700  language.  language.
701  .  .
702  The  The
703  .B \%groffer  .B \%groffer
704  program also includes many of the features for finding and displaying  program also includes many of the features for finding and displaying
705  the \%UNIX manual pages  the \%\f[CR]Unix\f[] manual pages
706  .nh  .nh
707  .RI ( man\~pages ),  .RI ( man\~pages ),
708  .hy  .hy
# Line 729  environment variable Line 730  environment variable
730  .BR \%$GROFFER_OPT ,  .BR \%$GROFFER_OPT ,
731  or on the command line.  or on the command line.
732  .  .
 For example, it makes sense to specify a faster shell in a  
 configuration file.  
 .  
733  .  .
734  .P  .P
735  The output can be generated and viewed in several different ways  The output can be generated and viewed in several different ways
# Line 740  available for Line 738  available for
738  .  .
739  This includes the  This includes the
740  .I \%groff  .I \%groff
741  native X\~\%viewer  native \%\f[CR]X\~Window\f[] viewer
742  .BR \%gxditview (@MAN1EXT@),  .BR \%gxditview (@MAN1EXT@),
743  each Postcript or  each
744    .IR \%Postcript ,
745    .IR \%pdf ,
746    or
747  .I \%dvi  .I \%dvi
748  display program, a web browser by generating  display program, a web browser by generating
749  .I \%html  .I \%html
# Line 773  They are transformed into a single docum Line 774  They are transformed into a single docum
774  .  .
775  .  .
776  .P  .P
777  Option handling is done in GNU style.  Option handling is done in \f[CR]GNU\f[] style.
778  .  .
779  Options and file names can be mixed freely.  Options and file names can be mixed freely.
780  .  .
# Line 793  Long options can be abbreviated. Line 794  Long options can be abbreviated.
794  .I breaking options  .I breaking options
795  .RS  .RS
796  .P  .P
 .Opt_[alt] -- apropos name  
 .Opt_[alt] -- apropos\-data name  
 .Opt_[alt] -- apropos\-devel name  
 .Opt_[alt] -- apropos\-progs name  
797  .Opt_[alt] - h -- help  .Opt_[alt] - h -- help
798  .Opt_[alt] - v -- version  .Opt_[alt] - v -- version
799  .RE  .RE
# Line 811  Long options can be abbreviated. Line 808  Long options can be abbreviated.
808  .Opt_[alt] -- default\-modes mode1,mode2,\*[Ellipsis]  .Opt_[alt] -- default\-modes mode1,mode2,\*[Ellipsis]
809  .Opt_[alt] -- dvi  .Opt_[alt] -- dvi
810  .Opt_[alt] -- dvi\-viewer prog  .Opt_[alt] -- dvi\-viewer prog
811    .Opt_[alt] -- dvi\-viewer\-tty prog
812  .Opt_[alt] -- groff  .Opt_[alt] -- groff
813  .Opt_[alt] -- html  .Opt_[alt] -- html
814  .Opt_[alt] -- html\-viewer prog  .Opt_[alt] -- html\-viewer prog
815  .Opt_[alt] -- man  .Opt_[alt] -- html\-viewer\-tty prog
816  .Opt_[alt] -- mode display_mode  .Opt_[alt] -- mode display_mode
 .Opt_[alt] -- no-man  
817  .Opt_[alt] -- pdf  .Opt_[alt] -- pdf
818  .Opt_[alt] -- pdf\-viewer prog  .Opt_[alt] -- pdf\-viewer prog
819    .Opt_[alt] -- pdf\-viewer\-tty prog
820  .Opt_[alt] -- ps  .Opt_[alt] -- ps
821  .Opt_[alt] -- ps\-viewer prog  .Opt_[alt] -- ps\-viewer prog
822    .Opt_[alt] -- ps\-viewer\-tty prog
823  .Opt_[alt] -- text  .Opt_[alt] -- text
824  .Opt_[alt] -- tty  .Opt_[alt] -- tty
825  .Opt_[alt] -- tty\-viewer prog  .Opt_[alt] -- tty\-viewer prog
826    .Opt_[alt] -- tty\-viewer\-tty prog
827  .Opt_[alt] -- www  .Opt_[alt] -- www
828  .Opt_[alt] -- www\-viewer prog  .Opt_[alt] -- www\-viewer prog
829    .Opt_[alt] -- www\-viewer\- prog
830  .Opt_[alt] -- x -- X  .Opt_[alt] -- x -- X
831  .Opt_[alt] -- x\-viewer -- X\-viewer prog  .Opt_[alt] -- x\-viewer -- X\-viewer prog
832    .Opt_[alt] -- x\-viewer\-tty -- X\-viewer\-tty prog
833  .RE  .RE
834  .  .
835  .  .
# Line 857  short options are accepted. Line 859  short options are accepted.
859  .  .
860  .  .
861  .TP  .TP
862  .I X\~\%Window\~\%Toolkit options  .I options for man\~pages
863  .RS  .Opt_[alt] -- apropos
864  .P  .Opt_[alt] -- apropos\-data
865  .Opt_[alt] -- bd pixels  .Opt_[alt] -- apropos\-devel
866  .Opt_[alt] -- bg -- background color  .Opt_[alt] -- apropos\-progs
867  .Opt_[alt] -- bw pixels  .Opt_[alt] -- whatis
868  .Opt_[alt] -- display X-display  .Opt_[alt] -- man
869  .Opt_[alt] -- fg -- foreground color  .Opt_[alt] -- no-man
870  .Opt_[alt] -- ft -- font font_name  .Opt_[alt] -- no-special
 .Opt_[alt] -- geometry size_pos  
 .Opt_[alt] -- resolution value  
 .Opt_[alt] -- rv  
 .Opt_[alt] -- title string  
 .Opt_[alt] -- xrm X-resource  
 .RE  
871  .  .
872  .  .
873  .TP  .TP
874  .I options from GNU man  .I long options taken over from GNU man
875  .RS  .RS
876  .P  .P
877  .Opt_[alt] -- all  .Opt_[alt] -- all
# Line 889  short options are accepted. Line 885  short options are accepted.
885  .Opt_[alt] -- sections sec1:sec2:\*[Ellipsis]  .Opt_[alt] -- sections sec1:sec2:\*[Ellipsis]
886  .Opt_[alt] -- systems sys1,sys2,\*[Ellipsis]  .Opt_[alt] -- systems sys1,sys2,\*[Ellipsis]
887  .Opt_[alt] -- troff-device device  .Opt_[alt] -- troff-device device
 .Opt_[alt] -- whatis  
888  .P  .P
889  Further long options of GNU  Further long options of \f[CR]GNU\f[]
890  .B man  .B man
891  are accepted as well.  are accepted as well.
892  .RE  .RE
893  .  .
894  .  .
895  .TP  .TP
896  .I filespec argument  .I X Window Toolkit options
897    .RS
898    .P
899    .Opt_[alt] -- bd pixels
900    .Opt_[alt] -- bg -- background color
901    .Opt_[alt] -- bw pixels
902    .Opt_[alt] -- display X-display
903    .Opt_[alt] -- fg -- foreground color
904    .Opt_[alt] -- ft -- font font_name
905    .Opt_[alt] -- geometry size_pos
906    .Opt_[alt] -- resolution value
907    .Opt_[alt] -- rv
908    .Opt_[alt] -- title string
909    .Opt_[alt] -- xrm X-resource
910    .RE
911    .
912    .
913    .TP
914    .I \%filespec arguments
915  .RS  .RS
916  .P  .P
917  No  No
918  .I filespec  .I \%filespec
919  parameters means standard input.  parameters means standard input.
920  .  .
921  .  .
# Line 960  in \%man\~section Line 973  in \%man\~section
973  .  .
974  .TP  .TP
975  .I name  .I name
976  if  if
977  .I \%name  .I \%name
978  is not an existing file search for the man\~page  is not an existing file search for the man\~page
979  .I \%name  .I \%name
# Line 1006  is terminated thereafter. Line 1019  is terminated thereafter.
1019  All other arguments are ignored.  All other arguments are ignored.
1020  .  .
1021  .  .
 .Opt_def -- apropos name  
 Start the  
 .BR \%apropos (1)  
 command for searching within  
 .I \%man\~page  
 descriptions.  
 .  
 That slightly differs from the strange behavior of the  
 .Opt_long apropos  
 program of  
 .BR \%man (1),  
 which has no argument of its own, but takes the file arguments  
 instead.  
 .  
 Practically both concepts are compatible.  
 .  
 .  
 .Opt_def -- apropos\-data name  
 Show only the  
 .BR \%apropos (1)  
 descriptions for data documents, in the  
 .BR \%man (7)  
 sections 4, 5, and 7.  
 .  
 .  
 .Opt_def -- apropos\-devel name  
 Show only the  
 .BR apropos (1)  
 descriptions for development documents, in the  
 .BR man (7)  
 sections 2, 3, and 9.  
 .  
 .  
 .Opt_def -- apropos\-progs name  
 Show only the  
 .BR \%apropos (1)  
 descriptions for documents on programs, in the  
 .BR \%man (7)  
 sections 1, 6, and 8.  
 .  
 .  
1022  .Opt_def - h -- help  .Opt_def - h -- help
1023  Print a helping information with a short explanation of option sto  Print a helping information with a short explanation of option sto
1024  standard output.  standard output.
# Line 1067  If none of these mode and viewer options Line 1039  If none of these mode and viewer options
1039  .B \%groffer  .B \%groffer
1040  tries to find a suitable display mode automatically.  tries to find a suitable display mode automatically.
1041  .  .
1042    The default modes are
1043    .I mode x
1044    with
1045    .B gxditview
1046    in \%\f[CR]X\~Window\f[] and
1047    .I mode tty
1048    with device
1049    .I latin1
1050    under
1051    .B less
1052    on a terminal.
1053    .
1054    .
1055    .P
1056    There are two kinds of options for viewers.
1057    .Opt_long \fImode\fP-viewer
1058    chooses the normal viewer programs that run on their own in
1059    \%\f[CR]X\~Window\f[], while
1060    .Opt_long \fImode\fP-viewer-tty
1061    chooses programs that run on the terminal (on tty).
1062    .
1063    Most graphical viewers are programs running in \%\f[CR]X\~Window\f[],
1064    so there aren't many opportunities to call the tty viewers.
1065    .
1066    But they give the chance to view the output source; for example,
1067    .Opt_long ps\-viewer\-tty=less
1068    shows the content of the
1069    .I Postscript
1070    output with the pager
1071    .BR less .
1072    .
1073    .
1074    .P
1075    The \%\f[CR]X\~Window\f[] viewers are not critical, you can use both
1076    .Opt_long *\-viewer
1077    and
1078    .Opt_long *\-viewer\-tty
1079    for them; with
1080    .Opt_long *\-viewer\-tty
1081    the viewer program will not become independently, it just stays
1082    coupled with
1083    .BR groffer .
1084    But the program will not run if you specify a terminal program with
1085    .Opt_long *\-viewer
1086    because this viewer will stay in background without a chance to reach
1087    it.
1088    .
1089    So you really need
1090    .Opt_long *\-viewer\-tty
1091    for viewers that run on tty.
1092    .
1093  .  .
1094  .Opt_def -- auto  .Opt_def -- auto
1095  Equivalent to  Equivalent to
# Line 1105  Equivalent to Line 1128  Equivalent to
1128  .  .
1129  .  .
1130  .Opt_def -- dvi\-viewer prog  .Opt_def -- dvi\-viewer prog
1131  Set the viewer program for  Choose an \%\f[CR]X\~Window\f[] viewer program for
1132  .IR \%dvi\~mode .  .IR \%dvi\~mode .
1133  .  .
1134  This can be a file name or a program to be searched in  This can be a file name or a program to be searched in
1135  .Env_var $PATH .  .Env_var $PATH .
1136  .  .
1137  Known  Known \%\f[CR]X\~Window\f[]
1138  .I \%dvi  .I \%dvi
1139  viewers inlude  viewers include
1140  .BR \%xdvi (1)  .BR \%xdvi (1)
1141  and  and
1142  .BR \%dvilx (1)  .BR \%dvilx (1)
# Line 1121  and Line 1144  and
1144  In each case, arguments can be provided additionally.  In each case, arguments can be provided additionally.
1145  .  .
1146  .  .
1147    .Opt_def -- dvi\-viewer\-tty prog
1148    Choose a program running on the terminal for viewing the output of
1149    .IR \%dvi\~mode .
1150    .
1151    This can be a file name or a program to be searched in
1152    .Env_var $PATH ;
1153    arguments can be provided additionally.
1154    .
1155    .
1156  .Opt_def -- groff  .Opt_def -- groff
1157  Equivalent to  Equivalent to
1158  .Opt_long_arg mode groff .  .Opt_long_arg mode groff .
# Line 1132  Equivalent to Line 1164  Equivalent to
1164  .  .
1165  .  .
1166  .Opt_def -- html\-viewer  .Opt_def -- html\-viewer
1167  Set the web browser program for viewing in  Choose an \%\f[CR]X\~Window\f[] web browser program for viewing in
1168  .I \%html\~mode .  .I \%html\~mode .
1169  .  .
1170  Each program that accepts html input and allows the  It can be the path name of an executable file or a program in
 .BI \%file://localhost/ dir / file  
 syntax on the command line is suitable as viewer program; it can be  
 the path name of an executable file or a program in  
1171  .Env_var $PATH .  .Env_var $PATH .
1172  .  .
1173  In each case, arguments can be provided additionally.  In each case, arguments can be provided additionally.
1174  .  .
1175  .  .
1176    .Opt_def -- html\-viewer\-tty
1177    Choose a terminal program for viewing the output of
1178    .I \%html\~mode .
1179    .
1180    It can be the path name of an executable file or a program in
1181    .Env_var $PATH ;
1182    arguments can be provided additionally.
1183    .
1184    .
1185  .Opt_def -- mode value  .Opt_def -- mode value
1186  .  .
1187  Set the display mode.  Set the display mode.
# Line 1257  by default, can be chosen with option Line 1295  by default, can be chosen with option
1295  Format in a  Format in a
1296  .I \%groff\~text\~mode  .I \%groff\~text\~mode
1297  and write the result to standard output using a text pager program,  and write the result to standard output using a text pager program,
1298  even when in X\~\%Window.  even when in \%\f[CR]X\~Window\f[].
1299  .  .
1300  .  .
1301  .TP  .TP
# Line 1276  By default, the formatted input is displ Line 1314  By default, the formatted input is displ
1314  .BR \%gxditview (@MAN1EXT@)  .BR \%gxditview (@MAN1EXT@)
1315  program being distributed together with  program being distributed together with
1316  .BR \%groff .  .BR \%groff .
1317  But the standard X\~tool  But the standard \%\f[CR]X\~Window\f[] tool
1318  .BR \%xditview (1)  .BR \%xditview (1)
1319  can also be chosen with the option  can also be chosen with the option
1320  .Opt_long x\-viewer .  .Opt_long x\-viewer .
# Line 1352  Equivalent to Line 1390  Equivalent to
1390  .  .
1391  .  .
1392  .Opt_def -- pdf\-viewer prog  .Opt_def -- pdf\-viewer prog
1393  Set the viewer program for  Choose an \%\f[CR]X\~Window\f[] viewer program for
1394  .IR \%pdf\~mode .  .IR \%pdf\~mode .
1395  .  .
1396  This can be a file name or a program to be searched in  This can be a file name or a program to be searched in
1397  .Env_var $PATH .  .Env_var $PATH ;
1398    arguments can be provided additionally.
1399  .  .
1400  In each case, arguments can be provided additionally.  .
1401    .Opt_def -- pdf\-viewer\-tty prog
1402    Choose a terminal viewer program for
1403    .IR \%pdf\~mode .
1404    .
1405    This can be a file name or a program to be searched in
1406    .Env_var $PATH ;
1407    arguments can be provided additionally.
1408  .  .
1409  .  .
1410  .Opt_def -- ps  .Opt_def -- ps
# Line 1367  Equivalent to Line 1413  Equivalent to
1413  .  .
1414  .  .
1415  .Opt_def -- ps\-viewer prog  .Opt_def -- ps\-viewer prog
1416  Set the viewer program for  Choose an \%\f[CR]X\~Window\f[] viewer program for
1417  .IR \%ps\~mode .  .IR \%ps\~mode .
1418  .  .
1419  This can be a file name or a program to be searched in  This can be a file name or a program to be searched in
# Line 1382  and Line 1428  and
1428  In each case, arguments can be provided additionally.  In each case, arguments can be provided additionally.
1429  .  .
1430  .  .
1431    .Opt_def -- ps\-viewer\-tty prog
1432    Choose a terminal viewer program for
1433    .IR \%ps\~mode .
1434    .
1435    This can be a file name or a program to be searched in
1436    .Env_var $PATH ;
1437    arguments can be provided additionally.
1438    .
1439    .
1440  .Opt_def -- text  .Opt_def -- text
1441  Equivalent to  Equivalent to
1442  .Opt_long_arg mode text .  .Opt_long_arg mode text .
# Line 1401  This option is eqivalent to Line 1456  This option is eqivalent to
1456  .I man  .I man
1457  option  option
1458  .Opt_long_arg pager prog .  .Opt_long_arg pager prog .
1459    The option argument can be a file name or a program to be searched in
1460    .Env_var $PATH ;
1461    arguments can be provided additionally.
1462    .
1463    .
1464    .Opt_def -- tty\-viewer\-tty prog
1465    This is equivalent to
1466    .Opt_long tty\-viewer
1467    because the programs for
1468    .I tty
1469    mode run on a terminal anyway.
1470  .  .
1471  .  .
1472  .Opt_def -- www  .Opt_def -- www
# Line 1413  Equivalent to Line 1479  Equivalent to
1479  .Opt_long html\-viewer .  .Opt_long html\-viewer .
1480  .  .
1481  .  .
1482    .Opt_def -- www\-viewer\-tty prog
1483    Equivalent to
1484    .Opt_long html\-viewer\-tty .
1485    .
1486    .
1487  .Opt_def -- X -- x  .Opt_def -- X -- x
1488  Equivalent to  Equivalent to
1489  .Opt_long_arg mode x .  .Opt_long_arg mode x .
1490  .  .
1491  .  .
1492  .Opt_def -- X\-viewer -- x\-viewer prog  .Opt_def -- X\-viewer -- x\-viewer prog
1493  Set the viewer program for  Choose an \%\f[CR]X\~Window\f[] viewer program for
1494  .IR \%x\~mode .  .IR \%x\~mode .
 .  
1495  Suitable viewer programs are  Suitable viewer programs are
1496  .BR \%gxditview (@MAN1EXT@)  .BR \%gxditview (@MAN1EXT@)
1497  which is the default and  which is the default and
1498  .BR \%xditview (1).  .BR \%xditview (1).
1499    The argument can be any executable file or a program in
1500    .Env_var $PATH ;
1501    arguments can be provided additionally.
1502  .  .
 But the argument can be any executable file or a program in  
 .Env_var $PATH .  
1503  .  .
1504  In each case, arguments can be provided additionally.  .Opt_def -- X\-viewer\-tty -- x\-viewer\-tty prog
1505    Choose a terminal viewer program for
1506    .IR \%x\~mode .
1507    The argument can be any executable file or a program in
1508    .Env_var $PATH ;
1509    arguments can be provided additionally.
1510  .  .
1511  .  .
1512  .TP  .TP
# Line 1444  parameters. Line 1520  parameters.
1520  .P  .P
1521  Besides these,  Besides these,
1522  .B \%groffer  .B \%groffer
1523  accepts all arguments that are valid for the  accepts all short options that are valid for the
1524  .BR \%groff (@MAN1EXT@)  .BR \%groff (@MAN1EXT@)
1525  program.  program.
1526  .  .
# Line 1455  options are sent unmodified via Line 1531  options are sent unmodified via
1531  to  to
1532  .BR \%groff .  .BR \%groff .
1533  .  .
1534  Postprocessors, macro packages, compatibility with  So postprocessors, macro packages, compatibility with
1535  .I classical  .I classical
1536  .IR \%troff ,  .IR \%troff ,
1537  and much more can be manually specified.  and much more can be manually specified.
# Line 1466  and much more can be manually specified. Line 1542  and much more can be manually specified.
1542  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
1543  .  .
1544  .Opt_def -- debug  .Opt_def -- debug
1545  Enable three debugging informations.  Enable five debugging informations.
1546    .
1547    The temporary files are kept and not deleted, the name of the
1548    temporary directory and the shell name for
1549    .File_name groffer2.sh
1550    are printed, the parameters are printed at several steps of
1551    development, and a function stack is output with function
1552    \f[CR]error_user()\f[] as well.
1553    .
1554    Neither the function call stack that is printed at each opening and
1555    closing of a function call nor the landmark information that is
1556    printed to determine how far the program is running are used.
1557    .
1558    This seems to be the most useful among all debugging options.
1559    .
1560    .
1561    .Opt_def -- debug\-all
1562    Enable all seven debugging informations including the function call
1563    stack and the landmark information.
1564  .  .
1565  A function call stack is printed at each opening and closing of a  .
1566  function call; a landmark information is printed to determine how far  .Opt_def -- debug\-keep
1567  the program is running, and the early deletion of the temporary  Enable two debugging information, the printing of the name of the
1568  formatting files is prohibited.  temporary directory and the keeping of the temporary files.
1569    .
1570    .
1571    .Opt_def -- debug\-lm
1572    Enable one debugging information, the landmark information.
1573    .
1574    .
1575    .Opt_def -- debug\-params
1576    Enable one debugging information, the parameters at several steps.
1577    .
1578    .
1579    .Opt_def -- debug\-shell
1580    Enable one debugging information, the shell name for
1581    .File_name groffer2.sh .
1582    .
1583    .
1584    .Opt_def -- debug\-stacks
1585    Enable one debugging information, the function call stack.
1586    .
1587    .
1588    .Opt_def -- debug\-tmpdir
1589    Enable one debugging information, the name of the temporary directory.
1590    .
1591    .
1592    .Opt_def -- debug\-user
1593    Enable one debugging information, the function stack with
1594    \f[CR]error_user()\f[].
1595  .  .
1596  .  .
1597  .Opt_def -- do-nothing  .Opt_def -- do-nothing
# Line 1482  but without the output; no viewer is sta Line 1602  but without the output; no viewer is sta
1602  This makes only sense in development.  This makes only sense in development.
1603  .  .
1604  .  .
1605    .Opt_def -- print=text
1606    Just print the argument to standard error.
1607    .
1608    This is good for parameter check.
1609    .
1610    .
1611  .Opt_def -- shell "shell_program"  .Opt_def -- shell "shell_program"
1612  Specify the shell under which the  Specify the shell under which the
1613  .File_name \%groffer2.sh  .File_name \%groffer2.sh
1614  script should be run.  script should be run.
1615  .  .
1616    This option overwrites the automatic shell determination of the
1617    program.
1618    .
1619  If the argument  If the argument
1620  .I shell_program  .I shell_program
1621  is empty a former shell option is cancelled and the default shell is  is empty a former shell option and the automatic shell determination
1622  restored.  is cancelled and the default shell is restored.
1623  .  .
1624  Some shells run considerably faster than the standard shell.  Some shells run considerably faster than the standard shell.
1625  .  .
 It makes sense to set this option in a configuration file.  
 .  
1626  .  .
1627  .Opt_def - Q -- source  .Opt_def - Q -- source
1628  Output the roff source code of the input files without further  Output the roff source code of the input files without further
# Line 1703  options should be needed, except for adv Line 1830  options should be needed, except for adv
1830  .  .
1831  .  .
1832  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
1833  .SS "X\~\%Window\~\%Toolkit Options"  .SS "Options for man\~pages"
1834  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
1835  .  .
1836  The following long options were adapted from the corresponding  .Opt_def -- apropos
1837  X\~\%Toolkit options.  Start the
1838  .  .BR \%apropos (1)
1839  .B \%groffer  command or facility of
1840  will pass them to the actual viewer program if it is an X\~\%Window  .BR \%man (1)
1841  program.  for searching the
1842  .  .I \%filespec
1843  Otherwise these options are ignored.  arguments within all
1844  .  .I \%man\~page
1845  .  descriptions.
 .P  
 Unfortunately these options use the old style of a single minus for  
 long options.  
 .  
 For  
 .B \%groffer  
 that was changed to the standard with using a double minus for long  
 options, for example,  
 .B \%groffer  
 uses the option  
 .Opt_long font  
 for the X\~\%option  
 .Opt_short font .  
 .  
 .  
 .P  
 See  
 .BR \%X (1),  
 .BR \%X (7),  
 and the documentation on the X\~\%Toolkit\~\%options for more details on  
 these options and their arguments.  
 .  
 .  
 .Opt_def -- background color  
 Set the background color of the viewer window.  
 .  
 .  
 .Opt_def -- bd pixels  
 Specifies the color of the border surrounding the viewer window.  
 .  
 .  
 .Opt_def -- bg color  
 This is equivalent to  
 .Opt_long background .  
 .  
 .  
 .Opt_def -- bw pixels  
 Specifies the width in pixels of the border surrounding the viewer  
 window.  
 .  
 .  
 .Opt_def -- display X-display  
 Set the X\~\%display on which the viewer program shall be started, see the  
 .I X\~\%Window  
 documentation for the syntax of the argument.  
 .  
 .  
 .Opt_def -- foreground color  
 Set the foreground color of the viewer window.  
 .  
 .  
 .Opt_def -- fg color  
 This is equivalent to  
 .Opt_short foreground .  
 .  
 .  
 .Opt_def -- font font_name  
 Set the font used by the viewer window.  
 .  
 The argument is an X\~\%font\~\%name.  
 .  
 .  
 .Opt_def -- ft font_name  
 This is equivalent to  
 .Opt_long ft .  
 .  
 .  
 .Opt_def -- geometry size_pos  
 Set the geometry of the display window, that means its size and its  
 starting position.  
 .  
 See  
 .BR \%X (7)  
 for the syntax of the argument.  
 .  
 .  
 .Opt_def -- resolution value  
 Set X\~\%resolution in dpi (dots per inch) in some viewer programs.  
1846  .  .
1847  The only supported dpi values are  Each
1848  .B 75  .I \%filespec
1849    argument is taken for search as it is; section specific parts are not
1850    handled, such that
1851    .B 7 groff
1852    searches for the two arguments
1853    .B 7
1854  and  and
1855  .BR 100 .  .B groff
1856    with a large result; for the
1857    .I \%filespec
1858    .B groff.7
1859    nothing will be found.
1860  .  .
1861  Actually, the default resolution for  The display differs from the
1862  .B \%groffer  .B \%apropos
1863  is set to  program by the following concepts:
1864  .BR 75\~dpi .  .RS
1865  The resolution also sets the default device in  .Topic
1866  .IR "mode x" .  construct a
1867    .I \%groff
1868    frame to the output of
1869    .BR \%apropos ,
1870    .Topic
1871    each
1872    .I \%filespec
1873    argument is searched on its own.
1874    .Topic
1875    the restriction by
1876    .Opt_long sections
1877    is handled as well,
1878    .Topic
1879    wildcard characters are allowed and handled without a further option.
1880    .RE
1881  .  .
1882  .  .
1883  .Opt_def -- rv  .Opt_def -- apropos\-data
1884  Reverse foreground and background color of the viewer window.  Show only the
1885    .B \%apropos
1886    descriptions for data documents, these are the
1887    .BR \%man (7)
1888    sections 4, 5, and 7.
1889  .  .
1890    Direct section declarations are ignored, wildcards are accepted.
1891  .  .
 .Opt_def -- title "'some text'"  
 Set the title for the viewer window.  
1892  .  .
1893    .Opt_def -- apropos\-devel
1894    Show only the
1895    .B \%apropos
1896    descriptions for development documents, these are the
1897    .BR man (7)
1898    sections 2, 3, and 9.
1899  .  .
1900  .Opt_def -- xrm "'resource'"  Direct section declarations are ignored, wildcards are accepted.
 Set X\~\%resource.  
1901  .  .
1902  .  .
1903  .\" --------------------------------------------------------------------  .Opt_def -- apropos\-progs
1904  .SS "Options for man"  Show only the
1905  .\" --------------------------------------------------------------------  .B \%apropos
1906    descriptions for documents on programs, these are the
1907    .BR \%man (7)
1908    sections 1, 6, and 8.
1909  .  .
1910  The long options of  Direct section declarations are ignored, wildcards are accepted.
 .B \%groffer  
 were synchronized with the long options of GNU  
 .BR man .  
1911  .  .
1912  All long options of GNU  .
1913  .B man  .Opt_def -- whatis
1914  are recognized, but not all of these options are important to  For each
1915  .BR \%groffer ,  .I \%filespec
1916  so most of them are just ignored.  argument search all
1917    .I \%man\~pages
1918    and display their description \[em] or say that it is not a
1919    .IR \%man\~page .
1920    This differs from
1921    .IR man 's
1922    .B whatis
1923    output by the following concepts
1924    .RS
1925    .Topic
1926    each retrieved file name is added,
1927    .Topic
1928    local files are handled as well,
1929    .Topic
1930    the display is framed by a
1931    .I groff
1932    output format,
1933    .Topic
1934    wildcard characters are allowed without a further option.
1935    .RE
1936  .  .
1937  .  .
1938  .P  .P
# Line 1870  is the corresponding Line 1969  is the corresponding
1969  option.  option.
1970  .  .
1971  .  .
1972    .Opt_def -- no-special
1973    Disable former calls of
1974    .Opt_long all ,
1975    .Opt_long apropos* ,
1976    and
1977    .Opt_long whatis .
1978    .
1979    .
1980    .\" --------------------------------------------------------------------
1981    .SS "Long options taken over from GNU man"
1982    .\" --------------------------------------------------------------------
1983    .
1984    The long options of
1985    .B \%groffer
1986    were synchronized with the long options of \f[CR]GNU\f[]
1987    .BR man .
1988    .
1989    All long options of \f[CR]GNU\f[]
1990    .B man
1991    are recognized, but not all of these options are important to
1992    .BR \%groffer ,
1993    so most of them are just ignored.
1994    .
1995    .
1996  .P  .P
1997  In the following, the  In the following, the
1998  .B man  .B man
# Line 1879  are documented. Line 2002  are documented.
2002  .  .
2003  .  .
2004  .P  .P
2005  The full set of long and short options of the GNU  The full set of long and short options of the \f[CR]GNU\f[]
2006  .B man  .B man
2007  program can be passed via the environment variable  program can be passed via the environment variable
2008  .Env_var $MANOPT ;  .Env_var $MANOPT ;
2009  see  see
2010  .BR \%man (1)  .BR \%man (1)
2011  if your system has GNU  if your system has \f[CR]GNU\f[]
2012  .B man  .B man
2013  installed.  installed.
2014  .  .
# Line 1985  for the given operating systems; the arg Line 2108  for the given operating systems; the arg
2108  is a comma-separated list.  is a comma-separated list.
2109  .  .
2110  .  .
 .Opt_def -- whatis  
 Instead of displaying the content, get the one-liner description from  
 the retrieved  
 .I \%man\~page  
 files \[em] or say that it is not a  
 .IR \%man\~page .  
 .  
 .  
2111  .Opt_def -- where  .Opt_def -- where
2112  Eqivalent to  Eqivalent to
2113  .Opt_long location .  .Opt_long location .
2114  .  .
2115  .  .
2116  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2117    .SS "X\~\%Window\~\%Toolkit Options"
2118    .\" --------------------------------------------------------------------
2119    .
2120    The following long options were adapted from the corresponding
2121    \%\f[CR]X\~\Window\~Toolkit\f[] options.
2122    .
2123    .B \%groffer
2124    will pass them to the actual viewer program if it is an
2125    \%\f[CR]X\~Window\f[] program.
2126    .
2127    Otherwise these options are ignored.
2128    .
2129    .
2130    .P
2131    Unfortunately these options use the old style of a single minus for
2132    long options.
2133    .
2134    For
2135    .B \%groffer
2136    that was changed to the standard with using a double minus for long
2137    options, for example,
2138    .B \%groffer
2139    uses the option
2140    .Opt_long font
2141    for the \%\f[CR]X\~Window\f[] option
2142    .Opt_short font .
2143    .
2144    .
2145    .P
2146    See
2147    .BR \%X (1),
2148    .BR \%X (7),
2149    and the documentation on the \%\f[CR]X\~Window\~Toolkit\f[] options
2150    for more details on these options and their arguments.
2151    .
2152    .
2153    .Opt_def -- background color
2154    Set the background color of the viewer window.
2155    .
2156    .
2157    .Opt_def -- bd pixels
2158    Specifies the color of the border surrounding the viewer window.
2159    .
2160    .
2161    .Opt_def -- bg color
2162    This is equivalent to
2163    .Opt_long background .
2164    .
2165    .
2166    .Opt_def -- bw pixels
2167    Specifies the width in pixels of the border surrounding the viewer
2168    window.
2169    .
2170    .
2171    .Opt_def -- display X-display
2172    Set the \%\f[CR]X\~Window\f[] display on which the viewer program
2173    shall be started, see the \%\f[CR]X\~Window\f[] documentation for the
2174    syntax of the argument.
2175    .
2176    .
2177    .Opt_def -- foreground color
2178    Set the foreground color of the viewer window.
2179    .
2180    .
2181    .Opt_def -- fg color
2182    This is equivalent to
2183    .Opt_short foreground .
2184    .
2185    .
2186    .Opt_def -- font font_name
2187    Set the font used by the viewer window.
2188    .
2189    The argument is an \%\f[CR]X\~Window\f[] font name.
2190    .
2191    .
2192    .Opt_def -- ft font_name
2193    This is equivalent to
2194    .Opt_long ft .
2195    .
2196    .
2197    .Opt_def -- geometry size_pos
2198    Set the geometry of the display window, that means its size and its
2199    starting position.
2200    .
2201    See
2202    .BR \%X (7)
2203    for the syntax of the argument.
2204    .
2205    .
2206    .Opt_def -- resolution value
2207    Set \%\f[CR]X\~Window\f[] resolution in dpi (dots per inch) in some
2208    viewer programs.
2209    .
2210    The only supported dpi values are
2211    .B 75
2212    and
2213    .BR 100 .
2214    .
2215    Actually, the default resolution for
2216    .B \%groffer
2217    is set to
2218    .BR 75\~dpi .
2219    The resolution also sets the default device in
2220    .IR "mode x" .
2221    .
2222    .
2223    .Opt_def -- rv
2224    Reverse foreground and background color of the viewer window.
2225    .
2226    .
2227    .Opt_def -- title "'some text'"
2228    Set the title for the viewer window.
2229    .
2230    .
2231    .Opt_def -- xrm "'resource'"
2232    Set \f[CR]\%X\~Window\f[] resource.
2233    .
2234    .
2235    .\" --------------------------------------------------------------------
2236  .SS "Filespec Arguments"  .SS "Filespec Arguments"
2237  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2238  .  .
2239  A  A
2240  .I \%filespec  .I \%filespec
2241  parameter is an argument meaning an input source, such as a file name  parameter is an argument that is not an option or option argument.
2242  or template for searching  .
2243    It means an input source.
2244    .
2245    In
2246    .BR \%groffer ,
2247    .I \%filespec
2248    parameters are a file name or a template for searching
2249  .IR \%man\~pages .  .IR \%man\~pages .
2250  .  .
2251  These input sources are collected and composed into a single output  These input sources are collected and composed into a single output
# Line 2015  does. Line 2255  does.
2255  .  .
2256  .  .
2257  .P  .P
2258  The strange \%POSIX behavior that maps all arguments behind the first  The strange \%\f[CR]POSIX\f[] behavior to regard all arguments behind
2259  non-option argument into  the first non-option argument as
2260  .I \%filespec  .I \%filespec
2261  arguments is ignored.  arguments is ignored.
2262  .  .
2263  The GNU behavior to recognize options even when mixed with  The \f[CR]GNU\f[] behavior to recognize options even when mixed with
2264  .I \%filespec  .I \%filespec
2265  arguments is used througout.  arguments is used througout.
2266  .  .
2267  But, as usual, the double minus argument  But, as usual, the double minus argument
2268  .Opt_long  .Opt_long
2269  still takes all following arguments as  ends the option handling and interprets all following arguments as
2270  .I \%filespec  .I \%filespec
2271  arguments.  arguments; so the \%\f[CR]POSIX\f[] behavior can be easily adopted.
 .  
 .  
 .P  
 Each  
 .I \%filespec  
 parameters can have one of the following forms.  
2272  .  .
2273  .  .
2274  .P  .P
2275  No  For the following, it is necessary to know that on each system the
 .I \%filespec  
 parameters means that  
 .B \%groffer  
 waits for standard input.  
 .  
 The minus option  
 .Opt_short ""  
 stands for standard input, too, but can occur several times.  
 .  
 Next  
 .I \%filespec  
 is tested whether it is the path name of an existing file.  
 .  
 Otherwise it is assumed as a searching pattern for a  
 .IR \%man\~page .  
 .  
 .  
 .P  
 On each system, the  
2276  .I \%man\~pages  .I \%man\~pages
2277  are sorted according to their content into several sections.  are sorted according to their content into several sections.
2278  .  .
2279  The  The
2280  .I classical man sections  .I classical man sections
2281  have a single-character name, either are a digit from  have a single-character name, either a digit from
2282  .B 1  .B 1
2283  to  to
2284  .B 9  .B 9
# Line 2074  or Line 2289  or
2289  .  .
2290  In the following, a stand-alone character  In the following, a stand-alone character
2291  .I s  .I s
2292  means this scheme.  stands for a
2293  .  .IR "classical man section" .
 .  
 .P  
2294  The internal precedence of  The internal precedence of
2295  .B \%man  .B \%man
2296  for searching  for searching
# Line 2095  facility is based on the classical singl Line 2308  facility is based on the classical singl
2308  .  .
2309  .  .
2310  .P  .P
2311    Each
2312    .I \%filespec
2313    parameter can have one of the following forms in decreasing sequence.
2314    .
2315    .
2316    .Topic
2317    No
2318    .I \%filespec
2319    parameters means that
2320    .B \%groffer
2321    waits for standard input.
2322    .
2323    The minus option
2324    .Opt_short ""
2325    stands for standard input, too; it can occur several times.
2326    .
2327    .
2328    .Topic
2329    Next a
2330    .I \%filespec
2331    is tested whether it is the path name of an existing file.
2332    .
2333    Otherwise it is assumed to be a searching pattern for a
2334    .IR \%man\~page .
2335    .
2336    .
2337    .Topic
2338  .BI \%man: name ( section )  .BI \%man: name ( section )
2339  and  and
2340  .IB \%name ( section )  .IB \%name ( section )
# Line 2109  can be any string, but it must exist in Line 2349  can be any string, but it must exist in
2349  system.  system.
2350  .  .
2351  .  .
2352  .P  .Topic
2353  Next some patterns based on the  Next some patterns based on the
2354  .I classical man sections  .I classical man sections
2355  were constructed.  are checked.
2356  .  .
2357  .BI \%man: name . s  .BI \%man: name . s
2358  and  and
# Line 2127  is a Line 2367  is a
2367  .I classical man section  .I classical man section
2368  mentioned above.  mentioned above.
2369  .  .
2370  Otherwise search for a  Otherwise a
2371  .I \%man\~page  .I \%man\~page
2372  named  named
2373  .IR \%name.s  .IR \%name.s
2374  in the lowest  is searched in the lowest
2375  .B man\~section .  .B man\~section .
2376  .  .
2377  .  .
2378  .P  .Topic
2379  Now  Now
2380  .BI \%man: name  .BI \%man: name
2381  searches for a  searches for a
# Line 2146  that has a document called Line 2386  that has a document called
2386  .IR \%name .  .IR \%name .
2387  .  .
2388  .  .
2389  .P  .Topic
2390  The pattern  The pattern
2391  .I \%s\~name  .I \%s\~name
2392  originates from a strange argument parsing of the  originates from a strange argument parsing of the
# Line 2163  called Line 2403  called
2403  .I \%name  .I \%name
2404  in man\~section  in man\~section
2405  .IR s ,  .IR s ,
2406  otherwise interpret  otherwise interpret both
2407  .I s  .I s
2408  as a file argument and  and
2409  .I \%name  .I \%name
2410  as another  as two independent
2411  .I \%filespec  .I \%filespec
2412  argument.  arguments.
2413  .  .
2414  .  .
2415  .P  .Topic
2416  We are left with the argument  We are left with the argument
2417  .I \%name  .I \%name
2418  which is not an existing file.  which is not an existing file.
# Line 2187  that has a document for this name. Line 2427  that has a document for this name.
2427  .  .
2428  .  .
2429  .P  .P
2430    Wildcards in
2431    .I \%filespec
2432    arguments are only accepted for
2433    .Opt_long apropos*
2434    and
2435    .Opt_long whatis ;
2436    for normal display, they are interpreted as characters.
2437    .
2438    .
2439    .P
2440  Several file name arguments can be supplied.  Several file name arguments can be supplied.
2441  .  .
2442  They are mixed by  They are mixed by
# Line 2235  option that is constructed like Line 2485  option that is constructed like
2485  .  .
2486  .P  .P
2487  Several different modes are offered, graphical modes for  Several different modes are offered, graphical modes for
2488  .IR \%X\~Window ,  \f[CR]\%X\~Window\f[],
2489  .IR \%text\~modes ,  .IR \%text\~modes ,
2490  and some direct  and some direct
2491  .I \%groff\~modes  .I \%groff\~modes
# Line 2269  and the decompression of the input are a Line 2519  and the decompression of the input are a
2519  .SS "Graphical Display Modes"  .SS "Graphical Display Modes"
2520  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2521  .  .
2522  The graphical display modes work only in the  The graphical display modes work mostly in the \%\f[CR]X\~Window\f[]
2523  .I X\~\%Window environment  environment (or similar implementations within other windowing
2524  (or similar implementations within other windowing environments).  environments).
2525  .  .
2526  The environment variable  The environment variable
2527  .Env_var $DISPLAY  .Env_var $DISPLAY
2528  and the option  and the option
2529  .Opt_long display  .Opt_long display
2530  are used for specifying the X\~\%display to be used.  are used for specifying the \%\f[CR]X\~Window\f[] display to be used.
2531  .  .
2532  If neither is given,  If this environment variable is empty
2533  .B \%groffer  .B \%groffer
2534  assumes that no X and changes to one  assumes that no \%\f[CR]X\~Window\f[] is running and changes to a
2535  .IR \%text\~mode .  .IR \%text\~mode .
2536  .  .
2537  You can change this automatic behavior by the option  You can change this automatic behavior by the option
# Line 2290  You can change this automatic behavior b Line 2540  You can change this automatic behavior b
2540  .  .
2541  .P  .P
2542  Known viewers for the graphical display modes and their standard  Known viewers for the graphical display modes and their standard
2543  X\~\%Window viewer progams are  \%\f[CR]X\~Window\f[] viewer progams are
2544  .  .
2545  .Topic  .Topic
2546  X\~\%Window  \%\f[CR]X\~Window\f[]
2547  .I roff  .I roff
2548  viewers such as  viewers such as
2549  .BR \%gxditview (@MAN1EXT@)  .BR \%gxditview (@MAN1EXT@)
# Line 2325  in a web browser Line 2575  in a web browser
2575  .nh  .nh
2576  .RI ( html  .RI ( html
2577  or  or
2578  .IR \%www\~mode ),  .IR \%www\~mode ).
2579  .hy  .hy
2580  .RE  .RE
2581  .  .
# Line 2343  format, so it was not chosen as the majo Line 2593  format, so it was not chosen as the majo
2593  .  .
2594  .P  .P
2595  These graphical viewers can be customized by options of the  These graphical viewers can be customized by options of the
2596  X\~\%Window\~\%Toolkit.  \%\f[CR]X\~Window\~Toolkit\f[].
2597  .  .
2598  But the  But the
2599  .B \%groffer  .B \%groffer
2600  options use a leading double minus instead of the single minus used by  options use a leading double minus instead of the single minus used by
2601  the  the \%\f[CR]X\~Window\~Toolkit\f[].
 .I X\~\%Window\~\%Toolkit .  
2602  .  .
2603  .  .
2604  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 2480  This behavior can be modified by the fol Line 2729  This behavior can be modified by the fol
2729  .  .
2730  .TP  .TP
2731  .Opt_long man  .Opt_long man
2732  forces to interpret all file parameters as filespecs for searching  forces to interpret all file parameters as
2733    .I \%filespecs
2734    for searching
2735  .IR \%man\~pages .  .IR \%man\~pages .
2736  .  .
2737  .TP  .TP
# Line 2506  program provides a search facility for Line 2757  program provides a search facility for
2757  .IR \%man\~pages .  .IR \%man\~pages .
2758  .  .
2759  All long options, all environment variables, and most of the  All long options, all environment variables, and most of the
2760  functionality of the GNU  functionality of the \f[CR]GNU\f[]
2761  .BR \%man (1)  .BR \%man (1)
2762  program were implemented.  program were implemented.
2763  .  .
# Line 2612  environment variables and command line o Line 2863  environment variables and command line o
2863  .  .
2864  .  .
2865  .P  .P
2866  The locale (language) is determined like in GNU  The locale (language) is determined like in \f[CR]GNU\f[]
2867  .BR man ,  .BR man ,
2868  that is from highest to lowest precedence:  that is from highest to lowest precedence:
2869  .Topic  .Topic
# Line 2635  that is from highest to lowest precedenc Line 2886  that is from highest to lowest precedenc
2886  .  .
2887  .  .
2888  .P  .P
2889  The language locale is usually specified in the \%POSIX 1003.1 based  The language locale is usually specified in the
2890  format:  \%\f[CR]POSIX\~1003.1\f[] based format:
2891  .P  .P
2892  .nh  .nh
2893  \f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\f[]\  \f[I]<language>\f[][\f[CB]_\f[]\f[I]<territory>\f[][\f[CB].\f[]\
# Line 2707  with the additional language and system Line 2958  with the additional language and system
2958  The search can further be restricted by limiting it to certain  The search can further be restricted by limiting it to certain
2959  sections.  sections.
2960  .  .
2961  A single section can be specified within each filespec argument,  A single section can be specified within each
2962  several sections as a colon-separated list in command line option  .I \%filespec
2963    argument, several sections as a colon-separated list in command line
2964    option
2965  .Opt_long sections  .Opt_long sections
2966  or environment variable  or environment variable
2967  .Env_var $MANSECT .  .Env_var $MANSECT .
# Line 2750  or Line 3003  or
3003  .BR \%bzip2 (1)  .BR \%bzip2 (1)
3004  it is decompressed on-the-fly.  it is decompressed on-the-fly.
3005  .  .
3006  This includes the GNU  This includes the \f[CR]GNU\f[]
3007  .BR \%.gz ,  .BR \%.gz ,
3008  .BR \%.bz2 ,  .BR \%.bz2 ,
3009  and the traditional  and the traditional
# Line 2772  other programs. Line 3025  other programs.
3025  .  .
3026  All environment variables of  All environment variables of
3027  .BR \%groff (@MAN1EXT@)  .BR \%groff (@MAN1EXT@)
3028  and GNU  and \f[CR]GNU\f[]
3029  .BR \%man (1)  .BR \%man (1)
3030  and some standard system variables are honored.  and some standard system variables are honored.
3031  .  .
# Line 2793  The content of this variable is run thro Line 3046  The content of this variable is run thro
3046  so arguments containing white-space or special shell characters should  so arguments containing white-space or special shell characters should
3047  be quoted.  be quoted.
3048  .  .
3049    Do not forget to export this variable, otherwise it does not exist
3050    during the run of
3051    .BR groffer .
3052    .
3053  .  .
3054  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
3055  .SS "System Variables"  .SS "System Variables"
# Line 2812  The following variables have a special m Line 3069  The following variables have a special m
3069  .  .
3070  .TP  .TP
3071  .Env_var $DISPLAY  .Env_var $DISPLAY
3072  If this variable is set this indicates that the X\~\%Window system is  If this variable is set this indicates that the \%\f[CR]X\~Window\f[]
3073  running.  system is running.
3074  .  .
3075  Testing this variable decides on whether graphical or text output is  Testing this variable decides on whether graphical or text output is
3076  generated.  generated.
# Line 2821  generated. Line 3078  generated.
3078  This variable should not be changed by the user carelessly, but it can  This variable should not be changed by the user carelessly, but it can
3079  be used to start the graphical  be used to start the graphical
3080  .B \%groffer  .B \%groffer
3081  on a remote X\~\%terminal.  on a remote \%\f[CR]X\~Window\f[] terminal.
3082  .  .
3083  For example, depending on your system,  For example, depending on your system,
3084  .B \%groffer  .B \%groffer
# Line 2860  is a character set or encoding identifie Line 3117  is a character set or encoding identifie
3117  see  see
3118  .BR \%setlocale (3).  .BR \%setlocale (3).
3119  .  .
3120  The locale values\~\c  The locale values \f[CR]C\f[] and \%\f[CR]POSIX\f[]
 .B C  
 and  
 .B \%POSIX  
3121  stand for the default, i.e. the  stand for the default, i.e. the
3122  .I \%man\~page  .I \%man\~page
3123  directories without a language prefix.  directories without a language prefix.
# Line 2907  are internally used within Line 3161  are internally used within
3161  .B \%groffer  .B \%groffer
3162  as well.  as well.
3163  .  .
3164  The following variables have a direct meaning for the  The following variable has a direct meaning for the
3165  .B \%groffer  .B \%groffer
3166  program.  program.
3167  .  .
# Line 2915  program. Line 3169  program.
3169  .Env_var $GROFF_TMPDIR  .Env_var $GROFF_TMPDIR
3170  If the value of this variable is an existing, writable directory,  If the value of this variable is an existing, writable directory,
3171  .B \%groffer  .B \%groffer
3172  uses it for storing its temporary files, just as groff does.  uses it for storing its temporary files, just as
3173    .B groff
3174    does.
3175  .  .
3176  .  .
3177  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 3095  It makes sense to use these configuratio Line 3351  It makes sense to use these configuratio
3351  tasks:  tasks:
3352  .  .
3353  .Topic  .Topic
3354  Preset command line options by writing them into lines starting with a  Preset command line options, such as choosing a
3355  minus sign.  .I \%mode
3356    or a viewer.
3357    .
3358    These are written into lines starting with a single or double minus
3359    sign, followed by the option name.
3360  .  .
3361  .Topic  .Topic
3362  Preset environment variables recognized by  Preset environment variables recognized by
# Line 3104  Preset environment variables recognized Line 3364  Preset environment variables recognized
3364  but do not forget to export them.  but do not forget to export them.
3365  .  .
3366  .Topic  .Topic
3367  Write a function for calling a viewer program for a special  You can also write a shell function for calling, for example a viewer
3368  .I \%mode  program for some
3369  and feed this name into its corresponding  .IR \%mode .
3370    Such a function can be fed into a corresponding
3371  .Opt_long \f[I]mode\f[]\-viewer  .Opt_long \f[I]mode\f[]\-viewer
3372  option.  option.
3373  .  .
 Note that the name of such a function must either be given as the full  
 file name or coincide with some existing program in the system path  
 .Env_var $PATH  
 in order to be recognized by  
 .BR groffer .  
 .  
3374  .Topic  .Topic
3375  Enter  Enter
3376  .Opt_long shell  .Opt_long shell
3377  to specify a shell for the run of  to specify a shell for the run of
3378  .File_name groffer2.sh .  .File_name groffer2.sh .
3379  Some shells run much faster than the standard shell; the fastest  Some shells run much faster than the standard shell.
 Bourne shell that I know is  
 .BR ash (1).  
 It makes really sense to add a line like  
 .Opt_long shell=ash  
 to your configuration file as long as the given shell is installed on  
 your system.  
3380  .  .
3381  .  .
3382  .P  .P
# Line 3142  say. Line 3391  say.
3391  # groffer configuration file  # groffer configuration file
3392  #  #
3393  # groffer options that are used in each call of groffer  # groffer options that are used in each call of groffer
3394  \-\-shell=ash  \-\-shell=ksh
3395  \-\-foreground=DarkBlue  \-\-foreground=DarkBlue
3396  \-\-resolution=100  \-\-resolution=100
3397  \-\-x\-viewer='gxditview \-geometry 900x1200'  \-\-x\-viewer='gxditview \-geometry 900x1200'
# Line 3172  This has the following effects: Line 3421  This has the following effects:
3421  .  .
3422  .Topic  .Topic
3423  Use  Use
3424  .B ash  .B ksh
3425  as the shell to run the  as the shell to run the
3426  .B \%groffer  .B \%groffer
3427  script; if it works it should be faster than the usual  script; if it works it should be faster than the usual
# Line 3219  is empty set it to Line 3468  is empty set it to
3468  .  .
3469  That allows to start  That allows to start
3470  .B \%groffer  .B \%groffer
3471  in the standard X\~\%display, even when the program is called from a  in the standard \%\f[CR]X\~Window\f[] display, even when the program
3472  text console.  is called from a text console.
3473  .  .
3474  .  .
3475  .Topic  .Topic
# Line 3253  Decompress, format and display the compr Line 3502  Decompress, format and display the compr
3502  .File_name meintro.ms.gz  .File_name meintro.ms.gz
3503  in the directory  in the directory
3504  .File_name /usr/local/share/doc/groff ,  .File_name /usr/local/share/doc/groff ,
3505  using  using the standard viewer
3506  .B \%gxditview  .B \%gxditview
3507  as graphical viewer when in X\~\%Window, or the  as graphical viewer when in \%\f[CR]X\~Window\f[], or the
3508  .BR \%less (1)  .BR \%less (1)
3509  pager program when not in X.  pager program when not in \%\f[CR]X\~Window\f[].
3510  .  .
3511  .  .
3512  .TP  .TP
# Line 3345  The formatted files are concatenated and Line 3594  The formatted files are concatenated and
3594  .  .
3595  .  .
3596  .TP  .TP
3597  .Shell_cmd "LANG=de\~groffer\~--man\~--www\~--www-viever=mozilla\~ls"  .Shell_cmd "LANG=de\~groffer\~--man\~--www\~--www-viever=galeon\~ls"
3598  .  .
3599  Retrieve the German  Retrieve the German
3600  .I \%man\~page  .I \%man\~page
# Line 3446  option Line 3695  option
3695  .  .
3696  .P  .P
3697  Both scripts are compatible with both  Both scripts are compatible with both
3698  GNU and \%POSIX.  \f[CR]GNU\f[] and \%\f[CR]POSIX\f[].
3699  .  .
3700  \%POSIX compatibility refers to  \%\f[CR]POSIX\f[] compatibility refers to
3701  .B IEEE P1003.2/D11.2  \%\f[CR]IEEE\~P1003.2/D11.2\f[] of September 1991, a very early
3702  of September 1991, a very early version of the \%POSIX standard that  version of the \%\f[CR]POSIX\f[] standard that is still freely
3703  is still freely available in the internet at  available in the internet at
3704  .URL http://\:www.funet.fi/\:pub/\:doc/\:posix/\:p1003.2/\:d11.2/\:all \  .URL http://\:www.funet.fi/\:pub/\:doc/\:posix/\:p1003.2/\:d11.2/\:all \
3705  "\%POSIX P1003.2 draft 11.2" .  "\%POSIX\~P1003.2\~draft\~11.2" .
3706  .  .
3707  .  .
3708  .P  .P
3709  Only a restricted set of shell language elements and shell builtins is  Only a restricted set of shell language elements and shell builtins is
3710  used to achieve even compatibility with some Bourne shells that are  used to achieve even compatibility with some Bourne shells that are
3711  not fully \%POSIX compatible.  not fully \%\f[CR]POSIX\f[] compatible.
3712  .  .
3713  The  The
3714  .B \%groffer  .B \%groffer
# Line 3494  configuration files you must write a lin Line 3743  configuration files you must write a lin
3743  The  The
3744  .B \%groffer  .B \%groffer
3745  program provides its own parser for command line arguments that is  program provides its own parser for command line arguments that is
3746  compatible to both  compatible to both \%\f[CR]POSIX\f[]
 .I \%POSIX  
3747  .BR \%getopts (1)  .BR \%getopts (1)
3748  and  and \%\f[CR]GNU\f[]
 .I \%GNU  
3749  .BR \%getopt (1).  .BR \%getopt (1).
3750  It can handle option arguments and file names containing white space  It can handle option arguments and file names containing white space
3751  and a large set of special characters.  and a large set of special characters.
# Line 3537  is equivalent to Line 3784  is equivalent to
3784  An argument of  An argument of
3785  .Opt_--  .Opt_--
3786  ends option parsing; all further command line arguments are  ends option parsing; all further command line arguments are
3787  interpreted as filespec parameters, i.e. file names or constructs for  interpreted as
3788  searching  .I \%filespec
3789    parameters, i.e. file names or constructs for searching
3790  .IR \%man\~pages ).  .IR \%man\~pages ).
3791  .  .
3792  .  .
3793  .Topic  .Topic
3794  All command line arguments that are neither options nor option  All command line arguments that are neither options nor option
3795  arguments are interpreted as filespec parameters and stored until  arguments are interpreted as
3796  option parsing has finished.  .I \%filespec
3797    parameters and stored until option parsing has finished.
3798  .  .
3799  For example, the command line  For example, the command line
3800  .Shell_cmd "groffer file1 -a -o arg file2"  .Shell_cmd "groffer file1 -a -o arg file2"
# Line 3554  is equivalent to Line 3803  is equivalent to
3803  .  .
3804  .  .
3805  .P  .P
3806  The free mixing of options and filespec parameters follows the GNU  The free mixing of options and
3807  principle.  .I \%filespec
3808    parameters follows the GNU principle.
3809  .  .
3810  That does not fulfill the strange option behavior of \%POSIX that ends  That does not fulfill the strange option behavior of \%\f[CR]POSIX\f[]
3811  option processing as soon as the first non-option argument has been  that ends option processing as soon as the first non-option argument
3812  reached.  has been reached.
3813  .  .
3814  The end of option processing can be forced by the option  The end of option processing can be forced by the option
3815  .RB ` \-\- '  .RB ` \-\- '

Legend:
Removed from v.1.27  
changed lines
  Added in v.1.28

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26