CVSROOT: /cvsroot/groff
Module name: groff
Changes by: Werner LEMBERG <wl> 10/05/23 05:58:30
Modified files:
. : ChangeLog
doc : groff.texinfo
Log message:
Document preconv in texinfo.
* doc/groff.texinfo: Mention preconv and its related command line
options for groff.
Add stubs for direct preconv documentation.
Sort groff options and environment variables.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/groff/ChangeLog?cvsroot=groff&r1=1.1233&r2=1.1234
http://cvs.savannah.gnu.org/viewcvs/groff/doc/groff.texinfo?cvsroot=groff&r1=1.289&r2=1.290
Patches:
Index: ChangeLog
===================================================================
RCS file: /cvsroot/groff/groff/ChangeLog,v
retrieving revision 1.1233
retrieving revision 1.1234
diff -u -b -r1.1233 -r1.1234
--- ChangeLog 23 May 2010 05:09:00 -0000 1.1233
+++ ChangeLog 23 May 2010 05:58:30 -0000 1.1234
@@ -1,5 +1,14 @@
2010-05-22 Werner LEMBERG <[email protected]>
+ Document preconv in texinfo.
+
+ * doc/groff.texinfo: Mention preconv and its related command line
+ options for groff.
+ Add stubs for direct preconv documentation.
+ Sort groff options and environment variables.
+
+2010-05-22 Werner LEMBERG <[email protected]>
+
Use DESC's `unicode' keyword for grotty.
Consequently, no longer check directly for the `utf8' device name
Index: doc/groff.texinfo
===================================================================
RCS file: /cvsroot/groff/groff/doc/groff.texinfo,v
retrieving revision 1.289
retrieving revision 1.290
diff -u -b -r1.289 -r1.290
--- doc/groff.texinfo 1 May 2010 05:41:20 -0000 1.289
+++ doc/groff.texinfo 23 May 2010 05:58:30 -0000 1.290
@@ -842,6 +842,9 @@
can be obtained as an extra package; @code{groff} can use @code{grap}
also.
+Unique to @code{groff} is the @code{preconv} preprocessor which enables
+...@code{groff} to handle documents in various input encodings.
+
There are other preprocessors in existence, but, unfortunately, no free
implementations are available. Among them are preprocessors for drawing
mathematical pictures (@code{ideal}) and chemical structures
@@ -935,38 +938,40 @@
@pindex gtbl
@pindex grefer
@pindex gsoelim
+...@pindex preconv
@code{groff} normally runs the @code{gtroff} program and a postprocessor
appropriate for the selected device. The default device is @samp{ps}
(but it can be changed when @code{groff} is configured and built). It
can optionally preprocess with any of @code{gpic}, @code{geqn},
-...@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
+...@code{gtbl}, @code{ggrn}, @code{grap}, @code{grefer}, @code{gsoelim}, or
+...@code{preconv}.
This section only documents options to the @code{groff} front end. Many
of the arguments to @code{groff} are passed on to @code{gtroff},
therefore those are also included. Arguments to pre- or postprocessors
can be found in @ref{Invoking gpic}, @ref{Invoking geqn}, @ref{Invoking
gtbl}, @ref{Invoking ggrn}, @ref{Invoking grefer}, @ref{Invoking
-gsoelim}, @ref{Invoking grotty}, @ref{Invoking grops}, @ref{Invoking
-grohtml}, @ref{Invoking grodvi}, @ref{Invoking grolj4}, @ref{Invoking
-grolbp}, and @ref{Invoking gxditview}.
+gsoelim}, @ref{Invoking preconv}, @ref{Invoking grotty}, @ref{Invoking
+grops}, @ref{Invoking grohtml}, @ref{Invoking grodvi}, @ref{Invoking
+grolj4}, @ref{Invoking grolbp}, and @ref{Invoking gxditview}.
The command line format for @code{groff} is:
@Example
-groff [ -abceghilpstvzCEGNRSUVXZ ] [ -...@var{dir} ] [ -...@var{name} ]
- [ -...@var{def} ] [ -...@var{fam} ] [ -...@var{name} ] [ -...@var{name} ]
- [ -...@var{dir} ] [ -...@var{cs} ] [ -...@var{cn} ] [ -...@var{num} ]
- [ -...@var{list} ] [ -...@var{arg} ] [ -...@var{arg} ] [ -...@var{dir} ]
- [ @var{fil...@dots{} ]
+groff [ -abceghiklpstvzCEGNRSUVXZ ] [ -...@var{cs} ] [ -...@var{arg} ]
+ [ -...@var{fam} ] [ -...@var{dir} ] [ -...@var{dir} ] [ -...@var{arg} ]
+ [ -...@var{arg} ] [ -...@var{name} ] [ -...@var{dir} ] [ -...@var{num} ]
+ [ -...@var{list} ] [ -...@var{arg} ] [ -...@var{cn} ] [ -...@var{def} ]
+ [ -...@var{name} ] [ -...@var{name} ] [ @var{fil...@dots{} ]
@endExample
The command line format for @code{gtroff} is as follows.
@Example
-gtroff [ -abcivzCERU ] [ -...@var{name} ] [ -...@var{name} ] [ -...@var{cs} ]
- [ -...@var{fam} ] [ -...@var{name} ] [ -...@var{num} ]
- [ -...@var{list} ] [ -...@var{cn} ] [ -...@var{name} ]
- [ -...@var{dir} ] [ -...@var{dir} ] [ @var{fil...@dots{} ]
+gtroff [ -abcivzCERU ] [ -...@var{cs} ] [ -...@var{fam} ] [ -...@var{dir} ]
+ [ -...@var{name} ] [ -...@var{dir} ] [ -...@var{num} ] [ -...@var{list}
]
+ [ -...@var{cn} ] [ -...@var{name} ] [ -...@var{name} ] [ -...@var{name}
]
+ [ @var{fil...@dots{} ]
@endExample
@noindent
@@ -985,14 +990,61 @@
@cindex command-line options
@table @samp
-...@item -h
-Print a help message.
+...@item -a
+...@cindex @acronym{ASCII} approximation output register (@code{.A})
+Generate an @acronym{ASCII} approximation of the typeset output. The
+read-only register @code{.A} is then set t...@tie{}1. @xref{Built-in
+Registers}. A typical example is
+
+...@example
+groff -a -man -Tdvi troff.man | less
+...@endexample
+
+...@noindent
+which shows how lines are broken for the DVI device. Note that this
+option is rather useless today since graphic output devices are
+available virtually everywhere.
+
+...@item -b
+Print a backtrace with each warning or error message. This backtrace
+should help track down the cause of the error. The line numbers given
+in the backtrace may not always be correct: @code{gtroff} can get
+confused by @code{as} or @code{am} requests while counting line numbers.
+
+...@item -c
+Suppress color output.
+
+...@item -C
+Enable compatibility mode. @xref{Implementation Differences}, for the
+list of incompatibilities between @code{groff} and @acronym{AT&T}
+...@code{troff}.
+
+...@item -...@var{c}@var{s}
+...@itemx -...@var{name}=@var{s}
+Define @var{c} or @var{name} to be a str...@tie{}@var{s}.
+...@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
+length. All string assignments happen before loading any macro file
+(including the start-up file).
+
+...@item -...@var{arg}
+Set default input encoding used by @code{preconv} to @var{arg}. Implies
+...@option{-k}.
@item -e
Preprocess with @code{geqn}.
-...@item -t
-Preprocess with @code{gtbl}.
+...@item -E
+Inhibit all error messages.
+
+...@item -...@var{fam}
+Use @var{fam} as the default font family. @xref{Font Families}.
+
+...@item -...@var{dir}
+Search @fi...@var{dir}} for subdirectories @file{...@var{name}}
+(@var{name} is the name of the device), for the @file{DESC} file, and
+for font files before looking in the standard directories (@pxref{Font
+Directories}). This option is passed to all pre- and postprocessors
+using the @env{GROFF_FONT_PATH} environment variable.
@item -g
Preprocess with @code{ggrn}.
@@ -1000,46 +1052,43 @@
@item -G
Preprocess with @code{grap}.
-...@item -p
-Preprocess with @code{gpic}.
-
-...@item -s
-Preprocess with @code{gsoelim}.
+...@item -h
+Print a help message.
-...@item -c
-Suppress color output.
+...@item -i
+Read the standard input after all the named input files have been
+processed.
-...@item -R
-Preprocess with @code{grefer}. No mechanism is provided for passing
-arguments to @code{grefer} because most @code{grefer} options have
-equivalent commands which can be included in the file. @xref{grefer},
-for more details.
+...@item -...@var{dir}
+This option may be used to specify a directory to search for files.
+It is passed to the following programs:
-...@pindex troffrc
-...@pindex troffrc-end
-Note that @code{gtroff} also accepts a @option{-R} option, which is not
-accessible via @code{groff}. This option prevents the loading of the
-...@file{troffrc} and @file{troffrc-end} files.
+...@itemize
+...@item
+...@code{gsoelim} (see @ref{gsoelim} for more details);
+it also implies @code{groff}'s @option{-s} option.
-...@item -v
-Make programs run by @code{groff} print out their version number.
+...@item
+...@code{gtroff}; it is used to search files named in the @code{psbb} and
+...@code{so} requests.
-...@item -V
-Print the pipeline on @code{stdout} instead of executing it. If
-specified more than once, print the pipeline on @code{stderr} and
-execute it.
+...@item
+...@code{grops}; it is used to search files named in the
+...@w{@code{\X'ps: import}} and @w...@code{\x'ps: file}} escapes.
+...@end itemize
-...@item -z
-Suppress output from @code{gtroff}. Only error messages are printed.
+The current directory is always searched first. This option may be
+specified more than once; the directories are searched in the order
+specified. No directory search is performed for files specified using
+an absolute path.
-...@item -Z
-Do not postprocess the output of @code{gtroff}. Normally @code{groff}
-automatically runs the appropriate postprocessor.
+...@item -k
+Preprocess with @code{preconv}. This is run before any other
+preprocessor. Please refer to @code{preconv}'s manual page for its
+behaviour if no @option{-K} (or @option{-D}) option is specified.
-...@item -...@var{arg}
-Pass @var{arg} to the postprocessor. Each argument should be passed
-with a separate @option{-P} option. Note that @code{groff} does not
-prepend @samp{-} to @var{arg} before passing it to the postprocessor.
+...@item -...@var{arg}
+Set input encoding used by preconv to @var{arg}. Implies @option{-k}.
@item -l
Send the output to a spooler for printing. The command used for this is
@@ -1054,6 +1103,85 @@
@code{print} keyword in the device description file is missing,
@option{-L} is ignored.
+...@item -...@var{name}
+Read in the file @fi...@var{name}.tmac}. Normally @code{groff} searches
+for this in its macro directories. If it isn't found, it tries
+...@file{tmac.@var{name}} (searching in the same directories).
+
+...@item -...@var{dir}
+Search directory @fi...@var{dir}} for macro files before the standard
+directories (@pxref{Macro Directories}).
+
+...@item -...@var{num}
+Number the first page @var{num}.
+
+...@item -N
+Don't allow newlines with @code{eqn} delimiters. This is the same as
+the @option{-N} option in @code{geqn}.
+
+...@item -...@var{list}
+...@cindex print current page register (@code{.P})
+Output only pages in @var{list}, which is a comma-separated list of page
+ranges; @sa...@var{n}} means print p...@tie{}@var{n},
+...@samp{@var{...@var{n}} means print every page between @var{m}
+...@tie{}@var{n}, @sam...@var{n}} means print every page up
+...@tie{}@var{n}, @sa...@var{n}-} means print every page beginning
+w...@tie{}@var{n}. @code{gtroff} exits after printing the last page in
+the list. All the ranges are inclusive on both ends.
+
+Within @code{gtroff}, this information can be extracted with the
+...@samp{.p} register. @xref{Built-in Registers}.
+
+If your document restarts page numbering at the beginning of each
+chapter, then @code{gtroff} prints the specified page range for each
+chapter.
+
+...@item -p
+Preprocess with @code{gpic}.
+
+...@item -...@var{arg}
+Pass @var{arg} to the postprocessor. Each argument should be passed
+with a separate @option{-P} option. Note that @code{groff} does not
+prepend @samp{-} to @var{arg} before passing it to the postprocessor.
+
+...@item -...@var{c}@var{n}
+...@itemx -...@var{name}=@var{n}
+Set number regis...@tie{}@var{c} or @var{name} to the
+va...@tie{}@var{n}. @var...@tie{}must be a one-letter name; @var{name}
+can be of arbitrary length. @var...@tie{}can be any @code{gtroff}
+numeric expression. All register assignments happen before loading any
+macro file (including the start-up file).
+
+...@item -R
+Preprocess with @code{grefer}. No mechanism is provided for passing
+arguments to @code{grefer} because most @code{grefer} options have
+equivalent commands which can be included in the file. @xref{grefer},
+for more details.
+
+...@pindex troffrc
+...@pindex troffrc-end
+Note that @code{gtroff} also accepts a @option{-R} option, which is not
+accessible via @code{groff}. This option prevents the loading of the
+...@file{troffrc} and @file{troffrc-end} files.
+
+...@item -s
+Preprocess with @code{gsoelim}.
+
+...@item -S
+...@cindex @code{open} request, and safer mode
+...@cindex @code{opena} request, and safer mode
+...@cindex @code{pso} request, and safer mode
+...@cindex @code{sy} request, and safer mode
+...@cindex @code{pi} request, and safer mode
+...@cindex safer mode
+...@cindex mode, safer
+Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
+...@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
+requests. For security reasons, this is enabled by default.
+
+...@item -t
+Preprocess with @code{gtbl}.
+
@item -...@var{dev}
Prepare output for device @var{dev}. The default device is @samp{ps},
unless changed when @code{groff} was configured and built. The
@@ -1142,62 +1270,12 @@
Files}, for more info.) This can be overridden with the @option{-X}
option.
-...@item -X
-Preview with @code{gxditview} instead of using the usual postprocessor.
-This is unlikely to produce good results except with @option{-Tps}.
-
-Note that this is not the same as using @option{-TX75} or
-...@option{-tx100} to view a document with @code{gxditview}: The former
-uses the metrics of the specified device, whereas the latter uses
-X-specific fonts and metrics.
-
-...@item -N
-Don't allow newlines with @code{eqn} delimiters. This is the same as
-the @option{-N} option in @code{geqn}.
-
-...@item -S
-...@cindex @code{open} request, and safer mode
-...@cindex @code{opena} request, and safer mode
-...@cindex @code{pso} request, and safer mode
-...@cindex @code{sy} request, and safer mode
-...@cindex @code{pi} request, and safer mode
-...@cindex safer mode
-...@cindex mode, safer
-Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
-...@code{open}, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
-requests. For security reasons, this is enabled by default.
-
@item -U
@cindex mode, unsafe
@cindex unsafe mode
Unsafe mode. This enables the @code{open}, @code{opena}, @code{pso},
@code{sy}, and @code{pi} requests.
-...@item -a
-...@cindex @acronym{ASCII} approximation output register (@code{.A})
-Generate an @acronym{ASCII} approximation of the typeset output. The
-read-only register @code{.A} is then set t...@tie{}1. @xref{Built-in
-Registers}. A typical example is
-
-...@example
-groff -a -man -Tdvi troff.man | less
-...@endexample
-
-...@noindent
-which shows how lines are broken for the DVI device. Note that this
-option is rather useless today since graphic output devices are
-available virtually everywhere.
-
-...@item -b
-Print a backtrace with each warning or error message. This backtrace
-should help track down the cause of the error. The line numbers given
-in the backtrace may not always be correct: @code{gtroff} can get
-confused by @code{as} or @code{am} requests while counting line numbers.
-
-...@item -i
-Read the standard input after all the named input files have been
-processed.
-
@item -...@var{name}
Enable warning @var{name}. Available warnings are described in
@ref{Debugging}. Multiple @option{-w} options are allowed.
@@ -1205,90 +1283,29 @@
@item -...@var{name}
Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
-...@item -E
-Inhibit all error messages.
-
-...@item -C
-Enable compatibility mode. @xref{Implementation Differences}, for the
-list of incompatibilities between @code{groff} and @acronym{AT&T}
-...@code{troff}.
-
-...@item -...@var{c}@var{s}
-...@itemx -...@var{name}=@var{s}
-Define @var{c} or @var{name} to be a str...@tie{}@var{s}.
-...@var{c}@tie{}must be a one-letter name; @var{name} can be of arbitrary
-length. All string assignments happen before loading any macro file
-(including the start-up file).
-
-...@item -...@var{fam}
-Use @var{fam} as the default font family. @xref{Font Families}.
-
-...@item -...@var{name}
-Read in the file @fi...@var{name}.tmac}. Normally @code{groff} searches
-for this in its macro directories. If it isn't found, it tries
-...@file{tmac.@var{name}} (searching in the same directories).
-
-...@item -...@var{num}
-Number the first page @var{num}.
-
-...@item -...@var{list}
-...@cindex print current page register (@code{.P})
-Output only pages in @var{list}, which is a comma-separated list of page
-ranges; @sa...@var{n}} means print p...@tie{}@var{n},
-...@samp{@var{...@var{n}} means print every page between @var{m}
-...@tie{}@var{n}, @sam...@var{n}} means print every page up
-...@tie{}@var{n}, @sa...@var{n}-} means print every page beginning
-w...@tie{}@var{n}. @code{gtroff} exits after printing the last page in
-the list. All the ranges are inclusive on both ends.
-
-Within @code{gtroff}, this information can be extracted with the
-...@samp{.p} register. @xref{Built-in Registers}.
-
-If your document restarts page numbering at the beginning of each
-chapter, then @code{gtroff} prints the specified page range for each
-chapter.
-
-...@item -...@var{c}@var{n}
-...@itemx -...@var{name}=@var{n}
-Set number regis...@tie{}@var{c} or @var{name} to the
-va...@tie{}@var{n}. @var...@tie{}must be a one-letter name; @var{name}
-can be of arbitrary length. @var...@tie{}can be any @code{gtroff}
-numeric expression. All register assignments happen before loading any
-macro file (including the start-up file).
-
-...@item -...@var{dir}
-Search @fi...@var{dir}} for subdirectories @file{...@var{name}}
-(@var{name} is the name of the device), for the @file{DESC} file, and
-for font files before looking in the standard directories (@pxref{Font
-Directories}). This option is passed to all pre- and postprocessors
-using the @env{GROFF_FONT_PATH} environment variable.
-
-...@item -...@var{dir}
-Search directory @fi...@var{dir}} for macro files before the standard
-directories (@pxref{Macro Directories}).
+...@item -v
+Make programs run by @code{groff} print out their version number.
-...@item -...@var{dir}
-This option may be used to specify a directory to search for files.
-It is passed to the following programs:
+...@item -V
+Print the pipeline on @code{stdout} instead of executing it. If
+specified more than once, print the pipeline on @code{stderr} and
+execute it.
-...@itemize
-...@item
-...@code{gsoelim} (see @ref{gsoelim} for more details);
-it also implies @code{groff}'s @option{-s} option.
+...@item -X
+Preview with @code{gxditview} instead of using the usual postprocessor.
+This is unlikely to produce good results except with @option{-Tps}.
-...@item
-...@code{gtroff}; it is used to search files named in the @code{psbb} and
-...@code{so} requests.
+Note that this is not the same as using @option{-TX75} or
+...@option{-tx100} to view a document with @code{gxditview}: The former
+uses the metrics of the specified device, whereas the latter uses
+X-specific fonts and metrics.
-...@item
-...@code{grops}; it is used to search files named in the
-...@w{@code{\X'ps: import}} and @w...@code{\x'ps: file}} escapes.
-...@end itemize
+...@item -z
+Suppress output from @code{gtroff}. Only error messages are printed.
-The current directory is always searched first. This option may be
-specified more than once; the directories are searched in the order
-specified. No directory search is performed for files specified using
-an absolute path.
+...@item -Z
+Do not postprocess the output of @code{gtroff}. Normally @code{groff}
+automatically runs the appropriate postprocessor.
@end table
@@ -1303,6 +1320,11 @@
not within @code{gtroff}) which can modify the behavior of @code{groff}.
@table @code
+...@item GROFF_BIN_PATH
+...@tindex groff_bin_p...@r{, environment variable}
+This search path, followed by @code{PATH}, is used for commands executed
+by @code{groff}.
+
@item GROFF_COMMAND_PREFIX
@tindex groff_command_pre...@r{, environment variable}
@cindex command prefix
@@ -1311,21 +1333,22 @@
@co...@var{x}troff} instead of @code{gtroff}. This also applies to
@code{tbl}, @code{pic}, @code{eqn}, @code{grn}, @code{refer}, and
@code{soelim}. It does not apply to @code{grops}, @code{grodvi},
-...@code{grotty}, @code{pre-grohtml}, @code{post-grohtml}, @code{grolj4},
-and @code{gxditview}.
+...@code{grotty}, @code{pre-grohtml}, @code{post-grohtml}, @code{preconv},
+...@code{grolj4}, and @code{gxditview}.
The default command prefix is determined during the installation
process. If a non-GNU troff system is found, prefix @samp{g} is used,
none otherwise.
-...@item GROFF_TMAC_PATH
-...@tindex groff_tmac_p...@r{, environment variable}
-A colon-separated list of directories in which to search for macro files
-(before the default directories are tried). @xref{Macro Directories}.
-
-...@item GROFF_TYPESETTER
-...@tindex groff_typeset...@r{, environment variable}
-The default output device.
+...@item GROFF_ENCODING
+...@tindex groff_encod...@r{, environment variable}
+The value of this environment value is passed to the @code{preconv}
+preprocessor to select the encoding of input files. Setting this option
+implies @code{groff}'s command line option @option{-k} (this is,
+...@code{groff} actually always calls @code{preconv}). If set without a
+value, @code{groff} calls @code{preconv} without arguments. An explicit
+...@option{-k} command line option overrides the value of
+...@env{groff_encoding}. See the manual page of @code{preconv} for details.
@item GROFF_FONT_PATH
@tindex groff_font_p...@r{, environment variable}
@@ -1333,10 +1356,10 @@
@code{d...@var{name} directory (before the default directories are
tried). @xref{Font Directories}.
-...@item GROFF_BIN_PATH
-...@tindex groff_bin_p...@r{, environment variable}
-This search path, followed by @code{PATH}, is used for commands executed
-by @code{groff}.
+...@item GROFF_TMAC_PATH
+...@tindex groff_tmac_p...@r{, environment variable}
+A colon-separated list of directories in which to search for macro files
+(before the default directories are tried). @xref{Macro Directories}.
@item GROFF_TMPDIR
@tindex groff_tmp...@r{, environment variable}
@@ -1347,6 +1370,10 @@
default directory (on Unix and GNU/Linux systems, this is usually
@file{/tmp}). @code{grops}, @code{grefer}, @code{pre-grohtml}, and
@code{post-grohtml} can create temporary files in this directory.
+
+...@item GROFF_TYPESETTER
+...@tindex groff_typeset...@r{, environment variable}
+The default output device.
@end table
Note that MS-DOS and MS-Windows ports of @code{groff} use semi-colons,
@@ -14513,6 +14540,7 @@
* grap::
* grefer::
* gsoelim::
+* preconv::
@end menu
@@ -14647,7 +14675,7 @@
@c =====================================================================
-...@node gsoelim, , grefer, Preprocessors
+...@node gsoelim, preconv, grefer, Preprocessors
@section @code{gsoelim}
@cindex @code{soelim}, the program
@cindex @code{gsoelim}, the program
@@ -14668,6 +14696,27 @@
@c XXX
+...@c =====================================================================
+
+...@node preconv, , gsoelim, Preprocessors
+...@section @code{preconv}
+...@cindex @code{preconv}, the program
+
+...@c XXX
+
+...@menu
+* Invoking preconv::
+...@end menu
+
+...@c ---------------------------------------------------------------------
+
+...@node Invoking preconv, , preconv, preconv
+...@subsection Invoking @code{preconv}
+...@cindex invoking @code{preconv}
+...@cindex @code{preconv}, invoking
+
+...@c XXX
+
@c =====================================================================
@c =====================================================================
_______________________________________________
Groff-commit mailing list
[email protected]
http://lists.gnu.org/mailman/listinfo/groff-commit
