texinfo ChangeLog doc/texinfo.txi

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       10/07/26 00:34:35

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        invoking texi2any editing

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1078&r2=1.1079
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.269&r2=1.270

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1078
retrieving revision 1.1079
diff -u -b -r1.1078 -r1.1079
--- ChangeLog   25 Jul 2010 23:17:48 -0000      1.1078
+++ ChangeLog   26 Jul 2010 00:34:34 -0000      1.1079
@@ -1,8 +1,12 @@
+2010-07-25  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Invoking texi2any): general editing.
+
 2010-07-26  Patrice Dumas  <address@hidden>
 
        * texi2html/doc/: merge the texi2html manual in the texinfo
        manual, remove the manual and the directory.
-       * doc/texinfo.txi (Texi2HTML): add informations taken from
+       * doc/texinfo.txi (Texi2HTML): add information taken from
        the Texi2HTML manual with a bit more history.
 
 2010-07-25  Patrice Dumas  <address@hidden>

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.269
retrieving revision 1.270
diff -u -b -r1.269 -r1.270
--- doc/texinfo.txi     25 Jul 2010 23:17:49 -0000      1.269
+++ doc/texinfo.txi     26 Jul 2010 00:34:35 -0000      1.270
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.269 2010/07/25 23:17:49 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.270 2010/07/26 00:34:35 karl Exp $
 @c Ordinarily, Texinfo files have the extension .texi.  But texinfo.texi
 @c clashes with texinfo.tex on 8.3 filesystems, so we use texinfo.txi.
 
@@ -9711,14 +9711,14 @@
 @findex footnote
 
 A @dfn{footnote} is for a reference that documents or elucidates the
-primary address@hidden footnote should complement or expand upon
-the primary text, but a reader should not need to read a footnote to
+primary address@hidden footnote should complement or expand upon the
+primary text, but a reader should not need to read a footnote to
 understand the primary text.  For a thorough discussion of footnotes,
 see @cite{The Chicago Manual of Style}, which is published by the
 University of Chicago Press.}  Footnotes are distracting; use them
-sparingly, if at all.  Standard bibliographical references are better
-placed in a bibliography at the end of a document than in footnotes
-throughout.
+sparingly at most, and it is best to avoid them completely.  Standard
+bibliographical references are better placed in a bibliography at the
+end of a document instead of in footnotes throughout.
 
 @menu
 * Footnote Commands::           How to write a footnote in Texinfo.
@@ -9770,9 +9770,9 @@
 superscripted number which is rendered as a hypertext link to the
 footnote text.
 
-By the way, footnotes in the argument of an @code{@@item} command for a
address@hidden@@table} must be on the same line as the @code{@@item}
-(as usual).  @xref{Two-column Tables}.
+By the way, footnotes in the argument of an @code{@@item} command for
+a @code{@@table} must be on the same line as the @code{@@item} (as
+usual).  @xref{Two-column Tables}.
 
 
 @node Footnote Styles
@@ -9784,15 +9784,16 @@
 @itemize @bullet
 @cindex @address@hidden node footnote style
 @item
-In the `End' node style, all the footnotes for a single node
-are placed at the end of that node.  The footnotes are separated from
-the rest of the node by a line of dashes with the word
address@hidden within it.  Each footnote begins with an
address@hidden(@var{n})} reference mark.
+In the `End' node style, all the footnotes for a single node are
+placed at the end of that node.  The footnotes are separated from the
+rest of the node by a line of dashes with the word @samp{Footnotes}
+within it.  Each footnote begins with an @samp{(@var{n})} reference
+mark.
 
 @need 700
 @noindent
-Here is an example of a single footnote in the end of node style:@refill
+Here is an example of the Info output for a single footnote in the
+end-of-node style:
 
 @example
 @group
@@ -9855,16 +9856,15 @@
 @end example
 
 Write an @code{@@footnotestyle} command before or shortly after the
-end-of-header line at the beginning of a Texinfo file.  (If you
-include the @code{@@footnotestyle} command between the start-of-header
-and end-of-header lines, the region formatting commands will format
-footnotes as specified.)@refill
-
-If you do not specify a footnote style, the formatting commands use
-their default style.  Currently, @code{texinfo-format-buffer} and
address@hidden use the `separate' style and
address@hidden uses the `end' style.
+end-of-header line at the beginning of a Texinfo file.  (You should
+include any @code{@@footnotestyle} command between the start-of-header
+and end-of-header lines, so the region formatting commands will format
+footnotes as specified.)
 
