texinfo ChangeLog NEWS doc/texinfo.tex doc/texi...

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       11/02/23 21:24:43

Modified files:
        .              : ChangeLog NEWS 
        doc            : texinfo.tex texinfo.txi 
        doc/refcard    : txirefcard.tex 

Log message:
        new setting @xrefautomaticsectiontitle on|off

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1217&r2=1.1218
http://cvs.savannah.gnu.org/viewcvs/texinfo/NEWS?cvsroot=texinfo&r1=1.199&r2=1.200
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.tex?cvsroot=texinfo&r1=1.342&r2=1.343
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.371&r2=1.372
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/refcard/txirefcard.tex?cvsroot=texinfo&r1=1.15&r2=1.16

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1217
retrieving revision 1.1218
diff -u -b -r1.1217 -r1.1218
--- ChangeLog   22 Feb 2011 19:18:13 -0000      1.1217
+++ ChangeLog   23 Feb 2011 21:24:42 -0000      1.1218
@@ -1,3 +1,10 @@
+2011-02-23  Karl Berry  <address@hidden>
+
+       * texinfo.tex (\xrefautomaticsectiontitle): new command.
+       * NEWS,
+       * doc/refcard/txirefcard.tex,
+       * doc/texinfo.txi (Three Arguments): document it.
+
 2011-02-22  Karl Berry  <address@hidden>
 
        * info/ginfo.h2m: new file.

Index: NEWS
===================================================================
RCS file: /sources/texinfo/texinfo/NEWS,v
retrieving revision 1.199
retrieving revision 1.200
diff -u -b -r1.199 -r1.200
--- NEWS        14 Feb 2011 19:20:19 -0000      1.199
+++ NEWS        23 Feb 2011 21:24:42 -0000      1.200
@@ -1,4 +1,4 @@
-$Id: NEWS,v 1.199 2011/02/14 19:20:19 karl Exp $
+$Id: NEWS,v 1.200 2011/02/23 21:24:42 karl Exp $
 This NEWS file records noteworthy changes, very tersely.
 See the manual for detailed information.
 
@@ -28,6 +28,8 @@
   . new environments @raggedright and @smallquotation.
   . new command @headitemfont for the sake of template rows.
   . new command @urefbreakstyle to control breaking of @url/@uref in TeX.
+  . new command @xrefautomaticsectiontitle to allow using section titles
+    in cross references by default, instead of node names.
   . new diacritic command @ogonek.
   . new commands for Icelandic letters eth and thorn: @DH{} @dh{} @TH{} @th{}.
   . DEL (0x7f = 0177 = 127) is a true comment character (catcode 14 in TeX).

Index: doc/texinfo.tex
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.tex,v
retrieving revision 1.342
retrieving revision 1.343
diff -u -b -r1.342 -r1.343
--- doc/texinfo.tex     14 Feb 2011 19:13:42 -0000      1.342
+++ doc/texinfo.tex     23 Feb 2011 21:24:43 -0000      1.343
@@ -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{2011-02-14.11}
+\def\texinfoversion{2011-02-23.13}
 %
 % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
 % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
@@ -218,7 +218,7 @@
   \tracingmacros2
   \tracingrestores1
   \showboxbreadth\maxdimen \showboxdepth\maxdimen
-  \ifx\eTeXversion\undefined\else % etex gives us more logging
+  \ifx\eTeXversion\thisisundefined\else % etex gives us more logging
     \tracingscantokens1
     \tracingifs1
     \tracinggroups1
@@ -611,7 +611,7 @@
   \else\ifx\temp\offword \plainnonfrenchspacing
   \else
     \errhelp = \EMsimple
-    \errmessage{Unknown @frenchspacing option `\temp', must be on/off}%
+    \errmessage{Unknown @frenchspacing option `\temp', must be on|off}%
   \fi\fi
 }
 
@@ -1082,9 +1082,8 @@
 \newif\ifpdfmakepagedest
 
 % when pdftex is run in dvi mode, \pdfoutput is defined (so \pdfoutput=1
-% can be set).  So we test for \relax and 0 as well as \undefined,
-% borrowed from ifpdf.sty.
-\ifx\pdfoutput\undefined
+% can be set).  So we test for \relax and 0 as well as being undefined.
+\ifx\pdfoutput\thisisundefined
 \else
   \ifx\pdfoutput\relax
   \else
