ydoc (17feb11)

git-svn-id: svn://tug.org/texlive/trunk@21443 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 83 insertions, 3 deletions

diff --git a/Master/texmf-dist/source/latex/ydoc/ydoc.dtx b/Master/texmf-dist/source/latex/ydoc/ydoc.dtx
index b4cd14a106c..ff27403fa81 100644
--- a/Master/texmf-dist/source/latex/ydoc/ydoc.dtx
+++ b/Master/texmf-dist/source/latex/ydoc/ydoc.dtx
@@ -35,7 +35,7 @@
 %<expl>    [ydoc-expl]
 %<doc>     [ydoc-doc]
 %<*driver|class|package|code|desc|expl|doc>
-    {$Id: ydoc.dtx 2073 2011-01-26 11:25:50Z martin $}
+    {$Id: ydoc.dtx 2163 2011-02-16 17:19:27Z martin $}
     [v0.4alpha]
 %</driver|class|package|code|desc|expl|doc>
 %<class>   [ydoc class: document LaTeX class and packages]
@@ -74,7 +74,7 @@
 %</driver>
 % \fi
 %
-% \CheckSum{1488}
+% \CheckSum{1535}
 %
 % \CharacterTable
 %  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
@@ -227,7 +227,8 @@
 % This macro can only be used inside the \meta{macro arguments} of the above macros and typesets an additional macro as part
 % of the syntax of the described macro. The additional macro is normally an end- or other marker of some kind. Further macro arguments may
 % follow. Macros which are not part of the syntax but normal arguments should be written as
-% |<\textbackslash name>| (yielding \MacroArgs<\textbackslash name>) instead. 
+% |<\textbackslash name>| (yielding \MacroArgs<\textbackslash name>) instead.
+% The `\verb+|+' character is an abbreviation of \Macro\AlsoMacro, but only at places where this can appear.
 %
 % \subsubsection*{Examples:}
 % |\Macro\@for<\textbackslash var> ':=' <list> \AlsoMacro\do {<code>}|\\
@@ -236,6 +237,22 @@
 % |\Macro\pgfkeys{<key1>'='<value1>','<key2>'/.code='{<code>}}|\\
 %  \Macro\pgfkeys{<key1>'='<value1>','<key2>'/.code='{<code>}}\\
 %
+% \DescribeMacro\MakeShortMacroArgs*{<char>}
+% This macro is similar to \Macro\MakeShortVerb from the \pkg{shortvrb} package.
+% It can be used to globally define one character to act like \Macro\MacroArgs till the same character is discovered again.
+% Special characters must be escaped with an backslash for the definition.
+% One additional benefit beside the shorter size is that the argument list is automatically terminated.
+% For example |\MakeShortMacroArgs{\"}| will make `|"<arg>{<arg>}"|' act like `|\MacroArgs<arg>{<arg>}\relax|'.
+% One side-effect is that should the argument list be terminated, e.g. by an unknown element or macro, then the rest of the
+% text till the end-character is typeset as normal, but inside a group.
+%
+% The starred version will define the character equal to \Macro\Macro instead.
+%
+% \DescribeMacro\DeleteShortMacroArgs{<char>}
+% Globally removes the special meaning from \meta{char} given to him by \Macro\MakeShortMacroArgs.
+%
+% Note that special characters like |`| are
+% best defined |\AtBeginDocument| and deleted again |\AtEndDocument| to avoid issues if they are written to the |aux| file by some package.
 %
 % \begin{DescribeEnv}{DescribeMacros}
 %   \Macro\Macro<\textbackslash name><arguments>\\
@@ -295,6 +312,7 @@
 %   Space (explicit macro)     &  |\space|     & \\
 %  \midrule
 %   Second macro (e.g.\ endmarker) &  |\AlsoMacro\macro| & \MacroArgs\AlsoMacro\macro \\
+%   \hfill short version:        &  \verb+|\macro+     & \MacroArgs|\macro \\
 %  \bottomrule
 %   \multicolumn{4}{l}{{\Large\strut}$^{a}$) As alternative to be used inside normal text.} \\
 %   \multicolumn{4}{l}{Note that `|args|' can itself be further macro arguments except true verbatim.}
@@ -955,6 +973,11 @@
 \hypersetup{colorlinks=true,pdfborder=0 0 0,pdfborderstyle={}}
 %    \end{macrocode}
 %
+% The short verbatim code is required for the similar macros provided here.
+%    \begin{macrocode}
+\RequirePackage{shortvrb}
+%    \end{macrocode}
+%
 % \subsubsection{Color and style definitions}
 %    \begin{macrocode}
 \RequirePackage{xcolor}
@@ -1450,12 +1473,54 @@
   \hbox\y@bgroup
   \@ifundefined{href@impl@\name}{}{\hyperlink{impl:\name}}%
   {\hypertarget{desc:\name}{\PrintMacroName{#1}}}%
+  \ydoc@macrocatcodes
   \macroargsstyle
   \read@Macro@arg
 }
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\ydoc@macrocatcodes}
+% Sets the catcodes inside for |read@Macro@arg| material.
+%    \begin{macrocode}
+\def\ydoc@macrocatcodes{%
+  \ydoc@short@AlsoMacro
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\MakeShortMacroArgs}
+% Defines the given character as short version for |\MacroArgs|.
+% It is first define to be a short verbatim character to take
+% advantage of the house-keeping (save \& restore of the original
+% catcode and definition) of |shortvrb|.
+%
+% The starred version define the character to act like |\Macro| instead.
+%    \begin{macrocode}
+\newcommand*\MakeShortMacroArgs{%
+  \@ifstar
+    {\@MakeShortMacroArgs\Macro}%
+    {\@MakeShortMacroArgs\MacroArgs}%
+}
+\def\@MakeShortMacroArgs#1#2{%
+  \MakeShortVerb{#2}
+  \catcode`#2\active
+  \begingroup
+  \catcode`\~\active
+  \lccode`\~`#2\relax
+  \lowercase{\endgroup\gdef~{\bgroup\let~\egroup#1}}%
+}
+%    \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\DeleteShortMacroArgs}
+%    \begin{macrocode}
+\newcommand*\DeleteShortMacroArgs[1]{%
+  \DeleteShortVerb{#1}%
+}
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\Macro}
 % Simply uses the two macros below.
 %    \begin{macrocode}
@@ -1489,6 +1554,19 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\ydoc@short@AlsoMacro}
+% Makes |&| an alias for |\AlsoMacro|.
+%    \begin{macrocode}
+\begingroup
+\catcode`\|\active
+\gdef\ydoc@short@AlsoMacro{%
+  \catcode`\|\active
+  \let|\AlsoMacro
+}
+\endgroup
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\MacroArgs}
 % Uses the normal macro argument reading mechanism from \cs{DescribeMacro}.
 % Instead of a box a simple group is added.
@@ -1496,6 +1574,7 @@
 \newcommand*\MacroArgs{%
   \begingroup
   \def\end@Macro@args{\endgroup\xspace}%
+  \ydoc@macrocatcodes
   \macroargsstyle
   \read@Macro@arg
 }
@@ -1636,6 +1715,7 @@
   \let\PrintEnv\PrintSubEnv
   \hbox\y@bgroup
   \PrintEnvName{\begin}{\DescribeEnv@name}%
+  \ydoc@macrocatcodes
   \macroargsstyle
   \read@Macro@arg
 }