+In HTML, when the footnote style is @samp{end}, or if the output is
+not split, footnotes are put at the end of the output.  If set to
address@hidden, and the output is split, they are placed in a
+separate file.
 
 @node Indices
 @chapter Indices
@@ -15978,46 +15978,37 @@
 @pindex texi2any
 
 To process a Texinfo file, invoke @command{texi2any} or 
address@hidden followed by the 
-name of the Texinfo file.  Also select the format you want to output
-with the appropriate command line option (default is Info for 
address@hidden).  Thus, to create the Info file for Bison, type 
-the following to the shell:
address@hidden followed by the name of the Texinfo file.  Also
+select the format you want to output with the appropriate command line
+option (default is Info for @command{makeinfo}).  Thus, to create the
+Info file for Bison, type one of the following to the shell:
 
 @example
 texi2any --info bison.texinfo
 @end example
 
-or
address@hidden or
 
 @example
 makeinfo bison.texinfo
 @end example
 
-
address@hidden FIXME is it relevant here?
address@hidden (You can run a shell inside Emacs by typing @kbd{M-x shell}.)
-
address@hidden @command{makeinfo} has many options to control its actions and 
output;
address@hidden see the next section.
-
-You can give @command{makeinfo} more than one input file name; each is
-processed in turn.  If an input file name is @samp{-}, or no input
-file names are given at all, standard input is read.
+You can specify more than one input file name; each is processed in
+turn.  If an input file name is @samp{-}, or no input file names at
+all are given, standard input is read.
 
 @anchor{makeinfo options}
 @cindex @code{makeinfo} options
 @cindex Options for @code{makeinfo}
 
-The @command{texi2any}/@command{makeinfo} programs accept 
-many options.  Perhaps the most
-commonly needed are those that change the output format.  By default,
address@hidden outputs Info files, while @command{texi2any} outputs
-raw text with minimal formatting.
-
-Each command line option is a word preceded by @samp{--} or a letter
-preceded by @samp{-}.  You can use abbreviations for the long option
-names as long as they are unique.
+The @command{texi2any}/@command{makeinfo} programs accept many
+options.  Perhaps the most basic are those that change the output
+format.  By default, @command{makeinfo} outputs Info files, while
address@hidden outputs raw text with minimal formatting.
+
+Each command line option is either a long name preceded by @samp{--}
+or a single letter preceded by @samp{-}.  You can use abbreviations
+for the long option names as long as they are unique.
 
 For example, you could use the following shell command to create an Info
 file for @file{bison.texinfo} in which each line is filled to only 68
@@ -16027,7 +16018,7 @@
 makeinfo --fill-column=68 bison.texinfo
 @end example
 
-You can write two or more options in sequence, like this:@refill
+You can write two or more options in sequence, like this:
 
 @example
 makeinfo --no-split --fill-column=70 @dots{}
@@ -16041,42 +16032,41 @@
 
 @table @code
 
address@hidden -D @var{var}
address@hidden -D @var{var}
-Cause the variable @var{var} to be defined.  This is equivalent to
address@hidden@@set @var{var}} in the Texinfo file (@pxref{set clear value}).
-
 @item --commands-in-node-names
 @opindex --commands-in-node-names
-This command used to ensure that @code{@@}-commands in node names were
-expanded through all the document, especially @code{@@value}. This is now
-done by default, though @@-commands in node names are still not officially
-part of the Texinfo language.
+This option now does nothing, but remains for compatibility.  (It used
+to ensure that @code{@@}-commands in node names were expanded
+throughout the document, especially @code{@@value}.  This is now done
+by default.)
 
 @item address@hidden
 @opindex address@hidden
-Append @var{path} to the directory search list for finding
+Prepend @var{path} to the directory search list for finding
 customization files that may be loaded with @option{--init-file} (see
-below).  
+below).  @var{path} can be a single directory, or a list of several
+directories separated by the usual path separator character (@samp{:}
+on GNU and Unix systems, @samp{;} on MS-DOS/MS-Windows).
 @xref{Loading initialization files}.
 
address@hidden can be a single directory, or a list of several directories
-separated by the usual path separator character (@samp{:} on GNU and
-Unix systems, @samp{;} on MS-DOS/MS-Windows).
-
 @item address@hidden
 @opindex --css-include
