[6601] texinfo.tex macro changes for tar manual

[Gavin D. Smith]

Revision: 6601
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6601
Author:   gavin
Date:     2015-09-06 19:15:07 +0000 (Sun, 06 Sep 2015)
Log Message:
-----------
texinfo.tex macro changes for tar manual

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

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-09-06 12:05:28 UTC (rev 6600)
+++ trunk/ChangeLog     2015-09-06 19:15:07 UTC (rev 6601)
@@ -1,5 +1,34 @@
 2015-09-05  Gavin Smith  <address@hidden>
 
+       * doc/texinfo.tex (\macroargctxt): Do \catcode`\^^M=\other, to 
+       preserve newlines in a macro argument.
+       (\parsemargdef): Put \processmacroarg instead of \xeatspaces in 
+       \macarg.ARG.
+       (\gobblespaces): New macro.
+       (\defmacro): If number of parameters is 1, don't use \eatspaces 
+       on the argument, but do put \gobblespaces before it.
+
+       (\getargs): Say in comment what this macro does.
+
+       Move code to process macros with more than 9 arguments together 
+       in the file.
+       (\getargvals@@): Remove comment.
+       (\setemptyargvalues@): Change a word in a comment.
+
+       (\parsemacbody, \parsermacbody, \defmacro): Rename \temp to 
+       \macrobody.
+
+       (\texisavetoksstackpoint, \texirestoretoksstackpoint) 
+       (\texionouternewtoks): Remove these macros which aren't used anywhere.
+
+       * doc/texinfo-tex-test.texi: Add examples for a multi-line macro 
+       argument, and trimming whitespace from a macro argument.
+
+       Some of these changes are to handle better macros in the GNU tar 
+       manual.
+
+2015-09-05  Gavin Smith  <address@hidden>
+
        * doc/texinfo.texi: Re-add "@setfilename" line, required by 
        Automake 1.15.  Reported by Stefan Husmann.
 

Modified: trunk/doc/texinfo-tex-test.texi
===================================================================
--- trunk/doc/texinfo-tex-test.texi     2015-09-06 12:05:28 UTC (rev 6600)
+++ trunk/doc/texinfo-tex-test.texi     2015-09-06 19:15:07 UTC (rev 6601)
@@ -1,4 +1,4 @@
-% texinfo.tex -- test file for texinfo.tex
+% texinfo-tex-test.texi -- test file for texinfo.tex
 %
 % Copyright 2015 Free Software Foundation, Inc.
 %
@@ -16,7 +16,6 @@
 % along with this program.  If not, see <http://www.gnu.org/licenses/>.
 %
 \input texinfo
address@hidden
 @settitle Test Document for @file{texinfo.tex}
 
 @everyheading @thischapter @| @| @thissection
@@ -148,7 +147,6 @@
 
 Output should be doubled
 
address@hidden
 @macro Example
 @example
 @group
@@ -179,8 +177,6 @@
 \argfirst\+\argsecond\.
 @end macro
 
address@hidden
-
 @set fc Fran@,cois
 @address@hidden,address@hidden
 @mactwo{Fran@,cois,address@hidden
@@ -194,6 +190,53 @@
 
 exceeds @address@hidden,16}} pt
 
+
address@hidden Trim whitespace from macro arguments
+
address@hidden Mac{a}
+<X\a\X>
address@hidden macro
+
address@hidden Mactwo{a,b}
+<X\a\X\b\X>
address@hidden macro
+
+No space should appear right after an `X':
+
address@hidden @Mac{b} @Mac{ b} @Mac{b  } @Mac{ b }
+
address@hidden @Mactwo{b,c} @Mactwo{ b, c} @Mactwo{b  ,c  } @Mactwo{ b , c }
+
+
address@hidden Multi-line macro argument
+
address@hidden
address@hidden Mac{text}
address@hidden
+<@b{FIXME}>
address@hidden
+\text\
address@hidden example
+\text\
address@hidden </>
address@hidden cartouche
address@hidden macro
+
address@hidden
+Here's an extended
+macro argument, with
+newlines.
+
+And multiple paragraphs.
+Like an argument to @code{@@footnote}.
+}
+
+(The double space in the @code{@@example} is due to the way 
address@hidden inserts spaces after control sequences.)
+
+
+
+
 @chapter Index display
 
 @section End-column glue
@@ -482,7 +525,6 @@
 
 See following pages
 
address@hidden
 @showboxdepth=1000
 @showboxbreadth=1000
 

