diff options
| -rw-r--r-- | Master/texmf-dist/doc/latex/knowledge/README.md | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/knowledge/knowledge.pdf | bin | 771140 -> 802176 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/knowledge/knowledge.tex | 363 | ||||
| -rw-r--r-- | Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx | 17 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/knowledge/knowledge.sty | 11 |
5 files changed, 197 insertions, 198 deletions
diff --git a/Master/texmf-dist/doc/latex/knowledge/README.md b/Master/texmf-dist/doc/latex/knowledge/README.md index 07b55368a00..a03e55834a5 100644 --- a/Master/texmf-dist/doc/latex/knowledge/README.md +++ b/Master/texmf-dist/doc/latex/knowledge/README.md @@ -3,8 +3,8 @@ This directory contains the package name: knowledge license: LaTeX Project Public License version 1.2 or above - version: v1.28 - date: 2022/02/12 + version: v1.29 + date: 2024/03/10 author: Thomas Colcombet mail: thomas.colcombet@irif.fr web: https://ctan.org/pkg/knowledge diff --git a/Master/texmf-dist/doc/latex/knowledge/knowledge.pdf b/Master/texmf-dist/doc/latex/knowledge/knowledge.pdf Binary files differindex 2e7e53daac5..a4a481ddb00 100644 --- a/Master/texmf-dist/doc/latex/knowledge/knowledge.pdf +++ b/Master/texmf-dist/doc/latex/knowledge/knowledge.pdf diff --git a/Master/texmf-dist/doc/latex/knowledge/knowledge.tex b/Master/texmf-dist/doc/latex/knowledge/knowledge.tex index a821315e1b6..8d0c1102aa8 100644 --- a/Master/texmf-dist/doc/latex/knowledge/knowledge.tex +++ b/Master/texmf-dist/doc/latex/knowledge/knowledge.tex @@ -7,6 +7,7 @@ \usepackage{hyperref} \usepackage{cleveref} %\usepackage{complexity} +\usepackage{marginfix} \usepackage[quotation,scope,silent]{knowledge} \knowledgeconfigure{visible anchor points=false} \knowledgeconfigure{notion,diagnose line=false} @@ -58,7 +59,7 @@ \textmenu{\hyperref[section:doc]{doc}} --- \textmenu{\hyperref[section:faq]{FAQ}} --- \textmenu{\hyperref[section:resources]{resources}} --- - \ifcodeTF{\textmenu{\hyperref[section:code]{code}} ---}{} + \ifcodeTF{\textmenu{\hyperref[section:code]{CODE}} ---}{} \end{tabular}% }}} } @@ -136,8 +137,10 @@ PDF string={\detokenize{#1}} } -\knowledgestyle{cs}{wrap=\Robustdisplay,typewriter,up,md,color=NavyBlue} -\knowledgestyle{cs unknown}{wrap=\Robustdisplay,typewriter,up,md,color=black} +%\knowledgestyle{cs}{wrap=\Robustdisplay,typewriter,up,md,color=NavyBlue} +%\knowledgestyle{cs unknown}{wrap=\Robustdisplay,typewriter,up,md,color=black} +\knowledgestyle{cs}{wrap=\detokenize,typewriter,up,md,color=NavyBlue} +\knowledgestyle{cs unknown}{wrap=\detokenize,typewriter,up,md,color=black} \knowledgenewvariant\csintro {namespace=cs, @@ -593,7 +596,7 @@ \fbox{\usebox{\fminipagebox}}% \kern\dimexpr-\fboxsep-\fboxrule\relax}\par\kern#2\relax} - \newenvironment{code}[1][12.4cm] + \newenvironment{CODE}[1][12.4cm] {\par \noindent \cminipage{#1}% @@ -787,6 +790,7 @@ I have seen Till Tantau who explained me how to test whether a material is displ \item[2021-12-27] Bug correction for corner shape, and doc update (thanks to Rémi Morvan). \item[2022-01-12] Minor changes. Removing dead link for the webpage. V1.27 \item[2022-02-12] Adding support of "imakeidx@@package" and the directive "index name=" (request and code change by Maximilian Keßler). V1.28 +\item[2024-03-10] Correcting typographic bug of \cs\withkl\ and \cs\cmdkl\ when in combination with e.g. \cs\mathrel\ (suggested by Rémi Morvan). V1.29 \end{compactdesc} \normalsize %\restoregeometry @@ -831,20 +835,20 @@ using either: \marginpar{\begin{hint} You may use other options like \kl(option){xcolor} for allowing debugging with colors (for undefined knowledges). \end{hint}} -\begin{code}[8cm] +\begin{CODE}[8cm] \cs{\usepackage}["hyperref@@package",\kl(option){quotation}]\{"knowledge@@package"\} -\end{code} +\end{CODE} \noindent or equivalently: -\begin{code}[8cm] +\begin{CODE}[8cm] \cs\usepackage\{\kl(package){hyperref}\}\\ \cs\usepackage[\kl(option){quotation}\footnote{If you want to use the \kl{"..."} notation.}]\{"knowledge@@package"\} -\end{code} +\end{CODE} Then, in the preamble (or in an external file), one uses commands of the form either: -\begin{code} +\begin{CODE} \cs\knowledge\{\kl{url=}\{https://en.wikipedia.org/wiki/LaTeX\}\}\par \qquad\kl{|}\quad latex -\end{code} +\end{CODE} This configures the text `\texttt{latex}' to be associated with the sole directive \kl{url=}, which means an hyperreference to this address. @@ -858,13 +862,13 @@ Hence: In fact, it is good practice to use many \cs{\kl} commands or \kl{"..."} notations while writing a text, and only resolve these questions at the end (see also the \kl{diagnose file}). \end{hint}} -\begin{code}[10cm] +\begin{CODE}[10cm] This package has been written for use in \cs\kl\{latex\}. -\end{code}\noindent +\end{CODE}\noindent or, if the \kl(option){quotation} option is activated, -\begin{code}[10cm] +\begin{CODE}[10cm] This package has been written for use in \kl{"}latex\kl{"}. -\end{code}\noindent +\end{CODE}\noindent yields \knowledge{urllatex}{url=https://en.wikipedia.org/wiki/LaTeX,color=black} \begin{PDFoutput} @@ -875,11 +879,11 @@ This package has been written for use in \kl[urllatex]{latex}. But in fact, I would like `\texttt{latex}' to also be properly typeset \LaTeX{}, and in \textcolor{gray}{gray}. This requires to load the package with the \kl(option){xcolor} option (for being able to use colors, obviously), or by loading the package "xcolor@@package" before, and then modify the \cs{\knowledge} command using extra "directives": -\begin{code}%[10.9cm] +\begin{CODE}%[10.9cm] \cs\knowledge\{\kl{url=}\{https://en.wikipedia.org/wiki/LaTeX\},\par \qquad~\qquad\kl{text=}\cs\LaTeX,~\kl{color=}gray\}\par \qquad\kl{|}\quad latex -\end{code} +\end{CODE} \noindent yields with the same text \knowledge{urllatexgray}{url=https://en.wikipedia.org/wiki/LaTeX, color=gray, text=\LaTeX} @@ -900,20 +904,20 @@ the result is that the text `\textit{text}' is displayed, but urls, colors, etc Another more systematic way to do it is to declare synonyms. This obtained by adding the corresponding lines: - \begin{code}[4.35cm] + \begin{CODE}[4.35cm] \cs{\knowledge}\{"url="\dots\}\\ \indent~\vbar~Donald Ervin Knuth\\ \indent~\vbar~Donald Knuth\\ \indent~\vbar~D. Knuth\\ \indent~\vbar~Knuth - \end{code} + \end{CODE} \noindent would allow \begin{center} \smallcode{\cs\kl\{Knuth\}}~~~as well as~~~\smallcode{\cs\kl\{Donald Knuth\}},\\ or simply \smallcode{\kl"Knuth\kl"}~~~as well as~~~\smallcode{\kl"Donald Knuth\kl"} and so on \end{center} to all point to the same web address. It is even more convenient to use it for nouns that are sometimes in plural form or at the beginning of a sentence. There is also a scoping feature that helps distinguishing the same names in a different context. For instance: -\begin{code}[12.4cm] +\begin{CODE}[12.4cm] \cs\knowledge\{\kl{url=}https://en.wikipedia.org/wiki/Group\_(mathematics)\} \qquad\indent~~~\vbar~~group\\ \qquad\indent~~~\vbar~~groups\\ @@ -924,13 +928,13 @@ It is even more convenient to use it for nouns that are sometimes in plural form \qquad\indent~~~\vbar~~morphism@GROUP\\ \qquad\indent~~~\vbar~~morphisms@GROUP\\ \qquad\indent~~~\vbar~~Morphisms@GROUP -\end{code} +\end{CODE} \end{variation} \noindent makes it possible to use the notions in many contexts: -\begin{code} +\begin{CODE} \kl"Groups\kl" form a category when equipped with \kl"group morphisms\kl". Consider now some \kl"morphism@@GROUP\kl" \$\cs\alpha\$ ... -\end{code} +\end{CODE} In the above code all quoted parts send the reader to the same wikipedia page about groups. Note in particular that \smallcode{\kl"morphism@@GROUP\kl"} simply displays `morphism' at compilation. The \smallcode{GROUP} part is a "scope". @@ -952,9 +956,9 @@ However, I do not want it to be a hassle when writing. A solution is as follows. First load the "knowledge@@package" package in the preamble: -\begin{code}[11cm] +\begin{CODE}[11cm] \cs\usepackage[\kl(option){xcolor},\kl(option){hyperref},\kl(option){notion},\kl(option){quotation}]\{"knowledge@@package"\} -\end{code} +\end{CODE} \noindent with suitable options: \kl(option){hyperref} for links, \kl(option){xcolor} for colors (if required, but always advised), "quotation@@option" for using the "quotation notation" and \kl(option){notion} for automatic configuration of the "notion" "directive". @@ -964,15 +968,15 @@ Then write the document using \cs{\intro} (or \kl{""...""} if \kl(option){quotat \marginpar{\begin{hint} Using an \cs{\AP} command is strongly advised, and allows to control more precisely where the target of hyperreferences is: at the beginning of a paragraph is better than the beginning of the section several pages before...\end{hint}} \cs{\kl} (or \kl{"..."} if \kl(option){quotation} is activated) when it is used. For instance: -\begin{code}[12cm] +\begin{CODE}[12cm] \cs\AP{} A \cs\intro\{semigroup\} is an ordered pair \verb|$(S,\cdot)$| in which \verb|$S$| is a set and \verb|$\cdot$| is an associative binary operator over~\verb|$S$|. A \cs\intro\{semigroup morphism\} is "[...]"\\ "[...]"\\ Consider a \cs\kl\{semigroup morphism\} between \cs\kl\{semigroups\} \verb|$S$| and \verb|$T$|. "[...]" -\end{code} +\end{CODE} \noindent or when the "quotation notation" is activated: -\begin{code}[12cm] +\begin{CODE}[12cm] \cs\AP{} A \kl{""}semigroup\kl{""} is an ordered pair \verb|$(S,\cdot)$| in which \verb|$S$| is a set and \verb|$\cdot$| is an associative binary operator over~\verb|$S$|. @@ -980,7 +984,7 @@ associative binary operator over~\verb|$S$|. A \kl{""}semigroup morphism\kl{""} is "[...]"\\ "[...]"\\ Consider a \kl"semigroup morphism\kl" between \kl"semigroups\kl" \verb|$S$| and \verb|$T$|. "[...]" -\end{code} +\end{CODE} This yields \knowledgeconfigure{visible anchor points=true}% @@ -1006,13 +1010,13 @@ which means that the strings `\texttt{semigroup}', `\texttt{semigroups}' and `\ \AP To solve this, let us copy these four lines in the preamble\footnote{It is good practice to use a separate file, something like `paper-knowledge.tex'.}, replacing ignore by the \kl{notion} \kl{directive} and separating it into two blocks. We obtain: -\begin{code}[6.7cm] +\begin{CODE}[6.7cm] \cs\knowledge\{\kl{notion}\}\\ \indent~~~\klbn|~~semigroup\\ \indent~~~\klbn|~~semigroups\\ \cs\knowledge\{\kl{notion}\}\\ \indent~~~\klbn|~~semigroup morphism -\end{code} +\end{CODE} \noindent This informally means that `\texttt{semigroup}' and `\texttt{semigroups}' are two strings that represent the same notion, and that `\texttt{semigroup morphism}' is a different one. @@ -1035,7 +1039,7 @@ location of the red corner depicting the presence of the \cs{\AP}-command before If now one adds the option \kl{electronic} while loading the package, then the red corners disappear as well as the undefined knowledges which become black. When using the option \kl{paper}, the links are still there, but all texts are in black. A more complete example would look as follows: -\begin{code}[6.7cm] +\begin{CODE}[6.7cm] \cs\knowledge\{\kl{notion}\}\\ \indent~~~\klbn|~~semigroup\\ \indent~~~\klbn|~~semigroups\\ @@ -1045,7 +1049,7 @@ A more complete example would look as follows: \indent~~~\klbn|~~semigroup morphisms\\ \indent~~~\klbn|~~morphism@SG\\ \indent~~~\klbn|~~morphisms@SG -\end{code}\noindent +\end{CODE}\noindent The most interesting part consists of the two last lines. These define `\texttt{morphism}' and `\texttt{morphisms}' to represent the same notion as `\texttt{semigroup morphism}' when in the scope `\texttt{SG}' (a convenient abbreviation chosen by the writer for meaning `semigroup'). This is particularly useful for separating morphisms of semigroups from, say, ring morphisms. Now, using \smallcode{Take a \cs\kl\{morphism\} ...} would yield an unknown knowledge. However, \smallcode{Take a \cs\kl(SG)\{morphism\} ...} or \smallcode{Take a \kl"morphism@@SG\kl" ...} would yield @@ -1065,9 +1069,9 @@ These \kl(ex1)[semigroup]{algebraic objects} "[...]" The term is properly linked to the definition of semigroups. Another possibility is to refer to the location of the definition, using commands \cs\kref, \cs\kpageref, and even better their improvements \cs\kcref, \cs\kCref, etc (when using the "cleveref@@option" package). For instance, -\begin{code} +\begin{CODE} \kl"Semigroups\kl" are introduced in \cs\kCref\{semigroup\},\\ Page~\cs\kpageref\{semigroup\}. -\end{code} +\end{CODE} \noindent yields: \begin{PDFoutput}[10cm] \kl(ex1)[semigroups]{Semigroups} are introduced in \kCref(ex1){semigroups}, @@ -1077,7 +1081,7 @@ Finally, in particular for large documents, it is good to have an "index". For t one should load the package "makeidx@@package" before "knowledge@@package". Then use it normally: putting \cs{\makeindex} in the preamble and \cs{\printindex} at the end of the document. Finally, the \cs{knowledge} commands are adapted in a straightforward manner: -\begin{code}[10.7cm] +\begin{CODE}[10.7cm] \cs\knowledge\{\kl{notion},"index="semigroup\}\\ \indent~~~\klbn|~~semigroup\\ \indent~~~\klbn|~~semigroups\\ @@ -1087,7 +1091,7 @@ Finally, the \cs{knowledge} commands are adapted in a straightforward manner: \indent~~~\klbn|~~semigroup morphisms\\ \indent~~~\klbn|~~morphism@SG\\ \indent~~~\klbn|~~morphisms@SG -\end{code}\noindent +\end{CODE}\noindent Now, the index (after running \texttt{makeindex}) contains all entries and references to the use of semigroups and semigroup morphisms. See \kCref(option){makeidx} for more details on making an index. @@ -1102,13 +1106,13 @@ See \kCref(option){makeidx} for more details on making an index. \label{subsection:mathematics scenario} The examples above show various techniques for using \kl{knowledges} for enhancing the information associated to terms. In fact, these techniques are not incompatible with mathematics. Some special syntax is even offered: -\begin{code}[12.6cm] +\begin{CODE}[12.6cm] \cs\knowledgenewrobustcmd\cs\closure[1]\{\cs\cmdkl\{\cs\langle\}\#1\cs\cmdkl\{\cs\rangle\}\}\}\\ "[...]"\\ The closure of~\$X\$ under product is denoted~\$\cs\intro*\cs\closure\{X\}\$.\\ "[...]"\\ Consider now \$\cs\closure\{\cs\{a,b,c\cs\}\}\$. -\end{code}\noindent +\end{CODE}\noindent \noindent would yield: \begin{PDFoutput}[8cm] @@ -1126,7 +1130,7 @@ Even better, I would like to be able to have variables hyperlinking to the place attached to a particular context. This is particularly true when typesetting mathematics: a variable is meaningful inside a statement, and inside the proof of the statement. Furthermore, the same variable name may reappear elsewhere with a different meaning. The following code gives an idea of what is possible using \kl{scoping}: -\begin{code} +\begin{CODE} \cs\knowledgeconfigureenvironment\{theorem,lemma,proof\}\{\}\par\noindent "[...]"\par\noindent \cs\begin\{lemma\}\cs\label\{theorem:main\}\par\noindent @@ -1140,7 +1144,7 @@ Here \$\cs\kl\ n\$ is an undefined knowledge.\par\noindent ~~~~\cs\knowledgeimport\{theorem:main\}\par\noindent ~~~~Inside the proof, \$\cs\kl\ n\$ is hyperlinked to the theorem...\par\noindent \cs\end\{proof\} -\end{code} +\end{CODE} More on \kl{scoping} can be found in Section~\ref{subsection:scoping}. The use of "variants of \cs{\kl}" is also useful for typesetting mathematics. It allows for instance, to implicitly execute the \cs{\knowledge} command at the same time of the introduction. See~\ref{subsubsection:variants} for more detail. @@ -1189,15 +1193,15 @@ or &\smallcode{\cs\usepackage[\kl{composition}]\{"knowledge@@package"\}} &\smallcode{\cs\def\cs\knowledgepackagemode\texttt\{\kl{paper}\texttt\}} \end{tabular}\\ The idea is that this can be used in automatic compilation scripts. For instance, using in a terminal: -\begin{code}[12cm] +\begin{CODE}[12cm] \smallcode{\texttt{pdflatex} \quotesymbol\cs\def\cs\knowledgepackagemode% \texttt\{\kl{electronic}\texttt\}\cs\input\texttt\{file.tex\texttt\}\quotesymbol} -\end{code} +\end{CODE} \noindent would result in compiling `\texttt{file.tex}' using "knowledge@@package" in "electronic mode". The following primitives are available to the user for "writing mode"-sensitive configuration: -\begin{code}[11.4cm] +\begin{CODE}[11.4cm] \AP \csintro\IfKnowledgePaperModeTF\texttt\{true code\texttt\}\texttt\{false code\texttt\}\\ \AP @@ -1210,7 +1214,7 @@ The following primitives are available to the user for "writing mode"-sensitive \csintro{\IfKnowledgeCompositionModeTF}\texttt\{true code\texttt\}\texttt\{false code\texttt\}\\ \AP \csintro{\ ifKnowledgeCompositionMode} true code [\cs{\ else} false code] \cs{\ fi} -\end{code} +\end{CODE} \subsubsection{Automatic loading of other packages} @@ -1222,14 +1226,14 @@ For the moment, the packages that are concerned are \kl(option){hyperref}, For activating these functionalities, it is sufficient, either to load the package \emph{before} the "knowledge@@package" package, or to name it explicitly as an "option@package option" for "knowledge@@package". Loading separately the package is convenient for setting options for it. For instance, a typical preamble may look like: -\begin{code}[7cm] +\begin{CODE}[7cm] \cs\documentclass\{article\}\\ %\cs\usepackage[utf8]\{inputenc\}\\ %\cs\usepackage[T1]\{fontenc\}\\ \cs\usepackage[svgnames]\{\kl(package){xcolor}\}\\ \cs\usepackage[\texttt{draft}]\{\kl(package){hyperref}\}\\ \cs\usepackage[\kl(package){makeidx}]\{"knowledge@@package"\} -\end{code}\noindent +\end{CODE}\noindent Such a sequence will activate the "knowledge@@package" package using the features related to \kl(package){xcolor} configured with \texttt{svgnames} option, to \kl(package){hyperref} configured with \texttt{draft} option, and to \kl(package){makeidx} with its standard configuration. @@ -1324,13 +1328,13 @@ The second one is the ""`\vbar'-notation""\footnote{% Detecting the end of the line requires to change the catcode of the end of line character; this is not robust for being used in an argument or a macro. }: -\begin{code}[10cm] +\begin{CODE}[10cm] \csreintro\knowledge\{\kl[\knowledge directives]{directives}\}\\ \indent~~~~\klbn|~\kl[\knowledge knowledge name]{knowledge name}@\kl[\knowledge optional scope]{optional scope}\\ \indent~~~~\klbn|~\kl[\knowledge synonyms]{synonym 1}@\kl[\knowledge optional scope]{optional scope}\\ \indent~~~~\klbn|~\kl[\knowledge synonyms]{synonym 2}@\kl[\knowledge optional scope]{optional scope}\\ \indent~~~~~~~~$\cdots$ -\end{code} +\end{CODE} \AP The \intro[\knowledge knowledge name]{knowledge name} as well as the \intro[\knowledge synonyms]{synonyms} are plain text strings describing the knowledge. It may contain any combination of symbols, including accents or special characters as long as it well bracketted. This string will be used to fetch the \kl{knowledge}. Note (and this is a standard \kl{tex} behavior) that several consecutive spaces is the same as one or a line feed. @@ -1424,12 +1428,12 @@ yield the corresponding standard \TeX{} spacing features in math mode, This directive is often bypassed by the use of the \kl[\knowledge optional argument]{optional argument} of \cs{\knowledge} defining synonyms or the \kl{synonym} directive. \itemAP[\intro{synonym}] defines the knowledge as a link to the previously defined knowledge (in fact, the most recently defined that was not using \kl{synonym}). For instance -\begin{code}[11cm] +\begin{CODE}[11cm] \cs\knowledge\{Leslie Lamport\}\\ \indent~~~~~\{\kl{ref=}\{https://fr.wikipedia.org/wiki/Leslie\_Lamport\}\}\\ \cs\knowledge\{L. Lamport\}\{\kl{synonym}\}\\ \cs\knowledge\{Lamport\}\{\kl{synonym}\} -\end{code} +\end{CODE} \noindent results in the two subsequent \kl{knowledge names} to point to the first one. \itemAP[\intro{style=}\textmd{\{knowledge style\}}] will adopt the styling option of the \kl{knowledge style}. Surrounding braces can be omitted if there are no commas. @@ -1480,7 +1484,7 @@ sequence of directives are used. \intro{Macro directives} are here for simplifyi After execution of the command, `name' becomes a \kl[\knowledge directives]{directive} usable in \cs{\knowledge} commands, that amounts to execute the comma separated list `directives'. The newly created \kl[\knowledge directives]{directive} may receive a value, that is accessible as \texttt{\#1} in `directives'. By default, it does not allow the redefinition of a directive. This can be forced using the optional \texttt*. The `optional parameter' gives a default value. For instance: -\begin{code} +\begin{CODE} \cs\knowledgedirective\{highlight\}[brown]\{\kl{color=}\{\#1\},\kl{emphasize},\kl{md}\}\\{} "[...]"\\{} \cs\knowledge\{notion A\}\{highlight\}\\ @@ -1489,7 +1493,7 @@ a default value. For instance: \cs\knowledge\{important notion D\}\{highlight=red\}\\{} "[...]"\\ We shall now see \cs\kl\{notion A\}, \cs\kl\{notion B\}, \cs\kl\{notion C\}, as well as the \cs\kl\{important notion D\}. -\end{code} +\end{CODE} \noindent yields \begin{PDFoutput} @@ -1583,7 +1587,7 @@ notations for the \cs{\kl} and \cs{\intro} macros. Possible syntaxes are as foll \itemAP[\smallcode{\klqn"text\klqn"}]\phantomintro{"..."}% uses the "knowledge" pointed to by `text'. Equivalent to~\texttt{\cs\kl\{text\}}. \itemAP[\smallcode{\klqn"text\klqn@knowledge\klqn"}]\phantomintro{"...@..."}% - uses the "knowledge" pointed to by `knowledge to display `text'. Equivalent to~\texttt{\cs\kl[knowledge]\{text\}}. + uses the "knowledge" pointed to by `knowledge' to display `text'. Equivalent to~\texttt{\cs\kl[knowledge]\{text\}}. \itemAP[\smallcode{\klqn"text\klqn{@@}scope\klqn"}]\phantomintro{"...@@..."}% uses the "knowledge" pointed to by `text' in "scope" `scope' to display `text'. Equivalent to~\texttt{\cs\kl(scope)\{text\}}. \itemAP[\smallcode{\klqn"text\klqn@knowledge\klqn@scope\klqn"}]\phantomintro{"...@...@..."}% @@ -1611,9 +1615,9 @@ It can also be activated while loading the package. \AP It is sometimes the case that some packages do use the quote symbol, usually in some environment (this is the case of the "tikzcd@@env" environment). The "knowledge@@package" package can be configured to deactivate always the "quotation notation" when entering the environment. This is obtained using the "configuration option" ""protect quotation="" followed by a list of environments to be protected: -\begin{code}[12cm] +\begin{CODE}[12cm] \cs\knowledgeconfigure\{"protect quotation="\{env1,env2,\dots\}\} -\end{code} +\end{CODE} Note that the braces surrounding the list of environments can be omitted if the list contains only one item. There are nevertheless some situations in which one would prefer to use the original \cs{\kl} notation: @@ -1625,7 +1629,8 @@ There are nevertheless some situations in which one would prefer to use the orig -\subsubsection{\kl{Variants of \cs{\kl}}} +\subsubsection{Variants} + Several variants of the \cs\kl-command are defined by default. The syntax for their use is the same (including "scopes", \dots). The following variants are linked to the "autoref" directive: \begin{itemize} @@ -1640,7 +1645,7 @@ The following variants are linked to the "autoref" directive: following the semantics of the corresponding functions in the "cleveref@@package" package (see \kCref*"cleveref@@option"). \end{itemize} -\subsubsection{Defining your own \kl{variants of \cs{\kl}}} +\subsubsection{Defining your own variants} \label{subsubsection:variants} \phantomintro{variant of \cs{\kl}}% It may happen for several reasons that we may want to define new variants of the \cs{\kl} macros, that essentially perform the same task, but are configured differently. Typical examples may be: @@ -1690,7 +1695,7 @@ in which the ""stared sequence@@variant"" is of the form `\cs{variant1}*\cs{vari This sequence is declared to reduce to \cs{\variant}. For instance, \smallcode{\cs{\knowledgevariantmodifier}\{\cs{\intro*}\cs\kl\}\cs\intro} declares `\cs{\intro}*\cs{\kl}' to reduce to `\cs{\intro}'. -\subsubsection{Examples of \kl{variants of \cs{\kl}}} +\subsubsection{Examples of \kl{variants}} The best way for introducing new variants is to look at examples. We provide two of them now. the first one is the configuration of the \cs{\kl} and \cs{\intro} commands as defined in the "package@knowledge@package". @@ -1698,7 +1703,7 @@ The second one is the code used in this documentation for displaying macros, def and \cs{\csintro}. \paragraph{The configuration of \cs{\kl} and \cs{\intro}} It is also interesting to see this code since it gives more ideas on how to modify the standard behaviour of these commands correctly. -\begin{code} +\begin{CODE} \cs\knowledgestyle\{autoref link\}\{"autoref link"\}\par \cs\knowledgestyle\{autoref target\}\{"autoref target"\}\par \cs\knowledgestyle\{invisible\}\{"invisible"\}\par @@ -1717,7 +1722,7 @@ and \cs{\csintro}. ~~~~"style directive=@@variant" "intro style@intro style="\par \}\par \cs\knowledgevariantmodifier\{\cs{\intro*}\cs\kl\}\cs\intro -\end{code} +\end{CODE} Note that \cs{\reintro} and \cs{\phantomintro} are defined using similar code. \paragraph{Displaying control sequences} @@ -1734,7 +1739,7 @@ following semantics: then \smallcode{\cs\cs\{\cs[\ucommand]\command\}} simply displays \cs[\ucommand]\command\ in black, \item no \cs{\knowledge} command is necessary, and no warning is issued if a command is unknown. \end{itemize} -\begin{code} +\begin{CODE} \cs\knowledgestyle\{cs\}\par ~~~~\{"detokenize","remove space","typewriter","up","md","color="NavyBlue\}\par \cs\knowledgestyle\{cs unknown\}\par @@ -1761,7 +1766,7 @@ following semantics: \}\par \cs\knowledgevariantmodifier\{\cs{\intro*}\cs\cs\}\cs\csintro\par \cs\knowledgevariantmodifier\{\cs\csintro*\cs\cs\}\cs\csintro\par -\end{code} +\end{CODE} Several things can be noted about this code: \begin{asparaitem} \item the "directives" "detokenize" and "remove space" prevent the execution of the argument, and instead display its name, this is important since the argument is a control sequence, @@ -1801,34 +1806,34 @@ the "quotation notation": It works also for \cs{\intro} and with double quotes. Another option is to import the scope locally, using: -\begin{code}[10cm] +\begin{CODE}[10cm] \cs\knowledgeimport\{\textit{scope name 1,scope name 2,}\dots\} -\end{code} +\end{CODE} After this command, the knowledges will be searched automatically in the imported scopes. The import stops at the end of the current scoping environment. \paragraph{Attaching knowledge to a given scope} This can be done directly using the "scope=" "directive", for instance in: -\begin{code}[12cm] +\begin{CODE}[12cm] \cs\knowledge\{knowledge\}\{"scope="\textit{scope name},\textit{directives}\} -\end{code} +\end{CODE} \noindent or, this is obtained usint the "`\vbar'-notation" using `\klbn@'~: - \begin{code}[8cm] + \begin{CODE}[8cm] \cs\knowledge\{\textit{directives}\}\\ \indent~~~\klbn|~~knowledge\klbn@\textit{scope name 1}\\ \indent~~~\klbn|~~synonym\klbn@\textit{scope name 2}\\ \indent~~~$\vdots$~~~~~~~~~~~~$\vdots$ - \end{code} + \end{CODE} \AP The other possibility is to define a knowledge inside a "scope@@env" environment: -\begin{code}[8cm] +\begin{CODE}[8cm] \cs\begin\{"scope@@env"\}\cs\label\{label\}\\ \indent\quad\cs\knowledge\{knowledge 1\}\{\textit{directives}\}\\ \indent\qquad$\vdots$\\ \cs\end\{"scope@@env"\} -\end{code} +\end{CODE} \noindent In such a code, the knowledge defined is automatically visible in the environment, and from outside, using the scope name \texttt{label}. Indeed, the \cs{\label} is overloaded for doing automatically a \cs{\knowledgescope} command. @@ -1839,17 +1844,17 @@ In fact, it is possible to do even more: other environments can be defined to be \subsubsection{Scoping by examples} ""Explicit scoping"" consists in attaching a precise scope name to a "knowledge" using the "scope=" "directive": -\begin{code} +\begin{CODE} \cs\knowledge\{thing\}\{"scope="s1,"color="red\}\\ \cs\knowledge\{thing\}\{"scope="s2,"color="green\}\\ \\ Here, \klqn"thing\klqn" and \cs\kl\{thing\} are unknown.\\ But \klqn"thing\klqn{@@}s1\klqn" and \cs\kl(s1)\{thing\} are in red,\\ and \klqn"thing\klqn{@@}s2\klqn" and \cs\kl(s2)\{thing\} are in green. -\end{code} +\end{CODE} The "`\vbar'-notation" can also be used for "explicit scoping". This is convenient, in particular for having synonyms in different scopes: -\begin{code} +\begin{CODE} \cs\knowledge\{"color="red\}\\ \indent~~\klbn|~~abelian group\\ \indent~~\klbn|~~abelian groups\\ @@ -1863,11 +1868,11 @@ and correspond to \klqn"abelian groups\klqn".\\ \cs\begin\{"scope@@env"\}\cs\knowledgeimport\{abelian\}\\ \indent~~All \klqn"groups\klqn" here are abelian.\\ \cs\end\{"scope@@env"\} -\end{code} +\end{CODE} "Scopes" can also be attached to areas in the code. It is convenient to use the usual \cs{\label} command to name them (though, in practive, two different naming spaces are used). -\begin{code} +\begin{CODE} \textcolor{gray}{\% We declare first in the preamble the environments that can have}\\ \textcolor{gray}{\% knowledges attached to them.}\\ \cs\knowledgeconfigureenvironment\{theorem,lemma,proof\}\{\}\\ @@ -1883,7 +1888,7 @@ But \kl{"}rabbits\kl[quotation notation]{@@}theorem:main\kl{"} point to Theorem \cs\begin\{proof\}\cs\knowledgeimport\{theorem:main\}\\ \indent~~ Now, \kl"rabbit\kl" is hyperlinked to Theorem~\cs\ref\{theorem:main\}. \cs\end\{proof\} -\end{code} +\end{CODE} \subsubsection{What is the structure of \kl{scopes} in a document} @@ -1891,13 +1896,13 @@ To start with, one needs to understand what are the possible \kl{scopes}. Scopes \begin{itemize} \itemAP By default, all the body of the document belongs to a \kl{scope} called `\texttt{document}'. The user can open new scopes using the \intro(env){scope} environment: - \begin{code}[10cm] + \begin{CODE}[10cm] \cs\begin\{\kl(env){scope}\}\par ~~\cs\knowledge\{local notion\}\{\kl{color=}green\}\par ~~Here is a \cs\kl\{local notion\} that appears in green.\par \cs\end\{\kl(env){scope}\}\\ But here the \cs\kl\{local notion\} is undefined. - \end{code} + \end{CODE} Note that scoping is independent from the grouping mechanism of \LaTeX. \AP The user can also declare environments such as \texttt{lemma}, \texttt{theorem}, @@ -1915,7 +1920,7 @@ In general, when a \cs{\knowledge} command is used, the system tries to figure o \item This default behavior can be modified using the \kl{scope=} directive. The \kl{scope=} directive can be followed with a scope level, such as `section', `subsection', 'chapter' or `itemize' (in particular in combination with the \kl{scope option}), that will be looked for in the current context and will receive the \kl{knowledge}. The \kl[\knowledge directives]{directive} can also be followed by a label name, and the active scope at the moment of this label will be used. The following code (that requires the "scope option" for being functional) should be self explanatory: - \begin{code}[11.5cm] + \begin{CODE}[11.5cm] \cs\section\{First section\}\par\noindent \cs\label\{section:first\}\par\noindent \cs\knowledge\{one\}\{\kl{scope=}section,\kl{color=}green\}\par\noindent @@ -1930,14 +1935,14 @@ The following code (that requires the "scope option" for being functional) shoul Here neither \cs\kl\{one\} nor \cs\kl\{two\} is defined. However, I can still use them using \cs\kl(section:first)\{one\} and \cs\kl(some label)\{two\} (or \kl"one@@section:first\kl" and \kl"two@@some label\kl", or using the \cs{\knowledgeimport}\{section:first\}). - \end{code} + \end{CODE} \end{itemize} \subsubsection{Naming "scopes": the \cs{\knowledgeimport}, \cs{\knowledgescope} and \cs{label} commands } It is often the case in a text, that one has to locally break the nesting structure of a document, and refer to a object local in an environment. For instance, a comment may refer to a variables/concept that has been locally used in the proof. The "knowledge@@package" provides suitable mechanisms for complex referencing of scopes. Let us explain this through an example: -\begin{code} +\begin{CODE} \textcolor{gray}{\% We declare first in the preamble the environments that use knowledge.}\\ \cs\knowledgeconfigureenvironment\{definition\}\{knowledge=attracts\}\par\indent "[...]"\\ @@ -1946,7 +1951,7 @@ It is often the case in a text, that one has to locally break the nesting struct \indent~~\cs\knowledge\{something\}\{notion\}\\ \indent~~Here, \cs\intro\{something\} is a notion internal to the definition. \cs\end\{definition\} -\end{code} +\end{CODE} Note here that what is important is the location of the \cs\knowledge\ command, irrespective of the location ofthe \cs\intro\ command. \AP The \cs\label\ command is used to name the "scope". In fact, the real command is @@ -1966,7 +1971,7 @@ The result is that the \kl{knowledges} in the \kl{scope} identified by the label accessible until the closure of the current \kl{scope}. For instance: -\begin{code}[9cm] +\begin{CODE}[9cm] \cs\knowledgeconfigureenvironment\{theorem,proof\}\{\}\par\indent "[...]"\par\indent \cs\begin\{theorem\}\cs\label\{theorem:1\}\par\noindent @@ -1980,7 +1985,7 @@ Here \$\cs\kl\verb|\alpha|\$ is unknown.\par\noindent ~~\cs\knowledgeimport\{theorem:1\}\par\noindent ~~But now \$\cs\kl\verb|\alpha|\$ points to its definition.\par\noindent \cs\end\{proof\} -\end{code} +\end{CODE} @@ -1994,10 +1999,10 @@ Here \$\cs\kl\verb|\alpha|\$ is unknown.\par\noindent \smallcode{\csintro\knowledgeconfigureenvironment\{environments\}\{"scope directives"\}} \end{center} For instance: -\begin{code}[12cm] +\begin{CODE}[12cm] \cs\knowledgeconfigureenvironment \{lemma,theorem,fact,proof\}\par ~~~~~~~~\{knowledge=attracts\} -\end{code} +\end{CODE} \noindent will induce the corresponding environments to have internal knowledges. @@ -2095,13 +2100,13 @@ Exporting means outputting in the \kl{export file} some code that it is sufficie When this file is used, using for instance an \cs{\input} command, or simply copied and paste in another document, then the knowledge `Pythagorean theorem' becomes available, and points to the proper file. Hence in another document, we can use: -\begin{code} +\begin{CODE} \cs\knowledgeimport\{lesson1\} -\end{code} +\end{CODE} that would make immediately available all the knowledge attached to \kl{scope} `lesson1'. Another possibility if this should be linked only once is to use it directly in the text: -\begin{code} +\begin{CODE} -\end{code} +\end{CODE} It is useful to be able to 1) export some of the knowledges defined in a document, and 2) import them in another document. For the moment this feature is not coded. \kl{to be done} @@ -2145,17 +2150,17 @@ the options of the "xcolor@@package" package \label{subsection:hyperref option} \subsubsubsection{Activating the \kl{hyperref option}} - -The \intro{hyperref option} loads the \intro(package){hyperref} -and triggers a certain number of link-related features. -This is done either by the command: -\marginpar{% + \marginpar{% \begin{hint} The "hyperref@@package" surrounds by default links by boxes that are graphically heavy (this are visible in some viewers, and not in some others): this is automatically deactivated when loading - the "knowledge@@package" package. Such automatic behavior can ba avoided using the \kl{no patch} + the "knowledge@@package" package. Such automatic behaviour can be avoided using the \kl{no patch} option at loading. \end{hint}} +The \intro{hyperref option} loads the \intro(package){hyperref} +and triggers a certain number of link-related features. +This is done either by the command: + % \begin{center} \smallcode{% @@ -2213,7 +2218,7 @@ A typical use looks as follows: executed twice, once in the \kl{table of contents}, and once in the document itself. \end{hint}} -\begin{code} +\begin{CODE} \cs\knowledge\{house\}[Houses\vbar houses]\{\kl{autoref}\}\\~ "[...]"\\ \cs\begin\{document\}\\~ @@ -2224,7 +2229,7 @@ In this document, we will see the very important notion of \kl{"}houses\kl{"}.\\ Let us define a \kl{""}house\kl{""} to be a building that functions as a home.\\~ "[...]"\\ \cs\end\{document\} -\end{code}\noindent +\end{CODE}\noindent yields \begin{PDFoutput} \knowledge{house}[Houses| houses]{autoref}% @@ -2239,7 +2244,7 @@ Let us define a \intro{house} to be a building that functions as a home. \AP The variant \csintro{\intro*} makes the next \cs{\kl} command behave like \cs{\intro}. This is useful in particular in math mode: -\begin{code} +\begin{CODE} \cs\newcommand\kl[@token]\monoid\{\cs\kl[\kl[@token]\monoid]\{\cs\mathcal M\}\}\\ \cs\knowledge\kl[@token]\monoid\{autoref\}\\~ "[...]"\\ @@ -2247,7 +2252,7 @@ The variant \csintro{\intro*} makes the next \cs{\kl} command behave like \cs{\i Let now \$\cs{\intro*}\kl[@token]\monoid\$ be a monoid.\\~ "[...]"\\ Remember now who is \$\kl[@token]\monoid\$. -\end{code} +\end{CODE} % \marginpar{\begin{hint} This does not work in \kl{align*} and similar environments. Section~\ref{section:amsmath questions} gives some solutions. \end{hint}} @@ -2297,9 +2302,9 @@ there are new directives: \end{description} See the use of \cs{\knowledgesetvariant} for examples of configuration. %Hence: -%\begin{code} +%\begin{CODE} %%test -%\end{code} +%\end{CODE} \subsubsubsection{The \kl{autorefhere} \kl[\knowledge directives]{directive}} @@ -2340,7 +2345,7 @@ We offer here new commands for helping using this feature: Usually putting an \cs{\AP} (a standard command of the "hyperref@@package") at the beginning of every paragraph, and replacing \cs{\item} by \cs{\itemAP} in itemize-like environments is most of the time good and safe option. For instance: -\begin{code}[12.5cm] +\begin{CODE}[12.5cm] \cs\AP\\ In order to describe what is a \cs\kl\{monoid\}, let us us first define a \cs\intro\{product\} to be an associative binary operator, @@ -2351,7 +2356,7 @@ and a \cs\intro\{unit\} to be "[...]" \cs\itemAP[A \cs\intro\{semigroup\}] is a set equipped with a \cs\kl\{product\}.\\ \cs\itemAP[A \cs\intro\{monoid\}] is a \cs\kl\{semigroup\} that has a \cs\kl\{unit\}.\\ \cs\end\{description\} -\end{code} +\end{CODE} \noindent yields \begin{PDFoutput}[10cm] @@ -2423,22 +2428,22 @@ The following \kl[\knowledge directives]{directives} are to be used: \itemAP[\intro{index key=}] takes as argument the \kl{index key}: a text that is used for identifying the \kl{index entry} (usually an accent free version of it). You can use `!' in it, as long as it does not clash with "index=" in order to avoid clashes. \itemAP[\intro{index parent key=}] makes the \kl{index entry} be a subentry of the given \kl{main index entry} (a replacement of `!'). Once more, it should not clash with "index=" and "index key=". \itemAP[\intro{index style=}] is followed by a token (without the scape character) that will be used for displaying the number (e.g. "index style="\texttt{textbf}). Usually, this is to be used in order to typeset in a particular manner the knowledges in the index when introduced. Thus, by default, the \cs{\intro}, \cs{\reintro} and \cs{\phantomintro} command use the command \csintro{\knowledgeIntroIndexStyle}. Hence, you can use for instance: -\begin{code}[8cm] +\begin{CODE}[8cm] \cs\def\cs\knowledgeIntroIndexStyle\#1\{\cs\fbox\{\#1\}\} -\end{code} +\end{CODE} \itemAP[\intro{index name=}] requires to activate "imakeidx@@option", and allows to choose the index name in case of multiple indexes. \end{description} \AP The "directive" ""no index"", deactivates the index feature for a knowledge. This is meant to be used in a "style". For instance -\begin{code} +\begin{CODE} \cs\knowledgedirective\{standard\}\par\noindent~~~~~ \{"autoref","style="standard,"intro style="intro standard\}\\ \cs\knowledgestyle\{standard\}\{"no index"\}\\ \cs\knowledgestyle\{intro standard\}\{"emphasize"\}\\ \cs\knowledge\{test\}\{standard,"index=" test\} -\end{code}\noindent +\end{CODE}\noindent result in that the introductions of `test' will be gathered in the index, but not the other uses. \subsubsection{The \kl{cleveref option}} @@ -2450,10 +2455,10 @@ The \intro(option){cleveref} option loads the "cleveref@@package" package and gi These commands are variants of \cs\kl\ and hence are subject to the same syntax. For instance, -\begin{code} +\begin{CODE} \kl{"}Anchor points\kl{"} have been described in~\cs\kCref\{anchor point\},\\ Page \cs\kpageref\{anchor point\}. -\end{code}\noindent +\end{CODE}\noindent would typeset as \begin{PDFoutput}[10cm] "Anchor points" have been introduced in~\kCref{anchor point}, Page \kpageref{anchor point}. @@ -2489,21 +2494,21 @@ In the subsequent sections, some more explanations are given covering the case o \paragraph*{The use through an example}\AP Let us define the $\intro*\floor{x}$ command representing the floor rounding of~$x$, and use it in $\floor{1.5}$. This is achieved by first defining a macro \cs\floor\ (for instance in the preamble): -\begin{code} +\begin{CODE} \cs\knowledgenewrobustcmd\cs\floor[1]\{\cs\cmdkl\{\cs\lfloor\}\#1\cs\cmdkl\{\cs\rfloor\}\} -\end{code}\noindent +\end{CODE}\noindent and then use it in a natural way: -\begin{code} +\begin{CODE} \cs\AP\ Let us define the \$\cs\intro*\cs\floor\ x\$ command representing the floor rounding of \$x\$, and use it in \$\cs\floor\{1.5\}\$. -\end{code}\noindent +\end{CODE}\noindent There, we used a special command, \cs\knowledgenewrobustcmd, which is similar to the \cs\newrobustcmd\footnote{It has the same syntax as \cs\newcommand\ and should always be used instead as far as a good reason for not to do it is given.} and at the same time introduces a "knowledge" for the macro name (defined using the directive "automatic in command"). It sets the contexts such that \cs\cmdkl\ implements the code for using this "knowledge". It is somehow similar to: -\begin{code} +\begin{CODE} \cs\newrobustcmd\cs\floor[1]\{\cs\kl[\cs\floor]\{\cs\lfloor\}\#1\cs\kl[\cs\floor]\{\cs\rfloor\}\}\\ \cs\knowledge\{\cs\floor\}\{"automatic in command"\} -\end{code}\noindent +\end{CODE}\noindent but is shorter to write and also corrects some bugs of this direct implementation\footnote{For instance, with this wrong implementation, \smallcode{\cs\intro*\cs\floor\ x} would display in \cs\intro\ aspect the `\cs\lfloor'\ symbol but not the `\cs\rfloor' one.}. @@ -2523,11 +2528,11 @@ The behavior of these commands is identical to the original ones, and furthemore \AP The commands \begin{quote} - \csintro\knowledgerenewcommand,\\ - \csintro\knowledgenewrobustcmd, and \\ - \csintro\knowledgenewcommand\footnote{You should always prefer \cs\knowledgenewrobustcmd\ instead. It is just here for completeness.}, + \csintro\knowledgenewrobustcmd, [ + \csintro\knowledgerenewcommand, and \\ + \csintro\knowledgenewcommand\footnote{These commands are here for completeness. You should always prefer \cs\knowledgenewrobustcmd\ instead, in particular to avoid problems in sectioning commands.}], \end{quote} -correspond to \cs\newcommand, \cs\renewcommand, and \cs\newrobustcmd\ (from "etoolbox@@package") respectively. +correspond to \cs\newrobustcmd (from "etoolbox@@package") , \cs\newcommand, \cs\renewcommand respectively. \AP The commands \begin{quote} @@ -2588,20 +2593,20 @@ gets to be evaluated as An example of use of this technique is if we want "knowledges" aware of the parameters of a macro. Imagine that you use the norms $1$ and $2$ of a function: -\begin{code} +\begin{CODE} \cs\newrobustcmd\cs\norm[2]\par ~~~~\{\cs\withkl\{\cs\kl[\cs\norm\{\#1\}]\}\{\cs\cmdkl\{\cs\|\}\#2\cs\cmdkl\{\cs\|\}\_\{\cs\cmdkl\{\#1\}\}\}\}\\ \cs\knowledge\{\cs\norm\{1\}\}\{notion\}\\ \cs\knowledge\{\cs\norm\{2\}\}\{notion\} -\end{code}\noindent +\end{CODE}\noindent Now, the norm $1$ and the norm $2$ can be defined in different places since "knowledge" is specific to each case. -\begin{code} +\begin{CODE} \cs\AP\ The norm~\$1\$ of a function~\$f\$ is denoted \$\cs\intro*\cs\norm1f\$.\\ "[...]"\\ \cs\AP\ The norm~\$2\$ of a function~\$f\$ is denoted \$\cs\intro*\cs\norm2f\$.\\ "[...]"\\ Here, \$\cs\norm 1g\$ and \$\cs\norm2h\$ link to the proper place, while\\\$\cs\norm3g\$ is an undefined knowledge. -\end{code} +\end{CODE} \subsubsection{Defining macros for math: the "mathcommand@@package" package} @@ -2620,27 +2625,27 @@ We shall use it in the advanced examples below. It allows: \item to define/redefine commands to be used in math mode only. This allows for instance to use the macro \cs\c\ for producing as usual a cedilla in text mode, and at the same time some variable $\mathbf c$ in math mode. This is achieved using for instance: \smallcode{\cs\renewmathcommand\cs\c\{\cs\mathbf\{c\}\}}. \item When redefining a command, it automatically stores the original command \cs\macro\ as \cs\LaTeXmacro. So for instance, if one wants to introduce the constant~$\pi$ in a document and have it linked, one can use: - \begin{code} + \begin{CODE} \cs\renewmathcommand\cs\pi\{\cs\kl[\cs\pi]\{\cs\LaTeXpi\}\}\\ \cs\knowledge\cs\pi\{notion\}\\ "[...]"\\ \cs\AP\ Let \$\cs{\intro*}\cs\pi=3.1415\$.\\ "[...]"\\ Now \$\cs\pi\$ points to the above sentence. - \end{code} + \end{CODE} This code works because a different name \cs\LaTeXpi\ stores the original macro. Using~\cs\pi\ instead would yield an infinite loop. Even better is to use the knowledge-aware version: - \begin{code} + \begin{CODE} \cs\knowledgerenewmathcommand\cs\pi\{\cs\cmdkl\{\cs\LaTeXpi\}\} - \end{code} + \end{CODE} \item The package also gives access to the exponents and indices as well as primes that follow a command (see the documentation). \item It also has some facilities for disabling \LaTeX\ commands and provide suggestions of replacement (useful for remembering the macros and working with colleagues). \item Finally, it offers some commodity for redefining many variables in one command. E.g. for defining \cs\calA, \cs\calB,\dots to be shortcuts for \smallcode{\cs\cal\{A\}}, \smallcode{\cs\cal\{B\}}, \dots: - \begin{code} + \begin{CODE} \cs\LoopCommands\{ABCDEFGHIJKLMNOPQRSTUVWXYZ\}[cal\#1]\par ~~~~\quad\{\cs\newmathcommand\#2\{\cs\cal\{\#1\}\}\} - \end{code} + \end{CODE} \end{itemize} \subsubsection{Mathematical objects that are singly introduced} @@ -2661,24 +2666,24 @@ Five points have to be kept in mind: \item The surrounding typography may be broken when using the command \cs{\kl}, or \cs\cmdkl\ (if someone knows how to solve that, please contact me). Commands such as \cs\mathrel\ should be used to recover it. \end{itemize} These five points are illustrated in the following code: -\begin{code} +\begin{CODE} \cs\knowledgenewrobustcmd\cs\comp\{\cs\mathrel\{\cs\cmdkl\{\cs\circ\}\}\}\\ "[...]"\\ \cs\AP\ Composition is denoted \$\cs{\intro*}\cs\comp\$.\\ "[...]"\\ Now, each use of \$\cs\comp\$ points to its introduction. -\end{code} +\end{CODE} Two variation may be comfortable to use. \paragraph{Disabling commands} When writing a paper, in particular with coauthors, one may be tempted to not always use the macros designed for each case. For helping to remember the macro, one can use instead (using the "mathcommand@@package" package): -\begin{code} +\begin{CODE} \csintro\disablecommand\cs\circ\\ \csintro\suggestcommand\cs\circ\{Use instead \cs\comp\ for function composition.\}\\ \cs\knowledgenewrobustcmd\cs\comp\{\cs\cmdkl\{\cs\LaTeXcirc\}\}\\ -\end{code} +\end{CODE} \noindent The result is that if one uses \cs\circ\ in the code, an error will be issued, and \cs\comp\ will be suggested as a replacement. Note that more than one suggestions can be attached to the macro (if several macros use the symbol~\cs\comp\ with different meanings). Note also that in the definition of \cs\comp, \cs\LaTeXcirc\ is used instead of~\cs\circ. Indeed, \cs\circ\ has been deactivated, but~\cs\LaTeXcirc\ gives access to its original meaning. @@ -2686,13 +2691,13 @@ but~\cs\LaTeXcirc\ gives access to its original meaning. \paragraph{Redefining the original \TeX\ macro} Another situation is that one would like to use the \cs\circ\ control sequence for accessing our function instead of \cs\comp\ (simply because this is more convenient and easy to remember, and we know in advance that no confusion may arise). In this case, the "mathcommand@@package" package can also be of some help: -\begin{code} +\begin{CODE} \cs\knowledgerenewmathcommand\cs\circ\{\cs\mathrel\{\cs\cmdkl\{\cs\LaTeXcirc\}\}\}\\ "[...]"\\ \cs\AP\ Let \$g\cs{\intro*}\cs\circ\ f\$ denote the composition of functions.\\ "[...]"\\ Now, each use of \$\cs\circ\$ points to its introduction. -\end{code} +\end{CODE} \noindent The effect of \cs\knowledgerenewmathcommand\ is that it sets~\cs\LaTeXcirc\ to have the same effect as the original \cs\circ\ command, and then redefines~\cs\circ. @@ -2705,9 +2710,9 @@ This section is not yet written. We enter now a more advanced situation. We want to track all the variables in a mathematic document... the first thing to do is to give access to the "knowledge@@package" package to the scope of the document. The easiest way to do that is to declare in the preamble what are the environments that we want to use. -\begin{code} +\begin{CODE} \cs\knowledgeconfigureenvironment\{theorem,lemma,proof\}\{\}\par\noindent -\end{code}} +\end{CODE}} The "knowledge@@package" package offers several tools for dealing with mathematics. It is mostly still experimental. @@ -2741,7 +2746,7 @@ The behavior of the "notion" directive is to activate "autoref", and to configur \end{itemize} A typical document using notion could start by the following commands: -\begin{code} +\begin{CODE} \cs\documentclass\{article\}\\ \cs\usepackage\{\kl(package){xcolor}\}\\ \cs\usepackage\{\kl(package){hyperref}\}\\ @@ -2749,7 +2754,7 @@ A typical document using notion could start by the following commands: \cs\knowledgeconfigure\{"notion@@option"\}\\ "[...]"\\ \cs\knowledge\{some text\}\{notion\} -\end{code}\noindent +\end{CODE}\noindent Then the paper is displayed in a colorful way. @@ -2792,7 +2797,7 @@ The notation \kl{"..."} does not have this issue. \paragraph{The use of \cs{\kl} does not work in (e.g.) the table of content.} When the \kl{knowledge name} contains expandable macros, or accentuated letters, then these are not copied in the table of content as the exact same text, but are expanded/translated. Thus, when the table of content is displayed, the \cs{\kl} command complains of not knowing the \kl{knowledge}. For instance\footnote{with \texttt{\cs\usepackage[utf8]\{inputenc\}} and, for instance \texttt{\cs\usepackage[T1]\{fontenc\}} for the accents.}: \begin{center} -\begin{code}[11cm] +\begin{CODE}[11cm] \cs\newcommand\robustdisplay\Ltwo\{\cs\ensuremath\{L\^{}2\}\}\\ \cs\knowledge\{\robustdisplay\Ltwo-space\}[\robustdisplay\Ltwo-spaces]\{autoref\}\\ \cs\knowledge\{\'etale topology\}[\'Etale topology]\par @@ -2805,29 +2810,29 @@ The notation \kl{"..."} does not have this issue. \cs\section\{On the \cs\kl\{\'etale topology\}\}\\ {"[...]"}\\ \cs\end\{document\} -\end{code}\end{center}\noindent +\end{CODE}\end{center}\noindent will result in that both \kl{knowledges} are considered unknown in the table of contents. For the first one, this is due to the expansion of~\cs\Ltwo. For the second, this is due to an implicit translation of the accentuated letter into an internal sequence of commands (for instance `\'e' is translated into the internal sequence `\verb|\IeC {\'e}|'). Some solutions are as follows: \begin{itemize} \item Make the macros non-expandable, for instance using \cs{\newrobustcmd} (of the \kl(package){etoolbox} package) or \cs{\NewDocumentCommand} (of the \kl(package){xparse} package, with a different handling of arguments) instead of \cs{\newcommand}. Hence: -\begin{code} +\begin{CODE} \cs\newrobustcmd\robustdisplay\Ltwo\{\cs\ensuremath\{L\^{}2\}\} -\end{code}\noindent +\end{CODE}\noindent solves the first problem. \item Using an equivalent text that does not have the problem: - \begin{code} + \begin{CODE} \cs\knowledge\{$\backslash$'etale topology\}\{\kl{link=}\'etale topology\}\\ {"[...]"}\\ \cs\section\{On the \cs\kl\{$\backslash$'etale topology\}\} - \end{code} + \end{CODE} \item Both problems can be solved using synonyms/links that have no problem. For instance: - \begin{code} + \begin{CODE} \cs\knowledge\{Ltwo-space\}\{\kl{link=}\robustdisplay\Ltwo-space\}\\ \cs\knowledge\{etale topology\}\{\kl{link=}\'etale topology\}\\ {"[...]"}\\ \cs\section\{On \cs\kl[Ltwo-space]\{\robustdisplay\Ltwo-spaces\}\}\\ \cs\section\{On the \cs\kl[etale topology]\{étale topology\}\} - \end{code} + \end{CODE} \item Other solutions? None so far. I am trying to systematize the treatment of these problems. \end{itemize} @@ -2837,13 +2842,13 @@ Do not use \cs{\intro} in titles, but rather \cs{\reintro}. If you want the sect \begin{center} \begin{tabular}{ccc} %\hline -\begin{code}[5.5cm] +\begin{CODE}[5.5cm] \cs\section\{On \cs\intro\{topology\}\}\\ -\end{code}&& -\begin{code}[5.9cm] +\end{CODE}&& +\begin{CODE}[5.9cm] \cs\section\{On \cs{\reintro}\{topology\}\}\\ \cs{\phantomintro}\{topology\} -\end{code}\\ +\end{CODE}\\ \textit{Problematic code}&& \textit{A solution} \end{tabular} @@ -2861,18 +2866,18 @@ active when you do so, and \end{itemize} This can be done either explicitly using before each figure: -\begin{code}[8.5cm] +\begin{CODE}[8.5cm] \cs\knowledgeconfigure\{"quotation@@option"=false\} -\end{code} +\end{CODE} \noindent and after the figure: -\begin{code}[7cm] +\begin{CODE}[7cm] \cs\knowledgeconfigure\{"quotation@@option"\} -\end{code} +\end{CODE} Another possibility is to force some environment to deactivate systematically the "quotation notation" when used. For instance -\begin{code}[10cm] +\begin{CODE}[10cm] \cs\knowledgeconfigure\{"protect quotation="\{"tikzcd@@env"\}\} -\end{code}\noindent +\end{CODE}\noindent will deactivate the "quotation notation" in all the "tikzcd@@env" environments. \subsection{Problems with \kl(package){amsmath}} @@ -2886,18 +2891,18 @@ the incriminated environment using \cs\phantomsection, and then use \cs{\reintro \begin{center} \begin{tabular}{ccc} does not work&&works\\ - \begin{code}[5cm] + \begin{CODE}[5cm] \cs\begin\{\kl{align*}\}\\ \cs{\intro*}\texttt{\robustdisplay{\SomeCommand}}\\ \cs\end\{\kl{align*}\}\\ - \end{code} + \end{CODE} && - \begin{code}[5cm] + \begin{CODE}[5cm] \cs\phantomintro\texttt{\robustdisplay{\SomeCommand}}\\ \cs\begin\{\kl{align*}\}\\ \cs\reintro*\texttt{\robustdisplay{\SomeCommand}}\\ \cs\end\{\kl{align*}\} - \end{code} + \end{CODE} \end{tabular} \end{center} @@ -2912,19 +2917,19 @@ This happens in particular wen used in combination with the "complexity@@package The problem has to be resolved by hand. The two following solutions are quick hacks: \begin{center} \begin{tabular}{ccc} -\begin{code}[5.2cm] +\begin{CODE}[5.2cm] \cs\usepackage\{\kl(package){complexity}\}\\ \cs\let\cs\compAP\robustdisplay\AP\\ \cs\let\robustdisplay\AP\cs\undefined\\ \cs\usepackage"[...]"\{"knowledge@@package"\} -\end{code} +\end{CODE} && -\begin{code}[5.2cm] +\begin{CODE}[5.2cm] \cs\usepackage"[...]"\{"knowledge@@package"\}\\ \cs\let\cs\kAP\robustdisplay\AP\\ \cs\let\robustdisplay\AP\cs\undefined\\ \cs\usepackage\{\kl(package){complexity}\} -\end{code}\\ +\end{CODE}\\ for using \texttt{\robustdisplay\AP}from "knowledge@@package", && for using \texttt{\robustdisplay\AP}from "complexity@@package",\\ and \cs\compAP\ for "complexity@@package", @@ -2940,7 +2945,7 @@ It may happen that some hyperlinks generated by "knowledge@@package" are not bro at the end of lines. This is an issue with the \kl(package){hyperref} package. This happens in particular for files compiled by the "arXiv" system while the file on the local computer was not having any problem. A workaround is to use the \kl{breaklinks} option of \kl(package){hyperref}. If you need this for "arXiv", then you also have to force the use of \cs\pdflatex\ (because the \kl{breaklinks} option does not work if compiled via the ancestral sequence TEX$\rightarrow$DVI$\rightarrow$PS$\rightarrow$PDF). This can be obtained by adding \smallcode{\cs\pdfoutput=1} within the five first lines of the preamble. The preamble thus looks like: -\begin{code}[9cm] +\begin{CODE}[9cm] \cs\documentclass\{"[...]"\}\par\noindent \cs\pdfoutput=1\par\noindent "[...]"\par\noindent @@ -2948,13 +2953,13 @@ The preamble thus looks like: "[...]"\par\noindent \cs\usepackage\{\kl(package){knowledge}\}\par\noindent "[...]"\par\noindent -\end{code} +\end{CODE} \subsection{Display errors in pdf output, in particular "arXiv"} Again, try in the preamble: -\begin{code}[9cm] +\begin{CODE}[9cm] \cs\pdfoutput=1 -\end{code} +\end{CODE} \subsubsection{Red boxes around links} @@ -2964,21 +2969,21 @@ unless the "no patch" option is used when loading the package. When the "no patc \subsubsection{Incorrect color for links in "paper mode" (e.g. red in with \kl(package){acmart})} Some classes, like \kl(package){acmart}, change the default color of the hyperlinks of \kl(package){hyperref}. Since "knowledge@@package" does not apply any color to the links in "paper mode", this unexpected color appears. The black color of the "paper mode" can be forced by using: -\begin{code} +\begin{CODE} \cs\IfKnowledgePaperMode\\ \cs\knowledgestyle\{"kl@@style"\}\{"color="black\}\\ \cs\knowledgestyle\{"notion@@style"\}\{"color="black\}\\ \cs{\ fi} -\end{code} +\end{CODE} \subsubsection{Unexepected color in margin paragraph} This is a problem of the combination of the package "xcolor@@package" with \cs\marginpar: when a colored text gets to be broken into separated lines and the \cs\marginpar\ be inserted at this place, the colors leaks in to the margin text. It is independent of "knowledge@@package", but is more likely to occur when colors are often used. A correction is to force going the use of color black whenever inside a \cs\marginpar. For instance: -\begin{code} +\begin{CODE} \cs\let\cs\LaTeXmarginpar\cs\marginpar\\ \cs\def\cs\marginpar\#1\{\cs\LaTeXmarginpar\{\cs\textcolor\{black\}\{\#1\}\}\} -\end{code} +\end{CODE} \subsection{Problems with scope} @@ -2989,22 +2994,22 @@ The "scope option" of the package triggers some analysis of the code, and restra However, this is what does the environment "thebibliography@@env", yielding a scoping error. A simple hack to treat this situation: -\begin{code}[6cm] +\begin{CODE}[6cm] \cs\let\cs\section\cs\SUPERsection\\ \cs\begin\{"thebibliography@@env"\}\\ \cs\bibitem\dots\\ {}"[...]"\\ \cs\end\{"thebibliography@@env"\}\\ \cs\let\cs\section\cs\NEWsection -\end{code} +\end{CODE} The result is to revert to the original version of the macro \smallcode{\cs\section}, which does not make any structural test, and then reactivate the modified version of the command. Another solution is to reconfigure the environment "thebibliography@@env" using in the preamble: -\begin{code} +\begin{CODE} \cs\ScopeConfigure\{"thebibliography@@env"\}\par \hspace{3cm}\{push code=\cs\let\cs\section\cs\SUPERsection,\par \hspace{3cm}~pop code=\cs\let\cs\section\cs\NEWsection\} -\end{code} +\end{CODE} \subsection{Editors} @@ -3096,7 +3101,6 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr \item[\kl{italic=}] displays in italic \item[\kl{fbox}] Surround the text with a box. \item[\kl{md}] Removes boldface typesetting. -\item[\kl{notion}] %\item[\kl{import=}] (\kl{not implemented}) \item[\kl{index=}] Chooses the text to be displayed in the \kl{index=}. \item[\kl{index key=}] the key used to choose the place in the \kl{index}. @@ -3111,6 +3115,7 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr \item[\kl{lowercase}] Put all letters of the output in lowercase. \item[\kl{mathord}, \kl{mathop}, \kl{mathbin}, \kl{mathrel}, \kl{mathopen}, \kl{mathclose}, \kl{mathpunct}] Selects a spacing behaviour in math mode. \item[\kl{no index}] avoids the indexing of the term. +\item[\kl{notion}] automatic configuration for displaying and autoreferencing. \item[\kl{protect link}] Disables the hyperlinks inside the link. \item[\kl{ref=}] Links to a label inside the document. \item[\kl{scope=}] Choose the \kl{scope} of the definition. diff --git a/Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx b/Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx index 2f6a4f0a129..6bc619c558e 100644 --- a/Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx +++ b/Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx @@ -23,7 +23,7 @@ % % \iffalse %<head>\usepackage{expl3} -%<head>\ProvidesExplPackage{knowledge}{2022/02/12}{1.28}{} +%<head>\ProvidesExplPackage{knowledge}{2024/03/10}{1.29}{} %<*driver> \def\knowledgecode{active} \input{knowledge.tex} @@ -61,6 +61,7 @@ % \changes{1.26}{2021/12/20}{enhanced math+other functionalities+extra options} % % \changes{1.27}{2022/01/12}{doc changes} % % \changes{1.28}{2022/02/12}{imakeidx support} % +% \changes{1.29}{2024/03/10}{typographic bug corrected} % % \GetFileInfo{knowledge.sty} % % \DoNotIndex{} % @@ -80,8 +81,8 @@ This directory contains the package name: knowledge license: LaTeX Project Public License version 1.2 or above - version: v1.28 - date: 2022/02/12 + version: v1.29 + date: 2024/03/10 author: Thomas Colcombet mail: thomas.colcombet@irif.fr web: https://ctan.org/pkg/knowledge @@ -604,7 +605,7 @@ This directory contains the package \KnowledgeConfigureTrigger{ fix~hyperref~twocolumn } {\knowledgeFixHyperrefTwocolumn} \KnowledgeConfigureTrigger{ notion } - {\KnowledgeConfigureNotion{notion} + {\KnowledgeConfigureNotion[blue]{notion} \knowledge_directives_require_aci_package:nn{notion}{hyperref} \knowledgesetvariant\kl{suggestion=notion} \knowledgesetvariant\intro{suggestion=notion} @@ -3777,7 +3778,7 @@ This directory contains the package \knowledgevariantmodifier{\phantomintro*\kl}{\phantomintro} \knowledgevariantmodifier{\phantomkl*\kl}{\phantomkl} -\knowledgedirective{automatic~in~command}{notion} +\knowledgedirective{automatic~in~command}{notion,also~now} % \end{macrocode} % \begin{macrocode} @@ -3787,11 +3788,8 @@ This directory contains the package \cs_new:Nn\knowledge_inner_command: {knowledge_cmdkl \int_to_arabic:n\knowledge_inner_modifier_count_int :n} - \NewDocumentCommand\withkl{mm}{ \int_gincr:N\knowledge_inner_modifier_count_int - \group_begin: - \group_end: \cs_gset:cpx {\knowledge_inner_command:} {\exp_not:N\cs_gset:Npn @@ -3799,7 +3797,7 @@ This directory contains the package {\knowledge_inner_modifer_re_tl\knowledge_kl_modifiers_tl\exp_not:n{#1}} \knowledge_kl_modifiers_tl\exp_not:n{#1}} \knowledge_kl_modifiers_reset: - #2{}{} + #2 \int_gdecr:N\knowledge_inner_modifier_count_int } @@ -3831,7 +3829,6 @@ This directory contains the package \exp_args:Nc\NewDocumentCommand{knowledge\cs_to_str:N#1}{} {\knowledge_knowledgified_newcommand:NNwn#1} }{ - %\tl_show:n{Unknown~#1~in~\KnowledgifyNewcommand} \use:x{\exp_not:N\NewDocumentCommand \exp_not:c{knowledge\cs_to_str:N#1} {} diff --git a/Master/texmf-dist/tex/latex/knowledge/knowledge.sty b/Master/texmf-dist/tex/latex/knowledge/knowledge.sty index 875271f7379..0d8e6e633a5 100644 --- a/Master/texmf-dist/tex/latex/knowledge/knowledge.sty +++ b/Master/texmf-dist/tex/latex/knowledge/knowledge.sty @@ -23,7 +23,7 @@ %% LaTeX version 1999/12/01 or later. %% \usepackage{expl3} -\ProvidesExplPackage{knowledge}{2022/02/12}{1.28}{} +\ProvidesExplPackage{knowledge}{2024/03/10}{1.29}{} %%%%%%%%%% \RequirePackage{l3keys2e} \RequirePackage{etoolbox} @@ -1080,7 +1080,7 @@ \KnowledgeConfigureTrigger{ fix~hyperref~twocolumn } {\knowledgeFixHyperrefTwocolumn} \KnowledgeConfigureTrigger{ notion } - {\KnowledgeConfigureNotion{notion} + {\KnowledgeConfigureNotion[blue]{notion} \knowledge_directives_require_aci_package:nn{notion}{hyperref} \knowledgesetvariant\kl{suggestion=notion} \knowledgesetvariant\intro{suggestion=notion} @@ -3200,7 +3200,7 @@ \knowledgevariantmodifier{\phantomintro*\kl}{\phantomintro} \knowledgevariantmodifier{\phantomkl*\kl}{\phantomkl} -\knowledgedirective{automatic~in~command}{notion} +\knowledgedirective{automatic~in~command}{notion,also~now} \tl_gset:Nn\knowledge_inner_modifer_re_tl{\rekl*} @@ -3210,8 +3210,6 @@ \NewDocumentCommand\withkl{mm}{ \int_gincr:N\knowledge_inner_modifier_count_int - \group_begin: - \group_end: \cs_gset:cpx {\knowledge_inner_command:} {\exp_not:N\cs_gset:Npn @@ -3219,7 +3217,7 @@ {\knowledge_inner_modifer_re_tl\knowledge_kl_modifiers_tl\exp_not:n{#1}} \knowledge_kl_modifiers_tl\exp_not:n{#1}} \knowledge_kl_modifiers_reset: - #2{}{} + #2 \int_gdecr:N\knowledge_inner_modifier_count_int } @@ -3250,7 +3248,6 @@ \exp_args:Nc\NewDocumentCommand{knowledge\cs_to_str:N#1}{} {\knowledge_knowledgified_newcommand:NNwn#1} }{ - %\tl_show:n{Unknown~#1~in~\KnowledgifyNewcommand} \use:x{\exp_not:N\NewDocumentCommand \exp_not:c{knowledge\cs_to_str:N#1} {} |