/[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.21 by wl, Fri May 20 06:12:24 2005 UTC revision 1.22 by wl, Sat May 21 07:08:00 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 : 20 May 2005  Last update : 21 May 2005
19    
20  Source file position: <groff-source>/contrib/groffer/groffer.man  Source file position: <groff-source>/contrib/groffer/groffer.man
21  ..  ..
# Line 60  Suite 330, Boston, MA 02111-1307, USA. Line 60  Suite 330, Boston, MA 02111-1307, USA.
60  .  ftr CB CW  .  ftr CB CW
61  .\}  .\}
62  .  .
 .ds @- "\-\""  
 .ds @-- "\-\^\-\""  
 .  
 .ds @b- "\f[CB]-\f[]\""  
 .ds @b-- "\f[CB]--\f[]\""  
 .  
 .ds @i- "\f[CI]-\f[]\""  
 .ds @i-- "\f[CI]--\f[]\""  
 .  
63  .ds Ellipsis ".\|.\|.\""  .ds Ellipsis ".\|.\|.\""
64  .  .
65  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 286  Suite 330, Boston, MA 02111-1307, USA. Line 277  Suite 330, Boston, MA 02111-1307, USA.
277  .c Alternating options; base macro for many others; do not use directly.  .c Alternating options; base macro for many others; do not use directly.
278  .c  .c
279  .c Arguments:  .c Arguments:
280  .c   <pre>: prefix, resulted is preceded by this.  .c   <pre>: prefix, result is preceded by this.
281  .c   <sep>: separator between minus/opt pairs.  .c   <sep>: separator between minus/opt pairs.
282  .c   <post>: postfix, is appended to the result.  .c   <post>: postfix, is appended to the result.
283  .c   <minus>: either `-' or `--' (font CB).  .c   <minus>: either `-' or `--' (font CB).
# Line 296  Suite 330, Boston, MA 02111-1307, USA. Line 287  Suite 330, Boston, MA 02111-1307, USA.
287  .c Result:  .c Result:
288  .c   String `<pre>' followed by the <minus>/<opt> argument pairs, each  .c   String `<pre>' followed by the <minus>/<opt> argument pairs, each
289  .c   separated by string `<sep>', optionally add '<arg>', separated by  .c   separated by string `<sep>', optionally add '<arg>', separated by
290  .c   a single space ` ', followed by the string `<post>'.  .c   a single space ` ', followed by the string `<post>'.  Terminated
291    .c   by the optional punctuation <punct>.
292  .c  .c
293  .de Opt_alt_base  .de Opt_alt_base
294  .  nr @font \\n[.f]\"  .  nr @font \\n[.f]\"
# Line 316  Suite 330, Boston, MA 02111-1307, USA. Line 308  Suite 330, Boston, MA 02111-1307, USA.
308  .    \}  .    \}
309  .    c                                  separator  .    c                                  separator
310  .    if (\\n[@count] > 0) \  .    if (\\n[@count] > 0) \
311  .      as @res \f[CR]\\*[@sep]\"  .      as @res \f[CR]\\*[@sep]\:\"
312  .    nr @count +1  .    nr @count +1
313  .    as @res \f[CB]\\$1\\$2\:\"         combine minus with option name  .    c                                  combine minus with option name
314    .    as @res \f[CB]\\-\"
315    .    if '\\$1'--' \
316    .      as @res \\-\"
317    .    as @res \\$2\"
318  .    shift 2  .    shift 2
319  .  \}  .  \}
320  .  if (\\n[.$] >= 3) \  .  if (\\n[.$] >= 3) \
# Line 555  Suite 330, Boston, MA 02111-1307, USA. Line 551  Suite 330, Boston, MA 02111-1307, USA.
551  .de Text  .de Text
552  .  if (\\n[.$] == 0) \  .  if (\\n[.$] == 0) \
553  .    return  .    return
554    .  nh
555  .  nop \)\\$*\)  .  nop \)\\$*\)
556    .  hy
557  ..  ..
558  .c --------------------------------------------------------------------  .c --------------------------------------------------------------------
559  .c .Topic  ([<indent>])  .c .Topic  ([<indent>])
# Line 671  Suite 330, Boston, MA 02111-1307, USA. Line 669  Suite 330, Boston, MA 02111-1307, USA.
669  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
670  .  .
671  The  The
672  .I groffer  .I \%groffer
673  program is the easiest way to use  program is the easiest way to use
674  .BR groff (@MAN1EXT@).  .BR \%groff (@MAN1EXT@).
675  It can display arbitrary documents written in the  It can display arbitrary documents written in the
676  .BR groff (@MAN7EXT@)  .BR \%groff (@MAN7EXT@)
677  language or other  language or other
678  .BR roff (@MAN7EXT@)  .BR \%roff (@MAN7EXT@)
679  languages that are compatible to the original troff language.  languages that are compatible to the original
680    .I \%troff
681    language.
682  .  .
683  The  The
684  .I groffer  .I \%groffer
685  program also includes many of the features for finding and displaying  program also includes many of the features for finding and displaying
686  the UNIX manual pages  the \%UNIX manual pages
687    .nh
688  .RI ( man\~pages ),  .RI ( man\~pages ),
689    .hy
690  such that it can be used as a replacement for a  such that it can be used as a replacement for a
691  .BR man (1)  .BR \%man (1)
692  program.  program.
693  .  .
694  Moreover, compressed files that can be handled by  Moreover, compressed files that can be handled by
695  .BR gzip (1)  .BR \%gzip (1)
696  or  or
697  .BR bzip2 (1)  .BR \%bzip2 (1)
698  are decompressed on-the-fly.  are decompressed on-the-fly.
699  .  .
700  .  .
# Line 705  behaviors. Line 707  behaviors.
707  .  .
708  This can be done in configuration files, with the shell environment  This can be done in configuration files, with the shell environment
709  variable  variable
710  .BR $GROFFER_OPT ,  .BR \%$GROFFER_OPT ,
711  or on the command line.  or on the command line.
712  .  .
713  .  .
714  .P  .P
715  The output can be generated and viewed in several different ways  The output can be generated and viewed in several different ways
716  available for  available for
717  .IR groff .  .IR \%groff .
718  .  .
719  This includes the groff native X viewer  This includes the
720    .I \%groff
721    native X viewer
722  .BR \%gxditview (@MAN1EXT@),  .BR \%gxditview (@MAN1EXT@),
723  each Postcript or dvi display program, a web browser by generating  each Postcript or
724  html in www-mode, or several text modes in text terminals.  .I \%dvi
725    display program, a web browser by generating
726    .I \%html
727    in www-mode, or several text modes in text terminals.
728  .  .
729  .  .
730  .P  .P
731  Most of the options that must be named when running  Most of the options that must be named when running
732  .I groff  .I \%groff
733  directly are determined automatically for  directly are determined automatically for
734  .IR groffer ,  .IR \%groffer ,
735  due to the internal usage of the  due to the internal usage of the
736  .BR grog (@MAN1EXT@)  .BR \%grog (@MAN1EXT@)
737  program.  program.
738  .  .
739  But all parts can also be controlled manually by arguments.  But all parts can also be controlled manually by arguments.
# Line 736  But all parts can also be controlled man Line 743  But all parts can also be controlled man
743  Several file names can be specified on the command line arguments.  Several file names can be specified on the command line arguments.
744  .  .
745  They are transformed into a single document in the normal way of  They are transformed into a single document in the normal way of
746  .IR groff .  .IR \%groff .
747  .  .
748  .  .
749  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 748  They are transformed into a single docum Line 755  They are transformed into a single docum
755  .RS  .RS
756  .P  .P
757  .Opt_[alt] -- apropos name  .Opt_[alt] -- apropos name
758  .Opt_[alt] -- apropos-data name  .Opt_[alt] -- apropos\-data name
759  .Opt_[alt] -- apropos-devel name  .Opt_[alt] -- apropos\-devel name
760  .Opt_[alt] -- apropos-progs name  .Opt_[alt] -- apropos\-progs name
761  .Opt_[alt] - h -- help  .Opt_[alt] - h -- help
762  .Opt_[alt] - v -- version  .Opt_[alt] - v -- version
763  .RE  .RE
764  .  .
765  .  .
766  .TP  .TP
767  .I groffer mode options  .I \%groffer mode options
768  .RS  .RS
769  .P  .P
770  .Opt_[alt] -- auto  .Opt_[alt] -- auto
771  .Opt_[alt] -- default  .Opt_[alt] -- default
772  .Opt_[alt] -- default-modes mode1,mode2,\*[Ellipsis]  .Opt_[alt] -- default\-modes mode1,mode2,\*[Ellipsis]
773  .Opt_[alt] -- dvi  .Opt_[alt] -- dvi
774  .Opt_[alt] -- dvi-viewer prog  .Opt_[alt] -- dvi\-viewer prog
775  .Opt_[alt] -- groff  .Opt_[alt] -- groff
776  .Opt_[alt] -- html  .Opt_[alt] -- html
777  .Opt_[alt] -- html-viewer prog  .Opt_[alt] -- html\-viewer prog
778  .Opt_[alt] -- man  .Opt_[alt] -- man
779  .Opt_[alt] -- mode display_mode  .Opt_[alt] -- mode display_mode
780  .Opt_[alt] -- no-man  .Opt_[alt] -- no-man
781  .Opt_[alt] -- pdf  .Opt_[alt] -- pdf
782  .Opt_[alt] -- pdf-viewer prog  .Opt_[alt] -- pdf\-viewer prog
783  .Opt_[alt] -- ps  .Opt_[alt] -- ps
784  .Opt_[alt] -- ps-viewer prog  .Opt_[alt] -- ps\-viewer prog
785  .Opt_[alt] -- text  .Opt_[alt] -- text
786  .Opt_[alt] -- tty  .Opt_[alt] -- tty
787  .Opt_[alt] -- tty-viewer prog  .Opt_[alt] -- tty\-viewer prog
788  .Opt_[alt] -- www  .Opt_[alt] -- www
789  .Opt_[alt] -- www-viewer prog  .Opt_[alt] -- www\-viewer prog
790  .Opt_[alt] -- x -- X  .Opt_[alt] -- x -- X
791  .Opt_[alt] -- x-viewer -- X-viewer prog  .Opt_[alt] -- x\-viewer -- X\-viewer prog
792  .RE  .RE
793  .  .
794  .  .
# Line 795  They are transformed into a single docum Line 802  They are transformed into a single docum
802  .  .
803  .  .
804  .TP  .TP
805  .I options related to groff  .I options related to \%groff
806  .RS  .RS
807  .P  .P
808  .Opt_[alt] - P -- postproc-arg opt_or_arg  .Opt_[alt] - P -- postproc\-arg opt_or_arg
809  .Opt_[alt] - Q -- source  .Opt_[alt] - Q -- source
810  .Opt_[alt] - T -- device device  .Opt_[alt] - T -- device device
811  .Opt_[alt] - Z -- intermediate-output -- ditroff  .Opt_[alt] - Z -- intermediate\-output -- ditroff
812  .P  .P
813  All further  All further
814  .I groff  .I \%groff
815  short options are accepted.  short options are accepted.
816  .RE  .RE
817  .  .
# Line 874  the path name of an existing file. Line 881  the path name of an existing file.
881  .TP+  .TP+
882  .IB name ( section )  .IB name ( section )
883  search the man\~page  search the man\~page
884  .I name  .I \%name
885  in man\~section\~\c  in man\~section
886  .IR section .  .IR section .
887  .  .
888  .  .
# Line 886  in man\~section\~\c Line 893  in man\~section\~\c
893  if  if
894  .I s  .I s
895  is a character in  is a character in
896  .BR [1-9on] ,  .BR \%[1-9on] ,
897  search for a man\~page  search for a man\~page
898  .I name  .I \%name
899  in man\~section  in man\~section
900  .IR s .  .IR s .
901  .  .
# Line 896  in man\~section Line 903  in man\~section
903  .TP  .TP
904  .BI man: name  .BI man: name
905  man\~page in the lowest man\~section that has  man\~page in the lowest man\~section that has
906  .IR name .  .IR \%name .
907  .  .
908  .  .
909  .TP  .TP
# Line 904  man\~page in the lowest man\~section tha Line 911  man\~page in the lowest man\~section tha
911  if  if
912  .I s  .I s
913  is a character in  is a character in
914  .BR [1-9on] ,  .BR \%[1-9on] ,
915  search for a man\~page  search for a man\~page
916  .I name  .I \%name
917  in man\~section  in man\~section
918  .IR s .  .IR s .
919  .  .
# Line 914  in man\~section Line 921  in man\~section
921  .TP  .TP
922  .I name  .I name
923  if  if
924  .I name  .I \%name
925  is not an existing file search for the man\~page  is not an existing file search for the man\~page
926  .I name  .I \%name
927  in the lowest man\~section.  in the lowest man\~section.
928  .  .
929  .RE  .RE
# Line 927  in the lowest man\~section. Line 934  in the lowest man\~section.
934  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
935  .  .
936  The  The
937  .I groffer  .I \%groffer
938  program can usually be run with very few options.  program can usually be run with very few options.
939  .  .
940  But for special purposes, it supports many options.  But for special purposes, it supports many options.
# Line 937  These can be classified in 5 option clas Line 944  These can be classified in 5 option clas
944  .  .
945  .P  .P
946  All short options of  All short options of
947  .I groffer  .I \%groffer
948  are compatible with the short options of  are compatible with the short options of
949  .BR groff (@MAN1EXT@).  .BR \%groff (@MAN1EXT@).
950  .  .
951  All long options of  All long options of
952  .I groffer  .I \%groffer
953  are compatible with the long options of  are compatible with the long options of
954  .BR man (1).  .BR \%man (1).
955  .  .
956  .  .
957  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 953  are compatible with the long options of Line 960  are compatible with the long options of
960  .  .
961  As soon as one of these options is found on the command line it is  As soon as one of these options is found on the command line it is
962  executed, printed to standard output, and the running  executed, printed to standard output, and the running
963  .I groffer  .I \%groffer
964  is terminated thereafter.  is terminated thereafter.
965  .  .
966  All other arguments are ignored.  All other arguments are ignored.
# Line 961  All other arguments are ignored. Line 968  All other arguments are ignored.
968  .  .
969  .Opt_def -- apropos name  .Opt_def -- apropos name
970  Start the  Start the
971  .BR apropos (1)  .BR \%apropos (1)
972  command for searching within man page  command for searching within man\~page
973  descriptions.  descriptions.
974  .  .
975  That slightly differs from the strange behavior of the  That slightly differs from the strange behavior of the
976  .Opt_long apropos  .Opt_long apropos
977  program of  program of
978  .BR man (1),  .BR \%man (1),
979  which has no argument of its own, but takes the file arguments  which has no argument of its own, but takes the file arguments
980  instead.  instead.
981  .  .
982  Practically both concepts are compatible.  Practically both concepts are compatible.
983  .  .
984  .  .
985  .Opt_def -- apropos-data name  .Opt_def -- apropos\-data name
986  Show only the  Show only the
987  .BR apropos (1)  .BR \%apropos (1)
988  descriptions for data documents, in the  descriptions for data documents, in the
989  .BR man (7)  .BR \%man (7)
990  sections 4, 5, and 7.  sections 4, 5, and 7.
991  .  .
992  .  .
993  .Opt_def -- apropos-devel name  .Opt_def -- apropos\-devel name
994  Show only the  Show only the
995  .BR apropos (1)  .BR apropos (1)
996  descriptions for development documents, in the  descriptions for development documents, in the
# Line 991  descriptions for development documents, Line 998  descriptions for development documents,
998  sections 2, 3, and 9.  sections 2, 3, and 9.
999  .  .
1000  .  .
1001  .Opt_def -- apropos-progs name  .Opt_def -- apropos\-progs name
1002  Show only the  Show only the
1003  .BR apropos (1)  .BR \%apropos (1)
1004  descriptions for documents on programs, in the  descriptions for documents on programs, in the
1005  .BR man (7)  .BR \%man (7)
1006  sections 1, 6, and 8.  sections 1, 6, and 8.
1007  .  .
1008  .  .
# Line 1016  The display mode and the viewer programs Line 1023  The display mode and the viewer programs
1023  options.  options.
1024  .  .
1025  If none of these mode and viewer options is specified  If none of these mode and viewer options is specified
1026  .I groffer  .I \%groffer
1027  tries to find a suitable display mode automatically.  tries to find a suitable display mode automatically.
1028  .  .
1029  .  .
# Line 1034  This is useful to wipe out all former op Line 1041  This is useful to wipe out all former op
1041  and restart option processing using only the rest of the command line.  and restart option processing using only the rest of the command line.
1042  .  .
1043  .  .
1044  .Opt_def -- default-modes mode1,mode2,\*[Ellipsis]  .Opt_def -- default\-modes mode1,mode2,\*[Ellipsis]
1045  Set the sequence of modes for  Set the sequence of modes for
1046  .I auto mode  .I \%auto mode
1047  to the comma separated list given in the argument.  to the comma separated list given in the argument.
1048  .  .
1049  See  See
# Line 1046  means to try the modes Line 1053  means to try the modes
1053  .IR x ,  .IR x ,
1054  .IR ps ,  .IR ps ,
1055  and  and
1056  .I tty  .I \%tty
1057  in this sequence.  in this sequence.
1058  .  .
1059  .  .
1060  .  .
1061  .Opt_def -- dvi  .Opt_def -- dvi
1062  Equivalent to  Equivalent to
1063  .Opt_long_arg mode dvi .  .Opt_long_arg mode \%dvi .
1064  .  .
1065  .  .
1066  .Opt_def -- dvi-viewer prog  .Opt_def -- dvi\-viewer prog
1067  Set the viewer program for dvi mode.  Set the viewer program for dvi mode.
1068  .  .
1069  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
1070  .Env_var $PATH .  .Env_var $PATH .
1071  .  .
1072  Known dvi viewers inlude  Known
1073  .BR xdvi (1)  .I \%dvi
1074    viewers inlude
1075    .BR \%xdvi (1)
1076  and  and
1077  .BR dvilx (1)  .BR \%dvilx (1)
1078  .  .
1079  In each case, arguments can be provided additionally.  In each case, arguments can be provided additionally.
1080  .  .
# Line 1080  Equivalent to Line 1089  Equivalent to
1089  .Opt_long_arg mode html .  .Opt_long_arg mode html .
1090  .  .
1091  .  .
1092  .Opt_def -- html-viewer  .Opt_def -- html\-viewer
1093  Set the web browser program for viewing in  Set the web browser program for viewing in
1094  .I html  .I \%html
1095  mode.  mode.
1096  .  .
1097  Each program that accepts html input and allows the  Each program that accepts html input and allows the
1098  .BI file://localhost/ dir / file  .BI \%file://localhost/ dir / file
1099  syntax on the command line is suitable as viewer program; it can be  syntax on the command line is suitable as viewer program; it can be
1100  the path name of an executable file or a program in  the path name of an executable file or a program in
1101  .Env_var $PATH .  .Env_var $PATH .
# Line 1107  The following mode values are recognized Line 1116  The following mode values are recognized
1116  Select the automatic determination of the display mode.  Select the automatic determination of the display mode.
1117  .  .
1118  The sequence of modes that are tried can be set with the  The sequence of modes that are tried can be set with the
1119  .Opt_long default-modes  .Opt_long default\-modes
1120  option.  option.
1121  .  .
1122  Useful for restoring the default mode when a different mode was  Useful for restoring the default mode when a different mode was
# Line 1117  specified before. Line 1126  specified before.
1126  .TP  .TP
1127  .Header_CB dvi  .Header_CB dvi
1128  Display formatted input in a  Display formatted input in a
1129  .I dvi  .I \%dvi
1130  viewer program.  viewer program.
1131  .  .
1132  By default, the formatted input is displayed with the  By default, the formatted input is displayed with the
1133  .BR xdvi (1)  .BR \%xdvi (1)
1134  program.  program.
1135  .Opt_long dvi .  .Opt_long dvi .
1136  .  .
# Line 1129  program. Line 1138  program.
1138  .TP  .TP
1139  .Header_CB groff  .Header_CB groff
1140  After the file determination, switch  After the file determination, switch
1141  .I groffer  .I \%groffer
1142  to process the input like  to process the input like
1143  .BR groff (@MAN1EXT@)  .BR \%groff (@MAN1EXT@)
1144  would do .  would do.
1145  .  .
1146  This disables the  This disables the
1147  .I groffer  .I \%groffer
1148  viewing features.  viewing features.
1149  .  .
1150  .  .
# Line 1146  browser program. Line 1155  browser program.
1155  .  .
1156  By default, the existence of a sequence of standard web browsers is  By default, the existence of a sequence of standard web browsers is
1157  tested, starting with  tested, starting with
1158  .BR konqueror (1)  .BR \%konqueror (1)
1159  and  and
1160  .BR mozilla (1).  .BR \%mozilla (1).
1161  The text html viewer is  The text html viewer is
1162  .BR lynx (1).  .BR \%lynx (1).
1163  .  .
1164  .  .
1165  .TP  .TP
1166  .Header_CB pdf  .Header_CB pdf
1167  Display formatted input in a  Display formatted input in a
1168  .I PDF  .I \%PDF
1169  (Portable Document Format) viewer  (Portable Document Format) viewer
1170  program.  program.
1171  .  .
1172  By default, the input is formatted by groff using the Postscript  By default, the input is formatted by groff using the Postscript
1173  device, then it is transformed into the PDF file format using  device, then it is transformed into the PDF file format using
1174  .BR gs (1),  .BR \%gs (1),
1175  and finally displayed either with the  and finally displayed either with the
1176  .BR xpdf (1)  .BR \%xpdf (1)
1177  or the  or the
1178  .BR acroread (1)  .BR \%acroread (1)
1179  program.  program.
1180  .  .
1181  PDF has a big advantage because the text is displayed graphically and  PDF has a big advantage because the text is displayed graphically and
# Line 1181  mode is not suitable as a default device Line 1190  mode is not suitable as a default device
1190  Display formatted input in a Postscript viewer program.  Display formatted input in a Postscript viewer program.
1191  .  .
1192  By default, the formatted input is displayed with the  By default, the formatted input is displayed with the
1193  .BR ghostview (@MAN1EXT@)  .BR \%ghostview (@MAN1EXT@)
1194  program.  program.
1195  .  .
1196  .  .
1197  .TP  .TP
1198  .Header_CB text  .Header_CB text
1199  Format in a  Format in a
1200  .I groff  .I \%groff
1201  text mode and write the result to standard output without a pager or  text mode and write the result to standard output without a pager or
1202  viewer program.  viewer program.
1203  .  .
1204  The text device,  The text device,
1205  .I latin1  .I \%latin1
1206  by default, can be chosen with option  by default, can be chosen with option
1207  .Opt_short T .  .Opt_short T .
1208  .  .
# Line 1201  by default, can be chosen with option Line 1210  by default, can be chosen with option
1210  .TP  .TP
1211  .Header_CB tty  .Header_CB tty
1212  Format in a  Format in a
1213  .I groff  .I \%groff
1214  text mode and write the result to standard output using a text pager  text mode and write the result to standard output using a text pager
1215  program, even when in X Window.  program, even when in X\~\%Window.
1216  .  .
1217  .  .
1218  .TP  .TP
# Line 1231  Equivalent to Line 1240  Equivalent to
1240  .  .
1241  .P  .P
1242  The following modes do not use the  The following modes do not use the
1243  .I groffer  .I \%groffer
1244  viewing features.  viewing features.
1245  .  .
1246  They are only interesting for advanced applications.  They are only interesting for advanced applications.
# Line 1240  They are only interesting for advanced a Line 1249  They are only interesting for advanced a
1249  .TP  .TP
1250  .Header_CB groff  .Header_CB groff
1251  Generate device output with plain  Generate device output with plain
1252  .I groff  .I \%groff
1253  without using the special viewing features of  without using the special viewing features of
1254  .IR groffer .  .IR \%groffer .
1255  If no device was specified by option  If no device was specified by option
1256  .Opt_short T  .Opt_short T
1257  the  the
1258  .I groff  .I \%groff
1259  default  default
1260  .B ps  .B \%ps
1261  is assumed.  is assumed.
1262  .  .
1263  .  .
# Line 1268  Equivalent to Line 1277  Equivalent to
1277  .  .
1278  .Opt_def -- pdf-viewer prog  .Opt_def -- pdf-viewer prog
1279  Set the viewer program for  Set the viewer program for
1280  .I pdf  .I \%pdf
1281  mode.  mode.
1282  .  .
1283  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 1284  Equivalent to Line 1293  Equivalent to
1293  .  .
1294  .Opt_def -- ps-viewer prog  .Opt_def -- ps-viewer prog
1295  Set the viewer program for  Set the viewer program for
1296  .I ps  .I \%ps
1297  mode.  mode.
1298  .  .
1299  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
1300  .Env_var $PATH .  .Env_var $PATH .
1301  .  .
1302  Common Postscript viewers inlude  Common Postscript viewers inlude
1303  .BR gv (1),  .BR \%gv (1),
1304  .BR ghostview (1),  .BR \%ghostview (1),
1305  and  and
1306  .BR gs (1),  .BR \%gs (1),
1307  .  .
1308  In each case, arguments can be provided additionally.  In each case, arguments can be provided additionally.
1309  .  .
# Line 1309  Equivalent to Line 1318  Equivalent to
1318  .Opt_long_arg mode tty .  .Opt_long_arg mode tty .
1319  .  .
1320  .  .
1321  .Opt_def -- tty-viewer  .Opt_def -- tty\-viewer
1322  Choose tty display mode, that means displaying in a text pager even  Choose tty display mode, that means displaying in a text pager even
1323  when in X; eqivalent to  when in X; eqivalent to
1324  .Opt_long_arg mode tty .  .Opt_long_arg mode tty .
# Line 1320  Equivalent to Line 1329  Equivalent to
1329  .Opt_long_arg mode html .  .Opt_long_arg mode html .
1330  .  .
1331  .  .
1332  .Opt_def -- www-viewer prog  .Opt_def -- www\-viewer prog
1333  Equivalent to  Equivalent to
1334  .Opt_long html-viewer .  .Opt_long html\-viewer .
1335  .  .
1336  .  .
1337  .Opt_def - X -- X -- x  .Opt_def - X -- X -- x
# Line 1330  Equivalent to Line 1339  Equivalent to
1339  .Opt_long_arg mode X .  .Opt_long_arg mode X .
1340  .  .
1341  .  .
1342  .Opt_def -- X-viewer -- x-viewer prog  .Opt_def -- X\-viewer -- x\-viewer prog
1343  Set the viewer program for  Set the viewer program for
1344  .I x  .I x
1345  mode.  mode.
# Line 1350  In each case, arguments can be provided Line 1359  In each case, arguments can be provided
1359  .Opt_--  .Opt_--
1360  Signals the end of option processing; all remaining arguments are  Signals the end of option processing; all remaining arguments are
1361  interpreted as  interpreted as
1362  .I filespec  .I \%filespec
1363  parameters.  parameters.
1364  .  .
1365  .  .
1366  .P  .P
1367  Besides these,  Besides these,
1368  .I groffer  .I \%groffer
1369  accepts all arguments that are valid for the  accepts all arguments that are valid for the
1370  .BR groff (@MAN1EXT@)  .BR \%groff (@MAN1EXT@)
1371  program.  program.
1372  .  .
1373  All non-groffer options are sent unmodified via  All non-groffer options are sent unmodified via
1374  .I grog  .I \%grog
1375  to  to
1376  .IR groff .  .IR \%groff .
1377  .  .
1378  Postprocessors, macro packages, compatibility with classical  Postprocessors, macro packages, compatibility with classical
1379  .IR troff ,  .IR \%troff ,
1380  and much more can be manually specified.  and much more can be manually specified.
1381  .  .
1382  .  .
# Line 1401  This is the equivalent Line 1410  This is the equivalent
1410  .  .
1411  .P  .P
1412  Other useful debugging options are the  Other useful debugging options are the
1413  .I groff  .I \%groff
1414  options  options
1415  .Opt_short V  .Opt_short V
1416  and  and
# Line 1415  and option Line 1424  and option
1424  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
1425  .  .
1426  All short options of  All short options of
1427  .I groffer  .I \%groffer
1428  are compatible with the short options of  are compatible with the short options of
1429  .BR groff (@MAN1EXT@).  .BR \%groff (@MAN1EXT@).
1430  .  .
1431  The following of  The following of
1432  .I groff  .I \%groff
1433  options have either an additional special meaning within  options have either an additional special meaning within
1434  .I groffer  .I \%groffer
1435  or make sense for normal usage.  or make sense for normal usage.
1436  .  .
1437  .  .
1438  .P  .P
1439  Because of the special outputting behavior of the  Because of the special outputting behavior of the
1440  .I groff  .I \%groff
1441  options  options
1442  .Opt_short V  .Opt_short V
1443  and  and
1444  .Opt_short Z  .Opt_short Z
1445  .I groffer  .I \%groffer
1446  was designed to be switched into  was designed to be switched into
1447  .I groff  .I \%groff
1448  mode by these; the  mode by these; the
1449  .I groffer  .I \%groffer
1450  viewing features are disabled there.  viewing features are disabled there.
1451  .  .
1452  The other  The other
1453  .I groff  .I \%groff
1454  options do not switch the mode, but allow to customize the formatting  options do not switch the mode, but allow to customize the formatting
1455  process.  process.
1456  .  .
# Line 1455  sequences. Line 1464  sequences.
1464  .  .
1465  .Opt_def - m file  .Opt_def - m file
1466  Add  Add
1467  .I file  .I \%file
1468  as a  as a
1469  .I groff  .I \%groff
1470  macro file.  macro file.
1471  .  .
1472  This is useful in case it cannot be recognized automatically.  This is useful in case it cannot be recognized automatically.
# Line 1465  This is useful in case it cannot be reco Line 1474  This is useful in case it cannot be reco
1474  .  .
1475  .Opt_def - P opt_or_arg  .Opt_def - P opt_or_arg
1476  Send the argument  Send the argument
1477  .I opt_or_arg  .I \%opt_or_arg
1478  as an option or option argument to the actual  as an option or option argument to the actual
1479  .I groff  .I \%groff
1480  postprocessor.  postprocessor.
1481  .  .
1482  .  .
1483  .Opt_def - T -- device devname  .Opt_def - T -- device devname
1484  .  .
1485  This option determines  This option determines
1486  .IR groff 's  .IR \%groff 's
1487  output device.  output device.
1488  .  .
1489  The most important devices are the text output devices for referring  The most important devices are the text output devices for referring
1490  to the different character sets, such as  to the different character sets, such as
1491  .BR ascii ,  .BR \%ascii ,
1492  .BR utf8 ,  .BR \%utf8 ,
1493  .BR latin1 ,  .BR \%latin1 ,
1494  and others.  and others.
1495  .  .
1496  Each of these arguments switches  Each of these arguments switches
1497  .I groffer  .I \%groffer
1498  into a text mode using this device, to  into a text mode using this device, to
1499  .I mode tty  .I mode \%tty
1500  if the actual mode is not a text mode.  if the actual mode is not a text mode.
1501  .  .
1502  The following  The following
1503  .I devname  .I \%devname
1504  arguments are mapped to the corresponding  arguments are mapped to the corresponding
1505  .I groffer  .I \%groffer
1506  .Opt_long_arg mode \fIdevname\fR  .Opt_long_arg mode \fIdevname\fR
1507  option:  option:
1508  .BR dvi ,  .BR \%dvi ,
1509  .BR html ,  .BR \%html ,
1510  and  and
1511  .BR ps .  .BR \%ps .
1512  All  All
1513  .B X*  .B \%X*
1514  arguments are mapped to mode  arguments are mapped to mode
1515  .BR X .  .BR \%X .
1516  Each other  Each other
1517  .I devname  .I \%devname
1518  argument switches to  argument switches to
1519  .I mode groff  .I mode \%groff
1520  using this device.  using this device.
1521  .  .
1522  .  .
1523  .Opt_def - V  .Opt_def - V
1524  Switch into  Switch into
1525  .I groff  .I \%groff
1526  mode and show only the  mode and show only the
1527  .I groff  .I \%groff
1528  calling pipe without formatting the input.  calling pipe without formatting the input.
1529  .  .
1530  This an advanced option from  This an advanced option from
1531  .BR groff (@MAN1EXT@) ,  .BR \%groff (@MAN1EXT@) ,
1532  only useful for debugging.  only useful for debugging.
1533  .  .
1534  .  .
# Line 1527  only useful for debugging. Line 1536  only useful for debugging.
1536  was made equivalent to  was made equivalent to
1537  .Opt_long_arg mode x ;  .Opt_long_arg mode x ;
1538  this slightly enhances the facility of  this slightly enhances the facility of
1539  .IR groff 's  .IR \%groff 's
1540  option.  option.
1541  .  .
1542  .  .
1543  .Opt_def - Z -- intermediate-output -- ditroff  .Opt_def - Z -- intermediate-output -- ditroff
1544  Switch into  Switch into
1545  .I groff  .I \%groff
1546  mode and format the input with  mode and format the input with
1547  .I groff  .I \%groff
1548  intermediate output without postprocessing; see  intermediate output without postprocessing; see
1549  .BR groff_out (@MAN1EXT@).  .BR \%groff_out (@MAN1EXT@).
1550  This is equivalent to option  This is equivalent to option
1551  .Opt_long ditroff  .Opt_long ditroff
1552  of  of
1553  .IR man ,  .IR \%man ,
1554  which can be used as well.  which can be used as well.
1555  .  .
1556  .  .
1557  .P  .P
1558  All other  All other
1559  .I groff  .I \%groff
1560  options are supported by  options are supported by
1561  .IR groffer ,  .IR \%groffer ,
1562  but they are just transparently transferred to  but they are just transparently transferred to
1563  .I groff  .I \%groff
1564  without any intervention.  without any intervention.
1565  .  .
1566  The options that are not explicitly handled by  The options that are not explicitly handled by
1567  .I groffer  .I \%groffer
1568  are transparently passed to  are transparently passed to
1569  .IR groff .  .IR \%groff .
1570  .  .
1571  Therefore these transparent options are not documented here, but in  Therefore these transparent options are not documented here, but in
1572  .BR groff (@MAN1EXT@).  .BR \%groff (@MAN1EXT@).
1573  Due to the automatism in  Due to the automatism in
1574  .IR groffer ,  .IR \%groffer ,
1575  none of these  none of these
1576  .I groff  .I \%groff
1577  options should be needed, except for advanced usage.  options should be needed, except for advanced usage.
1578  .  .
1579  .  .
# Line 1575  options should be needed, except for adv Line 1584  options should be needed, except for adv
1584  The following long options were adapted from the corresponding X  The following long options were adapted from the corresponding X
1585  Toolkit options.  Toolkit options.
1586  .  .
1587  .I groffer  .I \%groffer
1588  will pass them to the actual viewer program if it is an X Window  will pass them to the actual viewer program if it is an X Window
1589  program.  program.
1590  .  .
# Line 1587  Unfortunately these options use the old Line 1596  Unfortunately these options use the old
1596  long options.  long options.
1597  .  .
1598  For  For
1599  .I groffer  .I \%groffer
1600  that was changed to the standard with using a double minus for long  that was changed to the standard with using a double minus for long
1601  options, for example,  options, for example,
1602  .I groffer  .I \%groffer
1603  uses the option  uses the option
1604  .Opt_long font  .Opt_long font
1605  for the  for the
# Line 1601  option Line 1610  option
1610  .  .
1611  .P  .P
1612  See  See
1613  .BR X (1),  .BR \%X (1),
1614  .BR X (7),  .BR \%X (7),
1615  and the documentation on the X toolkit options for more details on  and the documentation on the X toolkit options for more details on
1616  these options and their arguments.  these options and their arguments.
1617  .  .
# Line 1627  window. Line 1636  window.
1636  .  .
1637  .Opt_def -- display X-display  .Opt_def -- display X-display
1638  Set the X display on which the viewer program shall be started, see the  Set the X display on which the viewer program shall be started, see the
1639  .I X Window  .I X\~\%Window
1640  documentation for the syntax of the argument.  documentation for the syntax of the argument.
1641  .  .
1642  .  .
# Line 1656  Set the geometry of the display window, Line 1665  Set the geometry of the display window,
1665  starting position.  starting position.
1666  .  .
1667  See  See
1668  .BR X (7)  .BR \%X (7)
1669  for the syntax of the argument.  for the syntax of the argument.
1670  .  .
1671  .  .
# Line 1669  and Line 1678  and
1678  .BR 100 .  .BR 100 .
1679  .  .
1680  Actually, the default resolution for  Actually, the default resolution for
1681  .I groffer  .I \%groffer
1682  is set to  is set to
1683  .BR 75 .  .BR 75 .
1684  .  .
# Line 1691  Set X resource. Line 1700  Set X resource.
1700  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
1701  .  .
1702  The long options of  The long options of
1703  .I groffer  .I \%groffer
1704  were synchronized with the long options of  were synchronized with the long options of
1705  .IR GNU man .  .IR GNU man .
1706  .  .
1707  All long options of  All long options of
1708  .I GNU man  .I GNU man
1709  are recognized, but not all of these options are important to  are recognized, but not all of these options are important to
1710  .IR groffer ,  .IR \%groffer ,
1711  so most of them are just ignored.  so most of them are just ignored.
1712  .  .
1713  .  .
1714  .P  .P
1715  The following two options were added to  The following two options were added to
1716  .I groffer  .I \%groffer
1717  for choosing whether the file name arguments are interpreted as names  for choosing whether the file name arguments are interpreted as names
1718  for local files or as a search pattern for man pages.  for local files or as a search pattern for man pages.
1719  .  .
# Line 1713  The default is looking up for local file Line 1722  The default is looking up for local file
1722  .  .
1723  .Opt_def -- man  .Opt_def -- man
1724  Check the non-option command line arguments  Check the non-option command line arguments
1725    .nh
1726  .RI ( filespecs )  .RI ( filespecs )
1727    .hy
1728  first on being man\~pages, then whether they represent an existing  first on being man\~pages, then whether they represent an existing
1729  file.  file.
1730  .  .
1731  By default, a  By default, a
1732  .I filespec  .I \%filespec
1733  is first tested whether it is an existing file.  is first tested whether it is an existing file.
1734  .  .
1735  .  .
# Line 1735  option. Line 1746  option.
1746  In the following, the  In the following, the
1747  .I man  .I man
1748  options that have a special meaning for  options that have a special meaning for
1749  .I groffer  .I \%groffer
1750  are documented.  are documented.
1751  .  .
1752  .  .
# Line 1745  The full set of long and short options o Line 1756  The full set of long and short options o
1756  program can be passed via the environment variable  program can be passed via the environment variable
1757  .Env_var $MANOPT ;  .Env_var $MANOPT ;
1758  see  see
1759  .BR man (1)  .BR \%man (1)
1760  if your system has  if your system has
1761  .I GNU man  .I GNU man
1762  installed.  installed.
# Line 1762  In text modes, display ASCII translation Line 1773  In text modes, display ASCII translation
1773  .  .
1774  .Opt_def -- ditroff  .Opt_def -- ditroff
1775  Eqivalent to  Eqivalent to
1776  .I groffer  .I \%groffer
1777  .Opt_short Z .  .Opt_short Z .
1778  .  .
1779  .  .
1780  .Opt_def -- extension suffix  .Opt_def -- extension suffix
1781  Restrict man\~page search to file names that have  Restrict man\~page search to file names that have
1782  .I suffix  .I \%suffix
1783  appended to their section element.  appended to their section element.
1784  .  .
1785  For example, in the file name  For example, in the file name
1786  .I /usr/share/man/man3/terminfo.3ncurses.gz  .I \%/usr/share/man/man3/terminfo.3ncurses.gz
1787  the man\~page extension is  the man\~page extension is
1788  .IR ncurses .  .IR \%ncurses .
1789  .  .
1790  .  .
1791  .Opt_def -- locale language  .Opt_def -- locale language
# Line 1795  call to Line 1806  call to
1806  .Opt_long location .  .Opt_long location .
1807  .  .
1808  This was added by  This was added by
1809  .IR groffer .  .IR \%groffer .
1810  .  .
1811  .  .
1812  .Opt_def -- manpath "'dir1:dir2:\*[Ellipsis]'"  .Opt_def -- manpath "'dir1:dir2:\*[Ellipsis]'"
# Line 1808  is disabled. Line 1819  is disabled.
1819  .  .
1820  .Opt_def -- pager  .Opt_def -- pager
1821  Set the pager program in tty mode; default is  Set the pager program in tty mode; default is
1822  .IR less .  .IR \%less .
1823  This is equivalent to  This is equivalent to
1824  .Opt_long tty-viewer .  .Opt_long tty-viewer .
1825  .  .
# Line 1821  a colon-separated list. Line 1832  a colon-separated list.
1832  .  .
1833  .Opt_def -- systems "'sys1,sys2,\*[Ellipsis]'"  .Opt_def -- systems "'sys1,sys2,\*[Ellipsis]'"
1834  Search for man pages for the given operating systems; the argument  Search for man pages for the given operating systems; the argument
1835  .I systems  .I \%systems
1836  is a comma-separated list.  is a comma-separated list.
1837  .  .
1838  .  .
# Line 1837  Eqivalent to Line 1848  Eqivalent to
1848  .  .
1849  .P  .P
1850  Additionally, the following short option of  Additionally, the following short option of
1851  .I man  .I \%man
1852  is supported as well.  is supported as well.
1853  .  .
1854  .  .
# Line 1846  is supported as well. Line 1857  is supported as well.
1857  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
1858  .  .
1859  A  A
1860  .I filespec  .I \%filespec
1861  parameter is an argument meaning an input source, such as a file name  parameter is an argument meaning an input source, such as a file name
1862  or template for searching man\~pages.  or template for searching man\~pages.
1863  .  .
1864  These input sources are collected and composed into a single output  These input sources are collected and composed into a single output
1865  file such as  file such as
1866  .I groff  .I \%groff
1867  does.  does.
1868  .  .
1869  .  .
1870  .P  .P
1871  The strange POSIX behavior that maps all arguments behind the first  The strange POSIX behavior that maps all arguments behind the first
1872  non-option argument into  non-option argument into
1873  .I filespec  .I \%filespec
1874  arguments is ignored.  arguments is ignored.
1875  .  .
1876  The GNU behavior to recognize options even when mixed with  The GNU behavior to recognize options even when mixed with
1877  .I filespec  .I \%filespec
1878  arguments is used througout.  arguments is used througout.
1879  .  .
1880  But, as usual, the double minus argument  But, as usual, the double minus argument
1881  .Opt_long  .Opt_long
1882  still takes all following arguments as  still takes all following arguments as
1883  .IR filespecs .  .I \%filespec
1884    arguments.
1885  .  .
1886  .  .
1887  .P  .P
1888  Each  Each
1889  .I filespec  .I \%filespec
1890  parameters can have one of the following forms.  parameters can have one of the following forms.
1891  .  .
1892  .  .
1893  .P  .P
1894  No  No
1895  .I filespec  .I \%filespec
1896  parameters means that  parameters means that
1897  .I groffer  .I \%groffer
1898  waits for standard input.  waits for standard input.
1899  .  .
1900  The minus option  The minus option
# Line 1890  The minus option Line 1902  The minus option
1902  stands for standard input, too, but can occur several times.  stands for standard input, too, but can occur several times.
1903  .  .
1904  Next  Next
1905  .I filespec  .I \%filespec
1906  is tested whether it is the path name of an existing file.  is tested whether it is the path name of an existing file.
1907  .  .
1908  Otherwise it is assumed as a searching pattern for a man\~page.  Otherwise it is assumed as a searching pattern for a man\~page.
# Line 1918  means this scheme. Line 1930  means this scheme.
1930  .  .
1931  .P  .P
1932  The internal precedence of  The internal precedence of
1933  .I man  .I \%man
1934  for searching man pages with the same name within several sections  for searching man pages with the same name within several sections
1935  goes according to the classical single-character sequence.  goes according to the classical single-character sequence.
1936  .  .
# Line 1926  On some systems, this single character c Line 1938  On some systems, this single character c
1938  string.  string.
1939  .  .
1940  But the special  But the special
1941  .I groffer  .I \%groffer
1942  man page facility is based on the classical single character sections.  man\~page facility is based on the classical single character sections.
1943  .  .
1944  .  .
1945  .P  .P
1946  .BI man: name ( section )  .BI \%man: name ( section )
1947  and  and
1948  .IB name ( section )  .IB \%name ( section )
1949  search the man\~page  search the man\~page
1950  .I name  .I \%name
1951  in man\~section\~\c  in man\~section\~\c
1952  .IR section ,  .IR \%section ,
1953  where  where
1954  .I section  .I \%section
1955  can be any string, but it must exist in the  can be any string, but it must exist in the
1956  .I man  .I \%man
1957  system.  system.
1958  .  .
1959  .  .
# Line 1950  Next some patterns based on the Line 1962  Next some patterns based on the
1962  .I classical man sections  .I classical man sections
1963  were constructed.  were constructed.
1964  .  .
1965  .BI man: name . s  .BI \%man: name . s
1966  and  and
1967  .IB name . s  .IB \%name . s
1968  search for a man\~page  search for a man\~page
1969  .I name  .I \%name
1970  in man\~section  in man\~section
1971  .I s  .I s
1972  if  if
# Line 1964  is a Line 1976  is a
1976  mentioned above.  mentioned above.
1977  .  .
1978  Otherwise search for a man\~page named  Otherwise search for a man\~page named
1979  .IR name.s  .IR \%name.s
1980  in the lowest  in the lowest
1981  .I man  .I man\~\c
1982  section.  .IR section .
1983  .  .
1984  .  .
1985  .P  .P
1986  Now  Now
1987  .BI man: name  .BI \%man: name
1988  searches for a man\~page in the lowest man\~section that has a  searches for a man\~page in the lowest man\~section that has a
1989  document called  document called
1990  .IR name .  .IR \%name .
1991  .  .
1992  .  .
1993  .P  .P
1994  The pattern  The pattern
1995  .I "s name"  .I \%s\~name
1996  originates from a strange argument parsing of the  originates from a strange argument parsing of the
1997  .I man  .I man
1998  program.  program.
# Line 1990  If Line 2002  If
2002  is a  is a
2003  .I classical man section  .I classical man section
2004  interpret it as a search for a man\~page called  interpret it as a search for a man\~page called
2005  .I name  .I \%name
2006  in man\~section  in man\~section
2007  .IR s ,  .IR s ,
2008  otherwise interpret  otherwise interpret
2009  .I s  .I s
2010  as a file argument and  as a file argument and
2011  .I name  .I \%name
2012  as another  as another
2013  .I filespec  .I \%filespec
2014  argument.  argument.
2015  .  .
2016  .  .
2017  .P  .P
2018  We are left with the argument  We are left with the argument
2019  .I name  .I \%name
2020  which is not an existing file.  which is not an existing file.
2021  .  .
2022  So this searches for the man\~page called  So this searches for the man\~page called
2023  .I name  .I \%name
2024  in the lowest man\~section that has a document for this name.  in the lowest man\~section that has a document for this name.
2025  .  .
2026  .  .
# Line 2016  in the lowest man\~section that has a do Line 2028  in the lowest man\~section that has a do
2028  Several file name arguments can be supplied.  Several file name arguments can be supplied.
2029  .  .
2030  They are mixed by  They are mixed by
2031  .I groff  .I \%groff
2032  into a single document.  into a single document.
2033  .  .
2034  Note that the set of option arguments must fit to all of these file  Note that the set of option arguments must fit to all of these file
2035  arguments.  arguments.
2036  .  .
2037  So they should have at least the same style of the  So they should have at least the same style of the
2038  .I groff  .I \%groff
2039  language.  language.
2040  .  .
2041  .  .
# Line 2032  language. Line 2044  language.
2044  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2045  .  .
2046  By default, the  By default, the
2047  .I groffer  .I \%groffer
2048  program collects all input into a single file, formats it with the  program collects all input into a single file, formats it with the
2049  .I groff  .I \%groff
2050  program for a certain device, and then chooses a suitable viewer  program for a certain device, and then chooses a suitable viewer
2051  program.  program.
2052  .  .
2053  The device and viewer process in  The device and viewer process in
2054  .I groffer  .I \%groffer
2055  is called a  is called a
2056  .IR mode .  .IR \%mode .
2057  .  .
2058  The mode and viewer of a running  The mode and viewer of a running
2059  .I groffer  .I \%groffer
2060  program is selected automatically, but the user can also choose it  program is selected automatically, but the user can also choose it
2061  with options.  with options.
2062  .  .
# Line 2062  option that is constructed like Line 2074  option that is constructed like
2074  .P  .P
2075  Several different modes are offered, graphical X modes, text modes,  Several different modes are offered, graphical X modes, text modes,
2076  and some direct  and some direct
2077  .I groff  .I \%groff
2078  modes for debugging and development.  modes for debugging and development.
2079  .  .
2080  .  .
2081  .P  .P
2082  By default,  By default,
2083  .I groffer  .I \%groffer
2084  first tries whether  first tries whether
2085  .B x  .B x
2086  mode is possible, then  mode is possible, then
2087  .B ps  .B \%ps
2088  mode, and finally  mode, and finally
2089  .B tty  .B \%tty
2090  mode.  mode.
2091  .  .
2092  This mode testing sequence for  This mode testing sequence for
2093  .B auto  .B \%auto
2094  mode can be changed by specifying a comma separated list of modes  mode can be changed by specifying a comma separated list of modes
2095  with the option  with the option
2096  .Opt_long default\-modes.  .Opt_long default\-modes.
# Line 2093  active in every mode. Line 2105  active in every mode.
2105  .SS "Graphical Display Modes"  .SS "Graphical Display Modes"
2106  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2107  .  .
2108  The graphical display modes work only in the X Window environment (or  The graphical display modes work only in the
2109  similar implementations within other windowing environments).  .I X\~Window environment
2110    (or similar implementations within other windowing environments).
2111  .  .
2112  The environment variable  The environment variable
2113  .Env_var $DISPLAY  .Env_var $DISPLAY
# Line 2103  and the option Line 2116  and the option
2116  are used for specifying the X display to be used.  are used for specifying the X display to be used.
2117  .  .
2118  If neither is given,  If neither is given,
2119  .I groffer  .I \%groffer
2120  assumes that no X and changes to one text mode.  assumes that no X and changes to one text mode.
2121  .  .
2122  You can change this automatic behavior by the option  You can change this automatic behavior by the option
# Line 2127  mode), Line 2140  mode),
2140  .  .
2141  .Topic  .Topic
2142  in a Postscript viewer  in a Postscript viewer
2143    .nh
2144  .RI ( ps  .RI ( ps
2145  mode),  mode),
2146    .hy
2147  .  .
2148  .Topic  .Topic
2149  in a dvi viewer program  in a dvi viewer program
2150    .nh
2151  .RI ( dvi  .RI ( dvi
2152  mode),  mode),
2153    .hy
2154  .  .
2155  .Topic  .Topic
2156  in a PDF viewer  in a PDF viewer
2157    .nh
2158  .RI ( pdf  .RI ( pdf
2159  mode),  mode),
2160    .hy
2161  .  .
2162  .Topic  .Topic
2163  in a web browser  in a web browser
2164    .nh
2165  .RI ( html  .RI ( html
2166  or  or
2167  .I www  .I www
2168  mode),  mode),
2169    .hy
2170  .RE  .RE
2171  .  .
2172  .  .
2173  .P  .P
2174  The  The
2175  .I pdf  .I \%pdf
2176  mode has a major advantage \[em] it is the only graphical diplay mode  mode has a major advantage \[em] it is the only graphical diplay mode
2177  that allows to search for text within the viewer; this can be a really  that allows to search for text within the viewer; this can be a really
2178  important feature.  important feature.
# Line 2165  These graphical viewers can be customize Line 2186  These graphical viewers can be customize
2186  Toolkit.  Toolkit.
2187  .  .
2188  But the  But the
2189  .I groffer  .I \%groffer
2190  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
2191  the X Window Toolkit.  the
2192    .I X\~Window\~\c
2193    .IR Toolkit .
2194  .  .
2195  .  .
2196  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 2175  the X Window Toolkit. Line 2198  the X Window Toolkit.
2198  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2199  .  .
2200  There are to modes for text output, mode  There are to modes for text output, mode
2201  .I text  .I \%text
2202  for plain output without a pager and mode  for plain output without a pager and mode
2203  .I tty  .I \%tty
2204  for a text output on a text terminal using some pager program.  for a text output on a text terminal using some pager program.
2205  .  .
2206  .  .
# Line 2185  for a text output on a text terminal usi Line 2208  for a text output on a text terminal usi
2208  If the variable  If the variable
2209  .Env_var $DISPLAY  .Env_var $DISPLAY
2210  is not set or empty, groffer assumes that it should use  is not set or empty, groffer assumes that it should use
2211  .I tty  .I \%tty
2212  mode.  mode.
2213  .  .
2214  .  .
2215  .P  .P
2216  In the actual implementation, the groff output device  In the actual implementation, the groff output device
2217  .I latin1  .I \%latin1
2218  is chosen for text modes.  is chosen for text modes.
2219  .  .
2220  This can be changed by specifying option  This can be changed by specifying option
# Line 2208  and Line 2231  and
2231  or by the environment variable  or by the environment variable
2232  .Env_var $PAGER .  .Env_var $PAGER .
2233  If all of this is not used the  If all of this is not used the
2234  .BR less (1)  .BR \%less (1)
2235  program with the option  program with the option
2236  .Opt_short r  .Opt_short r
2237  for correctly displaying control sequences is used as the default  for correctly displaying control sequences is used as the default
# Line 2220  pager. Line 2243  pager.
2243  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2244  .  .
2245  These modes use the  These modes use the
2246  .I groffer  .I \%groffer
2247  file determination and decompression.  file determination and decompression.
2248  .  .
2249  This is combined into a single input file that is fed directly into  This is combined into a single input file that is fed directly into
2250  .I groff  .I \%groff
2251  with different strategy without the  with different strategy without the
2252  .I groffer  .I \%groffer
2253  viewing facilities.  viewing facilities.
2254  .  .
2255  These modes are regarded as advanced, they are useful for debugging  These modes are regarded as advanced, they are useful for debugging
# Line 2235  and development purposes. Line 2258  and development purposes.
2258  .  .
2259  .P  .P
2260  The  The
2261  .I source  .I \%source
2262  mode with just displays the generated input.  mode with just displays the generated input.
2263  .  .
2264  The  The
2265  .I groff  .I \%groff
2266  mode passes the input to  mode passes the input to
2267  .I groff  .I \%groff
2268  using only some suitable options provided to  using only some suitable options provided to
2269  .IR groffer .  .IR \%groffer .
2270  .  .
2271  This enables the user to save the generated output into a file or pipe  This enables the user to save the generated output into a file or pipe
2272  it into another program.  it into another program.
# Line 2251  it into another program. Line 2274  it into another program.
2274  .  .
2275  .P  .P
2276  In  In
2277  .I groff  .I \%groff
2278  mode, the option  mode, the option
2279  .Opt_short Z  .Opt_short Z
2280  disables post-processing, thus producing the  disables post-processing, thus producing the
2281    .nh
2282  .I groff intermediate  .I groff intermediate
2283  .IR output .  .IR output .
2284    .hy
2285  .  .
2286  In this mode, the input is formatted, but not postprocessed; see  In this mode, the input is formatted, but not postprocessed; see
2287  .BR groff_out (@MAN5EXT@)  .BR \%groff_out (@MAN5EXT@)
2288  for details.  for details.
2289  .  .
2290  .  .
2291  .P  .P
2292  All  All
2293  .I groff  .I \%groff
2294  short options are supported by  short options are supported by
2295  .IR groffer .  .IR \%groffer .
2296  .  .
2297  .  .
2298  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 2304  The groffer program provides a search fa Line 2329  The groffer program provides a search fa
2329  .  .
2330  All long options, all environment variables, and most of the  All long options, all environment variables, and most of the
2331  functionality of the GNU  functionality of the GNU
2332  .BR man (1)  .BR \%man (1)
2333  program were implemented.  program were implemented.
2334  .  .
2335  This inludes the extended file names of man\~pages, for example,  This inludes the extended file names of man\~pages, for example,
2336  the man\~page of  the man\~page of
2337  .I groff  .I \%groff
2338  in man\~section 7 may be stored under  in man\~section 7 may be stored under
2339  .File_name /usr/share/man/man7/groff.7.gz ,  .File_name /usr/share/man/man7/groff.7.gz ,
2340  where  where
2341  .File_name /usr/share/man/  .File_name /usr/share/man/
2342  is part of the man\~path, the subdirectory  is part of the man\~path, the subdirectory
2343  .I man7  .I \%man7
2344  and the file extension  and the file extension
2345  .I .7  .I .7
2346  refer to the man\~section 7;  refer to the man\~section 7;
2347  .I .gz  .I \%.gz
2348  shows the compression of the file.  shows the compression of the file.
2349  .  .
2350  .  .
# Line 2367  is searched for man\~pages. Line 2392  is searched for man\~pages.
2392  .  .
2393  .Topic  .Topic
2394  If this does not work, the  If this does not work, the
2395  .BR manpath (1)  .BR \%manpath (1)
2396  program for determining a path of man directories is tried.  program for determining a path of man directories is tried.
2397  .  .
2398  .  .
# Line 2377  system specific man\~pages are added to Line 2402  system specific man\~pages are added to
2402  is determined automatically.  is determined automatically.
2403  .  .
2404  For example, both  For example, both
2405  .I /usr/share/man/linux/fr  .File_name /usr/share/man/linux/fr
2406  and  and
2407  .I /usr/share/man/fr/linux  .File_name /usr/share/man/fr/linux
2408  for french linux man\~pages are found.  for french linux man\~pages are found.
2409  .  .
2410  The language and operating system names are determined from both  The language and operating system names are determined from both
# Line 2412  highest to lowest precedence: Line 2437  highest to lowest precedence:
2437  The language locale is usually specified in the POSIX 1003.1 based  The language locale is usually specified in the POSIX 1003.1 based
2438  format:  format:
2439  .P  .P
2440    .nh
2441  \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[]\
2442  \f[I]<character-set>\f[][\f[CB],\f[]\f[I]<version>\f[]]]],  \f[I]<character-set>\f[][\f[CB],\f[]\f[I]<version>\f[]]]],
2443    .hy
2444  .P  .P
2445  but the two-letter code in  but the two-letter code in
2446    .nh
2447  .I <language>  .I <language>
2448    .hy
2449  is sufficient for most purposes.  is sufficient for most purposes.
2450  .  .
2451  .  .
2452  .P  .P
2453  If no man\~pages for a complicated locale are found the country part  If no man\~pages for a complicated locale are found the country part
2454  consisting of the first two characters (without the `\f[CB]_\f[]',  consisting of the first two characters (without the `\f[CB]_\f[]',
2455  `\f[CB].\f[]', and `\f[CB],\f[]', parts) of the locale is searched as  `\f[CB].\f[]', and `\f[CB],\f[]' parts) of the locale is searched as
2456  well.  well.
2457  .  .
2458  .  .
# Line 2493  or environment variable Line 2522  or environment variable
2522  .  .
2523  .P  .P
2524  For further details on man\~page searching, see  For further details on man\~page searching, see
2525  .BR man (1).  .BR \%man (1).
2526  .  .
2527  .  .
2528  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 2504  The program has a decompression facility Line 2533  The program has a decompression facility
2533  .  .
2534  If standard input or a file that was retrieved from the command line  If standard input or a file that was retrieved from the command line
2535  parameters is compressed with a format that is supported by either  parameters is compressed with a format that is supported by either
2536  .BR gzip (1)  .BR \%gzip (1)
2537  or  or
2538  .BR bzip2 (1)  .BR \%bzip2 (1)
2539  it is decompressed on-the-fly.  it is decompressed on-the-fly.
2540  .  .
2541  This includes the GNU  This includes the GNU
2542  .BR .gz ,  .BR \%.gz ,
2543  .BR .bz2 ,  .BR \%.bz2 ,
2544  and the traditional  and the traditional
2545  .B .Z  .B \%.Z
2546  compression.  compression.
2547  .  .
2548  The program displays the concatenation of all decompressed input in  The program displays the concatenation of all decompressed input in
# Line 2528  The groffer programs supports many syste Line 2557  The groffer programs supports many syste
2557  courtesy of other programs.  courtesy of other programs.
2558  .  .
2559  All environment variables of  All environment variables of
2560  .BR groff (@MAN1EXT@)  .BR \%groff (@MAN1EXT@)
2561  and GNU  and GNU
2562  .BR man (1)  .BR \%man (1)
2563  and some standard system variables are honored.  and some standard system variables are honored.
2564  .  .
2565  .  .
# Line 2555  be quoted. Line 2584  be quoted.
2584  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2585  .  .
2586  The groffer program is a shell script that is run through  The groffer program is a shell script that is run through
2587  .BR /bin/sh ,  .File_name /bin/sh ,
2588  which can be internally linked to programs like  which can be internally linked to programs like
2589  .BR bash (1).  .BR \%bash (1).
2590  The corresponding system environment is automatically effective.  The corresponding system environment is automatically effective.
2591  .  .
2592  The following variables have a special meaning for groffer.  The following variables have a special meaning for groffer.
# Line 2590  is interpreted as the locale, the langua Line 2619  is interpreted as the locale, the langua
2619  retrieving man\~pages.  retrieving man\~pages.
2620  .  .
2621  A locale name is typically of the form  A locale name is typically of the form
2622    .nh
2623  .IR language [\c  .IR language [\c
2624  .B _\c  .B _\c
2625  .IR territory [\c  .IR territory [\c
# Line 2597  A locale name is typically of the form Line 2627  A locale name is typically of the form
2627  .IR codeset [\c  .IR codeset [\c
2628  .B @\c  .B @\c
2629  .IR modifier ]]],  .IR modifier ]]],
2630    .hy
2631  where  where
2632  .I language  .I \%language
2633  is an ISO 639 language code,  is an ISO 639 language code,
2634  .I territory  .I \%territory
2635  is an ISO 3166 country code, and  is an ISO 3166 country code, and
2636  .I codeset  .I \%codeset
2637  is a character set or encoding identifier like ISO-8859-1 or UTF-8;  is a character set or encoding identifier like ISO-8859-1 or UTF-8;
2638  see  see
2639  .BR setlocale (3).  .BR \%setlocale (3).
2640  .  .
2641  The locale values\~\c  The locale values\~\c
2642  .B C  .B C
2643  and  and
2644  .B POSIX  .B \%POSIX
2645  stand for the default, i.e. the man\~page directories without a  stand for the default, i.e. the man\~page directories without a
2646  language prefix.  language prefix.
2647  .  .
# Line 2623  This variable can be used to set the pag Line 2654  This variable can be used to set the pag
2654  .  .
2655  For example, to disable the use of a pager completely set this  For example, to disable the use of a pager completely set this
2656  variable to the  variable to the
2657  .BR cat (1)  .BR \%cat (1)
2658  program  program
2659  .Shell_cmd PAGER=cat\~groffer\~ anything  .Shell_cmd PAGER=cat\~groffer\~ anything
2660  .  .
# Line 2643  If set to a non-empty value this chooses Line 2674  If set to a non-empty value this chooses
2674  .  .
2675  This is done internally by some shells.  This is done internally by some shells.
2676  .  .
2677  .I groffer  .I \%groffer
2678  ignores the bad POSIX behavior for option processing, that means that  ignores the bad POSIX behavior for option processing, that means that
2679  option processing will be finished as soon as a non-option argument is  option processing will be finished as soon as a non-option argument is
2680  found.  found.
2681  .  .
2682  Instead the GNU behavior of freely mixing options and  Instead the GNU behavior of freely mixing options and
2683  .I filespec  .I \%filespec
2684  arguments is used in any case.  arguments is used in any case.
2685  .  .
2686  Usually, you do not want to set this environment variable externally.  Usually, you do not want to set this environment variable externally.
# Line 2661  Usually, you do not want to set this env Line 2692  Usually, you do not want to set this env
2692  .  .
2693  The groffer program internally calls groff, so all environment  The groffer program internally calls groff, so all environment
2694  variables documented in  variables documented in
2695  .BR groff (@MAN1EXT@)  .BR \%groff (@MAN1EXT@)
2696  are internally used within groffer as well.  are internally used within groffer as well.
2697  .  .
2698  The following variables have a direct meaning for the groffer program.  The following variables have a direct meaning for the groffer program.
# Line 2669  The following variables have a direct me Line 2700  The following variables have a direct me
2700  .TP  .TP
2701  .Env_var $GROFF_TMPDIR  .Env_var $GROFF_TMPDIR
2702  If the value of this variable is an existing, writable directory,  If the value of this variable is an existing, writable directory,
2703  groffer uses it for storing its temporary files, just as groff does.  .I \%groffer
2704    uses it for storing its temporary files, just as groff does.
2705  .  .
2706  .  .
2707  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
# Line 2678  groffer uses it for storing its temporar Line 2710  groffer uses it for storing its temporar
2710  .  .
2711  Parts of the functionality of the man\~program were implemented in  Parts of the functionality of the man\~program were implemented in
2712  groffer; support for all environment variables documented in  groffer; support for all environment variables documented in
2713  .BR man (1)  .BR \%man (1)
2714  was added to groffer, but the meaning was slightly modified due to the  was added to groffer, but the meaning was slightly modified due to the
2715  different approach in groffer; but the user interface is the same.  different approach in groffer; but the user interface is the same.
2716  .  .
# Line 2700  see there for details. Line 2732  see there for details.
2732  .TP  .TP
2733  .Env_var $MANOPT  .Env_var $MANOPT
2734  This variable contains options as a preset for  This variable contains options as a preset for
2735  .BR man (1).  .BR \%man (1).
2736  As not all of these are relevant for groffer only the essential parts  As not all of these are relevant for groffer only the essential parts
2737  of its value are extracted.  of its value are extracted.
2738  .  .
# Line 2751  determined automatically. Line 2783  determined automatically.
2783  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2784  .  .
2785  The  The
2786  .I groffer  .I \%groffer
2787  program can be preconfigured by two configuration files.  program can be preconfigured by two configuration files.
2788  .  .
2789  This configuration can be overridden at each program start by command  This configuration can be overridden at each program start by command
# Line 2783  The lines with the beginning minus are a Line 2815  The lines with the beginning minus are a
2815  of $GROFFER_OPT.  of $GROFFER_OPT.
2816  .  .
2817  This easily allows to set general  This easily allows to set general
2818  .I groffer  .I \%groffer
2819  options that are used with any call of  options that are used with any call of
2820  .IR groffer .  .IR \%groffer .
2821  .  .
2822  .  .
2823  .P  .P
2824  After the transformation of the minus lines the emerging shell scripts  After the transformation of the minus lines, the emerging
2825  that are called by  configuration shell scripts are called using the `\c
2826  .I groffer  .nh
2827  using the `\c  .CB \.\~\c
 .CB .\~\c  
2828  .IR filename '  .IR filename '
2829  syntax.  .hy
2830    shell syntax within
2831    .IR \%groffer .
2832  .  .
2833  .  .
2834  .P  .P
2835  The only option that needs a minus line in the configuration files is  In the configuration files, there is only one option that really needs
2836    a line starting with a minus character because it cannot be restored
2837    by any shell tricks.
2838    .
2839    This is
2840  .Opt_long shell .  .Opt_long shell .
2841  The reason is that its argument must be called at a very early stage  The reason is that its argument must be retrieved at a very early
2842  before the whole syntax of the configuration can be transformed.  stage of
2843    .IR \%groffer .
2844  .  .
2845  .  .
2846  .P  .P
# Line 2814  Preset command line options by writing t Line 2852  Preset command line options by writing t
2852  minus sign.  minus sign.
2853  .  .
2854  .Topic  .Topic
2855  Preset environment variables recognized by groffer.  Preset environment variables recognized by
2856    .IR \%groffer .
2857  .  .
2858  .Topic  .Topic
2859  Write a function for calling a viewer program for a special  Write a function for calling a viewer program for a special
2860  .I mode  .I \%mode
2861  and feed this name into its corresponding  and feed this name into its corresponding
2862  .Opt_long \f[I]mode\f[]\-viewer  .Opt_long \f[I]mode\f[]\-viewer
2863  option.  option.
# Line 2831  in order to be recognized by groffer. Line 2870  in order to be recognized by groffer.
2870  .  .
2871  .P  .P
2872  As an example, consider the following configuration file in  As an example, consider the following configuration file in
2873  ~/.groff/groffer.conf, say.  .File_name ~/.groff/groffer.conf ,
2874    say.
2875  .  .
2876  .P  .P
2877  .ft CR  .ft CR
# Line 2857  date >>~/mygroffer.log Line 2897  date >>~/mygroffer.log
2897  .  .
2898  .P  .P
2899  This configuration sets four  This configuration sets four
2900  .I groffer  .I \%groffer
2901  options and runs two shell commands.  options (the lines starting with `-') and runs two shell commands (the
2902    rest of the script).
2903  .  .
2904  This has the following effects:  This has the following effects:
2905  .  .
2906  .  .
2907  .Topic  .Topic
 Lines starting with a  
 .B #  
 character  
 are  
 .  
 .  
 .Topic  
