diff options
Diffstat (limited to 'Master/texmf-dist/doc')
| -rw-r--r-- | Master/texmf-dist/doc/latex/semantex/semantex.pdf | bin | 361207 -> 356833 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/semantex/semantex.tex | 257 |
2 files changed, 83 insertions, 174 deletions
diff --git a/Master/texmf-dist/doc/latex/semantex/semantex.pdf b/Master/texmf-dist/doc/latex/semantex/semantex.pdf Binary files differindex 71f086e8d01..7ccf0be8004 100644 --- a/Master/texmf-dist/doc/latex/semantex/semantex.pdf +++ b/Master/texmf-dist/doc/latex/semantex/semantex.pdf diff --git a/Master/texmf-dist/doc/latex/semantex/semantex.tex b/Master/texmf-dist/doc/latex/semantex/semantex.tex index 1ce506b54f9..e692b550105 100644 --- a/Master/texmf-dist/doc/latex/semantex/semantex.tex +++ b/Master/texmf-dist/doc/latex/semantex/semantex.tex @@ -38,7 +38,7 @@ \usepackage[nameinlink]{cleveref} -\title{Seman\!\TeX: semantic, keyval-based mathematics (v0.43)} +\title{Seman\!\TeX: semantic, keyval-based mathematics (v0.44)} \date{\today} \author{Sebastian Ørsted (\href{mailto:sorsted@gmail.com}{sorsted@gmail.com})} @@ -220,8 +220,6 @@ \makeatother - - \begin{document} \maketitle @@ -890,8 +888,8 @@ Adding support for free algebras, power series, and Laurent series is almost as {laurent}{ par, leftpar=(, rightpar=), - prearg={\!\!\mathopen\SemantexDelimiterSize(}, - postarg={\mathclose\SemantexDelimiterSize)\!\!}, + prearg={\!\!\mathopen{}\SemantexDelimiterSize(}, + postarg={\SemantexDelimiterSize)\mathclose{}\!\!}, % The "prearg" and "postarg" are printed before after % the argument, if the argument is non-empty. % The command "\SemantexDelimiterSize" is substituted @@ -916,8 +914,8 @@ Adding support for free algebras, power series, and Laurent series is almost as {laurent}{ par, leftpar=(, rightpar=), - prearg={\!\!\mathopen\SemantexDelimiterSize(}, - postarg={\mathclose\SemantexDelimiterSize)\!\!}, + prearg={\!\!\mathopen{}\SemantexDelimiterSize(}, + postarg={\SemantexDelimiterSize)\mathclose{}\!\!}, % These are printed before and after the argument. % The command "\SemantexDelimiterSize" is substituted % by \big, \Big, ..., or whatever size the @@ -1933,17 +1931,20 @@ $\norm{\va}$, $\inner{\va,\vb}$, $\inner{slot,slot}$ \end{LTXexample} + We can also use it for more complicated constructions, like sets. -The following is inspired from the \pack{mathtools} package where a similar construction is created using the commands from that package. My impression is that Lars Madsen is the main mastermind behind the code I use for the \lstinline!\where!~command: +The following is inspired from the \pack{mathtools} package where a similar construction is created using the commands from that package. My impression is that Lars Madsen is the main mastermind behind the code I use for the \lstinline!\where!~construction: \begin{lstlisting} -\newcommand\where{ +\newcommand\wherecommand[1]{ \nonscript\: - \SemantexDelimiterSize\vert + #1\vert \allowbreak \nonscript\: \mathopen{} } +\NewObject\MyVar\where{ \wherecommand{\SemantexDelimiterSize} } + \NewObject\MyDelim\Set{\lbrace}{\rbrace}[ prearg={\,},postarg={\,}, % adds \, inside {...}, as recommended by D. Knuth @@ -1951,20 +1952,24 @@ The following is inspired from the \pack{mathtools} package where a similar cons % this turns off all keyval syntax in the argument ] \end{lstlisting} -\newcommand\where{ +\newcommand\wherecommand[1]{ \nonscript\: - \SemantexDelimiterSize\vert + #1\vert \allowbreak \nonscript\: \mathopen{} } +\NewObject\MyVar\where{ \wherecommand{\SemantexDelimiterSize} } + \NewObject\MyDelim\Set{\lbrace}{\rbrace}[ prearg={\,},postarg={\,}, % adds \, inside {...}, as recommended by D. Knuth argkeyval=false, % this turns off all keyval syntax in the argument ] + +\noindent As we briefly mentioned previously, \lstinline!\SemantexDelimiterSize!~is a command that returns the size of the delimiters in the @@ -1975,7 +1980,7 @@ $\Set{ \vx\in\vY \where \vx\ge0 }$, $\Set[par=\big]{ \vx\in\vY \where \vx\ge0 }$ \end{LTXexample} Don't forget that, since the class~\lstinline!\MyDelim! inherits from~\lstinline!\MyVar!, -the output of any of these commands has class~\lstinline!\MyVar!. +the output of any of these commands also belongs to class~\lstinline!\MyVar!. So you can do stuff like \begin{LTXexample} $\Set{ @@ -2755,6 +2760,8 @@ Let us see it in action: \partialdif[\vu^2,\vv^2, d=4,raise=false]{ \vf }, +\] +\[ \partialdif[\vx[1], \vx[2],...,\vx[\vn], d=\vn,raise=false]{ @@ -2794,27 +2801,21 @@ The system has the following limitations: \item It is currently only able to strip the \semantex markup from your main document (so it will ignore anything in \lstinline!\input{...}! and~\lstinline!\include{...}!). So prior to running \pack{stripsemantex}, you should include your entire document body in your main \texttt{.tex}~file. + \item Partly because of the previous point, no attempt is made to remove + the \emph{setup} of \semantex, + so commands like \lstinline!\NewObject!, \lstinline!\SetupObject!, and~\lstinline!\SetupClass! + will remain in the document body. + You will then have to remove these yourself afterwards. + But the \semantex markup itself should be stripped completely from your document. \item As mentioned, as long as you do normal, supported things, everything should work fine. Non-normal, non-supported things are tings like \begin{lstlisting} \va[execute={\vb}] \end{lstlisting} - \item Occasionally, you will have to run the stripping algorithm - multiple times. This happens e.g.~if you have - a key that does stuff like \lstinline!symbolputleft=\vH[d=0]!, - i.e.~keys that are defined using other objects. When you run - \pack{stripsemantex}, such objects will remain in the text until you run it again. - \item Partly because of the previous point, no attempt is made to remove - the \emph{setup} of \semantex, - so commands like \lstinline!\NewObject!, \lstinline!\SetupObject!, and~\lstinline!\SetupClass! - will remain in the document body. - You will then have to remove these yourself afterwards. - But the \semantex markup itself should be stripped completely from your document - (possibly after more than one run of the algorithm). \item Things might go wrong if you define new keys between \lstinline!\begin{document}! and~\lstinline!\end{document}! - whose definitions make use of \semantex objects or classes, + whose definitions make use of other \semantex objects or classes, since the algorithm will try to strip these from the definitions. For instance, don't do stuff like this after~\lstinline!\begin{document}!: @@ -2833,9 +2834,20 @@ The system has the following limitations: \item When the document has just been stripped, it will load a small package called \pack{semtex}, which contains a couple of commands that the output will need - in order to run. You should be able to replace most (often all) of these commands + in order to run. You will be able to replace all of these commands by other commands and then render the package \pack{semtex} unnecessary. More on this in \cref{sec:semtex_package}. + \item When \semantex runs, the content of any argument is being wrapped + between \lstinline!\begingroup! and~\lstinline!\endgroup!. This is part of what + makes it possible to use the command~\lstinline!\SemantexDelimiterSize!. + However, these \lstinline!\begingroup! and~\lstinline!\endgroup! will not appear + in the stripped document. This means that if you do stuff like + \begin{lstlisting} +$ \def\foo{bar} \va{ \def\foo{barbar} \vx } \foo $ + \end{lstlisting} + then this will print~\( \va{\vx} bar \) before running \pack{stripsemantex}, + but~\( \va{\vx} barbar \) after. In order to avoid this, simply don't define + commands inside arguments, which you should never do in the first place (and why would you anyway?). \end{itemize} As a small proof of concept, this is what the example in the introduction @@ -2870,9 +2882,9 @@ you can have a look at my latest paper, which was stripped with When you have stripped your document and removed all \semantex package setup, it should be safe to remove the loading of \semantex from your preamble. However, the stripping algorithm will automatically -add the following right before~\lstinline!\begin{document}!: +add the following lines to your document right before~\lstinline!\begin{document}!: \begin{lstlisting} -% The following was added by "stripsemantex" +% The following was added by "stripsemantex": \usepackage{semtex,leftindex,graphicx} @@ -2896,18 +2908,12 @@ possible left indices. The package~\pack{graphicx} is loaded to provide the command~\lstinline!\scalebox!. This package~\pack{semtex} is a small package whose sole purpose is to be loaded by stripped \semantex documents. -It contains a couple of simple commands that the document -needs immediately after the stripping. -Depending on your document, -you should be able to completely replace these commands -by commands from other packages, or define them yourself, rendering the package~\pack{semtex} -unnecessary. -And actually, four of those commands are the commands +All it does is define the four commands \lstinline!\SemantexLeft!, \lstinline!\SemantexRight!, \lstinline!\SemantexBullet!, and~\lstinline!\SemantexDoubleBullet! -which are provided right below, making it even faster to just remove~\pack{semtex}. +so that you can remove these definitions from your document and just rely on the package instead. -In total, the package~\pack{semtex} adds the following commands: +Let us take a look at the commands defined by \pack{semtex}: \begin{itemize} \item @@ -2929,74 +2935,8 @@ In total, the package~\pack{semtex} adds the following commands: from the package~\pack{mleftright}, so it is safe to just load that package and replace the above commands by \lstinline!\mleft...\mright! instead, or use the redefinitions mentioned above. - - \item - \mylst!\SemantexParentheses{$\values\<normal|auto|*|{\textit{other}}\>$}{$\<left parenthesis\>$}!\\ - \mbox{\qquad}\mylst!{$\<right parenthesis\>$}{$\<content\>$}!, - - This one writes \<content\> enclosed in the pair of parentheses - and with the size given by the first argument. - Here,~\lstinline!normal! means normal size - parentheses, - and - \lstinline!auto! and~\lstinline!*! - mean auto-scaled parentheses using the commands~\lstinline!\SemantexLeft...\SemantexRight!. - If another value is received, that value - is used for the parenthesis size, - so the intended values are~\lstinline!\big!, \lstinline!\Big!, - \lstinline!\bigg!,~\lstinline!\Bigg!. - The important property of this command is that - inside the~\<content\>, you can access the delimiter size - at any point using the command~\lstinline!\SemantexDelimiterSize!. In other words, when - no~\lstinline!\SemantexDelimiterSize! is found inside the~\<content\>, - the command is completely redundant. We shall see - in a moment how to make sure it does not appear in your output - unless absolutely necessary. - - \item - \mylst!\SemantexNoParentheses{$\<content\>$}! - - This command prints the content with no parentheses, but importantly, it also resets - the command \lstinline!\SemantexDelimiterSize! - to~\lstinline!{}!, i.e.~blank. - As with the command~\lstinline!\SemantexParentheses!, - we shall see in a moment how to make this - command not appear in your output - unless absolutely necessary. \end{itemize} -As you see, most of these commands can be removed completely -or replaced by commands from other packages. The one -issue is with the annoying -commands \lstinline!\SemantexParentheses! -and~\lstinline!\SemantexNoParentheses!. -These exist solely for the purpose of allowing the use of -the command~\lstinline!\SemantexDelimiterSize! in the content. -However, there are very few cases, such as set constructions, where -\lstinline!\SemantexDelimiterSize! is even necessary. Therefore, -\textbf{it is possible to turns the use of these commands off}. -More precisely, there is a key that can be -activated for any object or class: -\begin{center} - \mylst!allowSemantexDelimiterSize=$\values\<\default{true}|false\>$! -\end{center} -When this is set to false, \semantex will not use the -commands~\lstinline!\SemantexParentheses! -and~\lstinline!\SemantexNoParentheses! internally, -and consequently, \lstinline!\SemantexDelimiterSize! will not work in that class or object. -Instead, it will simply print the parentheses as raw code, -and this is what will appear in your stripped document instead. -The natural thing to do is to turn it off by default and -only turn it back on for the few cases where you really need it: - -\begin{lstlisting} -\SetupClass\MyVar{allowSemantexDelimiterSize=false} - -% We turn it back on for the set constructions -% as defined above. -\SetupObject\Set{allowSemantexDelimiterSize=true} -\end{lstlisting} - \section{The \texttt{stripsemantex} algorithm} The stripping algorithm works like this. @@ -3009,18 +2949,12 @@ Suppose in the following that you \TeX\ document is called~\texttt{mydoc.tex}. \item Make sure to collect all of the \semantex markup you want stripped in the main document,~\texttt{mydoc.tex}. Also make sure to follow the recommendations - in \cref{sec:UseClassInCommand}, in case you have created keys + in \cref{sec:UseClassInCommand}, in case you have created commands of the form described there. - \item Set~\lstinline!allowSemantexDelimiterSize=false! - for your main class~\lstinline!\MyVar!, and only - turn it back on in the few cases where you need it, - i.e.~when you need to use the command~\lstinline!\SemantexDelimiterSize!. \item Put the following somewhere in your preamble, after the loading of \semantex: \begin{lstlisting} -\SemantexSetup{ - semtexfile=true, -} +\SemantexSetup{semtexfile=true} \end{lstlisting} \item Compile your document \texttt{mydoc.tex} using your preferred \TeX\ engine (\hologo{pdfTeX}, \hologo{XeTeX}, \hologo{LuaTeX}, or whatever). Because of the previous step, there @@ -3039,58 +2973,59 @@ Suppose in the following that you \TeX\ document is called~\texttt{mydoc.tex}. \begin{document} -\StripSemantexCopyFile{mydoc} - -%\StripSemantexStripFile{mydoc} +\StripSemantex{mydoc} \end{document} \end{lstlisting} Then compile it \textbf{with \hologo{LuaTeX}}. - \item After the previous step, another document will have been created in the same + + After this step, another document will have been created in the same folder, called~\lstinline!mydoc_prestripped.tex!. It will look just like \texttt{mydoc.tex}, but in the document body, each \semantex markup command will now have a command \mylst!\SemantexIDcommand{$\<a unique ID\>$}! - preceding it. Compile this new document \lstinline!mydoc_prestripped.tex! using the same \TeX\ engine as the one you used + preceding it. + + \item\label{pt:pre_strip_point} + Compile the document \lstinline!mydoc_prestripped.tex! using the same \TeX\ engine as the one you used for \texttt{mydoc.tex}. - \item\label{pt:strip_point} Edit~\texttt{stripdoc.tex}, commenting out the line~\lstinline!\StripSemantexCopyFile{mydoc}!, and - uncommentng the next one, so that the file now looks like this: - \begin{lstlisting} + \item\label{pt:strip_point} + Compile the document~\lstinline!stripdoc.tex! again, this time also \textbf{using \hologo{LuaTeX}}. + + \item After the previous step, some (but usually not all) \semantex markup will have been + removed from the file~\lstinline!mydoc_prestripped.tex!. + If the stripping algorithm has terminated (which it almost never does after a single run), there will now be a new document in your folder, + called~\lstinline!mydoc_stripped.tex!. + If this document is not there, repeat the steps \ref{pt:pre_strip_point} and~\ref{pt:strip_point}. + + Continue this way until the file \lstinline!mydoc_stripped.tex! appears. It can easily require three or more iterations, but each iteration will usually be faster than the previous one, and eventually, the file~\lstinline!mydoc_stripped.tex! will appear. + (Note that at the point~\ref{pt:strip_point}, \pack{stripsemantex} will also issue a warning if the algorithm has not yet terminated, asking you to repeat the steps \ref{pt:pre_strip_point} and~\ref{pt:strip_point}). + + Note again that your \semantex \textbf{setup} + will not be removed, so there + will still be commands like \lstinline!\NewObject!, + \lstinline!\SetupObject!, \lstinline!\SetupClass!,~etc. + left. You will then have to remove these few commands from your document manually. +\end{enumerate} + +Apart from the machinery for stripping \semantex markup from documents, +the package \pack{stripsemantex} also provides the command~\lstinline!\StripSemantexStripComments!, +which is in principle completely unrelated to \semantex itself. +This command allows you to strip all comments between \lstinline!\begin{document}! and~\lstinline!\end{document}!. +If your document is again called~\lstinline!mydoc.tex!, +you can create the following document and compile it \textbf{with \hologo{LuaTeX}}: +\begin{lstlisting} \documentclass{article} \usepackage{stripsemantex} \begin{document} -%\StripSemantexCopyFile{mydoc} - -\StripSemantexStripFile{mydoc} +\StripSemantexStripComments{mydoc} \end{document} - \end{lstlisting} - Then compile this document again, this time also \textbf{using \hologo{LuaTeX}}. - This will create a document called \lstinline!mydoc_stripped.tex!, which should (hopefully) - be completely stripped of \semantex markup in the document body. - Occasionally, as mentioned above, a few such commands may remain, in which case you will simply - have to repeat the above steps, this time with the document~\texttt{mydoc.tex} - replaced by~\lstinline!mydoc_stripped.tex!. - Note again that your \semantex \textbf{setup} - will not be removed, so there - will still be commands like \lstinline!\NewObject!, - \lstinline!\SetupObject!, \lstinline!\SetupClass!,~etc. - left. You will then have to remove these few commands from your document manually. -\end{enumerate} - -There is also another command in the \pack{stripsemantex} package, -called simply \mylst!\StripSemantex!, which will -run either the command \mylst!\StripSemantexCopyFile! or the command \mylst!\StripSemantexStripFile!, -depending on which of the files \lstinline!mydoc.semtex! -and~\mylst!mydoc_prestripped.semtex! is newer. -This will allow you to not have to edit -the file \texttt{stripdoc.tex} -at point~\ref{pt:strip_point}. -Unfortunately, due to a bug in \LaTeX3, -this command does not work right now (in~\hologo{LuaTeX}). This bug has been reported -and has hopefully already been fixed by the time you read this. +\end{lstlisting} +This will create a new document, called \lstinline!mydoc_comments_stripped.tex!, where all comments +in the document body have been removed. \chapter{Known bugs} @@ -3503,19 +3438,6 @@ In the following sections, we include the full list. The intended values are \lstinline!\mathord!, \lstinline!\mathop!, \lstinline!\mathbin!, \lstinline!\mathrel!, \lstinline!\mathopen!, \lstinline!\mathclose!, and~\lstinline!\mathpunct!. \item - \mylst!allowSemantexDelimiterSize={$\values\<\default{true}|false\>$}! - - Sets whether to allow the command \lstinline!\SemantexDelimiterSize! - inside the argument. - The default is~\lstinline!true!. - The only real reason to turn this off is if you are using - \lstinline!stripsemantex! to strip the document of \semantex markup. - For if it is set to false, the system will not - add \lstinline!\SemantexParentheses! and \lstinline!\SemantexNoParentheses! - all over the place to set the value of \lstinline!\SemantexDelimiterSize!, - and this probably looks better in the outputted code. - - \item \mylst!default={$\<value\>$}! This is the key that is applied whenever the @@ -5872,19 +5794,6 @@ the programming keys and commands: (boolean): If true, the next lower upper index will have a separator printed in front of it. \item - \mylst!allowSemantexDelimiterSize! - (boolean): - if true, the argument will - allow the command \lstinline!\SemantexDelimiterSize! - inside the argument; - the default is~\lstinline!true!. - The only real reason to turn this off is if you are using - \lstinline!stripsemantex! to strip the document of \semantex markup. - For if it is set to false, the system will not - add \lstinline!\SemantexParentheses! and \lstinline!\SemantexNoParentheses! - all over the place to set the value of \lstinline!\SemantexDelimiterSize!, - and this probably looks better in the outputted code. - \item \mylst!numberofarguments! (integer): the number of arguments. |