From 6d511b03036f0b15e6182a5c3718d6dd3309abae Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Wed, 3 Jul 2019 21:39:47 +0000
Subject: mathcommand (3jul19)

git-svn-id: svn://tug.org/texlive/trunk@51542 c570f23f-e606-0410-a88d-b1316a301751
---
 .../source/latex/mathcommand/mathcommand.dtx       | 156 ++++++++++++++-------
 1 file changed, 102 insertions(+), 54 deletions(-)

(limited to 'Master/texmf-dist/source/latex/mathcommand/mathcommand.dtx')

diff --git a/Master/texmf-dist/source/latex/mathcommand/mathcommand.dtx b/Master/texmf-dist/source/latex/mathcommand/mathcommand.dtx
index 86c19a91416..ca621c869d4 100644
--- a/Master/texmf-dist/source/latex/mathcommand/mathcommand.dtx
+++ b/Master/texmf-dist/source/latex/mathcommand/mathcommand.dtx
@@ -23,7 +23,7 @@
 %
 % \iffalse
 %<head>\usepackage{expl3}
-%<head>\ProvidesExplPackage{mathcommand}{2019/05/12}{1.01}{}
+%<head>\ProvidesExplPackage{mathcommand}{2019/07/03}{1.02}{}
 %<*driver>
 \documentclass{ltxdoc}
 \usepackage[utf8]{inputenc}
@@ -34,15 +34,19 @@
 \usepackage{mathcommand}
 \usepackage[hidelinks]{hyperref}
 \usepackage[quotation,scope,electronic]{knowledge}
+\usepackage{enumitem}
 
 \CheckSum{0}
 \changes{1.01}{2019/05/12}{Initial version} %
+\changes{1.02}{2019/07/03}{Bug correction} %
 \GetFileInfo{mathcommand.sty} %
 \DoNotIndex{}
 \edef\mathcommandversiondate{\fileversion--\filedate}
 
 
 
