diff options
Diffstat (limited to 'Master/texmf-dist/doc')
| -rw-r--r-- | Master/texmf-dist/doc/latex/knowledge/README.md | 4 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/knowledge/knowledge.pdf | bin | 734028 -> 767239 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/knowledge/knowledge.tex | 459 |
3 files changed, 345 insertions, 118 deletions
diff --git a/Master/texmf-dist/doc/latex/knowledge/README.md b/Master/texmf-dist/doc/latex/knowledge/README.md index 5292d7886d0..aeb2b6ed6d6 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.25 - date: 2021/03/31 + version: v1.26 + date: 2021/12/20 author: Thomas Colcombet mail: thomas.colcombet@irif.fr web: https://www.irif.fr/~colcombe/knowledge_en.html diff --git a/Master/texmf-dist/doc/latex/knowledge/knowledge.pdf b/Master/texmf-dist/doc/latex/knowledge/knowledge.pdf Binary files differindex 4afd478edc9..3937cecefaa 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 ba4b94a5989..b0d40485a8b 100644 --- a/Master/texmf-dist/doc/latex/knowledge/knowledge.tex +++ b/Master/texmf-dist/doc/latex/knowledge/knowledge.tex @@ -5,6 +5,7 @@ \usepackage[svgnames]{xcolor} \usepackage{expl3} \usepackage{hyperref} +\usepackage{cleveref} %\usepackage{complexity} \usepackage[quotation,scope,silent]{knowledge} \knowledgeconfigure{visible anchor points=false} @@ -128,7 +129,9 @@ unknown warning=false, unknown diagnose=true, suggestion=cs, - PDF string={\detokenize{#1}}} + PDF string={\detokenize{#1}} +} + \knowledgestyle{cs}{wrap=\Robustdisplay,typewriter,up,md,color=NavyBlue} \knowledgestyle{cs unknown}{wrap=\Robustdisplay,typewriter,up,md,color=black} @@ -292,11 +295,13 @@ \knowledge{link scope=}{directive} \knowledge{style=}{directive} \knowledge{intro style=}{directive} +\knowledge{no index}[no index=]{directive} \knowledge{wrap=}{directive} \knowledge{scope=}{directive} \knowledge{export=}[export]{directive} \knowledge{now}{directive} - +\knowledge{directive} + | automatic in command \knowledge{protect link}{directive} \knowledge{strict}{directive} @@ -347,6 +352,7 @@ \knowledge{hyperref}{option} \knowledge{xcolor}{option} \knowledge{makeidx}{option} + \knowledge{cleveref}{option} \knowledge{scope}{option} \knowledge{quotation}[quotation=]{option} \knowledge{notion}{option} @@ -354,6 +360,7 @@ \end{scope} \knowledge{hyperref option}{link=hyperref,link scope=option} \knowledge{makeidx option}{link=makeidx,link scope=option} +\knowledge{cleveref option}{link=cleveref,link scope=option} \knowledge{scope option}{link=scope,link scope=option} \knowledge{xcolor option}{link=xcolor,link scope=option} \knowledge{notion option}{link=notion,link scope=option} @@ -361,6 +368,9 @@ \knowledge{visible anchor points}[visible AP|visible AP=|visible anchor points=]{option} +\knowledge{anchor point shape}[anchor point shape=|AP shape=|AP shape]{option} +\knowledge{anchor point color}[anchor point color=|AP color=|AP color]{option} +\knowledge{anchor point shift}[anchor point shift=|AP shift=|AP shift]{option} \knowledge{protect quotation}[protect quotation=]{option} \knowledge{protect link co}{option,text=protect link} \knowledge{unprotect link co}{option,text=unprotect link} @@ -397,6 +407,7 @@ \knowledge{standalone}{package,url={https://www.ctan.org/pkg/standalone}} \knowledge{xcolor}{package,url={https://www.ctan.org/pkg/xcolor}} \knowledge{makeidx}{package,url={https://www.ctan.org/pkg/makeidx}} + \knowledge{cleveref}{package,url={https://www.ctan.org/pkg/cleveref}} \knowledge{etoolbox}{package,url={https://www.ctan.org/pkg/etoolbox}} \knowledge{xparse}{package,url={https://www.ctan.org/pkg/xparse}} \knowledge{amsmath}{package,url={https://www.ctan.org/pkg/amsmath}} @@ -404,6 +415,8 @@ \knowledge{mathcommand}{package,url={https://www.ctan.org/pkg/mathcommand}} \end{scope} +\knowledge{arXiv}{package,url={https://arxiv.org/}} + \knowledgedirective{environment}{typewriter} \begin{scope}\label{env} @@ -414,6 +427,7 @@ \knowledge{tikzcd}{environment,ref=section:tikzcd} \knowledge{thebibliography}{environment,ref=section:thebibliography} \knowledge{document}{environment} + \knowledge{picture}{environment} \end{scope} \knowledge{variant directives}[variant directive|Variant directives]{doc notion} @@ -428,6 +442,7 @@ \knowledge {unknown warning=}{directive} \knowledge {unknown diagnose=}{directive} \knowledge {suggestion=}{directive} + \knowledge {display code=}{directive} \knowledge {PDF string=}{directive} \knowledge {stared sequence}{doc notion} \knowledge {modifier}[modifiers|Modifiers]{doc notion} @@ -440,7 +455,7 @@ \knowledge{label}{} -\knowledge{variant of \cs{\kl}}[variants of \cs{\kl}|Variants of \cs{\kl}]{doc notion} +\knowledge{variant of \cs{\kl}}[variants of \cs{\kl}|Variants of \cs{\kl}|variants|variant]{doc notion} \knowledge{scoping}[Scoping]{doc notion} \knowledge{package option}[package options|Package options]{doc notion} \knowledge{configuration option}[configuration options|Configuration options]{link=package option} @@ -610,8 +625,8 @@ \maketitle \begin{abstract}\phantomintro(package){knowledge}% -The "knowledge@@package" package offers commands and notations for handling semantical notions in a (scientific) document. -This allows to link the use of a notion to its definition, to add it to the index automatically, etc. +The "knowledge@@package" package offers commands and notations for handling semantical notions in a document. +This allows to easily link the use of a notion to its definition, to add it to the index automatically, etc. \end{abstract} \ifcodeTF{\begin{quote}This version of the documentation includes a good part of the code. A casual user should \textit{a priori} not use this version of the documentation.\end{quote}}{} @@ -753,8 +768,13 @@ I have seen Till Tantau who explained me how to test whether a material is displ \item[2020-03-05] Now \texttt{hidelinks} and \texttt{breaklinks} are automatically activated unless the new option \kl{no patch} is activated. Doc update. V1.22 on CTAN. \item[2020-04-25] Made the package compatible with 2016 versions of LaTeX. Useful when \texttt{knowledge.sty} is included with and compile in arXiv. V1.23 on CTAN. \item[2020-05-02] Doc update ("acmart@@package" colors, thanks to Daniela Petri\c san). -\item[2020-09-22] Adding the "silent" option as suggested by Patrick Lambein-Monette. V1.24 on CTAN -\item[2021-03-31] Correcting a bug caused by a change of semantics in "expl3@@package". V1.25 on CTAN +\item[2020-09-22] Adding the "silent" option as suggested by Patrick Lambein-Monette. V1.24. +\item[2021-03-31] Correcting a bug caused by a change of semantics in "expl3@@package". V1.25. +\item[2021-05-25] Added the \cs\kref, \cs\kpageref, \cs\kcref, and \cs\kCref\ commands a suggested by Ziv Scully. +\item[2021-05-26] Corrected wrongly used default parameter in \cs\knowledgedirective. +\item[2021-05-27] The explicit text given in a \cs\kl-command now overrides the "text=" directive. +\item[2021-07-18] Adding the "no index" directive. +\item[2021-12-20] Adding options "anchor point shape", "anchor point color", "anchor point shift" (rom request of Rémi Morvan). \end{compactdesc} \normalsize %\restoregeometry @@ -902,7 +922,7 @@ makes it possible to use the notions in many contexts: 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". -In another part of the document, \smallcode{\kl"morphism@@RING\kl"} can be safely using while using an unspecialised \smallcode{\kl"morphism\kl"} would become quickly unmanageable. +In another part of the document, \smallcode{\kl"morphism@@RING\kl"} can be safely used whereas using an generic \smallcode{\kl"morphism\kl"} would become quickly unmanageable. @@ -1032,6 +1052,15 @@ These \kl(ex1)[semigroup]{algebraic objects} \kl{[...]} \end{PDFoutput}\noindent 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} +\kl"Semigroups\kl" are introduced in \cs\kCref\{semigroup\},\\ Page~\cs\kpageref\{semigroup\}. +\end{code} +\noindent yields: +\begin{PDFoutput}[10cm] + \kl(ex1)[semigroups]{Semigroups} are introduced in \kCref(ex1){semigroups}, + Page~\kpageref(ex1){semigroups}. +\end{PDFoutput} Finally, in particular for large documents, it is good to have an "index". For this, 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. @@ -1047,9 +1076,9 @@ Finally, the \cs{knowledge} commands are adapted in a straightforward manner: \indent~~~\klbn|~~morphism@SG\\ \indent~~~\klbn|~~morphisms@SG \end{code}\noindent -Now, the index (after running \texttt{makeidx}) contains all entries and references to the use of semigroups and semigroup morphisms. +Now, the index (after running \texttt{makeindex}) contains all entries and references to the use of semigroups and semigroup morphisms. -See Section~\ref{subsection:makeidx option} for more details on making an index. +See \kCref(option){makeidx} for more details on making an index. % %\subsection{Managing an index} %Though it is not its primary goal, without using its hyperlinking capabilities, the "knowledge@@package" offers convenient features for easily managing data for the construction of an index. @@ -1060,33 +1089,17 @@ See Section~\ref{subsection:makeidx option} for more details on making an index. \subsection{Mathematics} \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. Imagine, for instance that you would like each time a macro \kl[@token]{\monoid} is met, to display $\mathcal M$, you would do for instance: -\begin{code}[7cm] -\cs\newrobustcmd\kl[@token]\monoid\{\cs\mathcal\ M\} -\end{code}\noindent -Imagine that furthermore, you would like to hyperlink to the definition of a monoid. A standard \cs{\kl} command does the job\footnote{It is highly advised to not use the "quotation notation" in math mode or macros.}: -% -\marginpar{% - \begin{hint} - Defining new macros is best done using \cs{\newrobustcmd} - (of the "etoolbox@@package" package), rather than \cs{\newcommand} as usual in \LaTeX. - This remark is general independently of the use of "knowledge@@package". - \end{hint} - \begin{hint} - The package "mathcommand@@package" offers severals capabilities for redefining commands for math mode. - See Section~\ref{subsubsection:mathcommand} for more. - \end{hint}} -% +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}[9cm] -\cs\newrobustcmd\kl[@token]\monoid\{\cs\kl -monoid]\{\cs\mathcal\ M\}\}\\~ -What is \$\kl[@token]\monoid\$ ? +\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\}\$ \end{code}\noindent \noindent would yield: \begin{PDFoutput}[4cm] -\newcommand \monoid{\kl[monoid]{\mathcal M}} -What is $\monoid$ ? +\knowledgenewrobustcmd \monoid{\cmdkl{\mathcal M}} +A monoid is $\monoid$ ! \end{PDFoutput} \begin{problem} But I want more. I want to be able to introduce variables. @@ -1364,6 +1377,9 @@ A certain number of Boolean directives are available without any options. These (that leaves it in the default state, or the one determined by surrounding knowledges). The general boolean \kl[\knowledge directives]{directives} are the following: \begin{description} +\itemAP[\kl{autoref}] activates the ability to introduce once, use several times an instance. This is often used for defining links inside a document (see the "hyperref@@option" in \kCref*"hyperref@@option"). This can also be used for constructing the index (see the "makeidx@@option" in \kCref*"makeidx@@option"). It can simply be used for referencing the number of the environment or the proper page of introduction (see \cs\kref\ and \cs\kpageref\ commands and their more powerful "cleveref@@option" in \kCref*"cleveref@@option"). +\itemAP[\kl{autorefhere}] puts immediately a label at the location of the definition, and makes all \cs{\kl} occurrences of this \kl{knowledge} +hyperlink to this location. \itemAP[\intro{emphasize}] forces the text to be emphasized using `\cs{\emph}', \itemAP[\intro{italic}/\intro{up}] forces/unforces italic ("up" does nothing in math mode), \itemAP[\intro{boldface}/\intro{md}] forces/unforces boldface (be it in math or text mode), @@ -1451,12 +1467,12 @@ A certain number of \intro{default styles} are also offered, that in particular \label{subsubsection:macro directives} When defining \kl{knowledges}, it is often the case that the same -sequence of directives are used. \intro{Macro directives} are here for simplifying this situation (see also \cs{\knowledgedefault} and \cs{\knowledgestyle}). This is achieved using the \cs{\knowledgedirective} directive: +sequence of directives are used. \intro{Macro directives} are here for simplifying this situation (see also \cs{\knowledgedefault} and \cs{\knowledgestyle}). This is achieved using the \cs{\knowledgedirective} macro: \marginpar{\begin{hint} This should not be confused with \kl{styles} which offer another way to control the display.\end{hint}} \begin{center} \smallcode{\csintro{\knowledgedirective}*\{name\}[optional parameter]\{directives\}} \end{center} -After such a command has been issued, `name' becomes a \kl[\knowledge directives]{directive} +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} @@ -1518,9 +1534,12 @@ The optional star does not reset the \kl{default directives} but simply add new -\subsection{The \cs{\kl} command} +\subsection{The \cs{\kl} command and variants} \label{subsection:kl command} +The \cs\kl\ command is used for displaying a knowledge in the text, while using the data associated to it +(introducing a target link, linking to its definition, linking to an outer document, changing color, putting an entry in the index, etc). + \subsubsection{The standard syntax} \marginpar{\begin{hint} Note that the \cs{\kl} command can often be replaced by the @@ -1535,20 +1554,19 @@ or\quad& \smallcode{\csreintro{\kl}[\kl[knowledge name]{optional knowledge name}](\kl[klab]{optional scope})\{text\}}\ . \end{tabular} \end{center} -Its meaning is to search for the `optional knowledge name' if present, or for `text' otherwise. How this is exactly performed depends on the presence of the \kl[klab]{optional label}. +Its meaning is to search for the `optional knowledge name' if present, or for `text' otherwise. How this is exactly performed depends on the presence of the \kl[klab]{optional scope}. The search process is as follows: \begin{asparaitem} -\itemAP if an \intro[klab]{optional label} is given, the \kl{knowledge} is searched in the corresponding scope. +\itemAP if an \intro[klab]{optional scope} is given, the \kl{knowledge} is searched in the corresponding scope. \itemAP otherwise, the \kl{stack of visible scope instances} is processed through (starting from the inner most) - until a \kl{knowledge} of name `\kl{knowledge name}' or `text', of \kl{namespace} `default' and this \kl{scope} - is found. + until a \kl{knowledge} of name `\kl{knowledge name}' (or `text' if not optional \kl{knowledge name} has been given), of \kl{namespace} `default', and this \kl{scope} is found. If the `knowledge name/text' has not been found, the \kl{style} `"kl unknown@@style"' (or similar "styles", as defined by the "unknown style=@@variant" or "unknown style cont=@@variant") is used, and the text displayed. \item Otherwise, the \kl{knowledge} is executed. If it is a \kl{link=} or \kl{synonym} defined \kl{knowledge}, the link is followed, and the process continues. \item Finally, all the definitions involved in the \kl{knowledge} are processed, following a \kl{style=} if defined, the \kl{knowledge} is updated (essentially incrementing the counter of use), and the \kl{knowledge} is displayed. \end{asparaitem} -This general mechanism is used also by other commands that are variations around \cs{\kl} such as in particular \cs{\intro}. +This general mechanism is used also by other commands that are "variants of \cs{\kl}" such as \cs{\intro}, \cs{\reintro}, \cs{\kref}, \cs{\kpageref}, and so on. \subsubsection{The "quotation notation"} @@ -1602,7 +1620,22 @@ There are nevertheless some situations in which one would prefer to use the orig -\subsubsection{\kl{Variants of \cs{\kl}}, \cs{\knowledgenewvariant}, \cs{\knowledgevariantmodifier} } +\subsubsection{\kl{Variants of \cs{\kl}}} +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} +\item \cs\intro\ is used to introduce a knowledge. +\item \cs\reintro\ displays like for introducing the knowledge, but does not do it. +\item \cs\rekl\ behaves like \cs\kl\ acts as a modifier and transforms \cs\intro\ into \cs\reintro. +\item \cs\phantomintro\ performs the introduction, but does display anything. +\itemAP \csintro\kref\ displays the number of the environment in which the introduction took place. +\itemAP \csintro\kpageref\ displays the number of the page in which the knowledge introduction took place. +\item \csintro\kcref, \csintro\kCref, \csintro\kcpageref, \csintro\kCpageref, \csintro\knamecref, \csintro\knameCref, +\csintro\knamerefs, and \csintro\knameCrefs, display informations about the place of introduction of a "knowledge", +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}}} \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: @@ -1639,6 +1672,7 @@ These command define/modify a/the macro \cs{\variant} that uses the same syntax \itemAP[""suggestion=@@variant""\{directives\}] configures the "directives" to be suggested in the "diagnose file" when the "knowledge" is unknown. \itemAP[""PDF string=@@variant""\{code\}] gives a substitute text for "hyperref@@package" to use for producing the bookmarks. This code has to be expandable. The code may use three parameters; $\sharp1$ is the main text of the command, $\sharp 2$ is the optional parameter, and $\sharp 3$ is the scope. The macro \cs{\IfNoValueTF} of the package "xparse@@package" can be used to test if the second and third arguments are present. By default, the code is \texttt{\{$\sharp1$\}}. Note that the star syntax cannot be used in this context. It the expected result cannot be achieved using this directive, the less convenient macro \cs{\texorpdfstring} of the "hyperref@@package" package should be used. +\item[""display code=@@variant""] can be used to shortcut the standard code for display. See the code for more details. Typical examples are the "variants" \cs\kref,\ \cs\kpageref\ and so on, which do not display the knowledge itself, but instead treat the underlying label associated. \end{compactdesc} \smallskip @@ -1686,13 +1720,14 @@ Note that \cs{\reintro} and \cs{\phantomintro} are defined using similar code. \AP The second code example is used in this document (the documentation of the package) and consists of two macros \csintro{\cs} and \csintro{\csintro} which have the following semantics: \begin{itemize} -\item these have the same syntax as \cs{\kl} and \cs{\intro} respectively. -\item these are used to display control sequences without executing it, -\item if \cs{\csintro} is never used, it appears in black, -\item is \cs{\csintro} is used, then it is in color blue, and the calls to \cs{\cs} - are in dark blue, and furthermore, the \cs{\cs} calls possess an hyperlink to - the call to \cs{\csintro}. -\item no \cs{\knowledge} command is necessary, and no warnings are issued. +\item these correspond, and have the same syntax as, \cs{\kl} and \cs{\intro} respectively, +\item these are used to display control sequences without executing them, +\itemAP if \smallcode{\cs{\csintro}\{\cs[\ucommand]\command\}} is used, then it displays \csintro\command\ in color blue, and + every occurrences of \smallcode{\cs\cs\{\cs\command\}} yields \cs\command\ being displayed in dark blue + and linking to the introduction point, +\item if \smallcode{\cs\csintro\{\cs[\ucommand]\command\}} is never used, + 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} \cs\knowledgestyle\{cs\}\par @@ -1715,14 +1750,12 @@ following semantics: \cs\knowledgenewvariant\cs\csintro\{\par ~~~~"namespace=@@variant"cs,\par ~~~~"auto knowledge=@@variant"\{"autoref","scope="document,"also now"\},\par -~~~~"default style=@@variant"\{autoref target,csintro\},\par +~~~~"default style=@@variant"\{"autoref target",csintro\},\par ~~~~"unknown style=@@variant"csintro unknown,\par ~~~~"unknown style cont=@@variant"csintro unknown,\par \}\par \cs\knowledgevariantmodifier\{\cs{\intro*}\cs\cs\}\cs\csintro\par \cs\knowledgevariantmodifier\{\cs\csintro*\cs\cs\}\cs\csintro\par -\cs\knowledgevariantmodifier\{\cs\cs*\cs\kl\}\cs\cs\par -\cs\knowledgevariantmodifier\{\cs\csintro*\cs\kl\}\cs\csintro \end{code} Several things can be noted about this code: \begin{asparaitem} @@ -1732,7 +1765,7 @@ Several things can be noted about this code: \item when a \cs{\csintro} command is met, the corresponding \cs{\knowledge} command is automatically issued, in particular with `"scope="document' for guaranteeing the visibility of each command everywhere in the document, \item the "also now" directive is necessary for the compilation to (possibly) stabilize in two iterations, since it uses the proper \cs{\label} already at the first iteration (without "also now", it would be performed on the second one only, and with just "now", it would be visible only by the uses after the introduction). -\item warnings and diagnose information is explicitly eliminated. +\item warnings and diagnose pieces of information are explicitly eliminated. \end{asparaitem} @@ -1754,10 +1787,10 @@ the "quotation notation": \begin{tabular}{ccc} \smallcode{\cs\kl(scope name)\{knowledge\}}% &~or~&% - \smallcode{\cs\kl(scope name)[knowledge]\{displayed text\}}\\ + \smallcode{\cs\kl(scope name)[knowledge]\{text\}}\\ \smallcode{\klqn"knowledge\klqn{@@}scope\klqn"}% &~or~&% - \smallcode{\klqn"displayed text\klqn@knowledge\klqn@scope\klqn"} + \smallcode{\klqn"text\klqn@knowledge\klqn@scope\klqn"} \end{tabular} \end{center} It works also for \cs{\intro} and with double quotes. @@ -1823,12 +1856,12 @@ This is convenient, in particular for having synonyms in different scopes: Here, general \klqn"groups\klqn" are not defined but \klqn"groups\klqn{@@}abelian\klqn" are,\\ and correspond to \klqn"abelian groups\klqn".\\ \cs\begin\{"scope@@env"\}\cs\knowledgeimport\{abelian\}\\ -\indent~~Her, all \klqn"groups\klqn" here are abelian.\\ +\indent~~All \klqn"groups\klqn" here are abelian.\\ \cs\end\{"scope@@env"\} \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 a priori two different spaces of naming are used). +"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} \textcolor{gray}{\% We declare first in the preamble the environments that can have}\\ \textcolor{gray}{\% knowledges attached to them.}\\ @@ -1963,7 +1996,7 @@ For instance: \noindent will induce the corresponding environments to have internal knowledges. -Most of the times, it is not necessary to use "scope directives". +Most of the time, it is not necessary to use "scope directives". \begin{remark} Note that (in the current implementation) it is necessary to use the @@ -1977,10 +2010,11 @@ commands \cs{\begin} and \cs{\end}. Hence \cs{\proof}\dots\cs{\endproof} would \itemAP[\intro(area){scope=}\texttt{true/false}] tells whether an environment should induce a scope. For the moment, this is not used (as soon as configured, it always behaves like a scope). \itemAP[\intro(area){label=}\texttt{none/accepts}] tells whether a \cs{\label} command can refer to an "instance" of this "area", \itemAP[\intro(area){environment=}\texttt{true/false}] should be set to true if the scope has to be opened whenever an environment of same name is opened using the \cs{\begin} and \cs{\end} commands of "latex". - \itemAP[\intro(area){autoclose=}\texttt{true/false}] means that the closure is triggered by another event (closure of another enclosing instance, or pushing of an area that requires its closure). It should be true for "latex" environments, and false when configuring, e.g, \cs{\section} to open an "scope" (since the end of the section is automatic: when another section is opened, or some higher level sectioning command). - \itemAP[\intro(area){parents=}\{"area1@area","area2@area",\dots\}] takes a comma separated list of areas that are allowed as parent. For opening the area, some enclosing instances may be automatically closed for reaching such a parent (if their "autoclose=@@area" "directive@scope directive" is set to true). - \itemAP[\intro(area){push code=}\texttt{\{code\}}] defines the code to be executed when the area is pushed (each time, these are added). - \itemAP[\intro(area){pop code=}\texttt{\{code\}}] defines the code to be exected when the are is popped (added too). + \itemAP[\intro(area){autoclose=}\texttt{true/false}] means that the closure is triggered by another event (closure of another enclosing instance, or pushing of an area that requires its closure). It should be true for "latex" environments, and false when configuring, e.g, \cs{\section} opens a "scope" and its closure should be automatic when another section begins. + \itemAP[\intro(area){parents=}\{"area1@area","area2@area",\dots\}] takes a comma separated list of areas that are allowed as parent. For opening the area, some enclosing instances may be automatically closed for reaching such a parent (if their "autoclose=@@area" "directive@scope directive" is set to true). For instance, the parent of a subsection should be a section: + Hence when a subsection begins, the currently opened subsection and subsubsection are closed. + \itemAP[\intro(area){push code=}\texttt{\{code\}}] defines some code to be executed when the area is pushed (each time, these are added). + \itemAP[\intro(area){pop code=}\texttt{\{code\}}] defines some code to be executed when the area is popped (added too). \itemAP[\intro(area){occurrences=}\texttt{once/multiple/recursive}] can be one of `\texttt{once}' if the area can only have one instance in the document, `\texttt{multiple}' if there can be several instances, but not nested, and `\texttt{recursive}', if there is no restriction. \itemAP[\intro(area){forces=}"area"] requires a specific area as an ancestor of this area. This ancestor is implicitly pushed if necessary. \end{compactdesc} @@ -1993,7 +2027,7 @@ By default, the "knowledge@@package" package tries to not stop the compilation u \AP Very often there is some \kl[undefined knowledge]{undefined knowledge}. -Such \kl{knowledges} are displayed using "kl unknown@@style" and "kl unknown cont@@style") +Such \kl{knowledges} are displayed using the "kl unknown@@style" and "kl unknown cont@@style") \kl{styles} when issued by \cs{\kl}; using "intro unknown@@style" and "intro unknown cont@@style" when issued by \cs{\intro}. The detail of the problems are then gathered in the \kl{diagnose file}. @@ -2147,10 +2181,6 @@ deactivates or reactivates the links. \item[\intro{url=}]\texttt{\{url address\}} puts an hyperlink to an (external) url (the braces can be omitted when there is no comma). \marginpar{\begin{hint} You may have to use \texttt{$\backslash$\~} instead of \texttt{\~} in url's addresses.\end{hint}} -\item[\kl{autoref}] activates the ability to introduce once, use several times an instance. This is very convenient when writing scientific documents with many notions. This is the basic directive activating -the features of the \cs{\intro} command. -\item[\kl{autorefhere}] puts immediately a label at the location of the definition, and makes all \cs{\kl} occurrences of this \kl{knowledge} -hyperlink to this location. \end{description} \subsubsubsection{The \kl{autoref} directive} @@ -2343,10 +2373,28 @@ and a \intro{unit2} to be One can check that the different knowledges are properly hyperlinked, and that precise targets are the one described by \cs{\AP} and \cs{\itemAP}. For helping debugging the \kl{anchor points}, these are by default made visible as (red) corners on output. When the "knowledge@@package" package is loaded with the \kl{paper} option this graphical help disappears. -This can also be desactivated using:\phantomintro{visible anchor points} - \begin{code}[9cm] - \cs\knowledgeconfigure\{\kl{visible anchor points=}false\} - \end{code} +This can also be deactivated using:\phantomintro{visible anchor points} +\begin{quote} + \smallcode{\cs\knowledgeconfigure\{\kl{visible anchor points=}false\}}. +\end{quote} +\AP The color of "anchor points" can be changed using (in which colors are defined as in the package "xcolor@@package"): +\begin{quote} + \smallcode{\cs\knowledgeconfigure\{""anchor point color=""color\}}, or \\ + \smallcode{\cs\knowledgeconfigure\{""AP color=""color\}}. +\end{quote} +\AP The shape of "anchor points" can be changed using (in which shape can be one of + \texttt{tiny corner}, \texttt{small corner}, \texttt{corner}, \texttt{large corner}, + \texttt{tiny cross}, \texttt{small cross}, \texttt{cross}, \texttt{large cross}, or some code to be used in the "picture@@env" environment): +\begin{quote} + \smallcode{\cs\knowledgeconfigure\{""anchor point shape=""shape\}}, or \\ + \smallcode{\cs\knowledgeconfigure\{""AP shape=""shape\}}. +\end{quote} +Finally, the "anchor points" reference point can be shifted, using: +\begin{quote} + \smallcode{\cs\knowledgeconfigure\{""anchor point shift=""\{$x$,$y$\}}, or \\ + \smallcode{\cs\knowledgeconfigure\{""AP shift=""\{$x$,$y$\}\}}, +\end{quote}\noindent +in which $x$ and $y$ are by default in unit \texttt{em} (note the use of curly braces and of no parenthesis, which is mandatory). \subsubsection{The \kl{makeidx option}} @@ -2373,7 +2421,36 @@ The following \kl[\knowledge directives]{directives} are to be used: \cs\def\cs\knowledgeIntroIndexStyle\#1\{\cs\fbox\{\#1\}\} \end{code} \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} +\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 +result in that the introductions of `test' will be gathered in the index, but not the other uses. +\subsubsection{The \kl{cleveref option}} + +The \intro(option){cleveref} option loads the "cleveref@@package" package and gives access to new commands: +\csintro\kcref, \csintro\kCref, \csintro\kcpageref, \csintro\kCpageref, \csintro\knamecref, \csintro\knameCref, +\csintro\knamerefs, and \csintro\knameCrefs\ which are respectively equivalent to \cs\cref, \cs\Cref, \cs\cpageref, \cs\Cpageref, +\cs\namecref, and \cs\nameCref\ of the "cleveref@@package" package, but applied to the label corresponding to the "knowledge" (see the documentation of "cleveref@@package" for more details). +These commands are variants of \cs\kl\ and hence are subject to the same syntax. + +For instance, +\begin{code} + \kl{"}Anchor points\kl{"} have been described in~\cs\kCref\{anchor point\},\\ + Page \cs\kpageref\{anchor point\}. +\end{code}\noindent +would typeset as +\begin{PDFoutput}[10cm] + "Anchor points" have been introduced in~\kCref{anchor point}, Page \kpageref{anchor point}. +\end{PDFoutput} \subsection{Dealing with math} \label{subsection:math} @@ -2381,22 +2458,156 @@ The following \kl[\knowledge directives]{directives} are to be used: There are essentially two ways in which one would like to use "knowledge@@package" with mathematics: \begin{description} \item[Single introduction] Some mathematical objects are introduced once and for all in the paper. In this case, all the use of the object -should point to the same introduction location. +should point to the same introduction location. This way of doing is covered intensively in the \item[Variables] The more advanced case is when one wants to track variables. For instance, a macro variable~\cs\x\ could have a different meaning in two distinct theorems. This case is more similar to variables in a programming language, that have a scope. -Here the situation is slightly more complicated since a variable could be introduced in a theorem, and then used many pages later in a proof section for instance. +Here the situation is slightly more complicated since a variable could be introduced in a theorem, and then used many pages later in a proof section for instance. This is doable with the package, using scoping, but is not described yet in the documentation. \end{description} -The first use is fairly easy. The second one requires a bit more care. We review them one after the other, after some advertisements for the "mathcommand@@package" package. + + + + +\subsubsection{Defining knowledge-aware macros} +\label{subsubsection:knowledgenewcommands} + +It is possible to use the \cs\kl\ command inside , and in math mode (however, the "quotation notation" should really be avoided). +Nevertheless, this may cause problematic results in various situations. For this reason, specialized tools are offered. + +In this first section, we describe the simplest way to define macros that are linked to "knowledge". +This covers almost all situations, as long as one is not interested in having the knowledge dependant of the parameters of the macro. +In the subsequent sections, some more explanations are given covering the case of parameters. + + +\knowledgenewcommand\floor[1]{\cmdkl{\lfloor}#1\cmdkl{\rfloor}} + +\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} + \cs\knowledgenewrobustcmd\cs\floor[1]\{\cs\cmdkl\{\cs\lfloor\}\#1\cs\cmdkl\{\cs\rfloor\}\} +\end{code}\noindent +and then use it in a natural way: +\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 +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} + \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 +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.}. + +\AP As explained above, the \cs\knowledge\ command is implicit when defining such macros. The "knowledge" name is the macro name itself, and the directive used is ""automatic in command"". +Hence, you can modify the behavior by redefining the directive: +\begin{quote} + \cs\knowledgedirective*\{"automatic in command"\}\{\dots\} +\end{quote} + + +\paragraph{Defining new commands} +We have used \cs\knowledgenewrobustcmd\ in the above example. +In fact, several commands are available for defining such knowledge-enhanced macros. +Each of them corresponds to a normal command (from \LaTeX, or "xparse@@package", or "mathcommand@@package"), prefixed with `\texttt{knowledge}' or `\texttt{Knowledge}'. +The behavior of these commands is identical to the original ones, and furthemore activates the ability to use \cs\cmdkl. +(Note that it is forbidden for your macro to absorb anything more than the parameters described during its definition.) +\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.}, +\end{quote} +correspond to \cs\newcommand, \cs\renewcommand, and \cs\newrobustcmd\ (from "etoolbox@@package") respectively. +\AP +The commands +\begin{quote} + \csintro\KnowledgeNewDocumentCommand, \\ + \csintro\KnowledgeRenewDocumentCommand, \\ + \csintro\KnowledgeProvideDocumentCommand, and \\ + \csintro\KnowledgeDeclareDocumentCommand +\end{quote} +extend the corresponding commands from the "xparse@@package" package (it offers more complete possibilities to define the signature of macros, and do it in a cleaner and more systematic way). + +\AP Finally, the commands of the "mathcommand@@package" package (see~\Cref{subsubsection:mathcommand}) +are also extended (provided it has been loaded before the package "knowledge@@package"), yielding: +\begin{quote} + \csintro\knowledgedeclarecommand, \\ + \csintro\knowledgenewmathcommand, \\ + \csintro\knowledgenewtextcommand, \\ + \csintro\knowledgerenewmathcommand, \\ + \csintro\knowledgerenewtextcommand, \\ + \csintro\knowledgedeclaremathcommand, \\ + \csintro\knowledgedeclaretextcommand, \\ + \csintro\KnowledgeNewDocumentMathCommand, \\ + \csintro\KnowledgeNewDocumentTextCommand,\\ + \csintro\KnowledgeRenewDocumentMathCommand, \\ + \csintro\KnowledgeRenewDocumentTextCommand,\\ + \csintro\KnowledgeProvideDocumentMathCommand, \\ + \csintro\KnowledgeProvideDocumentTextCommand,\\ + \csintro\KnowledgeDeclareDocumentMathCommand, \\ + \csintro\KnowledgeDeclareDocumentTextCommand,\\ + \csintro\knowledgenewcommandPIE, \\ + \csintro\knowledgerenewcommandPIE,\\ + \csintro\knowledgedeclarecommandPIE, \\ + \csintro\knowledgenewmathcommandPIE, \\ + \csintro\knowledgerenewmathcommandPIE, \\ + \csintro\knowledgedeclaremathcommandPIE, \\ + \csintro\KnowledgeNewDocumentCommandPIE, \\ + \csintro\KnowledgeRenewDocumentCommandPIE,\\ + \csintro\KnowledgeDeclareDocumentCommandPIE, \\ + \csintro\KnowledgeProvideDocumentCommandPIE,\\ + \csintro\KnowledgeNewDocumentMathCommandPIE, \\ + \csintro\KnowledgeRenewDocumentMathCommandPIE,\\ + \csintro\KnowledgeDeclareDocumentMathCommandPIE, and \\ + \csintro\KnowledgeProvideDocumentMathCommandPIE. +\end{quote} + +\subsubsection{The combination \cs\withkl/\cs\cmdkl} +\label{subsubsection:withkl} + +In fact, inside commands like~\cs\knowledgenewrobustcmd, the command~\cs\withkl\ is used. +It has to be used in combination with \cs\cmdkl: +\begin{center} + \smallcode{\csintro\withkl\{\cs\kl-like command\}\{\dots\csintro\cmdkl\{A\}\dots\csreintro\cmdkl\{B\}\dots\}} +\end{center} +Inside the right argument of \cs\withkl, \cs\cmdkl\ stands for a shorthand for the \cs\kl-like command, with the following specificities: +the "modifiers@@variant" used before the \cs\withkl\ are absorbed and reinjected for each use of~\cs\cmdkl. Furthermore, all the uses of \cs\cmdkl, but the first one, get to be preceded of the \csintro\rekl* "modifier@@variant", which transformes in particular \cs\intro\ into \cs\reintro. Hence, +\smallcode{\cs\intro*\cs\withkl\{\cs\kl[example]\}\{\dots\cs\cmdkl\{A\}\dots\cs\cmdkl\{B\}\dots\}} +gets to be evaluated as +\smallcode{\dots\cs\intro[example]\{A\}\dots\cs\reintro[example]\{B\}\dots} + +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} +\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 +Now, the norm $1$ and the norm $2$ can be defined in different places since "knowledge" is specific to each case. +\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} + \subsubsection{Defining macros for math: the "mathcommand@@package" package} \label{subsubsection:mathcommand} -Defining macros is standard in \TeX, and it should be used systematically in writing scientific documents. +Defining macros is standard in \TeX, and it should be used systematically when writing scientific documents. This is particularly true when using the "knowledge@@package" package. The standard way in \LaTeX\ for defining macros is to use \cs\newcommand. However, the resulting macro, if it has no optional parameters, is then expandable, and it is better to avoid it using instead \cs\newrobustcmd\ from the "etoolbox@@package" -package (it has the same syntax). +package (it has the same syntax). Generally speaking, the "xparse@@package" package, which gives easier syntax for describing commands, possibly with more complex parameter templates, should be preferred. -Another package "mathcommand@@package" has been designed to be used in conjunction with "knowledge@@package". +Another package, "mathcommand@@package", has been designed to be used in conjunction with +"knowledge@@package"\footnote{Note that all the commands for defining macros also exist in a "knowledge"-compatible form (see \Cref{subsubsection:knowledgenewcommands})}. We shall use it in the advanced examples below. It allows: \begin{itemize} \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: @@ -2411,6 +2622,10 @@ We shall use it in the advanced examples below. It allows: Now \$\cs\pi\$ points to the above sentence. \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} + \cs\knowledgerenewmathcommand\cs\pi\{\cs\cmdkl\{\cs\LaTeXpi\}\} + \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. @@ -2433,14 +2648,14 @@ Five points have to be kept in mind: \item Do not mix the "knowledge" concerning math commands and normal text. It is in practice difficult to maintain. \item Use the control sequence of the macro itself as the "knowledge" name. - This does not cause problems and is easier to maintain. + This does not cause problems and is easier to maintain. This is automatically done when + commands such as \cs\knowledgenewrobustcmd\ are used. \item Use the \cs{\intro*} notation for introducing macros. -\item The surrounding typography is broken when using the command \cs{\kl} (if someone knows how to solve that, please contact me). Commands such as \cs\mathrel\ should be used to recover it. +\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} -\cs\newrobustcmd\cs\comp\{\cs\mathrel\{\cs\kl[\cs\comp]\{\cs\circ\}\}\}\\ -\cs\knowledge\cs\comp\{notion\}\\ +\cs\knowledgenewrobustcmd\cs\comp\{\cs\mathrel\{\cs\cmdkl\{\cs\circ\}\}\}\\ {[...]}\\ \cs\AP\ Composition is denoted \$\cs{\intro*}\cs\comp\$.\\ {[...]}\\ @@ -2453,34 +2668,27 @@ Two variation may be comfortable to use. 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} -\cs\disablecommand\cs\circ\\ -\cs\suggestcommand\cs\rho\{Use instead \cs\comp\ for function composition.\}\\ -\cs\newrobustcmd\cs\myFunction\{\cs\kl[\cs\myFunction]\{\cs\LaTeXrho\}\}\\ -\cs\knowledge\cs\myFunction\{notion\}\\ -{[...]}\\ -\AP Let \$\cs{\intro*}\cs\myFunction(x)=[...]\$\\ -{[...]}\\ -Now, each use of \$\cs\myFunction\$ points to its introduction. +\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} -\noindent The result is that if one uses \cs\rho\ in the code, an error will be issued, and \cs\myFunction\ be suggested as a replacement. -Note that more than one suggestions can be attached to the macro (if several macros use the symbol~$\rho$). Note also -that in the definition of \cs\myFunction, \cs\LaTeXrho\ is used instead of~\cs\rho. Indeed, \cs\rho\ has been deactivated, -but~\cs\LaTeXrho\ gives access to its original meaning. +\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. \paragraph{Redefining the original \TeX\ macro} -Another situation is that one would like to use the \cs\rho\ control sequence for accessing our function instead of \cs\myFunction\ (simply because this is more convenient and easy to remember, and we know in advance that no confusion may arise). +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} -\cs\renewmathcommand\cs\rho\{\cs\kl[\cs\rho]\{\cs\LaTeXrho\}\}\\ -\cs\knowledge\cs\rho\{notion\}\\ +\cs\knowledgerenewmathcommand\cs\circ\{\cs\mathrel\{\cs\cmdkl\{\cs\LaTeXcirc\}\}\}\\ {[...]}\\ -\cs\AP\ Let \$\cs{\intro*}\cs\rho(x)=[...]\$\\ +\cs\AP\ Let \$g\cs{\intro*}\cs\circ\ f\$ denote the composition of functions.\\ {[...]}\\ -Now, each use of \$\cs\rho\$ points to its introduction. +Now, each use of \$\cs\circ\$ points to its introduction. \end{code} \noindent -The effect of \cs\renewmathcommand\ is that it sets~\cs\LaTeXrho\ to have the same effect as the original \cs\rho\ command, -and then redefines~\cs\rho. +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. \subsubsection{Context dependent variables} @@ -2505,19 +2713,6 @@ For obtaining this, this requires: \fi - -\subsection{Fixes} -\label{subsection:fixes} - -In this section, we present some fixes that have been added to help the user solve problems. - -\paragraph{Hyperref and twocolumn} It happens that the "hyperref@@package" and two-column mode together may yield a fatal error. This happens when a link spans across the boundary between two pages. This is an issue which is not related to the "knowledge@@package" package, but becomes severely more annoying when more links have to be used. -A \emph{workaround} can be tried by using using -\begin{center} -\smallcode{\cs\knowledgeconfigure\{""fix hyperref twocolumn""\}}. -\end{center} -I do not know to which extend it is compatible with various classes... - \subsection{Predefined configuration} \subsubsection{The "notion@@option" directive} @@ -2550,6 +2745,19 @@ A typical document using notion could start by the following commands: \end{code}\noindent Then the paper is displayed in a colorful way. + + +\subsection{Fixes} +\label{subsection:fixes} + +In this section, we present some fixes that have been added to help the user solve problems. + +\paragraph{Hyperref and twocolumn} It happens that the "hyperref@@package" and two-column mode together may yield a fatal error. This happens when a link spans across the boundary between two pages. This is an issue which is not related to the "knowledge@@package" package, but becomes severely more annoying when more links have to be used. +A \emph{workaround} can be tried by using using +\begin{center} +\smallcode{\cs\knowledgeconfigure\{""fix hyperref twocolumn""\}}. +\end{center} +I do not know to which extend it is compatible with various classes... \newpage \section{Some questions and some answers} @@ -2719,10 +2927,10 @@ and \cs\compAP\ for "complexity@@package", \subsection{Incorrect display} -\subsubsection{Incorrect breaking at the end of lines (in Arxiv for instance)} +\subsubsection{Incorrect breaking at the end of lines (in "arXiv" for instance)} It may happen that some hyperlinks generated by "knowledge@@package" are not broken properly -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. +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] @@ -2749,6 +2957,16 @@ Some classes, like \kl(package){acmart}, change the default color of the hyperli \cs\knowledgestyle\{"notion@@style"\}\{"color="black\}\\ \cs{\ fi} \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} +\cs\let\cs\LaTeXmarginpar\cs\marginpar\\ +\cs\def\cs\marginpar\#1\{\cs\LaTeXmarginpar\{\cs\textcolor\{black\}\{\#1\}\}\} +\end{code} + \subsection{Problems with scope} \subsubsection{Problems in combination with \cs{\bibitem} and "thebibliography@@env"} @@ -2818,6 +3036,7 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr \begin{compactdesc} \item[\cs\AP] introduces an "anchor point". \item[\cs\intro] searches for a \kl{knowledge} and put an anchor to it (to be used with the \kl{autoref} directive). +\item[\cs\kcref, \cs\kCref, \cs\kcpageref, \cs\kCpageref, \cs\knamecref, \cs\knameCref, \cs\knamecref] and \cs\knameCref\ display some information concerning the place of introduction of a "knowledge" as the \cs\cref, \cs\Cref, \cs\cpageref, \cs\Cpageref, \cs\namecref, \cs\nameCref, \cs\namecref\ and \cs\nameCref\ commands of the \kl(package){cleveref} package. \item[\cs\kl] searches for a \kl{knowledge} and displays it accordingly. \item[\cs\knowledge] defines new \kl{knowledges}. \item[\cs\knowledgeconfigure] configures the package. @@ -2828,6 +3047,8 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr \item[\cs\knowledgesetvariant] configures a "variant of \cs{\kl}". \item[\cs\knowledgestyle] defines a new \kl{style}. \item[\cs\knowledgevariantmodifier] declares a meaning of \cs{*} in "variants of \cs{\kl}". +\item[\cs\kpageref] displays the page number of a reference, +\item[\cs\kref] displays the number associated to a reference introduction. \item[\cs\nointro] declares that the knowledge will never be introduced (does not work properly yet). \item[\cs\phantomintro] performs an invisible \cs\intro. \item[\cs\reintro] uses the \kl{display style} of \cs{\intro} without introducing an anchor. @@ -2845,7 +3066,7 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr \begin{compactdesc} -\item["autoref"] Activates the \cs{\intro} feature (requires the "hyperref@@package"). +\item["autoref"] Activates the \cs{\intro} feature. \item["autoref link"] activates an hyperlink to the target. \item["autoref target"] puts a target for a hyperlink. \item[\kl{autorefhere}] creates an \kl{anchor point} that points to the \cs{\knowledge} command (Requires the \kl{hyperref option}). @@ -2875,6 +3096,7 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr if present. \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{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. @@ -2891,10 +3113,15 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr \item[\kl{wrap=}] A macro used to process the displayed text. \end{compactdesc} -\subsection{List of \kl{configuration directives} (to use with \cs{\knowledgeconfigure})} +\subsection{List of \kl{configuration directives}} \label{subsection:configuration directive list} +The following directives can be used as options when loading the package, or later using \cs{\knowledgeconfigure}. \begin{compactdesc} +\item["anchor point color="color] changes the color of "anchor point", +\item["anchor point shape="shape] changes the shape of "anchor points", in which shape can be \texttt{tiny corner}, \texttt{small corner}, \texttt{corner}, \texttt{large corner}, + \texttt{tiny cross}, \texttt{small cross}, \texttt{cross}, \texttt{large cross}, or some code to be execute in the "picture@@env" environment, +\item["anchor point shift="\{$x$,$y$\}] shifts the "anchor point" (in \texttt{em} unit), \item["diagnose bar="\textmd{\{true,false\}}] activates the \kl{`\vbar'-notation} in the "diagnose file" (default is false) \item["composition"] switches to "composition mode", \item["cyclic colors=@@option"] fixes the cyclic list of colors used by the "directive" "cyclic color". |