texinfo ChangeLog doc/texinfo.txi util/htmlxref...

[Karl Berry]

CVSROOT:        /sources/texinfo
Module name:    texinfo
Changes by:     Karl Berry <karl>       10/11/11 19:12:18

Modified files:
        .              : ChangeLog 
        doc            : texinfo.txi 
        util           : htmlxref.cnf 

Log message:
        (Macro Details): more caveats about @macro in TeX; non-expansion 
contexts in makeinfo

CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/texinfo/ChangeLog?cvsroot=texinfo&r1=1.1177&r2=1.1178
http://cvs.savannah.gnu.org/viewcvs/texinfo/doc/texinfo.txi?cvsroot=texinfo&r1=1.347&r2=1.348
http://cvs.savannah.gnu.org/viewcvs/texinfo/util/htmlxref.cnf?cvsroot=texinfo&r1=1.33&r2=1.34

Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/texinfo/texinfo/ChangeLog,v
retrieving revision 1.1177
retrieving revision 1.1178
diff -u -b -r1.1177 -r1.1178
--- ChangeLog   9 Nov 2010 17:55:03 -0000       1.1177
+++ ChangeLog   11 Nov 2010 19:12:16 -0000      1.1178
@@ -1,3 +1,11 @@
+2010-11-11  Karl Berry  <address@hidden>
+
+       * doc/texinfo.txi (Macro Details): mention non-expansion contexts
+       for makeinfo.  More caveats about @macro in TeX.
+       (set value): mention the @value{something} can't be the argument
+       to accent commands.  (makeinfo supports it in braced arguments,
+       but texinfo.tex can't handle it.)
+
 2010-11-09  Karl Berry  <address@hidden>
 
        * doc/texinfo.txi (Macro Details): more caveats about newlines.

Index: doc/texinfo.txi
===================================================================
RCS file: /sources/texinfo/texinfo/doc/texinfo.txi,v
retrieving revision 1.347
retrieving revision 1.348
diff -u -b -r1.347 -r1.348
--- doc/texinfo.txi     9 Nov 2010 17:55:03 -0000       1.347
+++ doc/texinfo.txi     11 Nov 2010 19:12:17 -0000      1.348
@@ -1,5 +1,5 @@
 \input texinfo.tex    @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.347 2010/11/09 17:55:03 karl Exp $
address@hidden $Id: texinfo.txi,v 1.348 2010/11/11 19:12: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.
 
@@ -13677,6 +13677,14 @@
 @end group
 @end example
 
address@hidden@@value} cannot be reliably used as the argument to an accent
+command (@pxref{Inserting Accents}).  For example, this fails:
+
address@hidden
+@@set myletter a
+@@'@@address@hidden@}    @c fails!
address@hidden example
+
 
 @node ifset ifclear
 @subsection @code{@@ifset} and @code{@@ifclear}
@@ -14387,11 +14395,31 @@
 @cindex Details of macro usage
 @cindex Caveats for macro usage
 
-Due to unavoidable limitations, certain macro-related constructs cause
-problems with @TeX{}.  If you get macro-related errors when producing
-the printed version of a manual, try expanding the macros with
address@hidden by invoking @command{texi2dvi} with the @samp{-E}
-option (@pxref{Format with texi2dvi}).
address@hidden Macro expansion, contexts for
address@hidden Expansion of macros, contexts for
+By design, macro expansion does not happen in the following contexts
+in @command{makeinfo}:
+
address@hidden @bullet
address@hidden @code{@@macro} and @code{@@unmacro} lines.
+
address@hidden @code{@@if...} lines, including @code{@@ifset} and similar,
+
address@hidden @code{@@set}, @code{@@clear}, @code{@@value}.
+
address@hidden @code{@@clickstyle} lines.
+
address@hidden @code{@@end} lines.
address@hidden itemize
+
address@hidden @TeX{} may or may not do some expansion in these situations,
+possibly yielding errors.
+
+Also, due to unavoidable limitations, certain macro-related constructs
+cause problems with @TeX{}.  If you get macro-related errors when
+producing the printed version of a manual, you might try expanding the
+macros with @command{makeinfo} by invoking @command{texi2dvi} with the
address@hidden option (@pxref{Format with texi2dvi}).
 
 @itemize @bullet
 @item
@@ -14413,8 +14441,8 @@
 Macro arguments cannot cross lines.
 
 @item