-Include the contents of @var{file}, which should contain cascading
-style sheets specifications, in the @samp{<style>} block of the HTML
-output.  @xref{HTML CSS}.  If @var{file} is @samp{-}, read standard
-input.
+When producing HTML, literally include the contents of @var{file},
+which should contain W3C cascading style sheets specifications, in the
address@hidden<style>} block of the HTML output.  If @var{file} is @samp{-},
+read standard input.  @xref{HTML CSS}.
 
 @item address@hidden
 @opindex --css-ref
-In HTML mode, add a @samp{<link>} tag to the HTML output which
+When producing HTML, add a @samp{<link>} tag to the output which
 references a cascading style sheet at @var{url}. This allows using
 standalone style sheets.
 
address@hidden -D @var{var}
address@hidden -D @var{var}
+Cause the Texinfo variable @var{var} to be defined.  This is
+equivalent to @code{@@set @var{var}} in the Texinfo file (@pxref{set
+clear value}).
+
 @item --disable-encoding
 @itemx --enable-encoding
 @opindex --disable-encoding
@@ -16090,51 +16080,52 @@
 
 @item --docbook
 @opindex --docbook
-Generate Docbook output rather than Info.
+Generate Docbook output.
 
 @item address@hidden
 @opindex --document-language
address@hidden LANG
 Use @var{lang} to translate Texinfo keywords which end up in the
 output document.  The default is the locale specified by the
address@hidden@@documentlanguage} command if there is one
address@hidden@@documentlanguage} command if there is one, otherwise English
 (@pxref{documentlanguage}).
 
 @item address@hidden
 @itemx -e @var{limit}
 @opindex address@hidden
 @opindex -e @var{limit}
-Set the maximum number of errors that @code{makeinfo} will report
-before exiting (on the assumption that continuing would be useless);
-default 100.
+Specify the maximum number of errors to report before aborting (on the
+assumption that continuing would be useless); default 100.
 
 @item address@hidden
 @itemx -f @var{width}
 @opindex address@hidden
 @opindex -f @var{width}
-Specify the maximum number of columns in a line; this is the right-hand
-edge of a line.  Paragraphs that are filled will be filled to this
-width.  (Filling is the process of breaking up and connecting lines so
-that lines are the same length as or shorter than the number specified
-as the fill column.  Lines are broken between words.) The default value
-is 72.  Only useful when generating Info.
+Specify the maximum number of columns in a line; this is the
+right-hand edge of a line.  Paragraphs that are filled will be filled
+to this width.  (Filling is the process of breaking up and connecting
+lines so that lines are the same length as or shorter than the number
+specified as the fill column.  Lines are broken between words.) The
+default value is 72.
 
 @item address@hidden
 @itemx -s @var{style}
 @opindex address@hidden
 @opindex -s @var{style}
-Set the footnote style to @var{style}, either @samp{end} for the end
-node style (the default) or @samp{separate} for the separate node style.
-The value set by this option overrides the value set in a Texinfo file
-by an @code{@@footnotestyle} command (@pxref{Footnotes}).  When the
-footnote style is @samp{separate}, @code{makeinfo} makes a new node
-containing the footnotes found in the current node.  When the footnote
-style is @samp{end}, @code{makeinfo} places the footnote references at
-the end of the current node.  
+Set the footnote style to @var{style}: either @samp{end} for the end
+node style (the default) or @samp{separate} for the separate node
+style.  The value set by this option overrides the value set in a
+Texinfo file by an @code{@@footnotestyle} command (@pxref{Footnote
+Styles}).
+
+When the footnote style is @samp{separate}, @code{makeinfo} makes a
+new node containing the footnotes found in the current node.  When the
+footnote style is @samp{end}, @code{makeinfo} places the footnote
+references at the end of the current node.
 
 In HTML, when the footnote style is @samp{end}, or if the output is
 not split, footnotes are put at the end of the output.  If set to
address@hidden, and the output is split, they are placed in a separate file.
address@hidden, and the output is split, they are placed in a
+separate file.
 
 @item --force
 @itemx -F
@@ -16147,23 +16138,14 @@
 @itemx -h
 @opindex --help
 @opindex -h
-Print a usage message listing all available options, then exit successfully.
+Print a usage message listing available options, then exit successfully.
 
 @item --html
 @opindex --html