+
+
  \newcommand\smallcode[1]{\colorbox{Honeydew}{\texttt{#1}}}
 
 
@@ -127,6 +131,18 @@
 
 
 
+\newenvironment{commandlist}
+       {\begin{description}[font=\normalfont, 
+                                       nosep,
+                                       itemindent=-2cm,
+                                       leftmargin=0cm,
+                                       topsep=2.5mm]}
+       {\end{description}}
+
+
+
+
+
 \knowledgedirective{doc notion}
          {autoref,style=doc notion,intro style=intro doc notion}
 \knowledgestyle{doc notion}{color=DarkBlue}
@@ -158,17 +174,24 @@
 \author{Thomas Colcombet}
  \maketitle
  \begin{abstract}
-  The "mathcommand" package provides functionalities for defining macros
-  1. that have different behaviors depending on whether in math or text mode,
-  2. that absorb Primes, Indices and Exponents (PIE) as extra parameters usable in the code, and
-  3. offers some iteration facilities for defining macros with similar code.
+ \noindent The "mathcommand" package provides functionalities for defining macros
+  \begin{compactenum}
+  \item that have different behaviors depending on whether in math or text mode,
+  \item that absorb Primes, Indices and Exponents (PIE) as extra parameters usable in the code, and
+  \item offers some iteration facilities for defining macros with similar code.
+  \end{compactenum}
  The primary objective of this package is to be used together with the "knowledge"
  package for a proper handling of mathematical notations.
  \end{abstract}
 
  \section{History of the package}
- This first version of the package was written in May 2019.
-
+ 
+ \begin{compactdesc}
+\item[2019-05-12] First version of the package. V1.01 on CTAN,
+\item[2019-05-14] New macros \cs\IfEmptyTF, \cs\GetExponent, and \cs\GetIndex.
+\item[2019-07-03] Corrects bug of functions declaring PIE's issuing an error when already existing. Version 1.02 on CTAN.
+\end{compactdesc}
+ 
 
  \section{Defining text and math commands}
 
@@ -177,7 +200,7 @@
   (technically stored in a macro \verb|\Text macro|\footnote{These cannot be used accidentally by the user since these control sequences contain a space.}).
  The macro \cs{\macro} itself will execute one or the other depending on whether it is
  executed in math or text mode. Note that all the macros are non-expandable for avoiding problems
- with mathematics that would be sent, for instance, to the table of contents.
+ with mathematics that would be sent, for instance, to the table of contents. The list of commands is described at the end of the section.
 
  For instance after executing:
  \begin{code}
@@ -200,16 +223,19 @@
  For instance \cs{\c} is a convenient way to producing cedillas in \LaTeX, as in \smallcode{\cs\c\ a}
  which yields `\c a'. However, one may want \cs{\c} to reprensent a variable $c$ in math mode.
  This is done using, e.g.:
- \begin{code}
+ \begin{code}[5cm]
  \cs{\renewmathcommand}\cs\c\{c\}
  \end{code}
  \renewmathcommand\c{c}
  \noindent Then, the macro \cs{\c} still works in text mode,
  and using~\cs{\c} in math mode does display simply~`$\c$'.
 
+
+
+
  The name of the macros offered by the "mathcommand" package are mere adaptations of the standard macros of \LaTeX\ and of the package "xparse"\footnote{The package "xparse" offers a very convenient way to define macros with complicated parameter signatures.}.
  Their syntax is the same (in particular in terms of parameter definitions):
- \begin{asparadesc}
+ \begin{commandlist}
  \itemAP[\csintro{\newmathcommand}] is similar to \cs{\newcommand} and creates a "math variant",
  \itemAP[\csintro{\newtextcommand}] is similar to \cs{\newcommand} and creates a "text variant",
  \itemAP[\csintro{\renewmathcommand}] is similar to \cs{\renewcommand} and creates a "math variant",
@@ -224,13 +250,13 @@
  \itemAP[\csintro{\DeclareDocumentTextCommand}] is like \cs{\DeclareDocumentCommand} of the "xparse" package, but creates a "text variant",
  \itemAP[\csintro{\ProvideDocumentMathCommand}] is like \cs{\ProvideDocumentCommand} of the "xparse" package, but creates a "math variant",
  \itemAP[\csintro{\ProvideDocumentTextCommand}] is like \cs{\ProvideDocumentCommand} of the "xparse" package, but creates a "text variant".
- \end{asparadesc}
+ \end{commandlist}
 
  The package offers also the following commands:
- \begin{asparadesc}
+ \begin{commandlist}
  \itemAP[\csintro{\declarecommand}] which is similar to \cs{\newcommand} but defines the macro even if it exists before,
  \itemAP[\csintro{\storecommand}\texttt{[optional-prefix]}\texttt{\cs\macro}] which copies the content of the macro \cs\macro\ to \verb|\optional-prefixmacro|. By default, the optional prefix is \verb|LaTeX|. (Hence, it does what is automatically made by commands such as \cs\declarecommand).
- \end{asparadesc}
+ \end{commandlist}
  
  \section{Defining Prime/Indices/Exponents absorbing commands (PIE commands)}
 
@@ -241,7 +267,7 @@
  This terminology serves as a help for remembering the order prime-index-exponent.
  \AP A ""PIE command"" is similar to a normal macro/command, but for the fact
  that the "PIEs" that follow are absorbed and can be used in the macro as
- three extra parameters.
+ three extra parameters. The list of macros usable for for defining "PIE commands" can be found at the end of this section.
 
  This is best explained through an example. After writing:
  \begin{code}
@@ -252,16 +278,31 @@
  \begin{center}
  \smallcode{\$\cs\macro\{A\}\_2'\$} yields $\macrob{A}_2'$\ .
  \end{center}
- Indeed, in the body of the definition of \cs{macro}, \#1 represents the normal parameter of the command, while the three following parameters (\texttt{\#2},\texttt{\#3},\texttt{\#4} in this case) contain respectively the primes (either empty or a sequence of $'$ symbols), 
+ Indeed, in the body of the definition of \cs{macro}, \texttt{\#1} represents the normal parameter of the command, while the three following parameters (\texttt{\#2},\texttt{\#3},\texttt{\#4} in this case) contain respectively the primes (either empty or a sequence of $'$ symbols), 
  the index (either empty if there is no subscript or of the form \verb"_{index}" if there is
  an index), and the exponent (either empty if there is no superscript or of the form
  \verb"^{exponent}" if there is one).
  In the case of the above definition, the index (parameter \texttt{\#3}) is written inside the parenthesis,
  while primes and exponents are put outside.
 
- The commands provided for defining "PIE commands" are given in the following list. Once more, 
+The are furthermore some helper functions:
+\begin{commandlist}
+\itemAP[\csintro\IfEmptyTF] takes a string and two codes, and expands to the first one if the string is empty, and the second otherwise,
+\itemAP[\csintro{\GetIndex}] takes a string that is an index as in "PIE commands", and expands to its content: it maps the empty string to the empty string, and strings of the form \verb|_{sthg}| to \verb|sthg|,
+\itemAP[\csintro{\GetExponent}]  takes a string that is an exponent as in "PIE commands", and expands to its content: it maps the empty string to the empty string, and strings of the form \verb|^{sthg}| to \verb|sthg|.
+\end{commandlist}
+
+For instance:
+\begin{code}
+\cs\newmathcommandPIE\cs\F\{\#2F\#1\cs\IfEmptyTF\{\#3\}\{\}\{\verb.^.\{(\cs\GetExponent\{\#3\})\}\}\}
+\end{code}
+\newmathcommandPIE\F{#2F#1\IfEmptyTF{#3}{}{^{(\GetExponent{#3})}}}
+\noindent displays \verb|$\F_2^3$| as `$\F_2^3$': the index is placed before, and the exponent is surrounded by parentheses.
+
+
+\paragraph{List of macros of defining "PIE commands".} Once more, 
  appart from the specificity of "PIE commands", the syntax is as the original corresponding commands these are based on.
- \begin{asparadesc}
+ \begin{commandlist}
  \itemAP[\csintro{\newcommandPIE}] is similar to \cs\newcommand\ (but defines a non-expandable macro)
  \itemAP[\csintro{\renewcommandPIE}] is similar to \cs\renewcommand\ (but defines a non-expandable macro)
  \itemAP[\csintro{\declarecommandPIE}] is similar to \cs\newcommand\ and works even if the macro already exists (and defines a non-expandable macro)
@@ -269,10 +310,10 @@
  \itemAP[\csintro{\RenewDocumentCommandPIE}] is similar to \cs\RenewDocumentCommand\ of the "xparse" package,
  \itemAP[\csintro{\DeclareDocumentCommandPIE}] is similar to \cs\DeclareDocumentCommand\ of the "xparse" package,
  \itemAP[\csintro{\ProvideDocumentCommandPIE}] is similar to \cs\ProvideDocumentCommand\ of the "xparse" package.
- \end{asparadesc}
+ \end{commandlist}
 
  Finally, a bunch of macros are used to define "math variants" that are "PIE commands":
- \begin{asparadesc}
+ \begin{commandlist}
  \itemAP[\csintro{\newmathcommandPIE}] is like \cs{\newcommandPIE} and creates a "math variant",
  \itemAP[\csintro{\renewmathcommandPIE}] is like \cs{\renewcommandPIE} and creates a "math variant",
  \itemAP[\csintro{\declaremathcommandPIE}] is like \cs{\declarecommandPIE} and creates a "math variant",
@@ -280,7 +321,7 @@
  \itemAP[\csintro{\RenewDocumentMathCommandPIE}] is like \cs{\RenewDocumentCommandPIE}, but creates a "math variant",
  \itemAP[\csintro{\DeclareDocumentMathCommandPIE}] is like \cs{\DeclareDocumentCommandPIE}, but creates a "math variant",
  \itemAP[\csintro{\ProvideDocumentMathCommandPIE}] is like \cs{\ProvideDocumentCommandPIE}, but creates a "math variant",
- \end{asparadesc}
+ \end{commandlist}
 
 
   \section{Looping for defining commands}
@@ -299,18 +340,18 @@
  \AP The ""list on which to iterate"" is a list of letters or braced sequences of letters.
  \AP the ""name 1"", ""name 2"" up to ""name 7"" optional parameters are expandable
  pieces of code that are to be evaluated
- and then converted to control sequences; they may use the extra parameter~\texttt{\#1}.
- \AP ""code"" is the code to be executed that can
+ and then converted into control sequences; they may use the extra parameter~\texttt{\#1}.
+ \AP Finally, ""code"" is the code to be executed that can
  use the parameters~\texttt{\#1}, \texttt{\#2}, up to~\texttt{\#8}.
 
  The result of executing this macro is that each of the letters or sequences of letters
  in the "list on which to iterate" will be taken one after the other. For each of them, the "code" is executed,
- taking as value of the parameter~\#1 the element in the list, and as parameters~\#2  to~\#8
- control sequences constructed from the evaluation of "name 1" up to "name 7" (using as parameters~\#1 the element of the sequence).
+ taking as value of the parameter~\texttt{\#1} the element in the list, and as parameters~\texttt{\#2}  to~\texttt{\#8}
+ control sequences constructed from the evaluation of "name 1" up to "name 7" (using as parameters~\texttt{\#1} the element of the sequence).
 
  For instance, imagine one easily wants to denote vectors simply as `\cs\vx' instead of `\cs\vec~x' or `\cs\vec\{x\}',
  it is sufficient to write:
- \begin{code}
+ \begin{code}[9cm]
  \cs\LoopCommands\{abcdefghijklmnopqrstuvwxyz\}[v\#1]\\
  \indent~~~~\{\cs\newcommand\#2\{\cs\vec~\#1\}\}
  \end{code}
@@ -318,8 +359,8 @@
  \smallcode{\cs\newcommand\cs\va\{\cs\vec~a\}} and so on up to
  \smallcode{\cs\newcommand\cs\vz\{\cs\vec~z\}}.
 
- Note also that if by default that the "list on which to iterate" is automatically expanded,
- and if a non-expandable control sequence is met, then it is replaced by its main text.
+ Note also that the "list on which to iterate" is automatically expanded,
+ and if a non-expandable control sequence is met, then it is replaced by its the text defining the control sequence.
  Hence using \texttt{\{\cs\alpha\cs\beta\}} is equivalent to \texttt{\{\{alpha\}\{beta\}\}}.
 
 
@@ -336,38 +377,38 @@
  \indent~~~~\{\cs\declarecommandPIE\#2\{\cs\overline\{\#1\#\#2\}\#\#1\#\#3\}
  \end{code}
  \noindent will result in \cs\ou\ to be declared as the "PIE command"
-defined with as main body \texttt{\cs\overline\{u\#2\}\#1\#3\}}
+defined with as main body \texttt{\cs\overline\{u\#2\}\#1\#3}
  (note the translation of parameters, which is the standard way to proceed for \TeX).
  In our case {\tt \cs\ou\_1\verb.^.2} yields `$\ou_1^2$' (the subscript gets to be inside the bar, 
  and the superscript and primes outside), and so on...
- \item When defining multiple commands, some may already exists. To avoid conflict, one sould use
+ \item When defining multiple commands, some may already exist. To avoid conflicts, one should use
     the `declare' version of the defining commands. These will work independently of the 
     context. Is it also good to define only the "math variants" using the appropriate commands
  of the package.
  \itemAP The following strings are predefined for the user to loop on:
     \begin{asparaitem}
-    \itemAP \csintro\lettersUppercase\ stands for \texttt{\lettersUppercase}
-    \itemAP \csintro\lettersLowercase\ stands for \texttt{\lettersLowercase}
-    \itemAP \csintro\lettersAll\ stands for \texttt{\lettersAll}.
-    \itemAP \csintro\lettersGreekLowercase\ stands for $\lettersGreekLowercase$.
-    \itemAP \csintro\lettersGreekUppercase\ stands for $\lettersGreekUppercase$.
-    \itemAP \csintro\lettersGreekAll\ stands for $\lettersGreekAll$.
+    \itemAP[\csintro\lettersUppercase] stands for \texttt{\lettersUppercase}
+    \itemAP[\csintro\lettersLowercase] stands for \texttt{\lettersLowercase}
+    \itemAP[\csintro\lettersAll] stands for \texttt{\lettersAll}.
+    \itemAP[\csintro\lettersGreekLowercase] stands for $\lettersGreekLowercase$.
+    \itemAP[\csintro\lettersGreekUppercase] stands for $\lettersGreekUppercase$.
+    \itemAP[\csintro\lettersGreekAll] stands for $\lettersGreekAll$.
     \end{asparaitem}
  \end{itemize}
  \end{scope}
 
  Hence, for instance:
- \begin{code}
+ \begin{code}[10cm]
  \cs\LoopCommands\cs\lettersUppercase[bb\#1]\\
  \indent~~~~~~\{\cs\newmathcommand\{\cs\mathbb \#1\}\}\\
  \cs\LoopCommands\cs\lettersGreekLowercase[\#1][LaTeX\#1]\\
  \indent~~~~~~\{\cs\renewmathcommand\#2\{\cs\textcolor\{blue\}\{\#3\}\}
  \end{code}
  \noindent configures the macros \cs\bbA, \dots, \cs\bbZ\ to display
- the letters in blackboard bold alphabet (with the "amsfonts" package),
+ the letters in blackboard bold alphabet (e.g. with the "amsfonts" package),
  and the lowercase greek letters \cs\alpha,\dots\ to
  be displayed in blue (with the "xcolor" package loaded). Note in the last case
- the use of an extra parameter that is used for accessing the macros \cs\LaTeXalpha,\dots\
+ the use of the third parameter used for accessing the macros \cs\LaTeXalpha,\dots\
  that are automatically generated by the \cs\renewmathcommand\ macro.
  \newpage
 
@@ -391,8 +432,8 @@ This directory contains the package
 
   name: mathcommand
   license: LaTeX Project Public License version 1.2 or above
-  version: v1.01
-  date: 2019/05/12
+  version: v1.02
+  date: 2019/07/03
   author: Thomas Colcombet
   mail: thomas.colcombet@irif.fr
   web: -
@@ -427,9 +468,11 @@ Content of the file mathcommand-ctan.zip:
 % \subsection{Code preparation}
 %<*package>
 %    \begin{macrocode}
+\NeedsTeXFormat{LaTeX2e}[1994/06/01]
 \RequirePackage{expl3}
 \RequirePackage{etoolbox}
 \RequirePackage{xparse}
+
 \ExplSyntaxOn
 \bool_if_exist:NTF\mathcommand_package_loaded_bool
  \endinput
@@ -600,7 +643,7 @@ Content of the file mathcommand-ctan.zip:
 %    \begin{macrocode}
 \cs_new:Nn\__mathcommand_declarecommandPIE:Nnnn{
    \use:x{
-   \exp_not:N\__mathcommand_new_generic:Nnnn
+   \exp_not:N\__mathcommand_declarePIE_generic:Nnnn
       \exp_not:N#1
       {\IfNoValueTF{#2}{0}{#2}}
       {\cs_if_exist:NTF#1
@@ -665,7 +708,7 @@ Content of the file mathcommand-ctan.zip:
       \DeclareDocumentCommand#1{#2}{}
       \int_gset_eq:NN\g_tmpa_int\l__xparse_current_arg_int
    \group_end:
-   \__mathcommand_new_generic:Nnnn
+   \__mathcommand_declarePIE_generic:Nnnn
       #1
       {\g_tmpa_int}
       {\DeclareDocumentCommand#1{#2}}
@@ -674,19 +717,19 @@ Content of the file mathcommand-ctan.zip:
 %    \end{macrocode}
 % Control token, number parameters, defining command, code
 %    \begin{macrocode}
-\cs_new:Nn\__mathcommand_new_generic:Nnnn{
+\cs_new:Nn\__mathcommand_declarePIE_generic:Nnnn{
    \int_compare:nNnTF{#2}>{6}
     {\PackageError{mathcommand} 
           {At~most~6~parameters~in~PIE~commands~when~defining~`\token_to_str:N#1'}
           {PIE~commands~(mathcommand~package)~do~not~accept~more~than~six~parameters.}}
     {\int_case:nn{#2}
-     {{0} {\cs_new:cpn{\cs_to_str:N#1~PIE~code}##1##2##3}
-      {1} {\cs_new:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4}
-      {2} {\cs_new:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5}
-      {3} {\cs_new:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5##6}
-      {4} {\cs_new:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5##6##7}
-      {5} {\cs_new:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5##6##7##8}
-      {6} {\cs_new:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5##6##7##8##9}}
+     {{0} {\cs_set:cpn{\cs_to_str:N#1~PIE~code}##1##2##3}
+      {1} {\cs_set:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4}
+      {2} {\cs_set:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5}
+      {3} {\cs_set:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5##6}
+      {4} {\cs_set:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5##6##7}
+      {5} {\cs_set:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5##6##7##8}
+      {6} {\cs_set:cpn{\cs_to_str:N#1~PIE~code}##1##2##3##4##5##6##7##8##9}}
     {#4}
    \use:x{
       \exp_not:n{#3}
@@ -731,13 +774,18 @@ Content of the file mathcommand-ctan.zip:
 }
 %    \end{macrocode}
 %    \begin{macrocode}
-\cs_new:Npn\GetContent#1{
+\cs_new:Npn\GetExponent#1{
     \tl_if_empty:nTF{#1}{}{
-        \__mathcommand_GetContent:w #1*\end_marker:
+        \__mathcommand_GetIndexOrExponent:w #1\__end_marker__
     }
 }
-\cs_new:Npn\__mathcommand_GetContent:w #1#2\end_marker:{
-    #1*
+\cs_new:Npn\GetIndex#1{
+    \tl_if_empty:nTF{#1}{}{
+        \__mathcommand_GetIndexOrExponent:w #1\__end_marker__
+    }
+}
+\cs_new:Npn\__mathcommand_GetIndexOrExponent:w #1#2#3\__end_marker__{
+    #2
 }
 %    \end{macrocode}
 %
-- 
cgit v1.2.3

