texinfo ChangeLog doc/texinfo.txi

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       12/01/10 19:37:07

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        document #line

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1299&r2=1.1300
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.408&r2=1.409

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1299
retrieving revision 1.1300
diff -u -b -r1.1299 -r1.1300
--- ChangeLog   9 Jan 2012 01:14:26 -0000       1.1299
+++ ChangeLog   10 Jan 2012 19:37:03 -0000      1.1300
@@ -1,3 +1,12 @@
+2012-01-10  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (External Macro Processors,
+       #line Directive,
+       #line and TeX,
+       #line Syntax Details): new nodes.
+
+       Also, use http://ftp.gnu.org in examples per sysadmin recommendation.
+
 2012-01-08  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi (Internationalization): move to above Conditionals,

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.408
retrieving revision 1.409
diff -u -b -r1.408 -r1.409
--- doc/texinfo.txi     9 Jan 2012 01:14:26 -0000       1.408
+++ doc/texinfo.txi     10 Jan 2012 19:37:05 -0000      1.409
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.408 2012/01/09 01:14:26 karl Exp $
address@hidden $Id: texinfo.txi,v 1.409 2012/01/10 19:37:05 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.
 
@@ -576,6 +576,12 @@
 * definfoenclose::              Customized highlighting.
 * External Macro Processors::   @code{#line} directives.
 
+External Macro Processors
+
+* #line Directive::
+* #line and TeX::
+* #line Syntax Details::
+
 Include Files
 
 * Using Include Files::         How to use the @code{@@include} command.
@@ -814,7 +820,7 @@
 We welcome bug reports and suggestions for any aspect of the Texinfo system,
 programs, documentation, installation, anything.  Please email them to
 @email{bug-texinfo@@gnu.org}.  You can get the latest version of Texinfo
-from @uref{ftp://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
+from @uref{http://ftp.gnu.org/gnu/texinfo/} and its mirrors worldwide.
 
 @cindex Checklist for bug reports
 For bug reports, please include enough information for the maintainers
@@ -991,7 +997,7 @@
 traditional man page from the @samp{--help} output of a program.  In
 fact, this is currently used to generate man pages for the programs in
 the Texinfo distribution.  It is GNU software written by Brendan
-O'Dea, available from @uref{ftp://ftp.gnu.org/gnu/help2man/}.
+O'Dea, available from @uref{http://ftp.gnu.org/gnu/help2man/}.
 
 @cindex Output formats, supporting more
 @cindex SGML-tools output format
@@ -6064,6 +6070,7 @@
 
 @node One Argument
 @subsection @code{@@xref} with One Argument
address@hidden One-argument form of cross-references
 
 The simplest form of @code{@@xref} takes one argument, the name of
 another node in the same Info file.  The Info formatters produce
@@ -6123,6 +6130,7 @@
 
 @node Two Arguments
 @subsection @code{@@xref} with Two Arguments
address@hidden Two-argument form of cross-references
 
 With two arguments, the second is used as the name of the Info cross
 reference, while the first is still the name of the node to which the
@@ -6189,6 +6197,7 @@
 
 @node Three Arguments
 @subsection @code{@@xref} with Three Arguments
address@hidden Three-argument form of cross-references
 
 A third argument replaces the node name in the @TeX{} output.  The third
 argument should be the name of the section in the printed output, or
@@ -6268,7 +6277,7 @@
 
 As a practical matter, it is often best to write cross references with
 just the first argument if the node name and the section title are the
-same (or nearly so), and with the first and third arguments if the
+same (or nearly so), and with the first and third arguments only if the
 node name and title are different.
 
 If you want the section title to be used by default instead of
@@ -6288,6 +6297,7 @@
 
 @node Four and Five Arguments
 @subsection @code{@@xref} with Four and Five Arguments
address@hidden Four- and five argument form of cross-references
 
 In a cross reference, a fourth argument specifies the name of another
 Info file, different from the file in which the reference appears, and
@@ -6764,36 +6774,36 @@
 both the target and the text of the link:
 
 @example
-The official GNU ftp site is @@address@hidden://ftp.gnu.org/address@hidden
+The official GNU ftp site is @@address@hidden://ftp.gnu.org/address@hidden
 @end example
 
 @noindent produces:
 @display
-The official GNU ftp site is @uref{ftp://ftp.gnu.org/gnu}.
+The official GNU ftp site is @uref{http://ftp.gnu.org/gnu}.
 @end display
 
 
 An example of the two-argument form:
 @example
-The official @@address@hidden://ftp.gnu.org/gnu, GNU ftp address@hidden
+The official @@address@hidden://ftp.gnu.org/gnu, GNU ftp address@hidden
 holds programs and texts.
 @end example
 
 @noindent produces:
 @display
-The official @uref{ftp://ftp.gnu.org/gnu, GNU ftp site}
+The official @uref{http://ftp.gnu.org/gnu, GNU ftp site}
 holds programs and texts.
 @end display
 
 @noindent that is, the Info output is this:
 @example
-The official GNU ftp site (ftp://ftp.gnu.org/gnu)
+The official GNU ftp site (http://ftp.gnu.org/gnu)
 holds programs and texts.
 @end example
 
 @noindent and the HTML output is this:
 @example
-The official <a href="ftp://ftp.gnu.org/gnu";>GNU ftp site</a>
+The official <a href="http://ftp.gnu.org/gnu";>GNU ftp site</a>
 holds programs and texts.
 @end example
 
@@ -13808,7 +13818,7 @@
 related to conditionals, since in practice it is most likely to be
 useful in that context.  Technically, it can be used anywhere.
 @xref{External Macro Processors}, for a caveat regarding the line
-numbers.
+numbers which @code{@@errormsg} emits in @TeX{}.
 
 
 @node Conditional Not Commands
@@ -14380,11 +14390,16 @@
 @samp{@@definfoenclose} allows you to define new commands with
 customized output in the Info file.
 
address@hidden
-It is possible to invoke an external macro processor and have Texinfo
-recognize so-called @code{#line} directives for error reporting.
 @end itemize
 
+Most generally of all, not just for defining new commands, it is
+possible to invoke an external macro processor and have Texinfo
+recognize so-called @code{#line} directives for error reporting.
+
+If you want to do simple text substitution, @code{@@set} and
address@hidden@@value} is the simplest approach (@pxref{set clear value,,
address@hidden@@address@hidden @code{@@address@hidden and @code{@@value}}).
+
 @menu
 * Defining Macros::             Defining and undefining new commands.
 * Invoking Macros::             Using a macro, once you've defined it.
@@ -14972,8 +14987,129 @@
 @cindex External macro processors
 @cindex Macro processors, external
 
-Due to the peculiarities of Texinfo macros and other substitutions,
-you may wish to 
+Texinfo macros (and its other text substitution facilities) work fine
+in straightforward cases.  If your document needs unusually complex
+processing, however, their fragility and limitations can be a problem.
+In this case, you may want to use a different macro processor
+altogether, such as M4 (@pxref{Top,, Preliminaries, m4, M4}) or CPP
+(@pxref{Top,, Overview, cpp, The C Preprocessor}).
+
+With one exception, Texinfo does not need to know whether its input is
+``original'' source or preprocessed from some other source file.
+Therefore, you can arrange your build system to invoke whatever
+programs you like to handle macro expansion or other preprocessing
+needs.  Texinfo does not offer built-in support for any particular
+preprocessor, since no one program seemed likely to suffice for the
+requirements of all documents.
+
address@hidden Line numbers, in error messages
address@hidden Error messages, line numbers in
+The one exception is line numbers in error messages.  In that case,
+the line number should refer to the original source file, whatever it
+may be.  There's a well-known mechanism for this: the so-called
address@hidden directive.  Texinfo supports this.
+
address@hidden
+* #line Directive::
+* TeX: #line and TeX.
+* Syntax: #line Syntax Details.
address@hidden menu
+
+
address@hidden #line Directive
address@hidden @samp{#line} Directive
address@hidden @samp{#line} directive
+
+An input line such as this:
+
address@hidden
address@hidden 100 "foo.ptexi"
address@hidden example
+
address@hidden indicates that the next line was line 100 of the file
address@hidden, and so that's what an error message should refer to.
+Both M4 (@pxref{Preprocessor features,,, m4, GNU M4}) and CPP
+(@pxref{Line Control,,, cpp, The C Preprocessor}, and
address@hidden Output,,, cpp, The C Preprocessor}) can generate
+such lines.
+
+The @command{makeinfo} program recognizes these lines by default.  It
+can be turned off with @code{CPP_LINE_DIRECTIVES} (@pxref{Other
+Configuration Variables}), though there is normally no reason to do
+so.  For those few programs (M4, CPP, Texinfo) which need to document
address@hidden directives and therefore have examples which would
+otherwise match the pattern, the command @code{@@address@hidden@}} can be
+used (@pxref{Inserting a Hashsign}).  The example line above looks
+like this in the source for this manual:
+
address@hidden
+@@address@hidden@}line 100 "foo.ptexi"
address@hidden example
+
+The @code{@@hashchar} command was added to Texinfo in 2012.  If you
+don't want to rely on it, you can also use @code{@@set} and
address@hidden@@value} to insert the literal @samp{#}:
+
address@hidden
+@@set hash #
+@@address@hidden@}line 1 "example.c"
address@hidden example
+
+
address@hidden #line and TeX
address@hidden @samp{#line} and @TeX{}
address@hidden @TeX{} and @samp{#line} directives
+
+As mentioned, @command{makeinfo} recognizes the @samp{#line}
+directives described in the previous section.  However,
address@hidden does not and cannot.  Therefore, such a line will
+be incorrectly typeset verbatim if @TeX{} sees it.  The solution is to
+use the (Texinfo) macro expansion options.
+
+If you run @command{texi2dvi} or its variants (@pxref{Format with
+texi2dvi,, Format with @code{texi2dvi}}), you can pass @option{-E}.
+
+If you run @command{makeinfo} or its variants (@pxref{Generic
+Translator texi2any,, A Generic Translator: @command{texi2any}}), you
+can pass @option{--no-ifinfo --iftex -E somefile.mac} or @option{--dvi
+--Xopt -E}.  (Or @option{--pdf} instead of @option{--dvi}, of course.)
+With the former, you can then give @file{somefile.mac} to
address@hidden in a separate command; with the latter,
address@hidden will call @command{texi2dvi}.
+
address@hidden address@hidden, and line numbers in @TeX{}}
+There is one other caveat regarding use with @TeX{}: since the
address@hidden directives are not recognized, the line numbers emitted
+by the @code{@@address@hidden@}} command (@pxref{Conditional Commands}),
+or by @TeX{} itself, are the (incorrect) line numbers from the derived
+file which @TeX{} is reading, rather than the preprocessor-specified
+line numbers.  This is another instance of why we recommend running
address@hidden for the best diagnostics (@pxref{makeinfo
+advantages,, @code{makeinfo} Advantages}).
+
+
address@hidden #line Syntax Details
address@hidden @samp{#line} Syntax Details
address@hidden @samp{#line} syntax details
address@hidden Syntax details, @samp{#line}
+
+Syntax details for the @samp{#line} directive: the @samp{#} character
+can be preceded or followed by whitespace, the word @samp{line} is
+optional, and the file name can be followed by a whitespace-separated
+list of integers (these are so-called ``flags'' output by CPP in some
+cases).  For those who like to know the gory details, the actual
+(Perl) regular expression which is matched is this:
+
address@hidden
+^\s*#\s*(line)? (\d+)( "([^"]+)")?(\s+\d+)*\s*$
address@hidden example
+
+For example, the following is also a valid @samp{#line} directive,
+meaning line 1 of @file{/usr/include/stdio.h}:
+
address@hidden
+# 1 "/usr/include/stdio.h" 1 3 4
address@hidden example
 
 
 @node Include Files
@@ -17470,7 +17606,7 @@
 
 
 @node makeinfo advantages
address@hidden @code{makeinfo} Preferred
address@hidden @code{makeinfo} Advantages
 
 The @code{makeinfo} utility creates an Info file from a Texinfo source
 file more quickly than either of the Emacs formatting commands and
@@ -21393,7 +21529,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.408 2012/01/09 01:14:26 karl Exp $
+$Id: texinfo.txi,v 1.409 2012/01/10 19:37:05 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}
@@ -21992,13 +22128,13 @@
 
 
 @node makeinfo Preferred
address@hidden @code{makeinfo} Find Errors
address@hidden @code{makeinfo} Preferred
 
 The @code{makeinfo} 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 address@hidden
+many opportunities for human error.
 
 If you can, use the updating commands to create and insert pointers
 and menus.  These prevent many errors.  Then use @code{makeinfo} (or
@@ -22006,7 +22142,8 @@
 @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 is very puzzling, then you
-may want to use the tools described in this address@hidden
+may want to use the tools described in this appendix.
+
 
 @node Debugging with Info
 @section Catching Errors with Info Formatting