@@ -1516,7 +1515,7 @@
 % if we are producing pdf, and we have \pdffontattr, then define cmaps.
 % (\pdffontattr was introduced many years ago, but people still run
 % older pdftex's; it's easy to conditionalize, so we do.)
-\ifpdf \ifx\pdffontattr\undefined \else
+\ifpdf \ifx\pdffontattr\thisisundefined \else
   \begingroup
     \catcode`\^^M=\active \def^^M{^^J}% Output line endings as the ^^J char.
     \catcode`\%=12 \immediate\pdfobj stream {%!PS-Adobe-3.0 Resource-CMap
@@ -1783,7 +1782,7 @@
 % Use cm as the default font prefix.
 % To specify the font prefix, you must define \fontprefix
 % before you read in texinfo.tex.
-\ifx\fontprefix\undefined
+\ifx\fontprefix\thisisundefined
 \def\fontprefix{cm}
 \fi
 % Support font families that don't use the same naming scheme as CM.
@@ -2527,7 +2526,7 @@
     \allowcodebreaksfalse
   \else
     \errhelp = \EMsimple
-    \errmessage{Unknown @allowcodebreaks option `\txiarg'}%
+    \errmessage{Unknown @allowcodebreaks option `\txiarg', must be true|false}%
   \fi\fi
 }
 
@@ -3109,7 +3108,7 @@
 %  Textures 1.7.7 (preloaded format=plain 93.10.14)  (68K)  16 APR 2004 02:38
 % so we'll define it if necessary.
 %
-\ifx\Orb\undefined
+\ifx\Orb\thisisundefined
 \def\Orb{\mathhexbox20D}
 \fi
 
@@ -3384,7 +3383,7 @@
 % This produces Day Month Year style of output.
 % Only define if not already defined, in case a txi-??.tex file has set
 % up a different format (e.g., txi-cs.tex does this).
-\ifx\today\undefined
+\ifx\today\thisisundefined
 \def\today{%
   \number\day\space
   \ifcase\month
@@ -6465,7 +6464,7 @@
 %
 \def\Equotation{%
   \par
-  \ifx\quotationauthor\undefined\else
+  \ifx\quotationauthor\thisisundefined\else
     % indent a bit.
     \leftline{\kern 2\leftskip \sl ---\quotationauthor}%
   \fi
@@ -7000,7 +6999,7 @@
 
 % To do this right we need a feature of e-TeX, \scantokens,
 % which we arrange to emulate with a temporary file in ordinary TeX.
-\ifx\eTeXversion\undefined
+\ifx\eTeXversion\thisisundefined
   \newwrite\macscribble
   \def\scantokens#1{%
     \toks0={#1}%
@@ -7422,6 +7421,27 @@
   \fi
 }
 
+% @xrefautosectiontitle on|off says whether @section(ing) names are used
+% automatically in xrefs, if the third arg is not explicitly specified.
+% This was provided as a "secret" @set xref-automatic-section-title
+% variable, now it's official.
+% 
+\parseargdef\xrefautomaticsectiontitle{%
+  \def\temp{#1}%
+  \ifx\temp\onword
+    \expandafter\let\csname SETxref-automatic-section-title\endcsname
+      = \empty
+  \else\ifx\temp\offword
+    \expandafter\let\csname SETxref-automatic-section-title\endcsname
+      = \relax
+  \else
+    \errhelp = \EMsimple
+    \errmessage{Unknown @xrefautomaticsectiontitle option `\temp',
+                must be on|off}%
+  \fi\fi
+}
+
+
 % @xref, @pxref, and @ref generate cross-references.  For \xrefX, #1 is
 % the node name, #2 the name of the Info cross-reference, #3 the printed
 % node name, #4 the name of the Info file, #5 the name of the printed
@@ -7438,7 +7458,7 @@
   \setbox0=\hbox{\printedrefname\unskip}%
   \ifdim \wd0 = 0pt
     % No printed node name was explicitly given.
-    \expandafter\ifx\csname SETxref-automatic-section-title\endcsname\relax
+    \expandafter\ifx\csname SETxref-automatic-section-title\endcsname \relax
       % Use the node name inside the square brackets.
       \def\printedrefname{\ignorespaces #1}%
     \else
@@ -7908,7 +7928,7 @@
   it from ftp://tug.org/tex/epsf.tex.}
 %
 \def\image#1{%
-  \ifx\epsfbox\undefined
+  \ifx\epsfbox\thisiundefined
     \ifwarnednoepsf \else
       \errhelp = \noepsfhelp
       \errmessage{epsf.tex not found, images will be ignored}%

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.371
retrieving revision 1.372
diff -u -b -r1.371 -r1.372
--- doc/texinfo.txi     20 Feb 2011 18:39:39 -0000      1.371
+++ doc/texinfo.txi     23 Feb 2011 21:24:43 -0000      1.372
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.371 2011/02/20 18:39:39 karl Exp $
address@hidden $Id: texinfo.txi,v 1.372 2011/02/23 21:24:43 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.
 
@@ -6194,12 +6194,11 @@
 cross references into arguments according to the commas; a comma
 within a title or other section will divide it into two arguments.  In
 a reference, you need to write a title such as ``Clouds, Mist, and
-Fog'' without the address@hidden
+Fog'' without the commas.
 
 Also, 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 address@hidden
-
+examples, a clause follows a terminating comma.
 
 @need 750
 @noindent
@@ -6263,19 +6262,23 @@
 
 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, and with the first and third arguments if the node name and title
-are address@hidden
+same (or nearly so), and with the first and third arguments if the
+node name and title are different.
 
-Here are several examples from @cite{The GNU Awk User's Guide}:@refill
+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:
+
address@hidden
+@@xrefautomaticsectiontitle on
address@hidden 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
+(@code{@@xrefautomaticsectiontitle off}), for example, if you're
+including some other sub-document that doesn't have suitable section
+names.
 
address@hidden
-@@address@hidden address@hidden
-@@address@hidden@}.
-@@address@hidden, ,Case-sensitivity in address@hidden
-@@address@hidden Output, , Closing Output Files and address@hidden,
-  for more information.
-@@address@hidden, , Regular Expressions as address@hidden
address@hidden smallexample
 
 @node Four and Five Arguments
 @subsection @code{@@xref} with Four and Five Arguments
@@ -22520,6 +22523,10 @@
 command with a punctuation mark.  Only the first argument is
 mandatory.  @xref{xref, , @code{@@xref}}.
 
address@hidden @@xrefautomaticsectiontitle @var{on-off}
+By default, use the section title instead of the node name in cross
+references.  @xref{Three Arguments}.
+
 @end table
 
 
@@ -23128,7 +23135,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.371 2011/02/20 18:39:39 karl Exp $
+$Id: texinfo.txi,v 1.372 2011/02/23 21:24:43 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}
@@ -23207,7 +23214,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.371 2011/02/20 18:39:39 karl Exp $
address@hidden $Id: texinfo.txi,v 1.372 2011/02/23 21:24:43 karl Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi

Index: doc/refcard/txirefcard.tex
===================================================================
RCS file: /sources/texinfo/texinfo/doc/refcard/txirefcard.tex,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -b -r1.15 -r1.16
--- doc/refcard/txirefcard.tex  20 Feb 2011 18:39:40 -0000      1.15
+++ doc/refcard/txirefcard.tex  23 Feb 2011 21:24:43 -0000      1.16
@@ -1,5 +1,5 @@
 % Texinfo reference card.
-% $Id: txirefcard.tex,v 1.15 2011/02/20 18:39:40 karl Exp $
+% $Id: txirefcard.tex,v 1.16 2011/02/23 21:24:43 karl Exp $
 %
 %**start of header
 % This file can be printed with 1, 2, or 3 columns per page (see below).
@@ -517,6 +517,7 @@
 address@hidden, \rmbrack[entry], \rmbrack[node-title], \rmbrack[info-file], 
\rmbrack[manual]}}{Like address@hidden, but starts with `see' instead of `See', 
and must be used inside parentheses.}
 address@hidden, \rmbrack[entry], \rmbrack[node-title], \rmbrack[info-file], 
\rmbrack[manual]}}{Like address@hidden, but produces only the bare reference 
without `See' or `see'; must be followed by a punctuation mark.}
 address@hidden, \rmbrack[entry-name], info-file}}{Make a cross reference to an 
Info file for which there is no printed manual.}
address@hidden|off}}{By default, use the section title instead of the node name 
in cross references.}
 
 \subsection{Outside of Info}