4 Copyright (c) 2014 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
6 Copyright (C) 1989, 2002 - 2008
7 Free Software Foundation, Inc.
8 Rewritten in 2002 by Bernd Warken <bwarken@mayn.de>
10 Permission is granted to copy, distribute and/or modify this document
11 under the terms of the GNU Free Documentation License, Version 1.1 or
12 any later version published by the Free Software Foundation; with the
13 Invariant Sections being this .ig-section and AUTHOR, with no
14 Front-Cover Texts, and with no Back-Cover Texts.
16 You should have received a copy of the Free Documentation License
17 as part of the file COPYING; also located in the main directory of the
18 source package of this program.
22 .\" Environment variable
34 .TH @U_ROFF@ @MAN1EXT@ "@MDATE@" "@T_ROFF@ v@VERSION@"
38 @L_ROFF@ \- front-end for the @T_ROFF@ document formatting system
44 .OP \-abcegiklpstzCEGNRSUVZ
72 .RI [ option\~ .\|.\|.]
78 This document describes the
80 program, the main front-end for the
82 document formatting system, which is a
84 implementation that has all features of the classical
86 but also adds extensions.
91 program allows to control the whole
93 system by command line options.
98 Whitespace between a command line option and its argument is
101 Options can be grouped behind a single `\-' (minus character).
105 (minus character) denotes the standard input.
108 .SS Native @L_ROFF@ Options
110 The following options either do not exist for
112 or are differently interpreted by
117 Set default input encoding used by
143 Print a help message.
147 This option may be used to specify a directory to search for
148 files (both those on the command line and those named in
157 The current directory is always searched first.
158 This option may be specified more than once;
159 the directories are searched in the order specified.
160 No directory search is performed for files specified using an absolute path.
161 This option implies the
169 This is run before any other preprocessor.
173 manual page for its behaviour if no
181 Set input encoding used by
190 Send the output to a spooler program for printing.
191 The command that should be used for this is specified by the
193 command in the device description file, see
194 .BR \%@L_ROFF@_font (@MAN5EXT@).
195 If this command is not present, the output is piped into the
207 to the spooler program.
208 Several arguments should be passed with a separate
217 before passing it to the spooler program.
221 Don't allow newlines within
224 This is the same as the
237 .BI \-P\ \-option \ \-P\ arg
242 to the postprocessor.
243 The option must be specified with the necessary preceding minus
250 does not prepend any dashes before passing it to the postprocessor.
257 No mechanism is provided for passing arguments to
261 options have equivalent language elements that can be specified within
264 .BR \%@L_P_REFER@ (@MAN1EXT@)
279 and disable the following
288 For security reasons, safer mode is enabled by default.
305 .BR \%@L_ROFF@_out (@MAN5EXT@).
308 calls a postprocessor to convert
310 .I intermediate output
320 TeX DVI format (postprocessor is
327 HTML and XHTML output (preprocessors are
330 .BR \%@L_D_PREHTML@ ,
332 .BR \%@L_D_POSTHTML@ ).
336 PostScript output (postprocessor is
342 For the following TTY output devices (postprocessor is always
345 selects the output encoding:
351 7bit \f[CR]ASCII\f[].
355 \%Latin-1 character set for EBCDIC hosts.
363 Unicode character set in \%UTF-8 encoding.
368 The default device is
375 Reverts to the (old) unsafe behaviour; see option
382 Output version information (of all programs that would be run by the
387 Output the pipeline that would be run on the standard output, but do not
389 If given more than once,
390 the commands are both printed on the standard error and run.
394 Suppress output generated by
396 Only error messages are printed.
400 Do not automatically postprocess intermediate output in the usual manner.
403 output to appear on standard output,
404 replacing the usual postprocessor output; see
405 .BR \%@L_ROFF@_out (@MAN5EXT@).
408 .SS Transparent Options
410 The following options are transparently handed over to the formatter
413 These options are described in more detail in
414 .BR @L_TROFF@ (@MAN1EXT@).
418 \f[CR]ASCII\f[] approximation of output.
422 Backtrace on error or warning.
426 Disable color output.
429 .BR \%@L_D_TTY@ (@MAN1EXT@)
430 man page for more details.
434 Enable compatibility mode.
450 Set default font family.
454 Set path for font DESC files.
458 Process standard input after the specified input files.
467 .BR \%@L_ROFF@_tmac (@MAN5EXT@).
471 Path for macro files.
475 Number the first page
505 implements the infrastructure of classical roff; see
507 for a survey on how a
509 system works in general.
510 @T_ROFF@ adds front-end programs and other facilities which make using
513 with its pipeline approach.
514 This section gives an overview of those added parts and complements
515 .BR roff (@MAN7EXT@).
524 to format the input is controlled globally with the requests
530 .BR @L_ROFF@_tmac (@MAN5EXT@)
531 for the `papersize' macro package which provides a convenient interface.
536 paper size, giving the actual dimensions of the paper sheets, is
537 controlled by output devices like
539 with the command line options
544 .BR @L_ROFF@_font (@MAN5EXT@)
545 and the man pages of the output devices for more details.
547 uses the command line option
549 to pass options to output devices; for example, the following selects
550 A4 paper in landscape orientation for the PS device:
554 @L_ROFF@ -Tps -P-pa4 -P-l ...
560 @L_ROFF@ allows to specify the preprocessors by command line options,
561 and automatically runs the postprocessor that is appropriate for the
562 selected device after processing the data with @L_TROFF@.
563 @L_ROFF@ therefore acts as a replacement for the necessity to manually
564 specify the processor pipeline as is required by classical
565 .BR roff (@MAN7EXT@).
570 The standard preprocessors distributed along with
575 .BR \%@L_P_EQN@ (@MAN1EXT@)
576 for mathematical formul\(ae,
579 .BR \%@L_P_GRN@ (@MAN1EXT@)
585 .BR \%@L_P_PIC@ (@MAN1EXT@)
586 for drawing diagrams,
589 .BR \%@L_P_REFER@ (@MAN1EXT@)
590 for bibliographic references,
593 .BR \%@L_P_SOELIM@ (@MAN1EXT@)
594 for including macro files from standard locations,
597 .BR @L_P_TABLES (@MAN1EXT@)
601 A new preprocessor is
602 .BR \%@L_P_PRECONV@ (@MAN1EXT@)
603 which converts various input encodings to something
606 It is always run first before any other preprocessor.
611 Macro packages can be included by option
616 system implements and extends all classical macro packages in a
617 compatible way and adds some packages of its own.
619 Actually, the following macro packages are included:
623 The traditional man page format; see
624 .BR \%@L_ROFF@_man (@MAN7EXT@).
625 It can be specified on the command line as
632 The general package for man pages; it automatically recognizes
633 whether the documents uses the
637 format and branches to the corresponding macro package.
639 It can be specified on the command line as
646 The \f[CR]BSD\f[]-style man page format; see
647 .BR \%@L_ROFF@_mdoc (@MAN7EXT@).
648 It can be specified on the command line as
658 .BR \%@L_ROFF@_me (@MAN7EXT@).
659 It can be specified on the command line as
669 .BR \%@L_ROFF@_ms (@MAN7EXT@).
670 It can be specified on the command line as
677 HTML-like macros for inclusion in arbitrary
680 .BR \%@L_ROFF@_www (@MAN7EXT@).
683 Details on the naming of macro files and their placement can be found
685 .BR \%@L_ROFF@_tmac (@MAN5EXT@);
686 this man page also documents some other, minor auxiliary macro packages
690 .SS "Programming Language"
692 General concepts common to all
694 programming languages are described in
695 .BR roff (@MAN7EXT@).
700 extensions to the classical
702 language are documented in
703 .BR \%@L_ROFF@_diff (@MAN7EXT@).
704 In here you find also differences in between GNU troff and @T_ROFF@.
709 language as a whole is described in
710 .BR @L_ROFF@ (@MAN7EXT@).
720 .BR @L_TROFF@ (@MAN1EXT@).
721 It provides the features of both the classical
729 The command line option
734 .I "compatibility mode"
735 which tries to emulate classical
740 There is a shell script
741 .BR @L_NROFF@ (@MAN1EXT@)
742 that emulates the behavior of classical
744 It tries to automatically select the proper output encoding, according to
748 The formatter program generates
749 .IR "intermediate output" ;
751 .BR \%@L_ROFF@_out (@MAN7EXT@).
758 the output targets are called
760 A device can be a piece of hardware, e.g., a printer, or a software
763 A device is specified by the option
765 The following devices are included:
769 Text output using the
775 Text output using the EBCDIC code page IBM cp1047 (e.g., OS/390 Unix).
787 Text output using the ISO \%Latin-1 (ISO \%8859-1) character set; see
788 .BR \%iso_8859_1 (7).
792 PostScript output; suitable for printers and previewers like
797 Text output using the Unicode (ISO 10646) character set with \%UTF-8
806 The postprocessor to be used for a device is specified by the
808 command in the device description file; see
809 .BR \%@L_ROFF@_font (@MAN5EXT@).
812 The default device is
819 provides 3\~hardware postprocessors:
822 .BR \%@L_D_TTY@ (@MAN1EXT@)
823 for text output using various encodings, e.g., on text-oriented
824 terminals or line-printers.
827 Today, most printing or drawing hardware is handled by the operating
828 system, by device drivers, or by software interfaces, usually accepting
830 Consequently, there isn't an urgent need for more hardware device
834 The software devices for conversion into other document file formats are:
837 .BR \%@L_D_DVI@ (@MAN1EXT@)
841 .BR \%@L_D_HTML@ (@MAN1EXT@)
842 for HTML and XHTML formats,
845 .BR \%@L_D_PS@ (@MAN1EXT@)
849 Combined with the many existing free conversion tools this should
850 be sufficient to convert a
852 document into virtually any existing data format.
857 The following utility programs around are available:
860 .BR \%@L_ADDFTINFO@ (@MAN1EXT@)
863 font description files for use with
867 .BR \%@L_AFMTODIT@ (@MAN1EXT@)
868 Create font description files for PostScript device.
871 .BR \%@L_INDXBIB@ (@MAN1EXT@)
872 Make inverted index for bibliographic databases.
875 .BR \%@L_LKBIB@ (@MAN1EXT@)
876 Search bibliographic databases.
879 .BR \%@L_LOOKBIB@ (@MAN1EXT@)
880 Interactively search bibliographic databases.
883 .BR \%@L_PDFROFF@ (@MAN1EXT@)
884 Create PDF documents.
887 .BR \%@L_PFBTOPS@ (@MAN1EXT@)
888 Translate a PostScript font in .pfb format to \f[CR]ASCII\f[].
891 .BR \%@L_TFMTODIT@ (@MAN1EXT@)
892 Create font description files for TeX DVI device.
897 Normally, the path separator in the following environment variables is the
898 colon; this may vary depending on the operating system.
899 For example, DOS and Windows use a semicolon instead.
902 .EnvVar @U_ROFF@_BIN_PATH
903 This search path, followed by
905 is used for commands that are executed by
907 If it is not set then the directory where the
909 binaries were installed is prepended to
913 .EnvVar @U_ROFF@_COMMAND_PREFIX
914 When there is a need to run different
916 implementations at the same time
918 provides the facility to prepend a prefix to most of its programs that
919 could provoke name clashings at run time (default is to have none).
921 More exactly, if it is set to prefix
925 as a wrapper program internally calls
929 This also applies to the preprocessors
941 This feature does not apply to any programs different from the ones
947 .EnvVar @U_ROFF@_ENCODING
948 The value of this environment value is passed to the
950 preprocessor to select the encoding of input files, i.e.,
951 setting this option implies
955 If set to an empty value then the automatic character set guessing
956 heuristics are used, as documented for
957 .BR preconv (@MAN1EXT@).
960 command line option overrides the value of
961 .EnvVar @U_ROFF@_ENCODING .
964 .EnvVar @U_ROFF@_FONT_PATH
965 A list of directories in which to search for the
967 directory in addition to the default ones.
969 .BR @L_TROFF@ (@MAN1EXT@)
971 .BR \%@L_ROFF@_font (@MAN5EXT@)
975 .EnvVar @U_ROFF@_TMAC_PATH
976 A list of directories in which to search for macro files in addition to
977 the default directories.
979 .BR @L_TROFF@ (@MAN1EXT@)
981 .BR \%@L_ROFF@_tmac (@MAN5EXT@)
985 .EnvVar @U_ROFF@_TMPDIR
986 The directory in which temporary files are created.
987 If this is not set but the environment variable
989 instead, temporary files are created in the directory
991 On MS-DOS and Windows\~32 platforms, the environment variables
995 (in that order) are searched also, after
996 .EnvVar @U_ROFF@_TMPDIR
999 Otherwise, temporary files are created in
1002 .BR \%@L_P_REFER@ (@MAN1EXT@),
1003 .BR \%@L_D_HTML@ (@MAN1EXT@),
1005 .BR \%@L_D_PS@ (@MAN1EXT@)
1006 commands use temporary files.
1009 .EnvVar @U_ROFF@_TYPESETTER
1010 Preset the default device.
1011 If this is not set the
1013 device is used as default.
1014 This device name is overwritten by the option
1020 There are some directories in which
1022 installs all of its data files.
1023 Due to different installation habits on different operating systems,
1024 their locations are not absolutely fixed, but their function is
1025 clearly defined and coincides on all systems.
1028 .SS "groff Macro Directory"
1030 This contains all information related to macro packages;
1031 in the @T_ROFF@ system installation this directory is
1033 Note that more than a single directory is searched for those files
1035 .BR \%@L_ROFF@_tmac (@MAN5EXT@)
1038 The following files contained in the
1040 have a special meaning:
1044 Initialization file for
1046 This is interpreted by
1048 before reading the macro sets and any input.
1052 Final startup file for
1054 It is parsed after all macro sets have been read.
1060 Macro file for macro package
1064 .SS "groff Font Directory"
1066 This contains all information related to output devices;
1067 in the @T_ROFF@ system installation this directory is
1069 Note that more than a single directory is searched for those files; see
1070 .BR @L_TROFF@ (@MAN1EXT@).
1073 The following files contained in the
1075 have a special meaning:
1079 Device description file for device
1082 .BR \%@L_ROFF@_font (@MAN5EXT@).
1095 On \f[CR]EBCDIC\f[] hosts (e.g., \f[CR]OS/390 Unix\f[]), output
1101 Similarly, output for \f[CR]EBCDIC\f[] code page
1103 is not available on \f[CR]ASCII\f[] based operating systems.
1113 Copyright (c) 2014 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
1115 Copyright \(co 1989, 2002 - 2008
1116 Free Software Foundation, Inc.
1119 This document is distributed under the terms of the \f[CR]FDL\f[]
1120 (\f[CR]GNU Free Documentation License\f[]) version 1.1 or later.
1122 You should have received a copy of the \f[CR]FDL\f[] on your system,
1123 it is also available on-line at the
1124 .UR http://\:www.gnu.org/\:copyleft/\:fdl.html
1129 This document is based on the original
1136 It was rewritten, enhanced, and put under the FDL license by
1148 Introduction, history and further readings:
1149 .BR roff (@MAN7EXT@).
1152 Wrapper programs for formatters:
1153 .BR \%@L_ROFF@ (@MAN1EXT@).
1157 .BR \%@L_P_EQN@ (@MAN1EXT@),
1158 .BR \%@L_P_GRN@ (@MAN1EXT@),
1159 .BR \%@L_P_PIC@ (@MAN1EXT@),
1160 .BR \%@L_P_PRECONV@ (@MAN1EXT@),
1161 .BR \%@L_P_REFER@ (@MAN1EXT@),
1162 .BR \%@L_P_SOELIM@ (@MAN1EXT@),
1163 .BR \%@L_P_TBL@ (@MAN1EXT@),
1167 Roff language with the groff extensions:
1168 .BR \%@L_ROFF@ (@MAN7EXT@),
1169 .BR \%@L_ROFF@_char (@MAN7EXT@),
1170 .BR \%@L_ROFF@_diff (@MAN7EXT@),
1171 .BR \%@L_ROFF@_font (@MAN5EXT@).
1174 Roff formatter programs:
1175 .BR \%@L_NROFF@ (@MAN1EXT@),
1176 .BR \%@L_TROFF@ (@MAN1EXT@),
1177 .BR ditroff (@MAN7EXT@).
1180 The intermediate output language:
1181 .BR \%@L_ROFF@_out (@MAN7EXT@).
1184 Postprocessors for the output devices:
1185 .BR \%@L_D_DVI@ (@MAN1EXT@),
1186 .BR \%@L_D_HTML@ (@MAN1EXT@),
1187 .BR \%@L_D_PS@ (@MAN1EXT@),
1188 .BR \%@L_D_TTY@ (@MAN1EXT@).
1191 Groff macro packages and macro-specific utilities:
1192 .BR \%@L_ROFF@_tmac (@MAN5EXT@),
1193 .BR \%@L_ROFF@_man (@MAN7EXT@),
1194 .BR \%@L_ROFF@_mdoc (@MAN7EXT@),
1195 .BR \%@L_ROFF@_me (@MAN7EXT@),
1196 .BR \%@L_ROFF@_ms (@MAN7EXT@),
1197 .BR \%@L_ROFF@_www (@MAN7EXT@),
1198 .BR \%@L_ROFF@_trace (@MAN7EXT@),
1201 The following utilities are available:
1202 .BR \%@L_ADDFTINFO@ (@MAN1EXT@),
1203 .BR \%@L_AFMTODIT@ (@MAN1EXT@),
1204 .BR \%@L_INDXBIB@ (@MAN1EXT@),
1205 .BR \%@L_LKBIB@ (@MAN1EXT@),
1206 .BR \%@L_LOOKBIB@ (@MAN1EXT@),
1207 .BR \%@L_PDFROFF@ (@MAN1EXT@),
1208 .BR \%@L_PFBTOPS@ (@MAN1EXT@),
1209 .BR \%@L_TFMTODIT@ (@MAN1EXT@),