Modified: trunk/doc/texinfo.tex
===================================================================
--- trunk/doc/texinfo.tex       2015-09-06 12:05:28 UTC (rev 6600)
+++ trunk/doc/texinfo.tex       2015-09-06 19:15:07 UTC (rev 6601)
@@ -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{2015-09-05.22}
+\def\texinfoversion{2015-09-06.21}
 %
 % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
 % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
@@ -7502,6 +7502,7 @@
 % an argument to another Texinfo command.
 \def\macroargctxt{%
   \scanctxt
+  \catcode`\^^M=\other
   \catcode`\\=\active
 }
 
@@ -7581,59 +7582,36 @@
   \fi
 }
 
-% This makes use of the obscure feature that if the last token of a
-% <parameter list> is #, then the preceding argument is delimited by
-% an opening brace, and that opening brace is not consumed.
-% 
+% \getargs -- Parse the arguments to a @macro line.  Set \macname to
+% the name of the macro, and \argl to the braced argument list.
 \def\getargs#1{\getargsxxx#1{}}
 \def\getargsxxx#1#{\getmacname #1 \relax\getmacargs}
 \def\getmacname#1 #2\relax{\macname={#1}}
 \def\getmacargs#1{\def\argl{#1}}
+% This made use of the feature that if the last token of a
+% <parameter list> is #, then the preceding argument is delimited by
+% an opening brace, and that opening brace is not consumed.
 
-% For macro processing make @ a letter so that we can make
-% private-to-Texinfo macro names.
address@hidden
-\catcode address@hidden
-
-% Parse the optional {params} list.  Set up \paramno and \paramlist
-% so \defmacro knows what to do.  Define \macarg.BLAH for each BLAH
-% in the params list to some hook where the argument is to be expanded.  If
-% there are less than 10 arguments that hook is to be replaced by ##N where N
+% Parse the optional {params} list to @macro or @rmacro.
+% Set \paramno to the number of arguments,
+% and \paramlist to a parameter text for the macro (e.g. #1,#2,#3 for a
+% three-param macro.)  Define \macarg.BLAH for each BLAH in the params
+% list to some hook where the argument is to be expanded.  If there are
+% less than 10 arguments that hook is to be replaced by ##N where N
 % is the position in that list, that is to say the macro arguments are to be
 % defined `a la TeX in the macro body.  
 %
 % That gets used by \mbodybackslash (above).
 %
-% We need to get `macro parameter char #' into several definitions.
-% The technique used is stolen from LaTeX: let \hash be something
-% unexpandable, insert that wherever you need a #, and then redefine
-% it to # just before using the token list produced.
+% If there are 10 or more arguments, a different technique is used: see
+% \parsemmanyargdef.
 %
-% The same technique is used to protect \eatspaces till just before
-% the macro is used.
-%
-% If there are 10 or more arguments, a different technique is used, where the
-% hook remains in the body, and when macro is to be expanded the body is
-% processed again to replace the arguments.
-%
-% In that case, the hook is \the\toks N-1, and we simply set \toks N-1 to the
-% argument N value and then \edef  the body (nothing else will expand because 
of
-% the catcode regime underwhich the body was input).
-%
-% If you compile with TeX (not eTeX), and you have macros with 10 or more
-% arguments, no macro can have more than 256 arguments (else error).
-% 
 \def\parsemargdef#1;{%
   \paramno=0\def\paramlist{}%
   \let\hash\relax
