[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Groff-commit] groff ChangeLog doc/groff.texinfo
|
From: |
Werner LEMBERG |
|
Subject: |
[Groff-commit] groff ChangeLog doc/groff.texinfo |
|
Date: |
Sun, 23 May 2010 05:58:30 +0000 |
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 <address@hidden>
+ 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 <address@hidden>
+
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
address@hidden 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
address@hidden 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},
address@hidden, @code{ggrn}, @code{grap}, @code{grefer}, or @code{gsoelim}.
address@hidden, @code{ggrn}, @code{grap}, @code{grefer}, @code{gsoelim}, or
address@hidden
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 ] [ address@hidden ] [ address@hidden ]
- [ address@hidden ] [ address@hidden ] [ address@hidden ] [
address@hidden ]
- [ address@hidden ] [ address@hidden ] [ address@hidden ] [
address@hidden ]
- [ address@hidden ] [ address@hidden ] [ address@hidden ] [
address@hidden ]
- [ @address@hidden ]
+groff [ -abceghiklpstvzCEGNRSUVXZ ] [ address@hidden ] [ address@hidden ]
+ [ address@hidden ] [ address@hidden ] [ address@hidden ] [
address@hidden ]
+ [ address@hidden ] [ address@hidden ] [ address@hidden ] [
address@hidden ]
+ [ address@hidden ] [ address@hidden ] [ address@hidden ] [
address@hidden ]
+ [ address@hidden ] [ address@hidden ] [ @address@hidden ]
@endExample
The command line format for @code{gtroff} is as follows.
@Example
-gtroff [ -abcivzCERU ] [ address@hidden ] [ address@hidden ] [ address@hidden ]
- [ address@hidden ] [ address@hidden ] [ address@hidden ]
- [ address@hidden ] [ address@hidden ] [ address@hidden ]
- [ address@hidden ] [ address@hidden ] [ @address@hidden ]
+gtroff [ -abcivzCERU ] [ address@hidden ] [ address@hidden ] [ address@hidden ]
+ [ address@hidden ] [ address@hidden ] [ address@hidden ] [
address@hidden ]
+ [ address@hidden ] [ address@hidden ] [ address@hidden ] [
address@hidden ]
+ [ @address@hidden ]
@endExample
@noindent
@@ -985,14 +990,61 @@
@cindex command-line options
@table @samp
address@hidden -h
-Print a help message.
address@hidden -a
address@hidden @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 address@hidden @xref{Built-in
+Registers}. A typical example is
+
address@hidden
+groff -a -man -Tdvi troff.man | less
address@hidden
+
address@hidden
+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.
+
address@hidden -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.
+
address@hidden -c
+Suppress color output.
+
address@hidden -C
+Enable compatibility mode. @xref{Implementation Differences}, for the
+list of incompatibilities between @code{groff} and @acronym{AT&T}
address@hidden
+
address@hidden address@hidden@var{s}
address@hidden address@hidden@var{s}
+Define @var{c} or @var{name} to be a address@hidden@var{s}.
address@hidden@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).
+
address@hidden address@hidden
+Set default input encoding used by @code{preconv} to @var{arg}. Implies
address@hidden
@item -e
Preprocess with @code{geqn}.
address@hidden -t
-Preprocess with @code{gtbl}.
address@hidden -E
+Inhibit all error messages.
+
address@hidden address@hidden
+Use @var{fam} as the default font family. @xref{Font Families}.
+
address@hidden address@hidden
+Search @address@hidden for subdirectories @address@hidden
+(@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}.
address@hidden -p
-Preprocess with @code{gpic}.
-
address@hidden -s
-Preprocess with @code{gsoelim}.
address@hidden -h
+Print a help message.
address@hidden -c
-Suppress color output.
address@hidden -i
+Read the standard input after all the named input files have been
+processed.
address@hidden -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.
address@hidden address@hidden
+This option may be used to specify a directory to search for files.
+It is passed to the following programs:
address@hidden troffrc
address@hidden 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
address@hidden and @file{troffrc-end} files.
address@hidden
address@hidden
address@hidden (see @ref{gsoelim} for more details);
+it also implies @code{groff}'s @option{-s} option.
address@hidden -v
-Make programs run by @code{groff} print out their version number.
address@hidden
address@hidden; it is used to search files named in the @code{psbb} and
address@hidden requests.
address@hidden -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.
address@hidden
address@hidden; it is used to search files named in the
address@hidden@code{\X'ps: import}} and @address@hidden'ps: file}} escapes.
address@hidden itemize
address@hidden -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.
address@hidden -Z
-Do not postprocess the output of @code{gtroff}. Normally @code{groff}
-automatically runs the appropriate postprocessor.
address@hidden -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.
address@hidden address@hidden
-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.
address@hidden address@hidden
+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.
address@hidden address@hidden
+Read in the file @address@hidden Normally @code{groff} searches
+for this in its macro directories. If it isn't found, it tries
address@hidden@var{name}} (searching in the same directories).
+
address@hidden address@hidden
+Search directory @address@hidden for macro files before the standard
+directories (@pxref{Macro Directories}).
+
address@hidden address@hidden
+Number the first page @var{num}.
+
address@hidden -N
+Don't allow newlines with @code{eqn} delimiters. This is the same as
+the @option{-N} option in @code{geqn}.
+
address@hidden address@hidden
address@hidden print current page register (@code{.P})
+Output only pages in @var{list}, which is a comma-separated list of page
+ranges; @address@hidden means print address@hidden@var{n},
address@hidden@address@hidden means print every page between @var{m}
address@hidden@var{n}, @address@hidden means print every page up
address@hidden@var{n}, @address@hidden means print every page beginning
address@hidden@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
address@hidden 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.
+
address@hidden -p
+Preprocess with @code{gpic}.
+
address@hidden address@hidden
+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.
+
address@hidden address@hidden@var{n}
address@hidden address@hidden@var{n}
+Set number address@hidden@var{c} or @var{name} to the
address@hidden@var{n}. @address@hidden be a one-letter name; @var{name}
+can be of arbitrary length. @address@hidden be any @code{gtroff}
+numeric expression. All register assignments happen before loading any
+macro file (including the start-up file).
+
address@hidden -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.
+
address@hidden troffrc
address@hidden 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
address@hidden and @file{troffrc-end} files.
+
address@hidden -s
+Preprocess with @code{gsoelim}.
+
address@hidden -S
address@hidden @code{open} request, and safer mode
address@hidden @code{opena} request, and safer mode
address@hidden @code{pso} request, and safer mode
address@hidden @code{sy} request, and safer mode
address@hidden @code{pi} request, and safer mode
address@hidden safer mode
address@hidden mode, safer
+Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
address@hidden, @code{opena}, @code{pso}, @code{sy}, and @code{pi}
+requests. For security reasons, this is enabled by default.
+
address@hidden -t
+Preprocess with @code{gtbl}.
+
@item address@hidden
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.
address@hidden -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
address@hidden 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.
-
address@hidden -N
-Don't allow newlines with @code{eqn} delimiters. This is the same as
-the @option{-N} option in @code{geqn}.
-
address@hidden -S
address@hidden @code{open} request, and safer mode
address@hidden @code{opena} request, and safer mode
address@hidden @code{pso} request, and safer mode
address@hidden @code{sy} request, and safer mode
address@hidden @code{pi} request, and safer mode
address@hidden safer mode
address@hidden mode, safer
-Safer mode. Pass the @option{-S} option to @code{gpic} and disable the
address@hidden, @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.
address@hidden -a
address@hidden @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 address@hidden @xref{Built-in
-Registers}. A typical example is
-
address@hidden
-groff -a -man -Tdvi troff.man | less
address@hidden
-
address@hidden
-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.
-
address@hidden -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.
-
address@hidden -i
-Read the standard input after all the named input files have been
-processed.
-
@item address@hidden
Enable warning @var{name}. Available warnings are described in
@ref{Debugging}. Multiple @option{-w} options are allowed.
@@ -1205,90 +1283,29 @@
@item address@hidden
Inhibit warning @var{name}. Multiple @option{-W} options are allowed.
address@hidden -E
-Inhibit all error messages.
-
address@hidden -C
-Enable compatibility mode. @xref{Implementation Differences}, for the
-list of incompatibilities between @code{groff} and @acronym{AT&T}
address@hidden
-
address@hidden address@hidden@var{s}
address@hidden address@hidden@var{s}
-Define @var{c} or @var{name} to be a address@hidden@var{s}.
address@hidden@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).
-
address@hidden address@hidden
-Use @var{fam} as the default font family. @xref{Font Families}.
-
address@hidden address@hidden
-Read in the file @address@hidden Normally @code{groff} searches
-for this in its macro directories. If it isn't found, it tries
address@hidden@var{name}} (searching in the same directories).
-
address@hidden address@hidden
-Number the first page @var{num}.
-
address@hidden address@hidden
address@hidden print current page register (@code{.P})
-Output only pages in @var{list}, which is a comma-separated list of page
-ranges; @address@hidden means print address@hidden@var{n},
address@hidden@address@hidden means print every page between @var{m}
address@hidden@var{n}, @address@hidden means print every page up
address@hidden@var{n}, @address@hidden means print every page beginning
address@hidden@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
address@hidden 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.
-
address@hidden address@hidden@var{n}
address@hidden address@hidden@var{n}
-Set number address@hidden@var{c} or @var{name} to the
address@hidden@var{n}. @address@hidden be a one-letter name; @var{name}
-can be of arbitrary length. @address@hidden be any @code{gtroff}
-numeric expression. All register assignments happen before loading any
-macro file (including the start-up file).
-
address@hidden address@hidden
-Search @address@hidden for subdirectories @address@hidden
-(@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.
-
address@hidden address@hidden
-Search directory @address@hidden for macro files before the standard
-directories (@pxref{Macro Directories}).
address@hidden -v
+Make programs run by @code{groff} print out their version number.
address@hidden address@hidden
-This option may be used to specify a directory to search for files.
-It is passed to the following programs:
address@hidden -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.
address@hidden
address@hidden
address@hidden (see @ref{gsoelim} for more details);
-it also implies @code{groff}'s @option{-s} option.
address@hidden -X
+Preview with @code{gxditview} instead of using the usual postprocessor.
+This is unlikely to produce good results except with @option{-Tps}.
address@hidden
address@hidden; it is used to search files named in the @code{psbb} and
address@hidden requests.
+Note that this is not the same as using @option{-TX75} or
address@hidden 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.
address@hidden
address@hidden; it is used to search files named in the
address@hidden@code{\X'ps: import}} and @address@hidden'ps: file}} escapes.
address@hidden itemize
address@hidden -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.
address@hidden -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
address@hidden GROFF_BIN_PATH
address@hidden address@hidden, environment variable}
+This search path, followed by @code{PATH}, is used for commands executed
+by @code{groff}.
+
@item GROFF_COMMAND_PREFIX
@tindex address@hidden, environment variable}
@cindex command prefix
@@ -1311,21 +1333,22 @@
@address@hidden 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},
address@hidden, @code{pre-grohtml}, @code{post-grohtml}, @code{grolj4},
-and @code{gxditview}.
address@hidden, @code{pre-grohtml}, @code{post-grohtml}, @code{preconv},
address@hidden, 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.
address@hidden GROFF_TMAC_PATH
address@hidden address@hidden, environment variable}
-A colon-separated list of directories in which to search for macro files
-(before the default directories are tried). @xref{Macro Directories}.
-
address@hidden GROFF_TYPESETTER
address@hidden address@hidden, environment variable}
-The default output device.
address@hidden GROFF_ENCODING
address@hidden address@hidden, 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,
address@hidden actually always calls @code{preconv}). If set without a
+value, @code{groff} calls @code{preconv} without arguments. An explicit
address@hidden command line option overrides the value of
address@hidden See the manual page of @code{preconv} for details.
@item GROFF_FONT_PATH
@tindex address@hidden, environment variable}
@@ -1333,10 +1356,10 @@
@address@hidden directory (before the default directories are
tried). @xref{Font Directories}.
address@hidden GROFF_BIN_PATH
address@hidden address@hidden, environment variable}
-This search path, followed by @code{PATH}, is used for commands executed
-by @code{groff}.
address@hidden GROFF_TMAC_PATH
address@hidden address@hidden, 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 address@hidden, 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.
+
address@hidden GROFF_TYPESETTER
address@hidden address@hidden, 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 =====================================================================
address@hidden gsoelim, , grefer, Preprocessors
address@hidden gsoelim, preconv, grefer, Preprocessors
@section @code{gsoelim}
@cindex @code{soelim}, the program
@cindex @code{gsoelim}, the program
@@ -14668,6 +14696,27 @@
@c XXX
address@hidden
=====================================================================
+
address@hidden preconv, , gsoelim, Preprocessors
address@hidden @code{preconv}
address@hidden @code{preconv}, the program
+
address@hidden XXX
+
address@hidden
+* Invoking preconv::
address@hidden menu
+
address@hidden
---------------------------------------------------------------------
+
address@hidden Invoking preconv, , preconv, preconv
address@hidden Invoking @code{preconv}
address@hidden invoking @code{preconv}
address@hidden @code{preconv}, invoking
+
address@hidden XXX
+
@c =====================================================================
@c =====================================================================