-Generate HTML output.  @xref{Generating HTML}.  By
-default, the HTML output is split into one output file per Texinfo
-source node, and the split output is written into a subdirectory with
-the name of the top-level info file.
-
address@hidden --info
address@hidden --info
-Generate Info output.  By default, if the output file contains more 
-than about 300,000 bytes, the large Info output file is split 
-into shorter @dfn{indirect} subfiles of about 300,000 bytes each.  
-The name of the output file and of the indirect subfiles is 
-determined by @code{@@setfilename} (@pxref{setfilename}).  
address@hidden and Split Files}.
+Generate HTML output.  By default, the HTML output is split into one
+output file per Texinfo source node, and the split output is written
+into a subdirectory based on the name of the top-level Info file.
address@hidden HTML}.
 
 @item -I @var{dir}
 @opindex -I @var{dir}
@@ -16187,26 +16169,39 @@
 @opindex --iftex
 @itemx --ifxml
 @opindex --ifxml
-For the specified format, process @samp{@@address@hidden and
address@hidden@@@var{format}} commands even if not generating the given output
+For the given format, process @samp{@@address@hidden and
address@hidden@@@var{format}} commands, and do not process
address@hidden@@address@hidden, even if not generating the given output
 format.  For instance, if @option{--iftex} is specified, then
address@hidden@@iftex} and @samp{@@tex} blocks will be read.
address@hidden@@iftex} and @samp{@@tex} blocks will be read, and
address@hidden@@ifnottex} blocks will be ignored, even if @TeX{} is not being
+run.
+
address@hidden --info
address@hidden --info
+Generate Info output.  By default, if the output file contains more
+than about 300,000 bytes, it is split into shorter @dfn{indirect}
+subfiles of about that size.  The name of the output file and of the
+indirect subfiles is determined by @code{@@setfilename}
+(@pxref{setfilename}).  @xref{Tag and Split Files}.
 
 @item address@hidden
 @opindex address@hidden
 Load @var{file} as code to modify the behavior and output of the
 generated manual.  It is customary to use the @code{.init} extension
 for these customization files, but that is not enforced by anything;
-the @var{file} name is taken literally.  @option{--conf-dir}, see
-above, may be used to add to the list of directories in which these
-customization files are searched for.  @xref{Loading initialization files}.
+the @var{file} name is taken literally.  @option{--conf-dir} (see
+above) may be used to add to the list of directories in which these
+customization files are searched for.  @xref{Loading initialization
+files}.
 
 @item address@hidden
 @opindex address@hidden
 In HTML mode, output a tab separated file containing three columns:
 the internal link to an indexed item or item in the table of contents,
-the name of the index (or "toc") in which it occurs, and the term
-which was indexed or entered.
+the name of the index (or table of contents) in which it occurs, and
+the term which was indexed or entered.  This can be useful for
+post-processors.
 
 @item address@hidden
 @itemx -E @var{file}
@@ -16214,7 +16209,7 @@
 @opindex -E @var{file}
 Output the Texinfo source with all the macros expanded to the named
 file.  Normally, the results of macro expansion are used internally by
address@hidden and then discarded.  This option is used by
address@hidden and then discarded.  This option can be used by
 @command{texi2dvi}.
 
 @item --no-headers
@@ -16224,17 +16219,17 @@
 @cindex Menus, omitting
 Do not include menus or node separator lines in the output.
 
-If generating Info, this is the same as using @option{--plaintext},
+When generating Info, this is the same as using @option{--plaintext},
 resulting in a simple plain text file.  Furthermore,
 @code{@@setfilename} is ignored, and output is to standard output
 unless overridden with @option{-o}.  (This behavior is for backward
 compatibility.)
 
 @cindex Navigation links, omitting
-For HTML output, also omit menus.  If output is split, output
-navigation links only at the beginning of each file, while if output
-is not split, do not include a navigation links at the top of each
-node.  @xref{Generating HTML}.
+When generating HTML, and output is split, also output navigation
+links only at the beginning of each file.  If output is not split, do
+not include navigation links at the top of each node at all.
address@hidden HTML}.
 
 @item --no-ifdocbook
 @opindex --no-ifdocbook
@@ -16248,22 +16243,27 @@
 @opindex --no-iftex
 @itemx --no-ifxml
 @opindex --no-ifxml