2908  Use  Use
2909  .B /bin/bash  .B /bin/bash
2910  as the shell to run the  as the shell to run the
2911  .I groffer  .I \%groffer
2912  script.  script.
2913  .  .
2914  .  .
2915  .Topic  .Topic
2916  Take a resolution of  Use a resolution of
2917  .B 100 dpi  .B 100\~dpi
2918  and a text color of  in all viewers that support this.
2919  .B DarkBlue  .
2920    .
2921    .Topic
2922    Use a text color of
2923    .B \%DarkBlue
2924  in all viewers that support this.  in all viewers that support this.
2925  .  .
2926  .  .
# Line 2891  Force Line 2929  Force
2929  .BR \%gxditview (@MAN1EXT@)  .BR \%gxditview (@MAN1EXT@)
2930  as the X-mode viewer using the geometry option for setting the width  as the X-mode viewer using the geometry option for setting the width
2931  to  to
2932  .B 850 dpi  .B 850\~dpi
2933  and the height to  and the height to
2934  .B 800  .B 800\~\c
2935  .BR dpi .  .BR dpi .
2936  .  .
2937  .  .
2938  .Topic  .Topic
2939  The variable  If the environment variable
2940  .Env_var $DISPLAY  .Env_var $DISPLAY
2941  is set to  is empty set it to
2942  .IR localhost:0.0  .IR localhost:0.0 .
2943  which allows to start  .
2944  .I groffer  That allows to start
2945  in the standard X display, even when the program is called from a text  .I \%groffer
2946    in the standard X\~display, even when the program is called from a text
2947  console.  console.
2948  .  .
2949  .  .
2950  .Topic  .Topic
2951  Just for fun, the date of each  Just for fun, the date of each
2952  .I groffer  .I \%groffer
2953  start is written to the file  start is written to the file
2954  .B mygroffer.log  .File_name mygroffer.log
2955  in the home directory.  in the home directory.
2956  .  .
2957  .  .
# Line 2920  in the home directory. Line 2959  in the home directory.
2959  .SH "EXAMPLES"  .SH "EXAMPLES"
2960  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
2961  .  .
2962  The usage of groffer is very easy.  The usage of
2963    .I \%groffer
2964    is very easy.
2965  .  .
2966  Usually, it is just called with a file name or man\~page.  Usually, it is just called with a file name or man\~page.
2967  .  .
# Line 2931  capabilities. Line 2972  capabilities.
2972  .TP  .TP
2973  .Shell_cmd "groffer\~/usr/local/share/doc/groff/meintro.ms.gz"  .Shell_cmd "groffer\~/usr/local/share/doc/groff/meintro.ms.gz"
2974  Decompress, format and display the compressed file  Decompress, format and display the compressed file
2975  .I meintro.ms.gz  .File_name meintro.ms.gz
2976  in the directory  in the directory
2977  .IR /usr/local/share/doc/groff ,  .File_name /usr/local/share/doc/groff ,
2978  using  using
2979  .I \%gxditview  .I \%gxditview
2980  as graphical viewer when in X Window, or the  as graphical viewer when in X Window, or the
2981  .BR less (1)  .BR \%less (1)
2982  pager program when not in X.  pager program when not in X.
2983  .  .
2984  .  .
2985  .TP  .TP
2986  .Shell_cmd "groffer\~groff"  .Shell_cmd "groffer\~groff"
2987  If the file  If the file
2988  .I ./groff  .I \%./groff
2989  exists use it as input.  exists use it as input.
2990  .  .
2991  Otherwise interpret the argument as a search for the man\~page named  Otherwise interpret the argument as a search for the man\~page named
2992  .I groff  .I \%groff
2993  in the smallest possible man\~section, being secion 1 in this case.  in the smallest possible man\~section, being section 1 in this case.
2994  .  .
2995  .  .
2996  .TP  .TP
2997  .Shell_cmd "groffer\~man:groff"  .Shell_cmd "groffer\~man:groff"
2998  search for the man\~page of  search for the man\~page of
2999  .I groff  .I \%groff
3000  even when the file  even when the file
3001  .I ./groff  .File_name ./groff
3002  exists.  exists.
3003  .  .
3004  .  .
# Line 2966  exists. Line 3007  exists.
3007  .TP+  .TP+
3008  .Shell_cmd "groffer\~7\~groff"  .Shell_cmd "groffer\~7\~groff"
3009  search the man\~page of  search the man\~page of
3010  .I groff  .I \%groff
3011  in man\~section  in man\~section
3012  .BR 7 .  .BR 7 .
3013  This section search works only for a digit or a single character from  This section search works only for a digit or a single character from
# Line 2976  a small set. Line 3017  a small set.
3017  .TP  .TP
3018  .Shell_cmd "groffer\~fb.modes"  .Shell_cmd "groffer\~fb.modes"
3019  If the file  If the file
3020  .I ./fb.modes  .File_name ./fb.modes
3021  does not exist interpret this as a search for the man\~page of  does not exist interpret this as a search for the man\~page of
3022  .IR fb.modes .  .IR fb.modes .
3023  As the extension  As the extension
3024  .I modes  .I \%modes
3025  is not a single character in classical section style the argument is  is not a single character in classical section style the argument is
3026  not split to a search for  not split to a search for
3027  .IR fb .  .IR fb .
# Line 2991  not split to a search for Line 3032  not split to a search for
3032  .  .
3033  The arguments that are not existing files are looked-up as the  The arguments that are not existing files are looked-up as the
3034  following man\~pages:  following man\~pages:
3035  .I groff  .I \%groff
3036  (automatic search, should be found in man\~section\~1),  (automatic search, should be found in man\~section\~1),
3037  .I troff  .I \%troff
3038  (in section\~1),  (in section\~1),
3039  and  and
3040  .I roff  .I \%roff
3041  (in the section with the lowest number, being\~7 in this case).  (in the section with the lowest number, being\~7 in this case).
3042  .  .
3043  The quotes around  The quotes around
3044    .nh
3045  .I \[cq]troff(1)\[cq]  .I \[cq]troff(1)\[cq]
3046    .hy
3047  are necessary because the paranthesis are special shell characters;  are necessary because the paranthesis are special shell characters;
3048  escaping them with a backslash character  escaping them with a backslash character
3049  .I \[rs](  .I \[rs](
# Line 3019  Retrieve the German man\~page (language Line 3062  Retrieve the German man\~page (language
3062  for the  for the
3063  .B ls  .B ls
3064  program, decompress it, format it to  program, decompress it, format it to
3065  .I html  .I \%html
3066  format  format
3067    .nh
3068  .RI ( www  .RI ( www
3069  mode) and view the result in the web browser  mode)
3070  .I galeon .  .hy
3071    and view the result in the web browser
3072    .IR \%galeon .
3073  The option  The option
3074  .Opt_long man  .Opt_long man
3075  guarantees that the man\~page is retrieved, even when a local file  guarantees that the man\~page is retrieved, even when a local file
3076  .I ls  .I \%ls
3077  exists in the actual directory.  exists in the actual directory.
3078  .  .
3079  .  .
# Line 3035  exists in the actual directory. Line 3081  exists in the actual directory.
3081  .Shell_cmd "groffer\~--source\~'man:roff(7)'"  .Shell_cmd "groffer\~--source\~'man:roff(7)'"
3082  .  .
3083  Get the man\~page called  Get the man\~page called
3084  .I roff  .I \%roff
3085  in man\~section 7, decompress it, and print its unformatted content,  in man\~section 7, decompress it, and print its unformatted content,
3086  its source code.  its source code.
3087  .  .
# Line 3044  its source code. Line 3090  its source code.
3090  .Shell_cmd "cat\~file.gz\~|\~groffer\~-Z\~-mfoo"  .Shell_cmd "cat\~file.gz\~|\~groffer\~-Z\~-mfoo"
3091  .  .
3092  Decompress the standard input, send this to  Decompress the standard input, send this to
3093  .I groff  .I \%groff
3094  intermediate mode without post-processing (groff option  intermediate mode without post-processing (groff option
3095  .Opt_short Z ),  .Opt_short Z ),
3096  using macro package by  using macro package by
3097  .I foo  .I \%foo
3098  (groff option  (groff option
3099  .Opt_short m ) .  .Opt_short m ) .
3100  .  .
# Line 3067  bold font, using color yellow on red bac Line 3113  bold font, using color yellow on red bac
3113  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
3114  .  .
3115  The  The
3116  .B groffer  .B \%groffer
3117  shell script is compatible with both GNU and POSIX.  shell script is compatible with both GNU and POSIX.
3118  .  .
3119  POSIX compatibility refers to  POSIX compatibility refers to
# Line 3091  provide much more facilities. Line 3137  provide much more facilities.
3137  Nevertheless this script uses only a restricted set of shell language  Nevertheless this script uses only a restricted set of shell language
3138  elements and shell builtins.  elements and shell builtins.
3139  .  .
3140  The groffer script should work on most actual free and commercial  The
3141  operating systems.  .I \%groffer
3142    script should work on most actual free and commercial operating
3143    systems.
3144  .  .
3145  .  .
3146  .P  .P
3147  The groffer program provides its own parser for command line options;  The
3148  it can handle option arguments and file names containing white space  .I \%groffer
3149  and a large set of special characters.  program provides its own parser for command line options; it can
3150    handle option arguments and file names containing white space and a
3151    large set of special characters.
3152  .  .
3153  .  .
3154  .P  .P
3155  The groffer shell script was tested with the following common  The
3156  implementations of the GNU shells:  .I \%groffer
3157  POSIX  shell script was tested with the following common implementations of
3158  .BR sh (1),  the GNU shells:
3159  .BR bash (1),  .I \%POSIX
3160    .BR \%sh (1),
3161    .BR \%bash (1),
3162  and others.  and others.
3163  .  .
3164  Free POSIX compatible shells and shell utilities for most operating  Free
3165    .I \%POSIX
3166    compatible shells and shell utilities for most operating
3167  systems are available at the  systems are available at the
3168  .URL http://\:www.gnu.org/software/ "GNU software archive" .  .URL http://\:www.gnu.org/software/ "GNU software archive" .
3169  .  .
# Line 3120  The shell can be chosen by the option Line 3174  The shell can be chosen by the option
3174  This option can also be given to the environment variable  This option can also be given to the environment variable
3175  .Env_var $GROFF_OPT .  .Env_var $GROFF_OPT .
3176  If you want to write it to one of the  If you want to write it to one of the
3177  .I groffer  .I \%groffer
3178  configuration files you must use the single option style, a line  configuration files you must use the single option style, a line
3179  starting with  starting with
3180  .Opt_long shell .  .Opt_long shell .
3181  .  .
3182  .  .
3183  .P  .P
3184  The groffer program provides its own parser for command line arguments  The
3185  that is compatible to both POSIX  .I \%groffer
3186  .BR getopts (1)  program provides its own parser for command line arguments that is
3187  and GNU  compatible to both
3188  .BR getopt (1)  .I \%POSIX
3189    .BR \%getopts (1)
3190    and
3191    .I \%GNU
3192    .BR \%getopt (1)
3193  except for shortcuts of long options.  except for shortcuts of long options.
3194  .  .
3195  The following standard types of options are supported.  The following standard types of options are supported.
# Line 3140  The following standard types of options Line 3198  The following standard types of options
3198  .Topic  .Topic
3199  A single minus always refers to single character option or a  A single minus always refers to single character option or a
3200  combination thereof, for example, the  combination thereof, for example, the
3201  .I groffer  .I \%groffer
3202  short option combination  short option combination
3203  .Opt_short Qmfoo  .Opt_short Qmfoo
3204  is equivalent to  is equivalent to
# Line 3199  want to set Line 3257  want to set
3257  .\" --------------------------------------------------------------------  .\" --------------------------------------------------------------------
3258  .  .
3259  .TP  .TP
3260  .BR groff (@MAN1EXT@)  .BR \%groff (@MAN1EXT@)
3261  .TP+  .TP+
3262  .BR troff (@MAN1EXT@)  .BR \%troff (@MAN1EXT@)
3263  Details on the options and environment variables available in  Details on the options and environment variables available in
3264  .IR groff ;  .IR \%groff ;
3265  all of them can be used with groffer.  all of them can be used with groffer.
3266  .  .
3267  .  .
3268  .TP  .TP
3269  .BR groff (@MAN7EXT@)  .BR \%groff (@MAN7EXT@)
3270  Documentation of the  Documentation of the
3271  .I groff  .I \%groff
3272  language.  language.
3273  .  .
3274  .  .
3275  .TP  .TP
3276  .BR grog (@MAN1EXT@)  .BR \%grog (@MAN1EXT@)
3277  Internally, groffer tries to guess the groff command line options from  Internally,
3278  the input using this program.  .I \%groffer
3279    tries to guess the
3280    .I \%groff
3281    command line options from the input using this program.
3282  .  .
3283  .  .
3284  .TP  .TP
3285  .BR groff_out (@MAN5EXT@)  .BR groff_out (@MAN5EXT@)
3286  Documentation on the groff intermediate output (ditroff output).  Documentation on the
3287    .I \%groff intermediate output
3288    .nh
3289    .RI ( ditroff
3290    output).
3291    .hy
3292  .  .
3293  .  .
3294  .TP  .TP
3295  .BR man (1)  .BR \%man (1)
3296  The standard program to diplay man\~pages.  The standard program to diplay man\~pages.
3297  .  .
3298  The information there is only useful if it is the man\~page for  The information there is only useful if it is the man\~page for
3299  .IR "GNU\~man" .  .IR "GNU\~man" .
3300  Then it documents the options and environment variables that are  Then it documents the options and environment variables that are
3301  supported by groffer.  supported by
3302    .IR \%groffer .
3303  .  .
3304  .  .
3305  .TP  .TP
3306  .BR gxditview (@MAN1EXT@)  .BR \%gxditview (@MAN1EXT@)
3307  .TP+  .TP+
3308  .BR xditview (1x)  .BR \%xditview (1x)
3309  Viewers for groffer's  Viewers for
3310    .IR \%groffer 's
3311  .I x  .I x
3312  mode.  mode.
3313  .  .
3314  .  .
3315  .TP  .TP
3316  .BR kghostview (1)  .BR \%kghostview (1)
3317  .TP+  .TP+
3318  .BR ggv (1)  .BR \%ggv (1)
3319  .TP+  .TP+
3320  .BR gv (1)  .BR \%gv (1)
3321  .TP+  .TP+
3322  .BR ghostview (1)  .BR \%ghostview (1)
3323  .TP+  .TP+
3324  .BR gs (1)  .BR \%gs (1)
3325  Viewers for groffer's  Viewers for
3326    .IR \%groffer 's
3327  .I ps  .I ps
3328  mode.  mode.
3329  .  .
3330  .  .
3331  .TP  .TP
3332  .BR kghostview (1)  .BR \%kghostview (1)
3333  .TP+  .TP+
3334  .BR ggv (1)  .BR \%ggv (1)
3335  .TP+  .TP+
3336  .BR xpdf (1)  .BR \%xpdf (1)
3337  .TP+  .TP+
3338  .BR acroread (1)  .BR \%acroread (1)
3339  .TP+  .TP+
3340  .BR kpdf (1)  .BR \%kpdf (1)
3341  Viewers for groffer's  Viewers for
3342  .I pdf  .IR \%groffer 's
3343    .I \%pdf
3344  mode.  mode.
3345  .  .
3346  .  .
3347  .TP  .TP
3348  .BR kdvi (1)  .BR \%kdvi (1)
3349  .TP+  .TP+
3350  .BR xdvi (1)  .BR \%xdvi (1)
3351  .TP+  .TP+
3352  .BR dvilx (1)  .BR \%dvilx (1)
3353  Viewers for groffer's  Viewers for
3354  .I dvi  .IR \%groffer 's
3355    .I \%dvi
3356  mode.  mode.
3357  .  .
3358  .  .
3359  .TP  .TP
3360  .BR konqueror (1)  .BR \%konqueror (1)
3361  .TP+  .TP+
3362  .BR mozilla (1)  .BR \%mozilla (1)
3363  .TP+  .TP+
3364  .BR lynx (1)  .BR \%lynx (1)
3365  Web-browsers for groffer's  Web-browsers for
3366  .I html  .IR \%groffer 's
3367    .I \%html
3368  or  or
3369  .I www  .I \%www
3370  mode.  mode.
3371  .  .
3372  .  .
3373  .TP  .TP
3374  .BR less (1)  .BR \%less (1)
3375  Standard pager program for the  Standard pager program for the
3376  .I tty  .I \%tty
3377  .IR mode .  .IR mode .
3378  .  .
3379  .  .
3380  .TP  .TP
3381  .BR gzip (1)  .BR \%gzip (1)
3382  .TP+  .TP+
3383  .BR bzip2 (1)  .BR \%bzip2 (1)
3384  The decompression programs supported by groffer.  The decompression programs supported by groffer.
3385  .  .
3386  .  .

Legend:
Removed from v.1.21  
changed lines
  Added in v.1.22

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