[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
branch master updated: Avoid Texinfo processor name when not needed, pr
|
From: |
Patrice Dumas |
|
Subject: |
branch master updated: Avoid Texinfo processor name when not needed, prefere texi2any |
|
Date: |
Sun, 24 Jul 2022 12:56:12 -0400 |
This is an automated email from the git hooks/post-receive script.
pertusus pushed a commit to branch master
in repository texinfo.
The following commit(s) were added to refs/heads/master by this push:
new b8ccec2313 Avoid Texinfo processor name when not needed, prefere
texi2any
b8ccec2313 is described below
commit b8ccec2313a97ca9e290d474ab03abf5e9d8fa25
Author: Patrice Dumas <pertusus@free.fr>
AuthorDate: Sun Jul 24 18:50:51 2022 +0200
Avoid Texinfo processor name when not needed, prefere texi2any
* doc/texinfo.texi (Contents, Writing a Menu, Image Syntax)
(Conditional Commands, Defining Macros, Invoking Macros)
(Macro Details, HTML CSS, @code{@@documentdescription})
(Command Contexts): do not name a Texinfo
processor when features of the language or output expected from
all the processors are described.
(Macro Details): put information on @, in the by design limitations,
not in TeX caveats, as it is also relevant for texi2any.
(@code{@@alias}): use a similar wording with Macros for @alias
identifiers.
(Image Syntax): ignore text on compatibility for Info reader
not compatible with a feature introduced in 2003.
(@code{@@definfoenclose}): use @alias in TeX example, in order
to use Texinfo @-commands and not TeX only commands.
Remove the second definfoenclose example.
(Formatting Partial Documents, Updating Nodes and Menus)
(@command{texi2any} in Emacs, @code{texinfo-format} commands)
(Texinfo Mode Summary, Running @code{Info-validate})
(Info Format Indirect Table): use texi2any instead of makeinfo if
there is already texi2any or a reference to a node with texi2any in
the reference node name. Use @command instead of @code for texi2any
and makeinfo. For some Emacs related nodes, use texi2any
preferentially as those nodes are not often updated.
(@command{texi2any} in Emacs, @command{texi2any} Preferred): prefer
texi2any in node names.
---
ChangeLog | 30 +++++
doc/texinfo.texi | 332 +++++++++++++++++++++++++++----------------------------
2 files changed, 194 insertions(+), 168 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 05a7b3dd4b..56af8bd90f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,33 @@
+2022-07-24 Patrice Dumas <pertusus@free.fr>
+
+ Avoid Texinfo processor name when not needed, prefere texi2any
+
+ * doc/texinfo.texi (Contents, Writing a Menu, Image Syntax)
+ (Conditional Commands, Defining Macros, Invoking Macros)
+ (Macro Details, HTML CSS, @code{@@documentdescription})
+ (Command Contexts): do not name a Texinfo
+ processor when features of the language or output expected from
+ all the processors are described.
+ (Macro Details): put information on @, in the by design limitations,
+ not in TeX caveats, as it is also relevant for texi2any.
+ (@code{@@alias}): use a similar wording with Macros for @alias
+ identifiers.
+ (Image Syntax): ignore text on compatibility for Info reader
+ not compatible with a feature introduced in 2003.
+ (@code{@@definfoenclose}): use @alias in TeX example, in order
+ to use Texinfo @-commands and not TeX only commands.
+ Remove the second definfoenclose example.
+ (Formatting Partial Documents, Updating Nodes and Menus)
+ (@command{texi2any} in Emacs, @code{texinfo-format} commands)
+ (Texinfo Mode Summary, Running @code{Info-validate})
+ (Info Format Indirect Table): use texi2any instead of makeinfo if
+ there is already texi2any or a reference to a node with texi2any in
+ the reference node name. Use @command instead of @code for texi2any
+ and makeinfo. For some Emacs related nodes, use texi2any
+ preferentially as those nodes are not often updated.
+ (@command{texi2any} in Emacs, @command{texi2any} Preferred): prefer
+ texi2any in node names.
+
2022-07-24 Gavin Smith <gavinsmith0123@gmail.com>
* README-hacking: tab instead of spaces in git hook
diff --git a/doc/texinfo.texi b/doc/texinfo.texi
index 7593f227d4..c6556ec29d 100644
--- a/doc/texinfo.texi
+++ b/doc/texinfo.texi
@@ -630,10 +630,10 @@ Updating Nodes and Menus
Formatting for Info
-* @code{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
+* @command{texi2any} in Emacs:: How to run @command{texi2any} from
Emacs.
* @code{texinfo-format} commands:: Two Info formatting commands written
in Emacs Lisp are an alternative
- to @code{makeinfo}.
+ to @command{texi2any}.
Direct Formatting of Info files
@@ -642,7 +642,7 @@ Direct Formatting of Info files
Catching Mistakes
-* @command{makeinfo} Preferred:: @code{makeinfo} finds errors.
+* @command{texi2any} Preferred:: @command{texi2any} finds errors.
* Debugging with Info:: How to catch errors with Info formatting.
* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting.
* Running @code{Info-validate}:: How to find badly referenced nodes.
@@ -2545,11 +2545,10 @@ them.
Since an Info file uses menus instead of tables of contents, the Info
formatting commands ignore the contents commands. But the contents
-are included in plain text output (generated by @code{makeinfo
---plaintext}) and in other output formats, such as HTML.
+are included in plain text output and in other output formats, such
+as HTML.
-When @code{makeinfo} writes a short table of contents while producing
-HTML output, the links in the short table of contents point to
+In HTML output, the links in the short table of contents point to
corresponding entries in the full table of contents rather than the text
of the document. The links in the full table of contents point to the
main text of the document.
@@ -3202,8 +3201,8 @@ or chapter-level node. This is an exception to the rule
of
`Next' being at the same hierarchical level.
@cindex @code{accesskey} @subentry in HTML output of nodes
-The Info and HTML output from @command{makeinfo} for each node includes
-links to the `Next', `Previous', and `Up' nodes. The HTML also uses
+The Info and HTML output for each node includes links to the
+`Next', `Previous', and `Up' nodes. The HTML also uses
the @code{accesskey} attribute with the values @samp{n}, @samp{p}, and
@samp{u} respectively. This allows people using web browsers to
follow the navigation using (typically) @kbd{M-@var{letter}}, e.g.,
@@ -3422,11 +3421,11 @@ In Info, a user selects a node with the @kbd{m}
(@code{Info-menu})
command. The menu entry name is what the user types after the @kbd{m}
command.
@cindex @code{accesskey} @subentry in HTML output of menus
-In the HTML output from @command{makeinfo}, the @code{accesskey}
-attribute is used with the values @samp{1}@dots{}@samp{9} for the
-first nine entries. This allows people using web browsers to follow
-the first menu entries using (typically) @kbd{M-@var{digit}}, e.g.,
-@kbd{M-1} for the first entry.
+In the HTML output, the @code{accesskey} attribute is used with the
+values @samp{1}@dots{}@samp{9} for the first nine entries. This
+allows people using web browsers to follow the first menu entries
+using (typically) @kbd{M-@var{digit}}, e.g., @kbd{M-1} for the first
+entry.
@node Menu Example
@@ -8236,31 +8235,31 @@ extension, because the different processors support
different formats:
@pindex png image format
@pindex jpeg image format
@pindex pdf image inclusions
-pdf@TeX{} reads @file{@var{filename}.pdf}, @file{@var{filename}.png},
+@TeX{} (PDF output) reads @file{@var{filename}.pdf}, @file{@var{filename}.png},
@file{@var{filename}.jpg}, or @file{@var{filename}.jpeg} (in that
order). It also tries uppercase versions of the extensions. The PDF
format does not support EPS images, so such must be converted first.
@item
-For Info, @code{makeinfo} includes @file{@var{filename}.txt} verbatim
+In Info, @file{@var{filename}.txt} is included verbatim
(more or less as if it were in @code{@@verbatim}). The Info output
may also include a reference to @file{@var{filename}.png} or
@file{@var{filename}.jpg}. (See below.)
@item
-For HTML, @code{makeinfo} outputs a reference to
-@file{@var{filename}.png}, @file{@var{filename}.jpg},
-@file{@var{filename}.jpeg} or @file{@var{filename}.gif} (in that
-order). If none of those exist, it gives an error, and outputs a
+In HTML, a reference to @file{@var{filename}.png},
+@file{@var{filename}.jpg}, @file{@var{filename}.jpeg} or
+@file{@var{filename}.gif} (in that order) is output. If
+none of those exist, it gives an error, and outputs a
reference to @file{@var{filename}.jpg} anyway.
@item
@cindex SVG images, used in DocBook
-For DocBook, @code{makeinfo} outputs references to
+In DocBook, references to
@file{@var{filename}.eps}, @file{@var{filename}.gif}
@file{@var{filename}.jpeg}, @file{@var{filename}.jpg},
@file{@var{filename}.pdf}, @file{@var{filename}.png} and
-@file{@var{filename}.svg}, for every file found. Also,
+@file{@var{filename}.svg} are output, for every file found. Also,
@file{@var{filename}.txt} is included verbatim, if present. (The
subsequent DocBook processor is supposed to choose the appropriate one.)
@@ -8270,8 +8269,8 @@ the subsequent @LaTeX{} processor is supposed to choose
the
appropriate image type.
@item
-For Info and HTML output, @code{makeinfo} uses the optional fifth
-argument @var{extension} to @code{@@image} for the file extension,
+For Info and HTML output, the optional fifth argument @var{extension}
+to @code{@@image} is used for the file extension,
if it is specified and the file is found. Any leading period should
be included in @var{extension}. For example:
@@ -8303,10 +8302,10 @@ Use @code{@@center} to center an image
@cindex Alt attribute for images
@cindex Images @subentry alternate text for
@findex @sortas{-} -@r{ (in image alt string)}
-For HTML output, @code{makeinfo} sets the @dfn{alt attribute} for
-inline images to the optional @var{alttext} (fourth) argument to
-@code{@@image}, if supplied. If not supplied, @code{makeinfo} uses
-the full file name of the image being displayed. The @var{alttext} is
+For HTML output, the @dfn{alt attribute} for
+inline images is set to the optional @var{alttext} (fourth) argument to
+@code{@@image}, if supplied. If not supplied, the full file name of
+the image being displayed is used. The @var{alttext} is
processed as Texinfo text, so special characters such as @samp{"} and
@samp{<} and @samp{&} are escaped in the HTML output; also, you can
get an empty @code{alt} string with @code{@@-} (a command that
@@ -8316,15 +8315,17 @@ For Info output, the @code{alt} string is also
processed as Texinfo
text and output. In this case, @samp{\} is escaped as @samp{\\} and
@samp{"} as @samp{\"}; no other escapes are done.
-In Info output, @code{makeinfo} writes a reference to the binary image
-file (trying @var{filename} suffixed with @file{@var{extension}},
+In Info output, a reference to the binary image file is written
+(trying @var{filename} suffixed with @file{@var{extension}},
@file{@var{.extension}}, @file{.png}, or @file{.jpg}, in that order)
-if one exists. It also literally includes the @file{.txt} file if one
+if one exists. The @file{.txt} file is also literally included, if one
exists. This way, Info readers which can display images (such as the
Emacs Info browser, running under X) can do so, whereas Info readers
which can only use text (such as the standalone Info reader) can
display the textual version.
+@c Texinfo version 4.6 was released in 2003
+@ignore
@cindex @samp{^@@^H} for images in Info
The implementation of this is to put the following construct into the
Info output:
@@ -8341,6 +8342,7 @@ corresponding argument is omitted.
The reason for mentioning this here is that older Info browsers (this
feature was introduced in Texinfo version 4.6) will display the above
literally, which, although not pretty, should not be harmful.
+@end ignore
@node Image Scaling
@@ -12622,11 +12624,10 @@ format, to allow conditional inclusion of text for a
particular output
format.
@findex ifinfo
-@code{@@ifinfo} begins segments of text that should be ignored by
-@TeX{} when it typesets the printed manual, and by @command{makeinfo}
-when not producing Info output. The segment of text appears only in
-the Info file and, for historical compatibility, the plain text
-output.
+@code{@@ifinfo} begins segments of text that should be ignored when
+not producing Info output, in particular in printed output. The
+segment of text appears only in the Info file and, for historical
+compatibility, the plain text output.
@findex ifdocbook
@findex ifhtml
@@ -13498,13 +13499,13 @@ arguments supplied when the macro is subsequently
used in the document
@cindex Macro names, valid characters in
@cindex Names of macros, valid characters of
-For a macro to work consistently with @TeX{}, @var{macroname} must
-consist entirely of letters: no digits, hyphens, underscores, or other
-special characters. So, we recommend using only letters. However,
-@command{makeinfo} will accept anything consisting of alphanumerics,
+In principle, @var{macroname} should consist of alphanumerics,
and (except as the first character) @samp{-}. The @samp{_} character
is excluded so that macros can be called inside @code{@@math} without
-a following space (@pxref{Inserting Math}).
+a following space (@pxref{Inserting Math}). However, for a macro to
+work consistently with @TeX{}, @var{macroname} must consist entirely
+of letters: no digits, hyphens, or other special characters.
+So, we recommend using only letters.
If a macro needs no parameters, you can define it either with an empty
list (@samp{@@macro foo @{@}}) or with no braces at all (@samp{@@macro
@@ -13622,8 +13623,7 @@ character, as in @samp{\,}, but this does not work with
@TeX{}.
@cindex Automatic quoting of commas for some macros
@cindex Quoting, automatic for some macros
It's not always necessary to worry about commas. To facilitate use of
-macros, @command{makeinfo} implements two rules for @dfn{automatic
-quoting} in some circumstances:
+macros, two rules for @dfn{automatic quoting} are implemented:
@enumerate 1
@item If a macro takes only one argument, all commas in its invocation
@@ -13646,7 +13646,7 @@ will produce the following output
@strong{TRYME: A nice feature, though it can be dangerous.}
@end example
-And indeed, it can. Namely, @command{makeinfo} does not control the
+And indeed, it can. Namely, there is no control on the
number of arguments passed to one-argument macros, so be careful when
you invoke them.
@@ -13742,8 +13742,7 @@ Both: a.
@cindex Macro expansion, contexts for
@cindex Expansion of macros, contexts for
-By design, macro expansion does not happen in the following contexts
-in @command{makeinfo}:
+By design, macro expansion should not happen in the following contexts:
@itemize @bullet
@item @code{@@macro} and @code{@@unmacro} lines;
@@ -13836,30 +13835,6 @@ Macros can't be reliably used in the argument to
accent commands
The backslash escape for commas in macro arguments does not work;
@code{@@comma@{@}} must be used.
-@item
-Likewise, if you want to pass an argument with the Texinfo command
-@code{@@,} (to produce a cedilla, see @ref{Inserting Accents}), you have
-to use @code{@@value} or another workaround. Otherwise, the comma
-may be taken as separating the arguments. For example,
-
-@example
-@@macro mactwo@{argfirst, argsecond@}
-\argfirst\+\argsecond\.
-@@end macro
-@@set fc Fran@@,cois
-@@mactwo@{@@value@{fc@},@}
-@end example
-
-@noindent produces:
-
-@display
-Fran@,cois+.
-@end display
-
-@c currently @mactwo{Fran@,cois} works in TeX, but @mactwo{Franc@\,cois}
-@c works in makeinfo. better to avoid commas altogether using this trick.
-@c an alternative to @, could be invented if needed.
-
@item
Ending a macro body with @samp{@@c} may cause text following the macro
invocation to be ignored as a comment in @command{makeinfo}. This is
@@ -13906,10 +13881,37 @@ something involving \arg\ somehow
@end example
@end itemize
-The @command{makeinfo} implementation also has the following
-limitations (by design):
+The following limitations are by design:
@itemize
+@item
+If you want to pass an argument with the Texinfo command
+@code{@@,} (to produce a cedilla, see @ref{Inserting Accents}), you have
+to use @code{@@value} or another workaround. Otherwise, the comma
+may be taken as separating the arguments. With @command{makeinfo},
+the comma can be escaped by a backslash. With @TeX{} another workaround
+need to be used, therefore we recommend using such a workaround.
+
+For example,
+
+@example
+@@macro mactwo@{argfirst, argsecond@}
+\argfirst\+\argsecond\.
+@@end macro
+@@set fc Fran@@,cois
+@@mactwo@{@@value@{fc@},@}
+@end example
+
+@noindent produces:
+
+@display
+Fran@,cois+.
+@end display
+
+@c currently @mactwo{Fran@,cois} works in TeX, but @mactwo{Franc@\,cois}
+@c works in makeinfo. better to avoid commas altogether using this trick.
+@c an alternative to @, could be invented if needed.
+
@item
@code{@@verbatim} and macros do not mix; for instance, you can't start
a verbatim block inside a macro and end it outside
@@ -13924,7 +13926,8 @@ correctly paired. For example, you cannot start a
macro definition
within a macro, and then end that nested definition outside the macro.
@end itemize
-In the @code{makeinfo} implementation before Texinfo 5.0, ends of
+@c Texinfo 5.0 released in 2013
+In the @command{makeinfo} implementation before Texinfo 5.0, ends of
lines from expansion of a @code{@@macro} definition did not end an
@@-command line-delimited argument (@code{@@chapter}, @code{@@center},
etc.). This is no longer the case. For example:
@@ -13998,9 +14001,10 @@ Texinfo command name as an alias. Unfortunately this
is a very large
set of names, and the possible resulting errors from @TeX{} are
unpredictable.
-@command{makeinfo} will accept the same identifiers for aliases as it
-does for macro names, that is, alphanumerics and (except as the first
-character) @samp{-}.
+Alias identifiers should be the same as for macro names, that is
+alphanumerics and (except as the first character) @samp{-}. However,
+with @TeX{}, letters only should be used. So, we recommend using only
+letters.
@node @code{@@definfoenclose}
@@ -14052,7 +14056,7 @@ For @TeX{} formatting, you could write
@example
@@iftex
-@@global@@let@@phoo=@@i
+@@alias phoo = i
@@end iftex
@end example
@@ -14061,23 +14065,11 @@ to define @code{@@phoo} as a command that causes
@TeX{} to typeset the
argument to @code{@@phoo} in italics.
Each definition applies to its own formatter: one for @TeX{}, the
-other for everything else. The raw @TeX{} commands need to be in
+other for everything else. The @TeX{} definitions need to be in
@samp{@@iftex}. @code{@@definfoenclose} command need not be within
@samp{@@ifinfo} unless you want to use different definitions for
different output formats.
-@findex headword
-Here is another example: write
-
-@example
-@@definfoenclose headword, , :
-@end example
-
-@noindent
-near the beginning of the file, to define @code{@@headword} as an Info
-formatting command that inserts nothing before and a colon after the
-argument to @code{@@headword}.
-
@samp{@@definfoenclose} definitions must not be recursive, directly or
indirectly.
@@ -14808,7 +14800,7 @@ Thus, the beginning of your file would look
approximately like this:
@end example
@noindent @code{@@novalidate} also turns off validation in
-@code{makeinfo}, just like its @code{--no-validate} option
+@command{texi2any}, just like its @code{--no-validate} option
(@pxref{Invoking @command{texi2any}}).
Furthermore, you need not run @code{texindex} each time after you run
@@ -15406,11 +15398,11 @@ turn. If an input file name is @samp{-}, standard
input is read.
@anchor{@command{makeinfo} Options}
@c anchor{makeinfo options}@c prev name, but case-insensitive clash
-@cindex @code{makeinfo} options
-@cindex Options for @code{makeinfo}
-@anchor{texi2any Options}
-@cindex @code{texi2any} options
-@cindex Options for @code{texi2any}
+@cindex @command{makeinfo} options
+@cindex Options for @command{makeinfo}
+@anchor{@command{texi2any} Options}
+@cindex @command{texi2any} options
+@cindex Options for @command{texi2any}
The @command{texi2any} program accepts many options. Perhaps the
most basic are those that change the output format. By default,
@@ -17916,7 +17908,7 @@ node, in bytes from the beginning of the (unsplit)
output.
If you are using @code{texinfo-format-buffer} to create Info files,
you may want to run the @code{Info-validate} command. (The
-@code{makeinfo} command does such a good job on its own, you do not
+@command{texi2any} command does such a good job on its own, you do not
need @code{Info-validate}.) However, you cannot run the @kbd{M-x
Info-validate} node-checking command on indirect files. For
information on how to prevent files from being split with
@@ -18168,7 +18160,7 @@ Cascading Style Sheets (CSS for short) is an Internet
standard for
influencing the display of HTML documents: see
@uref{http://www.w3.org/Style/CSS/}.
-By default, @command{makeinfo} includes a few simple CSS commands to
+By default, a few simple CSS commands are included to
better implement the appearance of some Texinfo environments. Here
is one of them, as an example:
@@ -18213,7 +18205,7 @@ The CSS file may begin with so-called @samp{@@import}
directives,
which link to external CSS specifications for browsers to use when
interpreting the document. Again, a full description is beyond our
scope here, but we'll describe how they work syntactically, so we can
-explain how @command{makeinfo} handles them.
+explain how they are handled.
@cindex Comments, in CSS files
There can be more than one @samp{@@import}, but they have to come
@@ -18226,41 +18218,39 @@ C@. An @samp{@@import} directive must be in one of
these two forms:
@@import "http://example.net/bar.css";;
@end example
-As far as @command{makeinfo} is concerned, the crucial characters are
-the @samp{@@} at the beginning and the semicolon terminating the
-directive. When reading the CSS file, it simply copies any such
-@samp{@@}-directive into the output, as follows:
+The crucial characters are the @samp{@@} at the beginning and
+the semicolon terminating the directive. When reading the CSS
+file, any such @samp{@@}-directive is simply copied into the
+output, as follows:
@itemize
@item If @var{file} contains only normal CSS declarations, it is
-included after @command{makeinfo}'s default CSS, thus overriding it.
+included after the default CSS, thus overriding it.
@item If @var{file} begins with @samp{@@import} specifications (see
below), then the @samp{import}'s are included first (they have to come
-first, according to the standard), and then @command{makeinfo}'s
-default CSS is included. If you need to override @command{makeinfo}'s
-defaults from an @samp{@@import}, you can do so with the @samp{!@:
-important} CSS construct, as in:
+first, according to the standard), and then the default CSS is
+included. If you need to override the default CSS from an
+@samp{@@import}, you can do so with the @samp{!@: important} CSS
+construct, as in:
@example
pre.example @{ font-size: inherit ! important @}
@end example
@item If @var{file} contains both @samp{@@import} and inline CSS
specifications, the @samp{@@import}'s are included first, then
-@command{makeinfo}'s defaults, and lastly the inline CSS from
-@var{file}.
+default CSS, and lastly the inline CSS from @var{file}.
@item Any @@-directive other than @samp{@@import} and @samp{@@charset}
-is treated as a CSS declaration, meaning @command{makeinfo} includes
-its default CSS and then the rest of the file.
+is treated as a CSS declaration, meaning the default CSS is included
+and then the rest of the file is prepended.
@end itemize
-If the CSS file is malformed or erroneous, @command{makeinfo}'s output
-is unspecified. @command{makeinfo} does not try to interpret the
-meaning of the CSS file in any way; it just looks for the special
-@samp{@@} and @samp{;} characters and blindly copies the text into the
-output. Comments in the CSS file may or may not be included in the
-output.
+If the CSS file is malformed or erroneous, the output
+is unspecified. The meaning of the CSS file is not interpreted in
+any way; the special @samp{@@} and @samp{;} characters are looked for
+the text is blindly copied into the output. Comments in the CSS
+file may or may not be included in the output.
In addition to the possibilities offered by CSS, @command{makeinfo}
has many user-definable customization variables with which you can
@@ -18790,8 +18780,8 @@ usual. You can get the latest version from
@cindex @code{<meta>} HTML tag, and document description
@findex documentdescription
-When producing HTML output for a document, @command{makeinfo} writes a
-@samp{<meta>} element in the @samp{<head>} to give some idea of the
+When producing HTML output for a document, a @samp{<meta>} element
+is written in the @samp{<head>} to give some idea of the
content of the document. By default, this @dfn{description} is the
title of the document, taken from the @code{@@settitle} command
(@pxref{@code{@@settitle}}). To change this, use the
@@ -20183,9 +20173,9 @@ references, including in node headers in HTML.
@xref{Three Arguments}.
Here we describe approximately which @@-commands can be used in which
contexts. It is not exhaustive or meant to be a complete reference.
-Discrepancies between the information here and the @code{makeinfo} or
-@TeX{} implementations are most likely to be resolved in favor of the
-implementation.
+Discrepancies between the information here and the Texinfo processors
+implementations are most likely to be resolved in favor of the
+implementations.
By @dfn{general text} below, we mean anything except sectioning and
other such outer-level document commands, such as @code{@@section},
@@ -21336,12 +21326,12 @@ for more information.
@cindex Insert nodes, menus automatically
@cindex Automatically insert nodes, menus
-The @code{makeinfo} command will create an Info file for a hierarchically
+The @command{texi2any} command will create an Info file for a hierarchically
organized Texinfo file that lacks `Next', `Previous' and `Up' pointers
(@pxref{Writing a Node}). Thus, in general, there is no need for explicit
`Next', `Previous', and `Up' pointers. In this setting, menus will be added
automatically for nodes without an explicit menu. (@xref{Generic Translator
-@command{texi2any}}, for more information about @code{makeinfo}.)
+@command{texi2any}}, for more information about @command{texi2any}.)
If you still want explicit pointers, Texinfo mode provides commands for
automatically creating or updating menus and node pointers. The commands are
@@ -21781,29 +21771,33 @@ Texinfo mode provides several commands for formatting
part or all of a
Texinfo file for Info.
@menu
-* @code{makeinfo} in Emacs:: How to run @code{makeinfo} from Emacs.
+* @command{texi2any} in Emacs:: How to run @code{texi2any} from Emacs.
* @code{texinfo-format} commands:: Two Info formatting commands written
in Emacs Lisp are an alternative
- to @code{makeinfo}.
+ to @command{texi2any}.
@end menu
-@node @code{makeinfo} in Emacs
-@subsection Running @code{makeinfo} Within Emacs
+@node @command{texi2any} in Emacs
+@subsection Running @command{texi2any}/@command{makeinfo} Within Emacs
@c anchor{makeinfo in Emacs}@c prev name
-@cindex Running @code{makeinfo} in Emacs
-@cindex @code{makeinfo} inside Emacs
-@cindex Shell, running @code{makeinfo} in
-
-The @command{makeinfo} program provides better error messages
+@anchor{@code{makeinfo} in Emacs}@c prev name
+@cindex Running @command{makeinfo} in Emacs
+@cindex Running @command{texi2any} in Emacs
+@cindex @command{makeinfo} inside Emacs
+@cindex @command{texi2any} inside Emacs
+@cindex Shell, running @command{makeinfo} in
+@cindex Shell, running @command{texi2any} in
+
+The @command{texi2any} program provides better error messages
than either of the Emacs formatting commands. We recommend it.
-The @command{makeinfo} program is independent of Emacs.
+The @command{texi2any} program is independent of Emacs.
-You can run @code{makeinfo} in GNU Emacs Texinfo mode by using either the
-@code{makeinfo-region} or the @code{makeinfo-buffer} commands. In
-Texinfo mode, the commands are bound to @kbd{C-c C-m C-r} and @kbd{C-c
-C-m C-b} by default.
+You can run @command{texi2any} (or @command{makeinfo}) in GNU Emacs
+Texinfo mode by using either the @code{makeinfo-region} or the
+@code{makeinfo-buffer} commands. In Texinfo mode, the commands
+are bound to @kbd{C-c C-m C-r} and @kbd{C-c C-m C-b} by default.
@table @kbd
@item C-c C-m C-r
@@ -21823,8 +21817,8 @@ buffer. When you invoke @code{makeinfo-buffer} output
goes to the
file set with @code{@@setfilename} (@pxref{@code{@@setfilename}}).
The Emacs @code{makeinfo-region} and @code{makeinfo-buffer} commands
-run the @code{makeinfo} program in a temporary shell buffer. If
-@code{makeinfo} finds any errors, Emacs displays the error messages in
+run the @command{texi2any} program in a temporary shell buffer. If
+@command{texi2any} finds any errors, Emacs displays the error messages in
the temporary buffer.
@cindex Errors, parsing
@@ -21832,12 +21826,12 @@ the temporary buffer.
@findex next-error
You can parse the error messages by typing @kbd{C-x `}
(@code{next-error}). This causes Emacs to go to and position the
-cursor on the line in the Texinfo source that @code{makeinfo} thinks
+cursor on the line in the Texinfo source that @command{texi2any} thinks
caused the error. @xref{Compilation, , Running @code{make} or
Compilers Generally, emacs, The GNU Emacs Manual}, for more
information about using the @code{next-error} command.
-In addition, you can kill the shell in which the @code{makeinfo}
+In addition, you can kill the shell in which the @command{texi2any}
command is running or make the shell buffer display its most recent
output.
@@ -21845,13 +21839,13 @@ output.
@item C-c C-m C-k
@itemx M-x makeinfo-kill-job
@findex makeinfo-kill-job
-Kill the current running @code{makeinfo} job
+Kill the current running @command{texi2any} (or @command{makeinfo}) job
(from @code{makeinfo-region} or @code{makeinfo-buffer}).
@item C-c C-m C-l
@itemx M-x makeinfo-recenter-output-buffer
@findex makeinfo-recenter-output-buffer
-Redisplay the @code{makeinfo} shell buffer to display its most recent
+Redisplay the @command{texi2any} shell buffer to display its most recent
output.
@end table
@@ -21860,7 +21854,7 @@ output.
job are @kbd{C-c C-t C-k} and @kbd{C-c C-t C-l}. @xref{Texinfo Mode
Printing}.)
-You can specify options for @code{makeinfo} by setting the
+You can specify options for @command{texi2any} by setting the
@code{makeinfo-options} variable with either the @kbd{M-x
customize} or the @kbd{M-x set-variable} command, or by setting the
variable in your @file{.emacs} initialization file.
@@ -21879,7 +21873,7 @@ For example, you could write the following in your
@file{.emacs} file:
@c Writing these three cross-references using xref results in
@c three references to the same named manual, which looks strange.
@iftex
-For more information, see @ref{@command{makeinfo} Options}, as well as
+For more information, see @ref{@command{texi2any} Options}, as well as
``Easy Customization Interface,'' ``Examining and Setting Variables,''
and ``Init File'' in @cite{The GNU Emacs Manual}.
@end iftex
@@ -21888,7 +21882,7 @@ For more information, see@*
@ref{Easy Customization, , Easy Customization Interface, emacs, The GNU Emacs
Manual},@*
@ref{Examining, , Examining and Setting Variables, emacs, The GNU Emacs
Manual},@*
@ref{Init File, , , emacs, The GNU Emacs Manual}, and@*
-@ref{@command{makeinfo} Options}.
+@ref{@command{texi2any} Options}.
@end ifnottex
@@ -21925,8 +21919,8 @@ The @code{texinfo-format-region} and
@code{texinfo-format-buffer}
commands provide you with some error checking, and other functions can
provide you with further help in finding formatting errors. These
procedures are described in an appendix; see @ref{Catching Mistakes}.
-However, the @code{makeinfo} program provides better error checking
-(@pxref{@code{makeinfo} in Emacs}).
+However, the @command{texi2any} program provides better error checking
+(@pxref{@command{texi2any} in Emacs}).
A peculiarity of the @code{texinfo-format-buffer} and
@code{texinfo-format-region} commands is that they do not indent (nor
@@ -22102,8 +22096,9 @@ invoked by typing @kbd{C-c C-e} and then either
@kbd{C-r} for a region
or @kbd{C-b} for the whole buffer.
The Info formatting commands that are based on the
-@code{makeinfo} program are invoked by typing @kbd{C-c C-m} and then
-either @kbd{C-r} for a region or @kbd{C-b} for the whole buffer.
+@command{texi2any}/@command{makeinfo} program are invoked by typing
+@kbd{C-c C-m} and then either @kbd{C-r} for a region or @kbd{C-b} for
+the whole buffer.
@need 800
@noindent
@@ -22118,13 +22113,13 @@ C-c C-e C-b @r{Format the buffer.}
@need 750
@noindent
-Use @code{makeinfo}:
+Use @command{texi2any}/@command{makeinfo}:
@example
C-c C-m C-r @r{Format the region.}
C-c C-m C-b @r{Format the buffer.}
-C-c C-m C-l @r{Recenter the @code{makeinfo} output buffer.}
-C-c C-m C-k @r{Kill the @code{makeinfo} formatting job.}
+C-c C-m C-l @r{Recenter the @command{texi2any} output buffer.}
+C-c C-m C-k @r{Kill the @command{texi2any} formatting job.}
@end example
@subheading Typeset and Print
@@ -22294,28 +22289,29 @@ For finding problems with the structure of nodes and
chapters, you can use
command and you can use the @kbd{M-x Info-validate} command.
@menu
-* @command{makeinfo} Preferred:: @code{makeinfo} finds errors.
+* @command{texi2any} Preferred:: @command{texi2any} finds errors.
* Debugging with Info:: How to catch errors with Info formatting.
* Debugging with @TeX{}:: How to catch errors with @TeX{} formatting.
* Running @code{Info-validate}:: How to find badly referenced nodes.
@end menu
-@node @command{makeinfo} Preferred
-@subsection @command{makeinfo} Preferred
+@node @command{texi2any} Preferred
+@subsection @command{texi2any} Preferred
@c anchor{makeinfo Preferred}@c prev name
+@anchor{@code{makeinfo} Preferred}@c prev name
-The @code{makeinfo} program does an excellent job of catching errors
+The @command{texi2any} program does an excellent job of catching errors
and reporting them---far better than @code{texinfo-format-region} or
@code{texinfo-format-buffer}. In addition, the various functions for
automatically creating and updating node pointers and menus remove
many opportunities for human error.
-Use @code{makeinfo} (or its Texinfo mode manifestations,
+Use @command{texi2any} (or its Texinfo mode manifestations,
@code{makeinfo-region} and @code{makeinfo-buffer}) to format your
file and check for other errors. This is the best way to work with
-Texinfo. But if you cannot use @code{makeinfo}, or your problem
+Texinfo. But if you cannot use @command{texi2any}, or your problem
is very puzzling, then you may want to use the tools described
in this section.
@@ -22571,18 +22567,18 @@ node. This command checks that every node pointer
points to an
existing node. The @code{Info-validate} command works only on Info
files, not on Texinfo files.
-The @code{makeinfo} program validates pointers automatically, so you
+The @command{texi2any} program validates pointers automatically, so you
do not need to use the @code{Info-validate} command if you are using
-@code{makeinfo}. With the customization variable
-@code{CHECK_NORMAL_MENU_STRUCTURE} set, @command{makeinfo} will also
+@command{texi2any}. With the customization variable
+@code{CHECK_NORMAL_MENU_STRUCTURE} set, @command{texi2any} will also
warn if the nodes pointers (either explicitly or automatically set)
are not consistent with the order of node menu entries.
-@command{makeinfo} does not check that every `Next' pointer is matched
+@command{texi2any} does not check that every `Next' pointer is matched
by a `Previous' (in the node where the `Next' points) which points back,
since it may be correct for a non standard document structure.
You only may need to use @code{Info-validate} if you
-are unable to run @code{makeinfo} and instead must create an Info file
+are unable to run @command{texi2any} and instead must create an Info file
using @code{texinfo-format-region} or @code{texinfo-format-buffer}, or
if you write an Info file from scratch.
@@ -22747,7 +22743,7 @@ error occurs while attempting to format some of them.
Run @code{batch-texinfo-format} only with Emacs in batch mode as shown;
it is not interactive. It kills the batch mode Emacs on completion.
-@code{batch-texinfo-format} is convenient if you lack @code{makeinfo}
+@code{batch-texinfo-format} is convenient if you lack @command{texi2any}
and want to format several Texinfo files at once. When you use Batch
mode, you create a new Emacs process. This frees your current Emacs, so
you can continue working in it. (When you run
@@ -23656,7 +23652,7 @@ preamble.) The first node in the @file{gdb.info-2}
subfile would start at
byte 295733 if @file{gdb.info-2} were appended to @file{gdb.info-1},
including any preamble sections in both files.
-Unfortunately, Info-creating programs such as @code{makeinfo} have not
+Unfortunately, Info-creating programs such as @command{makeinfo} have not
always implemented these rules perfectly, due to various bugs and
oversights. Therefore, robust Info viewers should fall back to
searching ``nearby'' the given position for a node, instead of
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- branch master updated: Avoid Texinfo processor name when not needed, prefere texi2any,
Patrice Dumas <=