texinfo ChangeLog doc/texinfo.txi

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       12/02/16 18:38:18

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 

Log message:
        #line disabled in verbatim; @contents before sectioning

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1325&r2=1.1326
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.419&r2=1.420

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1325
retrieving revision 1.1326
diff -u -b -r1.1325 -r1.1326
--- ChangeLog   9 Feb 2012 23:51:50 -0000       1.1325
+++ ChangeLog   16 Feb 2012 18:38:16 -0000      1.1326
@@ -1,3 +1,11 @@
+2012-02-16  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (#line Directive): mention CPP_LINE_DIRECTIVES,
+       and #line not recognized in verbatim.
+       (#line Syntax Details): update regexp, discuss surprising
+       false positives.
+       (Contents): must come before any sectioning command.
+
 2012-02-10  Patrice Dumas  <address@hidden>
 
        * autogen.sh, tp/.cvsignore, tp/Makefile.am, 

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.419
retrieving revision 1.420
diff -u -b -r1.419 -r1.420
--- doc/texinfo.txi     7 Feb 2012 19:41:38 -0000       1.419
+++ doc/texinfo.txi     16 Feb 2012 18:38:17 -0000      1.420
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.419 2012/02/07 19:41:38 pertusus Exp $
address@hidden $Id: texinfo.txi,v 1.420 2012/02/16 18:38:17 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.
 
@@ -3075,7 +3075,7 @@
 exactly.  A practice we recommend is to include the version or edition
 number of the manual in the @code{@@settitle} title; on the title page,
 the version number generally appears as an @code{@@subtitle} so it would
-be omitted from the @code{@@title}.  @xref{titlepage}.
+be omitted from the @code{@@title}.  @xref{titlepage,, @code{@@titlepage}}.
 
 Conventionally, when @TeX{} formats a Texinfo file for double-sided
 output, the title is printed in the left-hand (even-numbered) page
@@ -3691,15 +3691,15 @@
 chapters, appendices, and unnumbered chapters.  Sections, subsections
 and subsubsections are omitted.  Only a long manual needs a short
 table of contents in addition to the full table of contents.
-
 @end table
 
 Both contents commands should be written on a line by themselves, and
-are best placed near the beginning of the file, after the @code{@@end
-titlepage} (@pxref{titlepage}).  The contents commands automatically
-generate a chapter-like heading at the top of the first table of
-contents page, so don't include any sectioning command such as
address@hidden@@unnumbered} before them.
+placed near the beginning of the file, after the @code{@@end
+titlepage} (@pxref{titlepage,, @code{@@titlepage}}), before any
+sectioning command.  The contents commands automatically generate a
+chapter-like heading at the top of the first table of contents page,
+so don't include any sectioning command such as @code{@@unnumbered}
+before them.
 
 Since an Info file uses menus instead of tables of contents, the Info
 formatting commands ignore the contents commands.  But the contents are
@@ -15055,10 +15055,14 @@
 @ref{Preprocessor 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 CPP_LINE_DIRECTIVES
+The @command{makeinfo} program recognizes these lines by default,
+except within @code{@@verbatim} blocks (@pxref{verbatim,,
address@hidden@@verbatim}}.  Their recognition can be turned off completely
+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
 @samp{#line} 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
@@ -15077,6 +15081,10 @@
 @@address@hidden@}line 1 "example.c"
 @end example
 
+Or, if suitable, a @code{@@verbatim} environment can be used instead
+of @code{@@example}.  As mentioned above, @code{#line}-recognition is
+disabled inside verbatim blocks.
+
 
 @node #line and TeX
 @subsection @samp{#line} and @TeX{}
@@ -15114,6 +15122,7 @@
 @subsection @samp{#line} Syntax Details
 @cindex @samp{#line} syntax details
 @cindex Syntax details, @samp{#line}
address@hidden Regular expression, for @samp{#line}
 
 Syntax details for the @samp{#line} directive: the @samp{#} character
 can be preceded or followed by whitespace, the word @samp{line} is
@@ -15123,7 +15132,7 @@
 (Perl) regular expression which is matched is this:
 
 @example
-^\s*#\s*(line)? (\d+)( "([^"]+)")?(\s+\d+)*\s*$
+^(\s*)#(\s*(line)? (\d+)( "([^"]+)")?(\s+\d+)*\s*)$
 @end example
 
 For example, the following is also a valid @samp{#line} directive,
@@ -15133,6 +15142,18 @@
 @hashchar{} 1 "/usr/include/stdio.h" 1 3 4
 @end example
 
+Unfortunately, the quoted filename (@samp{"..."}) has to be optional,
+because M4 (especially) can often generate @samp{#line} directives
+within a single file.  Since the @samp{line} is also optional, the
+result is that lines might match which you wouldn't expect, e.g.,
+
address@hidden
address@hidden 1 2 3 4
address@hidden example
+
+The possible solutions are described above (@pxref{#line Directive,,
address@hidden Directive}).
+
 
 @node Include Files
 @chapter Include Files
@@ -21641,7 +21662,7 @@
 Revision Control System}) or other version control systems, which
 expand it into a string such as:
 @example
-$Id: texinfo.txi,v 1.419 2012/02/07 19:41:38 pertusus Exp $
+$Id: texinfo.txi,v 1.420 2012/02/16 18:38:17 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}