-  \let\xeatspaces\relax
+  % \hash is redefined to `#' later to get it into definitions
+  \let\processmacroarg\relax
   \parsemargdefxxx#1,;,%
-  % In case that there are 10 or more arguments we parse again the arguments
-  % list to set new definitions for the \macarg.BLAH macros corresponding to
-  % each BLAH argument. It was anyhow needed to parse already once this list
-  % in order to count the arguments, and as macros with at most 9 arguments
-  % are by far more frequent than macro with 10 or more arguments, defining
-  % twice the \macarg.BLAH macros does not cost too much processing power.
   \ifnum\paramno<10\relax\else
     \paramno0\relax
     \parsemmanyargdef@@#1,;,% 10 or more arguments
@@ -7644,10 +7622,47 @@
   \else \let\next=\parsemargdefxxx
     \advance\paramno by 1
     \expandafter\edef\csname macarg.\eatspaces{#1}\endcsname
-        {\xeatspaces{\hash\the\paramno}}%
+        {\processmacroarg{\hash\the\paramno}}%
     \edef\paramlist{\paramlist\hash\the\paramno,}%
   \fi\next}
 
+% \parsemacbody, \parsermacbody
+%
+% Read recursive and nonrecursive macro bodies. (They're different since
+% rec and nonrec macros end differently.)
+% 
+% We are in \macrobodyctxt, and the \xdef causes backslashshes in the macro 
+% body to be transformed.
+% Set \macrobody to the body of the macro, and call \defmacro.
+%
+{\catcode`\ address@hidden macro{%
+\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}%
+{\catcode`\ address@hidden rmacro{%
+\xdef\macrobody{\eatcr{#1}}\endgroup\defmacro}}%
+
+%%%%%%%%%%%%%% Code for > 10 arguments only   %%%%%%%%%%%%%%%%%%
+
+% Make @ a letter, so that we can make private-to-Texinfo macro names.
address@hidden
+\catcode address@hidden
+
+% If there are 10 or more arguments, a different technique is used, where the
+% hook remains in the body, and when macro is to be expanded the body is
+% processed again to replace the arguments.
+%
+% In that case, the hook is \the\toks N-1, and we simply set \toks N-1 to the
+% argument N value and then \edef the body (nothing else will expand because of
+% the catcode regime under which the body was input).
+%
+% If you compile with TeX (not eTeX), and you have macros with 10 or more
+% arguments, no macro can have more than 256 arguments (else error).
+%
+% In case that there are 10 or more arguments we parse again the arguments
+% list to set new definitions for the \macarg.BLAH macros corresponding to
+% each BLAH argument. It was anyhow needed to parse already once this list
+% in order to count the arguments, and as macros with at most 9 arguments
+% are by far more frequent than macro with 10 or more arguments, defining
+% twice the \macarg.BLAH macros does not cost too much processing power.
 \def\parsemmanyargdef@@#1,{%
   \if#1;\let\next=\relax
   \else 
@@ -7663,15 +7678,6 @@
     \advance\paramno by 1\relax
   \fi\next}
 
-% These two commands read recursive and nonrecursive macro bodies.
-% (They're different since rec and nonrec macros end differently.)
-% Set \temp to the body of the macro, and call \defmacro.
-\catcode address@hidden
-{\catcode`\ address@hidden macro{%
-\xdef\temp{\eatcr{#1}}\endgroup\defmacro}}%
-{\catcode`\ address@hidden rmacro{%
-\xdef\temp{\eatcr{#1}}\endgroup\defmacro}}%
-\catcode address@hidden
 
 address@hidden
 address@hidden
@@ -7700,9 +7706,6 @@
     \getargvals@@
   \fi
 }
-
-% Internal for address@hidden
-%  
 \def\getargvals@@{%
   \ifx\paramlist\nilm@
       % Some sanity check needed here that \argvaluelist is also empty.
@@ -7810,16 +7813,7 @@
   \next
 }
 
-% Save the token stack pointer into macro #1:
address@hidden
-%
-% Restore the token stack pointer from number in macro #1:
-\def\texirestoretoksstackpoint#1{\expandafter\mathchardef
-  address@hidden
-% Variant \newtoks that can be used non-\outer:
-\def\texinonouternewtoks{\alloc@ 5\toks \toksdef address@hidden
-
-% Tailing missing arguments are set to empty.
+% Trailing missing arguments are set to empty.
 % 
 address@hidden
   \ifx\paramlist\nilm@
@@ -7850,27 +7844,58 @@
    \long\def#2{#4}%
 }
 
-% This defines a Texinfo @macro.  \temp has the body of the macro in it.
+\catcode address@hidden % end private-to-Texinfo catcodes
+
+
+%%%%%%%%%%%%%% End of code for > 10 arguments %%%%%%%%%%%%%%%%%%
+
+
+
+% Remove following spaces at the expansion stage.
+% This works because spaces are discarded before each argument when TeX is 
+% getting the arguments for a macro.
+% This must not be immediately followed by a }.
+\long\def\gobblespaces#1{#1}
+
+% This defines a Texinfo @macro or @rmacro, called by \parsemacbody.
+%    \macrobody has the body of the macro in it, with placeholders for
+% its parameters.
+%    \paramno is the number of parameters
+%    \paramlist is a TeX parameter text, e.g. "#1,#2,#3,"
 % There are eight cases: recursive and nonrecursive macros of zero, one,
 % up to nine, and many arguments.
-% Much magic with \expandafter here.
 % \xdef is used so that macro definitions will survive the file
-% they're defined in; @include reads the file inside a group.
+% they're defined in: @include reads the file inside a group.
 %
 \def\defmacro{%
   \let\hash=##% convert placeholders to macro parameter chars
+  \ifnum\paramno=1
+    \def\processmacroarg{\gobblespaces}%
+    % This removes the pair of braces around the argument.  We don't
+    % use \eatspaces, because this can cause ends of lines to be lost
+    % when the argument to \eatspaces is read, leading to line-based
+    % commands like "@itemize" not being read correctly.
+  \else
+    \let\xeatspaces\relax
+    \def\processmacroarg{\xeatspaces}%
+  \fi
   \ifrecursive   %%%%%%%%%%%%%% Recursive %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
     \ifcase\paramno
     % 0
       \expandafter\xdef\csname\the\macname\endcsname{%
-        \noexpand\scanmacro{\temp}}%
+        \noexpand\scanmacro{\macrobody}}%
     \or % 1
       \expandafter\xdef\csname\the\macname\endcsname{%
          \bgroup
          \noexpand\braceorline
          \expandafter\noexpand\csname\the\macname xxx\endcsname}%
       \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
-         \egroup\noexpand\scanmacro{\temp}}%
+         \expandafter\noexpand\csname\the\macname xxxx\endcsname{%
+           \noexpand\gobblespaces##1\empty}%
+           % The \empty is for \gobblespaces in case #1 is empty
+         }%
+      \expandafter\xdef\csname\the\macname xxxx\endcsname##1{%
+         \egroup\noexpand\scanmacro{\macrobody}}%
     \else
       \ifnum\paramno<10\relax % at most 9
         \expandafter\xdef\csname\the\macname\endcsname{%
@@ -7882,12 +7907,12 @@
         \expandafter\xdef
         \expandafter\expandafter
           \csname\the\macname xxx\endcsname
-            \paramlist{\egroup\noexpand\scanmacro{\temp}}%
+            \paramlist{\egroup\noexpand\scanmacro{\macrobody}}%
       \else % 10 or more
         \expandafter\xdef\csname\the\macname\endcsname{%
           address@hidden
         }%    
-        \global\expandafter\let\csname mac.\the\macname .body\endcsname\temp
+        \global\expandafter\let\csname mac.\the\macname 
.body\endcsname\macrobody
         \global\expandafter\let\csname mac.\the\macname 
.recurse\endcsname\gobble
       \fi
     \fi
@@ -7895,15 +7920,20 @@
     \ifcase\paramno
     % 0
       \expandafter\xdef\csname\the\macname\endcsname{%
-        \noexpand\scanmacro{\temp}}%
+        \noexpand\scanmacro{\macrobody}}%
     \or % 1
       \expandafter\xdef\csname\the\macname\endcsname{%
          \bgroup
          \noexpand\braceorline
          \expandafter\noexpand\csname\the\macname xxx\endcsname}%
       \expandafter\xdef\csname\the\macname xxx\endcsname##1{%
+         \expandafter\noexpand\csname\the\macname xxxx\endcsname{%
+           \noexpand\gobblespaces##1\empty}%
+           % The \empty is for \gobblespaces in case #1 is empty
+         }%
+      \expandafter\xdef\csname\the\macname xxxx\endcsname##1{%
         \egroup
-        \noexpand\scanmacro{\temp}%
+        \noexpand\scanmacro{\macrobody}%
         }%
     \else % at most 9
       \ifnum\paramno<10\relax
@@ -7918,20 +7948,18 @@
         \csname\the\macname xxx\endcsname
         \paramlist{%
             \egroup
-            \noexpand\scanmacro{\temp}%
+            \noexpand\scanmacro{\macrobody}%
             }%
       \else % 10 or more:
         \expandafter\xdef\csname\the\macname\endcsname{%
           address@hidden
         }%
-        \global\expandafter\let\csname mac.\the\macname .body\endcsname\temp
+        \global\expandafter\let\csname mac.\the\macname 
.body\endcsname\macrobody
         \global\expandafter\let\csname mac.\the\macname 
.recurse\endcsname\norecurse
       \fi
     \fi
   \fi}
 
-\catcode address@hidden % end private-to-Texinfo catcodes
-
 \def\norecurse#1{\bgroup\cslet{#1}{macsave.#1}}