-Do not process @samp{@@address@hidden and @samp{@@@var{format}}
-commands, and do process @samp{@@address@hidden, even if
-generating the given format.  For instance, if @option{--no-ifhtml} is
-specified, then @samp{@@ifhtml} and @samp{@@html} blocks will not be
-read, and @samp{@@ifnothtml} blocks will be.
+For the given format, do not process @samp{@@address@hidden and
address@hidden@@@var{format}} commands, and do process
address@hidden@@address@hidden, even if generating the given format.  For
+instance, if @option{--no-ifhtml} is specified, then @samp{@@ifhtml}
+and @samp{@@html} blocks will not be read, and @samp{@@ifnothtml}
+blocks will be.
 
 @item --no-number-footnotes
 @opindex --no-number-footnotes
-Suppress automatic footnote numbering.  By default, @code{makeinfo}
-numbers each footnote sequentially in a single node, resetting the
-current footnote number to 1 at the start of each node.
+Suppress automatic footnote numbering.  By default, footnotes are
+numbered sequentially within a node, i.e., the current footnote number
+is reset to 1 at the start of each node.
 
 @item --no-number-sections
address@hidden --number-sections
 @opindex --no-number-sections
-Do not output chapter, section, and appendix numbers.
-You need to specify this if your manual is not hierarchically-structured.
address@hidden --number-sections
+With @option{--number_sections} (the default), output chapter,
+section, and appendix numbers as in printed manuals.  This works only
+with hierarchically-structured manuals.  You should specify
address@hidden if your manual is not normally structured.
 
 @item --no-pointer-validate
 @itemx --no-validate
@@ -16278,29 +16278,24 @@
 
 @item --no-warn
 @opindex --no-warn
-Suppress warning messages (but @emph{not} error messages).
+Suppress warning messages (but not error messages).
 
 @item --node-files
 @itemx --no-node-files
 @opindex --node-files
 @opindex --no-node-files
-When generating HTML, produce redirection files for anchors, and for
+When generating HTML, create redirection files for anchors and for any
 nodes that are not already output with the name corresponding to the
-node name (@pxref{HTML Xref Node Name Expansion}).  This is set by
-default if the output is split.  This option makes it possible for
-section- and chapter-level cross-manual references to succeeed
-(@pxref{HTML Xref Configuration}).
-
-If the output is not split, @option{--node-files} enables the creation
-of the redirection files.  @option{--no-node-files} suppress the
-output of any redirection files.  @xref{Generating HTML}.  This option
-has no effect with any output format other than HTML.
-
address@hidden --number-sections
address@hidden --number-sections
-Output chapter, section, and appendix numbers as in printed manuals.
-This is the default.  It works only with hierarchically-structured
-manuals.
+node name (@pxref{HTML Xref Node Name Expansion}).  This option makes
+it possible for section- and chapter-level cross-manual references to
+succeed (@pxref{HTML Xref Configuration}).
+
+This is set by default if the output is split.  If the output is not
+split, @option{--node-files} enables the creation of the redirection
+files, in addition to the monolithic main output file.
address@hidden suppresses the creation of redirection files
+in any case.  This option has no effect with any output format other
+than HTML.  @xref{Generating HTML}.
 
 @item address@hidden
 @itemx -o @var{file}
@@ -18439,10 +18434,10 @@
 for each style that can be generated:
 
 @smallexample
-node    => node,    section, chapter, mono
-section => section, chapter, node,    mono
-chapter => chapter, section, node,    mono
-mono    => mono,    chapter, section, split
+node    @result{} node,    section, chapter, mono
+section @result{} section, chapter, node,    mono
+chapter @result{} chapter, section, node,    mono
+mono    @result{} mono,    chapter, section, split
 @end smallexample
 
 @opindex address@hidden, and HTML cross-references}
@@ -24185,7 +24180,7 @@
 (@url{http://www.gnu.org/software/rcs}) version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.269 2010/07/25 23:17:49 pertusus Exp $
+$Id: texinfo.txi,v 1.270 2010/07/26 00:34:35 karl Exp $
 @end example
 (This is useful in all sources that use version control, not just manuals.)
 You may wish to include the @samp{$Id:} comment in the @code{@@copying}
@@ -24264,7 +24259,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.269 2010/07/25 23:17:49 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.270 2010/07/26 00:34:35 karl Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi