[5370] doc: newline-delimited commands inside @inline, node name restrictions

[karl]

Revision: 5370
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=5370
Author:   karl
Date:     2013-09-11 01:26:31 +0000 (Wed, 11 Sep 2013)
Log Message:
-----------
doc: newline-delimited commands inside @inline, node name restrictions

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/doc/texinfo.tex
    trunk/doc/texinfo.texi
    trunk/doc/version.texi

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2013-09-09 18:08:48 UTC (rev 5369)
+++ trunk/ChangeLog     2013-09-11 01:26:31 UTC (rev 5370)
@@ -1,3 +1,10 @@
+2013-09-10  Karl Berry  <address@hidden>
+
+       * doc/texinfo.texi (Two Arguments, Three Arguments):
+       some node name requirements apply to arg#2 and arg#3 too.
+       (Inline Conditionals): TeX can't properly deal with
+       newline-delimited commands inside @inline*.
+
 2013-09-09  Karl Berry  <address@hidden>
 
        * NEWS,

Modified: trunk/doc/texinfo.tex
===================================================================
--- trunk/doc/texinfo.tex       2013-09-09 18:08:48 UTC (rev 5369)
+++ trunk/doc/texinfo.tex       2013-09-11 01:26:31 UTC (rev 5370)
@@ -3,7 +3,7 @@
 % Load plain if necessary, i.e., if running under initex.
 \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
 %
-\def\texinfoversion{2013-08-20.10}
+\def\texinfoversion{2013-09-10.16}
 %
 % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
 % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
@@ -322,10 +322,13 @@
   %
   % Do this outside of the \shipout so @code etc. will be expanded in
   % the headline as they should be, not taken literally (outputting ''code).
+  \def\commmonheadfootline{\let\hsize=\pagewidth \texinfochars}
+  %
   \ifodd\pageno \getoddheadingmarks \else \getevenheadingmarks \fi
-  \setbox\headlinebox = \vbox{\let\hsize=\pagewidth \makeheadline}%
+  \global\setbox\headlinebox = \vbox{\commmonheadfootline \makeheadline}%
+  %
   \ifodd\pageno \getoddfootingmarks \else \getevenfootingmarks \fi
-  \setbox\footlinebox = \vbox{\let\hsize=\pagewidth \makefootline}%
+  \global\setbox\footlinebox = \vbox{\commmonheadfootline \makefootline}%
   %
   {%
     % Have to do this stuff outside the \shipout because we want it to
@@ -6276,8 +6279,8 @@
   \catcode `\|=\other
   \catcode `\<=\other
   \catcode `\>=\other
-  \catcode`\`=\other
-  \catcode`\'=\other
+  \catcode `\`=\other
+  \catcode `\'=\other
   \escapechar=`\\
   %
   % ' is active in math mode (mathcode"8000).  So reset it, and all our
@@ -6301,7 +6304,7 @@
   \let\/=\ptexslash
   \let\*=\ptexstar
   \let\t=\ptext
-  \expandafter \let\csname top\endcsname=\ptextop  % outer
+  \expandafter \let\csname top\endcsname=\ptextop  % we've made it outer
   \let\frenchspacing=\plainfrenchspacing
   %
   \def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}%
@@ -9944,11 +9947,9 @@
 \catcode`\"=\active
 \def\activedoublequote{{\tt\char34}}
 \let"=\activedoublequote
-\catcode`\~=\active
-\def~{{\tt\char126}}
+\catcode`\~=\active \def\activetilde{{\tt\char126}} \let~ = \activetilde
 \chardef\hat=`\^
-\catcode`\^=\active
-\def^{{\tt \hat}}
+\catcode`\^=\active \def\activehat{{\tt \hat}} \let^ = \activehat
 
 \catcode`\_=\active
 \def_{\ifusingtt\normalunderscore\_}
@@ -9958,17 +9959,25 @@
 
 \catcode`\|=\active
 \def|{{\tt\char124}}
+
 \chardef \less=`\<
-\catcode`\<=\active
-\def<{{\tt \less}}
+\catcode`\<=\active \def\activeless{{\tt \less}}\let< = \activeless
 \chardef \gtr=`\>
-\catcode`\>=\active
-\def>{{\tt \gtr}}
-\catcode`\+=\active
-\def+{{\tt \char 43}}
-\catcode`\$=\active
-\def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix
+\catcode`\>=\active \def\activegtr{{\tt \gtr}}\let> = \activegtr
+\catcode`\+=\active \def+{{\tt \char 43}}
+\catcode`\$=\active \def${\ifusingit{{\sl\$}}\normaldollar}%$ font-lock fix
 
+% used for headline/footline in the output routine, in case the page
+% breaks in the middle of an @tex block.
+\def\texinfochars{%
+  \let< = \activeless
+  \let> = \activegtr
+  \let~ = \activetilde 
+  \let^ = \activehat
+  \markupsetuplqdefault \markupsetuprqdefault 
+  % in principle, all other definitions in \tex have to be undone too.
+}
+
 % If a .fmt file is being used, characters that might appear in a file
 % name cannot be active until we have parsed the command line.
 % So turn them off again, and have \everyjob (or @setfilename) turn them on.

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2013-09-09 18:08:48 UTC (rev 5369)
+++ trunk/doc/texinfo.texi      2013-09-11 01:26:31 UTC (rev 5370)
@@ -6305,11 +6305,16 @@
 @end quotation
 
 @noindent
-in a printed manual.
-(Note that in the preceding example the closing brace is followed by a
-comma, and then by the clause, which is followed by a period.)
+in a printed manual.  (Note that in the preceding example the closing
+brace is followed by a comma, and then by the clause, which is
+followed by a period.)
 
+The second argument to cross references must observe some of the
+restrictions for node names (@pxref{Node Line Requirements}).  The
+most common issue is that colons cannot be used, since that interferes
+with the parsing of the Info file.
 
+
 @node Three Arguments
 @subsection @code{@@xref} with Three Arguments
 @cindex Three-argument form of cross references
@@ -6321,12 +6326,7 @@
 reference is printed.  Use a third argument when the node name is
 unsuitable because of syntax or meaning.
 
-The third argument to the xref commands must observe the same
-restrictions as node names described in @ref{Node Line Requirements}.
-The issue you're most likely to run into is that commas, periods, and
-colons cannot be used.
-
-Also, remember to write a comma or period after the closing brace of an
+Remember to write a comma or period after the closing brace of an
 @code{@@xref} to terminate the cross reference.  In the following
 examples, a clause follows a terminating comma.
 
@@ -6396,22 +6396,27 @@
 @noindent
 in a printed manual.
 
+The third argument to cross references must observe some of the
+restrictions for node names (@pxref{Node Line Requirements}).  The
+most common issue is that colons cannot be used, since that interferes
+with the parsing of the Info file.
+
 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 only if the
 node name and title are different.
 
 @findex xrefautomaticsectiontitle
-If you want the section title to be used by default instead of
-node names in cross references (an explicitly specified third argument
-still takes precedence), Texinfo can do this automatically:
+Texinfo offers a setting to use the section title instead of node
+names by default in cross references (an explicitly specified third
+argument still takes precedence):
 
 @example
 @@xrefautomaticsectiontitle on
 @end example
 
 Typically this line would be given near the beginning of the document
-and used for the whole thing.  But you can turn it off if you want
+and used for the whole manual.  But you can turn it off if you want
 (@code{@@xrefautomaticsectiontitle off}), for example, if you're
 including some other sub-document that doesn't have suitable section
 names.
@@ -14177,8 +14182,8 @@
 recognize and even execute, to some extent, the contents of the raw
 regions, regardless of the final output format.  Therefore, specifying
 changes that globally affect the document inside a raw region leads to
-unpredictable and generally undesirable behavior.  For example,
-giving the @code{@@kbdinputstyle} command inside a raw region.
+unpredictable and generally undesirable behavior.  For example, it
+using the @code{@@kbdinputstyle} command inside a raw region is undefined.
 
 The remedy is simple: don't do that.  Use the raw formatter commands
 for their intended purpose, of providing material directly in the
@@ -14210,6 +14215,12 @@
 Similar, but for raw @var{text} (@pxref{Raw Formatter Commands}).
 @end table
 
+The supported @var{format} names are:
+
address@hidden
+docbook  html  info  plaintext  tex  xml
address@hidden example
+
 For example,
 
 @example
@@ -14240,7 +14251,15 @@
 exactly two arguments, so a @samp{,} cannot be mistaken for an
 argument separator.)
 
+For @TeX{} processing (@var{format} is @samp{tex}), the specific
address@hidden cannot contain newline-delimited commands.  Such commands
+are properly ignored by @TeX{} when @var{format} is something else,
+though.  In addition, literal brace characters (@address@hidden and
address@hidden@}}) must be balanced for @TeX{}, whether the text is ignored or
+not.  (You can use @code{@@address@hidden@}} and @code{@@address@hidden@}}
+to produce individual characters.)
 
+
 @node @t{@@set @@clear @@value}
 @section @code{@@set}, @code{@@clear}, and @code{@@value}
 

Modified: trunk/doc/version.texi
===================================================================
--- trunk/doc/version.texi      2013-09-09 18:08:48 UTC (rev 5369)
+++ trunk/doc/version.texi      2013-09-11 01:26:31 UTC (rev 5370)
@@ -1,4 +1,4 @@
address@hidden UPDATED 16 August 2013
address@hidden UPDATED-MONTH August 2013
address@hidden UPDATED 10 September 2013
address@hidden UPDATED-MONTH September 2013
 @set EDITION 5.1.90
 @set VERSION 5.1.90