-It is (usually) best to avoid comments inside macro definitions, but
-see the next item.
+Macros can't be reliably used in the argument to accent commands
+(@pxref{Inserting Accents}).
 
 @item
 Macros containing a command which must be on a line by itself, such as
@@ -14423,11 +14451,15 @@
 @code{@@example} environments, may behave unpredictably in @TeX{}.
 
 @item
+It is (usually) best to avoid comments inside macro definitions, but
+see the next item.
+
address@hidden
 In general, the interaction of newlines in the macro definitions and
 invocations depends on the precise commands and context, despite the
 previous statements.  You may be able to work around some problems
 with judicious use of @code{@@c}.  Suppose you define a macro that is
-always intended to be used on a line by itself:
+intended to always be used on a line by itself:
 
 @example
 @@macro linemac
@@ -14449,10 +14481,11 @@
 invocation would be treated as a comment).
 
 @item
-In general, you can't arbitrarily substitute a macro call for Texinfo
-command arguments, even when the text is the same.  Texinfo is not M4,
-or even @TeX{}.  It might work with some commands, it fails with
-others.  Best not to do it at all.  For instance, this fails:
+In general, you can't arbitrarily substitute a macro (or
address@hidden@@value}) call for Texinfo command arguments, even when the text
+is the same.  Texinfo is not M4 (or even plain @TeX{}).  It might work
+with some commands, it fails with others.  Best not to do it at all.
+For instance, this fails:
 
 @example
 @@macro offmacro
@@ -14462,9 +14495,9 @@
 @end example
 
 @noindent
-You would expect this to be equivalent to @code{@@headings off}, but
-for @TeX{}nical reasons, it fails with a mysterious error message
-(@code{Paragraph ended before @@headings was complete}).
+This looks equivalent to @code{@@headings off}, but for @TeX{}nical
+reasons, it fails with a mysterious error message (@code{Paragraph
+ended before @@headings was complete}).
 
 @item
 Macros cannot define macros in the natural way.  To do this, you must
@@ -14677,7 +14710,7 @@
 @@include buffers.texi
 @end example
 
-The name of the file is taken literally, with a single exception:
+The name of the file is taken literally, with the exception that
 @code{@@address@hidden@address@hidden references are expanded.  This makes it
 possible to reliably include files in other directories in a
 distribution.  @xref{verbatiminclude,,@code{@@verbatiminclude}}, for
@@ -18205,8 +18238,8 @@
 
 First, comments are removed.
 
-Next, any @code{@@value} commands (@pxref{set value}) and macro invocations
-(@pxref{Invoking Macros}) are fully expanded.
+Next, any @code{@@value} commands (@pxref{set value}) and macro
+invocations (@pxref{Invoking Macros}) are fully expanded.
 
 Then, for the following commands, the command name and braces are removed,
 the text of the argument is recursively transformed:
@@ -22885,7 +22918,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.347 2010/11/09 17:55:03 karl Exp $
+$Id: texinfo.txi,v 1.348 2010/11/11 19:12: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}
@@ -22964,7 +22997,7 @@
 
 @verbatim
 \input texinfo   @c -*-texinfo-*-
address@hidden $Id: texinfo.txi,v 1.347 2010/11/09 17:55:03 karl Exp $
address@hidden $Id: texinfo.txi,v 1.348 2010/11/11 19:12:17 karl Exp $
 @comment %**start of header
 @setfilename sample.info
 @include version.texi

Index: util/htmlxref.cnf
===================================================================
RCS file: /sources/texinfo/texinfo/util/htmlxref.cnf,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -b -r1.33 -r1.34
--- util/htmlxref.cnf   9 Nov 2010 17:55:04 -0000       1.33
+++ util/htmlxref.cnf   11 Nov 2010 19:12:18 -0000      1.34
@@ -1,6 +1,6 @@
 # htmlxref.cnf - reference file for Texinfo files on the web.
 
-htmlxrefversion=2010-11-09.16; # UTC
+htmlxrefversion=2010-11-11.16; # UTC
 
 # Copyright 2010 Free Software Foundation, Inc.
 # 
@@ -344,6 +344,8 @@
  sos             node  ${MIT_SCHEME}/sos/
  mit-scheme-imail node ${MIT_SCHEME}/mit-scheme-imail/
 
+moe            mono    ${GS}/moe/manual/moe_manual.html
+
 motti          node    ${GS}/motti/manual/
 
 ocrad          mono    ${GS}/ocrad/manual/ocrad_manual.html