Index of /CTAN/macros/latex/contrib/knowledge

(1)

The knowledge package

[v1.28 — 2022/02/12]

Thomas Colcombet [email protected]

February 12, 2022

Abstract

Theknowledgepackage offers commands and notations for handling se- mantical 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.

Status of this version

contact: [email protected] version: v1.28

date: 2022/02/12(documentation produced February 12, 2022) license: LaTeX Project Public License 1.2

web: https://ctan.org/pkg/knowledge CTAN: https://www.ctan.org/pkg/knowledge

(2)

1 History

2016-06-07 \knowledgemacrois now renamed to\knowledgedirective.

2017-01-13 \APhas been recoded, and is now more properly aligned in the margin. The visible anchor points option has also been made usable without the xcolor package.

2017-01-13 The packagescope optioncan now be omitted. This in particular avoid clashes with the over-restriction on the structure of the document it entails. It should be improved to stop overloading the\begincommand.

2017-01-14 The overloading of \begin and \end was done as protected commands, which should not be the case to be consistent with the behaviour of LaTeX (for instance, this was giving an extra line in the title in the conference mode of the class IEEEtran). Corrected: these commands are not protected anymore.

2017-01-15 A workaround for an incompatibility between the hyperref and the twocolumn mode as been added in the macro \knowledgeFixHyperrefTwocolumn-

(thanks to Daniela Petrişan).

2017-01-15 Added thedirectivesynonym.

2017-01-15 Added the noknowledge packagefor minimizing the effects of not having knowledgeactivated.

2017-01-17 Changed the way options are handled, decoupling the package options (options of\usepackage) from the configuration options (see\knowledgeconfigure).

2017-01-17 Proper treatment of ‘final’ option andcompositionoptions.

2017-01-17 Added\IfKnowledgeFinalMode[TF]commands for the user.

2017-01-17 Added the optionfix hyperref twocolumnas a shorthand for calling\k- nowledgeFixHyperrefTwocolumn(thanks to Daniela Petrişan and Luca Reggio).

2017-01-18 Added the configuration option notion that offers a basic configuration compatible withxcoloror not, andfinalandcompositionmodes.

2017-01-19 Added\phantomintroand an explanation on how to deal withalign*.

2017-02-20 Removed the warnings of latex for unknown labels inautoref.

2017-02-20 Removed nasty error making \AP not operative when anchor points were not visible.

2017-02-21 Added theprotect linkdirective.

2017-02-21 Added thehyperlinks=configuration.

2017-02-27 visible anchor pointsis active by default now.

2017-02-27 A simple example is now included.

2017-02-28 Minor changes on the documentation.

2017-02-28 Added thescopeenvironment.

2017-02-28 Added theprotect linkandunprotect linkconfiguration directives.

2017-02-28 Added the\knowledgeconfigureenvironmentcommand.

2017-03-03 Added thebreaklinksfaq (thanks to Luca Reggio for the request).

2017-03-10 Added the"· · ·"and""· · ·""notations and thequotationmode (requested by Gabriele Puppis and Andreas Krebs).

2017-03-11 Added the"· · ·@· · ·"and""· · ·@· · ·""notations.

2017-03-13 Corrected for being compatible with version of expl3 posterior to Mars 2015 (\c_sys_jobname_strdoes not exist anymore). (Thanks to Jean-Éric Pin).

2017-03-14 Corrected that the @letter was left a letter after\knowledgeFixHyperre- fTwocolumn.

2017-04-09 Internal change of code, forscopehandling and for thequotation notation:

slowly going toward an extendedquotation notation that can make thescopeof search explicit.

(5)

2017-04-09 Added theprotect quotationconfigure option, that is given a list of environments, and deactivates automatically the quotation notationwhen in there environments. This is a simple code for the moment. Typically, one can use

\knowledgeconfigure{protect quotation=tikzcd}. For the moment, it is not explained in the document.

2017-04-19 Changed the display code such that nested knowledges behave properly:

before, the introduction would be performed for the object and the subobjects.

2017-04-20 The electronic mode has been added, and the ‘final mode’ is now renamed into paper mode. The \knowledgepackagemode configuration variable is also available for easier scripting.

2017-06-06 FAQ on deactivating the quote inEmacs(thanks to Sylvain Perifel).

2017-06-08 Removed thenoknowledgepackage and all references to it.

2017-06-08 Removed theknowledgeutils.styand scopearticle.stywhich are now integrated in the main file.

2017-06-08 The fileknowledge-example.texhas been improved.

2017-06-09 First release of version 1.0 onCTAN.

2017-06-10 Corrected thequotation notationto make it expandable for avoiding problems in table of contents (the @ was not working).

2017-06-11 Corrected a bug linked to changes of expl3 on recent distributions (pointed by Murray Eisenberg). Release of v1.01 on CTAN.

2017-06-27 Overloaded labels now perform an expansion of the argument (this was causing problems with biblatex).

2017-06-28 Optionslog-declarationsofxparsepackage removed (causing clash with other packages, as pointed by Juliusz Chroboczek). Release of v1.02 on CTAN.

2017-06-30 added the field labelizable_bool to areas. Coded missing features of scoping. Now thescope= directive works with as parameter an enclosingarea, or a label.

2017-06-30 Added in the source a Regression subdirectory containing files to be tested (so far only one: regression-scope.tex)

2017-07-01 Corrected a conflict between thescopeandmakeidxoption.

2017-07-03 Scoping becomes operational.

2017-07-04 The documentation for notion and intro notion are added (thanks to Fabian Reiter).

2017-07-09 Added boolean environment_bool field to areas, in order to resolve an incompatibility with the packagestandalonenoticed by Fabian Reiter.

2017-07-20 Scoping becomes fully operational, with the parenthesis notation of \kl and\intro. The use of scope has been recoded. Now scope links reuse implicitly the key as a link. Documentation updated.

2017-07-26 File and line numbers added in thekaux file. Added the option diagnose line=to deactivate it.

2017-07-26 Corrections to the documentation. Version 1.03 on CTAN.

2017-07-28 Corrected a bug of scoping in the context of synonyms. Added ctan for producing the ctan zip file.

2017-08-06 Now passes the compliance testcheck-declarationsof expl3(thanks to Marc Zeitoun)

2017-09-12 Thehidelinksoption of hyperrefis now always activated.

2017-09-25 Ancient version of xparsedoes not have\NewExpandableDocumentComma- nd. Corrected. Version 1.05 onCTAN.

2017-10-10 Bug in the implementation of\knowledgenewvariant(that was invisible for

(6)

older versions of expl3). Found and corrected (thanks to Marc Zeitoun). Version 1.06 onCTAN.

2017-10-15 Diagnose extended (suggested by Fabian Reiter). Minor corrections. Ver- sion 1.07 onCTAN.

2017-10-17 Addedcyclic colorandcyclic colors=. Reorganization of the structure of the code for producing a betterCTANarchive. Version 1.08 onCTAN.

2018-01-31 Added thestrictconfiguration option.

2018-02-05 Added thesmallcapsformatting directive.

2018-02-17 Corrected incompatibility with latest version of expl3. Version 1.10 on CTAN.

2018-02-21 Bug correction concerning the activation of scopes.

2018-02-21 Documentation improvement forEmacs(thanks to Michặl Cadilhac).

2018-02-24 Documentation improvement for the environmentthebibliography.

2018-05-17 Correction to be compatible with the latest version of expl3 (thanks to Leo Stefanesco).

2018-07-26 Compatibility with utf8 symbols in labels (thanks to Yves Guiraud).

2018-11-22 Corrected bug formakeidx(thanks to Sylvain Schmitz). V1.14 onCTAN.

2019-01-27 Minor improvement of the doc, and hiding links in it. V1.15.

2019-02-15 Correction of a placement problem with\AP. V1.16.

2019-05-23 Adding of the ‘|’-notation for the\knowledge command. Explicit scopes are introduced. Updating of the documentation. up directive in math mode now silently does nothing, and\knowledgedirectivenow forbids redefinitions by default (thanks to Léo Stefanesco).

2019-07-02 Removing the ‘kl’ and ‘intro’ styles that prevented a proper configuration of intro notion(thanks to Léo Stefanesco).

2019-10-03 Update of the documentation, and V1.17.

2019-10-27 Bug correction and added the ‘patch label’ configuration directive (thanks to Rebecca Turner). V1.18.

2019-11-19 Now the labels are evaluated before being written to the kaux file in a

\KAuxNewLinkScopetagInstancecommand (bug fix). V1.19.

2019-11-29 Help added in thediagnose file. bar suggestion(still working) renamed to diagnose bar, and activated by default. patch labelis renamed into label scope.

2019-12-02 The kaux file is now checked for completeness before being used. This should avoid errors when the previous compilation failed.

2019-12-03 Corrected bug in the scope access. V1.20.

2020-01-25 Corrected bug whenknowledgeis used withouthyperref(thanks to Rémi Nollet).

2020-01-25 Corrected bug that made the kaux file not stabilize (thanks to Rémi Nollet).

V1.21 on CTAN.

2020-03-05 Nowhidelinksandbreaklinksare automatically activated unless the new optionno patchis activated. Doc update. V1.22 on CTAN.

2020-04-25 Made the package compatible with 2016 versions of LaTeX. Useful when knowledge.styis included with and compile in arXiv. V1.23 on CTAN.

2020-05-02 Doc update (acmartcolors, thanks to Daniela Petrişan).

2020-09-22 Adding the silent option as suggested by Patrick Lambein-Monette.

V1.24.

2021-03-31 Correcting a bug caused by a change of semantics inexpl3. V1.25.

2021-05-25 Added the\kref,\kpageref,\kcref, and\kCrefcommands as suggested by Ziv Scully.

(7)

2021-05-26 Corrected wrongly used default parameter in\knowledgedirective.

2021-05-27 The explicit text given in a\kl-command now overrides thetext=directive.

2021-07-18 Adding theno index directive.

2021-12-20 Adding optionsanchor point shape,anchor point color,anchor point shift(request of Rémi Morvan).

2021-12-27 Bug correction for corner shape, and doc update (thanks to Rémi Morvan).

2022-01-12 Minor changes. Removing dead link for the webpage. V1.27

2022-02-12 Adding support of imakeidx and the directiveindex name=(request and code change by Maximilian Keßler). V1.28

(8)

2 Quick start

The knowledge package offers several capabilities for handling colors, changing the display style, defining internal and external hyperlinks, producing an index, etc... All these possibilities arise from defining explicitly or implicitlyknowledges associated to terms in plain english (or other languages).

We start by describing a certain number of problems/scenarii that a user may be confronted to, and show how to solve them. In the subsequent sections, a more detailed account of how thepackageworks and can be parameterized is given.

There is also a file knowledge-example.tex that can be used as a starting point.

2.1 Linking to outer documents/urls, and to labels

The problem 1 I have a lot of external url’s that I would like to [[very] often] have a link to, but I do not want to always type the full url. I do not want to remember weird labels/internal references/macro names either.

A solution is as follows. One first loads the knowledge package with option hyperrefusing either:

Hint. You may use other options like xcolor for al- lowing debugging with colors (for undefined knowledges).

\usepackage[hyperref,quotation]{knowledge}

or equivalently:

\usepackage{hyperref}

\usepackage[quotation^a]{knowledge}

aIf you want to use the"· · ·"notation.

Then, in the preamble (or in an external file), one uses commands of the form either:

\knowledge{url={https://en.wikipedia.org/wiki/LaTeX}}

| latex

This configures the text ‘latex’ to be associated with the sole directive url=, which means an hyperreference to this address.

Finally in the body of the paper, the sole extra command\kl(or the "-symbol if thequotationoption is activated) is used, with as parameter a text. This text is searched for, and the directives attached to it (hereurl=), are used for formatting its printing¹. Hence:

Hint. If the knowledge is not defined, this does not make the compilation fail. In fact, it is good practice to use many \kl commands or

"· · ·"notations while writing a text, and only resolve these questions at the end (see also

This package has been written for use in \kl{latex}.

or, if thequotationoption is activated,

1This resembles a lot a macro so far. It nevertheless differs in that: (a) if not defined, it does not make the compilation fail as a macro would, and thus does not interfere with the writing process, (b) any text can be used and not only alphabetic letters as in default TEX, (c) you do not have to care about the space after, and (d) in fact the machinery for resolving the meaning of a knowledge is much more powerful than simple macro expansion.

(9)

This package has been written for use in "latex".

yields

This package has been written for use in latex.

Variation. But in fact, I would like ‘latex’ to also be properly typeset L^ATEX, and ingray. This requires to load the package with thexcolor option (for being able to use colors, obviously), or by loading the packagexcolorbefore, and then modify the\knowledge command using extradirectives:

\knowledge{url={https://en.wikipedia.org/wiki/LaTeX}, text=\LaTeX, color=gray}

| latex

yields with the same text

This package has been written for use inL^ATEX. Thedirectivestext= andcolor=have quite obvious meaning. Directivescan also control the style usingemphasize,boldface,italic,typewriterand so on.

See Section 5.3 for a complete list ofdirectives.

Variation (synonyms). It happens very often that there are several ways to name a notion, because of capitalized letters, conjugacy, grammar, or simply because it is not explicitly named in the text. There are two ways to resolve this issue. The first is to use the syntax

\kl[knowledge]{text} or "text@knowledge"

the result is that the text ‘text’ is displayed, but urls, colors, etc from ‘knowledge’ are used.

Another more systematic way to do it is to declare synonyms. This obtained by adding the corresponding lines:

\knowledge{url=...}

| Donald Ervin Knuth

| Donald Knuth

| D. Knuth

| Knuth would allow

\kl{Knuth} as well as \kl{Donald Knuth}, or simply "Knuth" as well as "Donald Knuth" and so on

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:

(10)

\knowledge{url=https://en.wikipedia.org/wiki/Group_(mathematics)}

| group

| groups

| Groups

| group morphism

| group morphisms

| Group morphisms

| morphism@GROUP

| morphisms@GROUP

| Morphisms@GROUP

makes it possible to use the notions in many contexts:

"Groups" form a category when equipped with "group morphisms".

Consider now some "morphism@@GROUP" $\alpha$ ...

In the above code all quoted parts send the reader to the same wikipedia page about groups. Note in particular that "morphism@@GROUP" simply displays

‘morphism’ at compilation. The GROUP part is a scope. In another part of the document, "morphism@@RING" can be safely used whereas using an generic

"morphism" would become quickly unmanageable.

2.2 Linking inside a document

The problem 2 I am writing a scientific document with many different definitions, typically a journal article, a PhD thesis², or a book.

I would like all the notions to be linked inside the document for being able in one click, whenever something is used, to jump to its definition. I also want to easily write an index. However, I do not want it to be a hassle when writing.

A solution is as follows. First load theknowledgepackage in the preamble:

\usepackage[xcolor,hyperref,notion,quotation]{knowledge}

with suitable options: hyperreffor links,xcolorfor colors (if required, but always advised),quotationfor using the quotation notation andnotion for automatic configuration of thenotiondirective.

Then write the document using\intro(or""· · ·""if quotationis activated) when a notion is defined/introduced, and\kl(or"· · ·"ifquotationis activated) Hint. Using an \AP com-

mand 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...

when it is used. For instance:

\AP A \intro{semigroup} is an ordered pair $(S,\cdot)$ in which

$S$ is a set and $\cdot$ is an associative binary operator over $S$. A \intro{semigroup morphism} is [...]

[...]

Consider a \kl{semigroup morphism} between \kl{semigroups} $S$

and $T$. [...]

2Reviewers should appreciate...

(11)

or when thequotation notationis activated:

\AP A ""semigroup"" is an ordered pair $(S,\cdot)$ in which $S$

is a set and $\cdot$ is an associative binary operator over $S$.

\AP A ""semigroup morphism"" is [...]

[...]

Consider a "semigroup morphism" between "semigroups" $S$ and $T$.

[...]

This yields Note that the \APcommand

is made visible thanks to a red corner. This red corner is shifted left in order to fall in the margin.

A semigroup is an ordered pair (S,·) in which S is a set and · is an associative binary operator overS. Asemigroup morphismis[...]

[...]

Consider asemigroup morphism betweensemigroups S andT. [...]

Undefined knowledges also yield warnings during the compilation. These can be avoided using thesilentop- tion.

Undefined knowledgesare displayed in orange the first time, and in brown the subsequent ones (it is an important feature that the compilation does not fail: undefined knowledges should not interfere with the main activity of the writer which is writing). One can now see the list of such problems in the file ‘filename.diagnose’, in particular in the‘Undefined knowledges’ section:

\knowledge{ignore}

| semigroup

| semigroups

| semigroup morphism

which means that the strings ‘semigroup’, ‘semigroups’ and ‘semigroup morphism’ are used but unknown knowledges.

To solve this, let us copy these four lines in the preamble³, replacing ignore by thenotiondirectiveand separating it into two blocks. We obtain:

\knowledge{notion}

| semigroup

| semigroups

\knowledge{notion}

This informally means that ‘semigroup’ and ‘semigroups’ are two strings that represent the same notion, and that ‘semigroup morphism’ is a different one.

The result is then (after two compilations):

Note that the \APcommand is made visible thanks to a

red corner. A semigroup is an ordered pair (S,·) in which S is a set and · is an associative binary operator overS. Asemigroup morphismis[...]

[...]

Consider asemigroup morphism betweensemigroups S andT. [...]

3It is good practice to use a separate file, something like ‘paper-knowledge.tex’.

(12)

Clicking on ‘semigroups’ now jumps to the place where it was introduced, and very precisely at the location of the red corner depicting the presence of the\- AP-command before. The same goes for ‘semigroup morphism’. If now one adds the optionelectronic while loading the package, then the red corners disappear as well as the undefined knowledges which become black. When using the option paper, the links are still there, but all texts are in black.

A more complete example would look as follows:

\knowledge{notion}

| semigroup

| semigroups

| Semigroups

\knowledge{notion}

| semigroup morphisms

| morphism@SG

| morphisms@SG

The most interesting part consists of the two last lines. These define ‘morphism’ and ‘morphisms’ to represent the same notion as ‘semigroup morphism’ when in the scope ‘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 Take a \kl{morphism} ... would yield an unknown knowledge. However, Take a \kl(SG){morphism} ... or

Take a "morphism@@SG" ... would yield

Take amorphism...

which is properly linked to a semigroup morphism. One can in particular imagine that "morphism@@RG" would instead represent ring morphisms.

Sometimes, one does not want to expand the knowledge base because the word is not specific. For instance These \kl[semigroup]{algebraic objects} [...], or These "algebraic objects@semigroup"} [...], yields

Thesealgebraic objects[...]

The term is properly linked to the definition of semigroups.

Another possibility is to refer to the location of the definition, using commands

\kref,\kpageref, and even better their improvements\kcref,\kCref, etc (when using thecleverefpackage). For instance,

"Semigroups" are introduced in \kCref{semigroup}, Page \kpageref{semigroup}.

yields:

Semigroupsare introduced in Section 2.2, Page 11.

(13)

Finally, in particular for large documents, it is good to have anindex. For this, one should load the package makeidxbefore knowledge. Then use it normally:

putting\makeindexin the preamble and\printindexat the end of the document.

Finally, theknowledgecommands are adapted in a straightforward manner:

\knowledge{notion,index=semigroup}

| semigroup

| semigroups

| Semigroups

\knowledge{notion,index=semigroup morphism}

| semigroup morphisms

| morphism@SG

| morphisms@SG

Now, the index (after runningmakeindex) contains all entries and references to the use of semigroups and semigroup morphisms.

See Section 3.8.3 for more details on making an index.

2.3 Mathematics

The examples above show various techniques for usingknowledgesfor enhancing the information associated to terms. In fact, these techniques are not incompatible with mathematics. Some special syntax is even offered:

\knowledgenewrobustcmd\closure[1]{\cmdkl{\langle}#1\cmdkl{\rangle}}}

[...]

The closure of $X$ under product is denoted $\intro*\closure{X}$.

[...]

Consider now $\closure{\{a,b,c\}}$.

would yield:

The closure ofX under product is denotedhXi. [...]

Consider nowh{a, b, c}i.

The problem 3 But I want more. I want to be able to introduce variables. Even better, I would like to be able to have variables hyperlinking to the place of their introduction, knowing that the same variable name may mean different things depending on the lemma or proof we are in. Hence, I want to properly control the scope of knowledges.

To be done, this requires to use scoping. The principle of scoping is that a knowledge can be 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.

(14)

The following code gives an idea of what is possible usingscoping:

\knowledgeconfigureenvironment{theorem,lemma,proof}{}

[...]

\begin{lemma}\label{theorem:main}

\knowledge{n}{notion}

For all number $\intro n$, [...]

\end{lemma}

[...]

Here $\kl n$ is an undefined knowledge.

[...]

\begin{proof}[Proof of theorem˜{theorem:main}]

\knowledgeimport{theorem:main}

Inside the proof, $\kl n$ is hyperlinked to the theorem...

\end{proof}

More onscoping can be found in Section 3.5.

The use ofvariants of \klis also useful for typesetting mathematics. It allows for instance, to implicitly execute the\knowledge command at the same time of the introduction. See 3.4.4 for more detail.

(15)

3 Usage of the knowledge package

3.1 Options and configuration

Options are used to activate some capabilities. Some options have to be used when loading theknowledge package, while some others can also be used inside the document thanks to the use of \knowledgeconfigure. In this section, we review thesepackage options.

3.1.1 Options at package loading

The options that can be used in the optional parameter of \usepackage when loading theknowledgepackage belong to the following classes:

Writing mode The paper, electronic or composition modes are possible (composition is by default) (see Section 3.1.2 for more details). These modes change several rendering settings.

Other packages some of the options concern the loading and the use of other packages (hyperref, xcolor, makeidx, imakeidx, cleveref, . . . ). Note that these package can also be loaded beforeknowledge. This is explained in Section 3.1.3.

Configuration options as used by the command\knowledgeconfigurecan be used when loading the package.

Scoping Thescopeoptionmakes the package aware at a fine level of the structure of the document (see Section 3.5 for explanations). This provides, for instance, the possibility to define pieces ofknowledgethat are attached to a sections of the document.

Other Theno patchoption prevents theknowledgeto apply some patches that are convenient by default.

3.1.2 Writing mode

There are threewriting modesusable when loading the packageknowledge:

• In paper mode, the paper is rendered as for printing: in particular, no informative colors are visible. Hyperlinks are nevertheless present.

• Inelectronicmode, the document has some colors witnessing the existence of the links for the reader to know that clicking is available.

• In composition mode (the default), the document has colors helping the writing: undefined knowledgesappear explicitly,anchor pointsare displayed, and so on.

Activating the modes is obtained either at load time using one of:

\usepackage[paper]{knowledge}

or \usepackage[electronic]{knowledge}

or \usepackage[composition]{knowledge}

(16)

or by setting before loading the variable\knowledgepackagemodeas in:

\def\knowledgepackagemode{paper}

The idea is that this can be used in automatic compilation scripts. For instance, using in a terminal:

pdflatex "\def\knowledgepackagemode{electronic}\input{file.tex}"

would result in compiling ‘file.tex’ using knowledgein electronic mode. The following primitives are available to the user for writing mode-sensitive configuration:

\IfKnowledgePaperModeTF{true code}{false code}

\ifKnowledgePaperMode true code [\else false code] \fi

\IfKnowledgeElectronicModeTF{true code}{false code}

\ifKnowledgeElectronicMode true code [\else false code] \fi

\IfKnowledgeCompositionModeTF{true code}{false code}

\ifKnowledgeCompositionMode true code [\else false code] \fi

3.1.3 Automatic loading of other packages

A certain number ofpackage optionscoincide with the loading of other packages.

For the moment, the packages that are concerned arehyperref,xcolor,makeidx, andimakeidx.

For activating these functionalities, it is sufficient, either to load the packagebe- foretheknowledgepackage, or to name it explicitly as anoptionforknowledge. Loading separately the package is convenient for setting options for it. For instance, a typical preamble may look like:

\documentclass{article}

\usepackage[svgnames]{xcolor}

\usepackage[draft]{hyperref}

\usepackage[makeidx]{knowledge}

Such a sequence will activate the knowledge package using the features related toxcolor configured withsvgnamesoption, to hyperrefconfigured withdraft option, and tomakeidxwith its standard configuration.

In fact, the syntax when a package is loaded as an option of knowledgeis of the form ‘package=choice’ in which choice can take the following values:

active The package will be loaded, and all the capabilities that it triggers are activated. This is the implicit meaning when nothing more is specified.

inactive The package is not loaded, and no capabilities are activated (even if it had been loaded previously by another\usepackagecommand).

compatibility The package is not loaded. The directives it uses do not cause any error, but have no effect.

(17)

auto If the package was loaded before, then the associated capabilities are activated. This is the default behavior when the package is not named while loading.

Currently, the packages that can be loaded are:

hyperref which activates all the (auto)referencing capabilities.

xcolor which activates coloring commands.

makeidxand imakeidx for handling the index automatically.

3.1.4 Configuring and \knowledgeconfigure

Some part of the configuration can be done outside of the\usepackagecommand that loads theknowledgepackage. This is done using the\knowledgeconfigure command:

\knowledgeconfigure{configuration directives}

Note that by default, the configuration directives used by \knowledgeconfigure can be used in the optional parameter of \usepackage when loading the knowledgepackage, but the converse is not true. Configuration directivesconsists of a comma separated list of elements that can take the following values:

diagnose bar= (de)activates the‘|’-notationin thediagnose file. True by default.

diagnose help= can be set to true or false. It activates or deactivates the help in thediagnose file. True by default.

diagnose line= can be set to true or false. It activates or deactivates the line numbering in thediagnose file. False by default.

fix hyperref twocolumn triggers a hack that solves a known problem that may occur whenhyperrefis used in two-columns mode.

label scope enables or disables the redefined \label command, which helps automatically define scopes (default is true).

notion configures thenotiondirectivewhich is a refined version of autoref. protect quotation= is followed by a comma separated list of environments in

which thequotation notationwill be automatically deactivated (surrounded by braces if more than one item in the list).

protect linkand unprotect link starts and ends respectively a zone in which theknowledgepackage do not create hyperlinks. These can be nested. This is typically useful around, e.g. the table of contents.

quotation activates thequotation notation, which allows to use"· · ·","· · ·@· · ·"

and"· · ·@· · ·@· · ·"instead of\klcommands and""· · ·"",""· · ·@· · ·""and

""· · ·@· · ·@· · ·""instead of the\introcommand.

(18)

silent is a Boolean option which, when activated, switches off all warnings during the compilation, but the recap ones at the end.

strict is a Boolean option which, when activated, turns some warnings (for instance when a knowledge is redefined) into errors.

visible anchor points is an option that makes visible or invisible theanchor pointsof the\APand\itemAPcommands. Usually, this is automatically set to true when thecomposition modeis used (the default), and to false when thepaper modeor theelectronic modeare used.

3.1.5 Other configuration option

no patch deactivates some patches which otherwise are applied automatically.

Currently, the optionhidelinksandbreaklinks of the packagehyperref are automatically applied, unless no patchis used while loading the package. Without hidelinksthe links in the document are surrounded by red or light blue boxes (it depends also on the pdf viewer): while this may be acceptable when links are seldom used, this becomes problematic in combination with the knowledgepackage. Withoutbreaklinks, links are not broken as normal text: this may corrupt the appearance of paragraphs, in particular in a multi column context.

3.2 What is a knowledge?

A knowledge is often informally used in this document. Essentially, it captures what is an elementary concept in the document. Internally, aknowledgeis identified by three components:

The knowledge name is a TEX string that has almost no limitation (but being well balanced, and containing no ]). It is the text entered by the user for defining and using theknowledge.

The scope which is a simple string identifying where the knowledge is usable.

Scopes can be created by the user, or automatically generated by the system.

For instance, internally, each section will be uniquely named ‘section-1’,

‘section-2’, and so on (this is invisible for the user). Each knowledge is primarily valid in exactly one such scope. Knowledges defined in the preamble are given thescope‘document’.

The namespace is a simple string that is used for avoiding clashes. It is most of the time simply ‘default’. It is ‘style’ for styles(that are internally as knowledges). It is a possibility available to a developer to, when creating a new set of functionalities, use a differentnamespace for avoiding clashes of names (for instance if one wants a french and an english set of knowledges that should not conflict, and would use separate sets of macros). Usually, a normal user does not seenamespaces.

(19)

3.3 The \knowledge command and variations

In this section, we describe the main commands that createknowledges. The main one is\knowledge. It can also be used in combination with\knowledgedirective,\knowledgestyleand\knowledgedefault.

3.3.1 General description of the \knowledge command

The key command for introducing knowledges is \knowledge. There are two syntaxes. The standard one is:

\knowledge{knowledge name}[synonym 1|synonym 2|...]{directives}

The second one is the‘|’-notation⁴:

\knowledge{directives}

| knowledge name@optional scope

| synonym 1@optional scope

| synonym 2@optional scope

· · ·

Theknowledge nameas well as thesynonymsare 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 knowledge. Note (and this is a standard TEX behavior) that several consecutive spaces is the same as one or a line feed. In the normal syntax,synonymsare given in a ‘|’ separated list, while in the‘|’-notationeach of them has to be in a distinct line. In the ‘|’-notation, an optional scope can be given after each knowledge name/synonym.

The directives consists of ‘key=value’ statements in a comma separated list.

There are manydirectives. A list of them can be found in Section 5.3. New ones can be defined using the\knowledgedirectivecommand.

The principle of the \knowledge command is to introduce a new knowledge, ready for being used. However, what it does exactly depends a lot on the situations. First, thedirectives (a comma separated list of ‘key=value’ commands) are parsed, and from it, the namespace and scope of the knowledge are determined, and it is decided if it will be defined immediately or postponed to the next compilation phase (using thekaux file).

3.3.2 Targeting and the corresponding directives

The\knowledge has to decide what to do when defining something. The basic behaviour is as follows.

4This is a non-standard L^ATEX syntax. The rule is that each knowledge appears in a distin- guished line that starts with some spaces and a ‘|’, and ends at the end of the line. 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.

(20)

• If the \knowledge command is used in the preamble, then the knowledge given as argument is defined immediately (the same effect can be obtained using the now directive), and is accessible in the first compilation phase everywhere in the document (one extra phase is nevertheless required if autoref or ref= directives are used, for the hyperref to do its job, or if scope=is used). This is the simplest way to use\knowledge.

• Otherwise, the knowledge is written in an external file (the jobname.kaux file), and theknowledgewill be really usable in the next compilation phase.

This is particularly useful in conjunction with thescope option: theknowledgewill have a scope depending on where it is introduced (for instance the document, or a theorem, or a lemma). The sameknowledge namecan then point to differentknowledgesdepending on where it is used.

• Exporting (not implemented) furthermore writes a document containing a list of \knowledge commands giving access to its content. This is to be imported by another document.

Thetargeting directivesrefine the above defined behaviour:

scope=or ‘@’ in the ‘|’-notation When using a directive ‘scope=name’ or

‘@name’ in the ‘|’-notation, the scope of the definition can be modified.

\knowledgewill first check if there is an outer areaof this name (theorem, section, . . . ), that accepts knowledge (only scope environments are sub- ject to this unless\knowledgeconfigureenvironmentis used, or thescope package option is used when loading the package). If this is the case, the knowledge will be associated to the correspondinginstance. For instance, inside a theorem, by default, the scope is the theorem, but adding the directive

‘scope=section’, theknowledgebecomes available in the whole section.

If no scope is found using the above search, an explicit scopeof the given name is used.

export= (not implemented) When using this directive, the knowledge will be (furthermore) written to another file, ready for being used in another document.

In particular, the knowledge (in the other document) will point to the present one. The details on how this is supposed to work is to be specified.

namespace= Allows to change the namespace. In itself, this is useless. It has to be used in conjunction with new forms of \kl-like commands.

now requires theknowledge to be defined immediately. This may save one compilation phase. The drawback is that the knowledge cannot be accessed before the\knowledgecommand that has been introduced. It may help for modularity considerations. (for instance aknowledgeis used inside a proof, it makes no sense to make it available elsewhere, and it is better style to locally define it). This is implicit if the \knowledge command happens in the preamble.

(21)

also now requires the knowledge to be defined immediately as well as delayed to the next compilation phase. This is in particular howauto references should be handled. See the use of \knowledgenewvariantfor more examples.

3.3.3 General directives

We give here the list ofdisplay directives that are available without loading any sub packages. A certain number of Boolean directives are available without any options. These most of the time are used for typesetting the output. Each of these can be used as ‘bool=true’ (or shortly just ‘bool’), ‘bool=false’ or

‘bool=default’ (that leaves it in the default state, or the one determined by surrounding knowledges). The general booleandirectivesare the following:

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 in Section 3.8.2). This can also be used for constructing the index (see the makeidx and in imakeidxSection 3.8.3). It can simply be used for referencing the number of the environment or the proper page of introduction (see\krefand\kpagerefcommands and their more powerfulcleverefin Section 3.8.4).

autorefhere puts immediately a label at the location of the definition, and makes all\kloccurrences of this knowledgehyperlink to this location.

emphasize forces the text to be emphasized using ‘\emph’, italic/up forces/unforces italic (updoes nothing in math mode), boldface/md forces/unforces boldface (be it in math or text mode), smallcaps forces small capitals,

underline forces the text to be emphasized using ‘\underline’, fbox puts a box around the text,

typewriter puts in typewriter font (be it in math or text mode),

ensuretext guarantees that text mode is used (using the ‘\text’ macro, thus in a way consistent with the surrounding style),

ensuremath guarantees that math mode is used,

mathord, mathop, mathbin, mathrel,mathopen, mathclose, mathpunct yield the corresponding standard TEX spacing features in math mode,

mathord for an ordinary mathematical object, mathop for a large operator (such asP,Q, . . . ),

mathbin for a binary operation (such as+,−, or⊗, . . . ),

(22)

mathrel for a binary relation (such as=,<,≤, . . . ), mathopen for an opening bracket, parenthesis, . . . mathclose for an closing bracket, parenthesis, . . . mathpunct for a punctuation symbol.

lowercase puts the content in lowercase, uppercase puts the content in uppercase,

detokenize detokenizes the content, i.e., instead of executing it provides a string that displays it (this is useful for commands),

remove space removes the spaces from the text invisible prevents the rendering of the knowledge.

The non-boolean generaldirectivesare the following:

text={text} will execute the L^ATEX code ‘text’ instead of the key used for calling

\kl. For instance, \knowledge{latex}{text=\LaTeX} will typeset ‘L^ATEX’

properly when used. Surrounding braces can be omitted if there are no commas. Be careful when linking to such knowledges, since the substitution of meaning will happen for all the knowledges linking to it, and this may not be the expected behaviour.

link={knowledge} will continue searching the for linkedknowledge. Surrounding braces can be omitted if there are no commas. This directive is often bypassed by the use of theoptional argumentof\knowledgedefining synonyms or thesynonymdirective.

link scope={label} will continue searching in the scope identified by the label.

Surrounding braces can be omitted if there are no commas. If nodirective link=is given, then the same key is searched for.

This directive is often bypassed by the use of theoptional argumentof \k- nowledgedefining synonyms or thesynonymdirective.

synonym defines the knowledge as a link to the previously defined knowledge (in fact, the most recently defined that was not usingsynonym). For instance

\knowledge{Leslie Lamport}

{ref={https://fr.wikipedia.org/wiki/Leslie_Lamport}}

\knowledge{L. Lamport}{synonym}

\knowledge{Lamport}{synonym}

results in the two subsequentknowledge namesto point to the first one.

style={knowledge style} will adopt the styling option of the knowledge style.

Surrounding braces can be omitted if there are no commas.

wrap=\token will execute the macro ‘\token ’ with as argument the knowledge text before displaying it. For instance, wrap=\robustdisplay, (where \r- obustdisplayis a variant of \tl_to_str:nremoving the trailing space) is used in this document for typesetting the commands.

(23)

3.3.4 Knowledge styles and the \knowledgestyle command

Styles are formatting pieces of information, as for knowledges, but that can be used by otherknowledges. In some respect, this is very similar tomacro directives (see below), but the difference lies in thatstyles are dynamically resolved, while macro directives are statically resolved. Styles in particular offer the access to some configuration features of the system. For instance, changing theintrostyle changes the way the\introcommand is displayed. See below for some instances.

The central command is\knowledgestyle, that has the following syntax:

\knowledgestyle*{style name}{directives}

The optional star* permits to overload an existing style (otherwise, this results in an error). The directivesfollow the same structure as for a normal \knowledge command. When defined, a style can be used in a \knowledge command using thedirectives‘style=style name’ (it will be used when a\klcommand calls for the knowledge) or ‘intro style=style name’ (that will be used by \intro commands).

A certain number ofdefault styles are also offered, that in particular includes warning styles. The list is as follows:

kl is the default style for macros using\kl. It can be modified dynamically using the ‘style=’directive.

kl unknown and kl unknown cont are the defaultstylesused when an undefined knowledgeis met.

introand is the default style for macros using \intro. It can be modified dynamically using the ‘intro style=’directive.

intro unknownand intro unknown cont are the default styles used when an undefinedknowledgeis met.

3.3.5 New directives: the\knowledgedirective command

When definingknowledges, it is often the case that the same sequence of directives are used. Macro directives are here for simplifying this situation (see also\know- ledgedefaultand\knowledgestyle). This is achieved using the\knowledged- irectivemacro:

Hint. This should not be confused with styles which offer another way to control the display.

\knowledgedirective*{name}[optional parameter]{directives}

After execution of the command, ‘name’ becomes adirectiveusable in\knowledgecommands, that amounts to execute the comma separated list ‘directives’. The newly createddirectivemay receive a value, that is accessible as#1in ‘directives’.

By default, it does not allow the redefinition of a directive. This can be forced using the optional*. The ‘optional parameter’ gives a default value. For instance:

(24)

\knowledgedirective{highlight}[brown]{color={#1},emphasize,md}

[...]

\knowledge{notion A}{highlight}

\knowledge{notion B}{highlight}

\knowledge{notion C}{highlight}

\knowledge{important notion D}{highlight=red}

[...]

We shall now see \kl{notion A}, \kl{notion B}, \kl{notion C}, as well as the \kl{important notion D}.

yields

We shall now seenotion A,notion B,notion C, as well as theimportant notion D.

3.3.6 \knowledgestyleversus \knowledgedirective

The two commands \knowledgestyleand \knowledgedirective offer ways to systematize the writing of knowledges. These can seem redundant. This is not the case, and for understanding it, it is necessary to understand a bit the way the

\knowledgecommand works.

In general when a\knowledge(or\knowledgestyle) command is found, the directives are parsed and a new internal form of the \knowledge command is written in thekaux file, that will be executed during the next compilation of the document. In this phase, some first operations are performed. For instance, in an autorefdirective, an internal label name is constructed.

The postponed command is then executed during the next compilation phase (or immediately if we are in the preamble, or if thenowdirective is used). The execution effectively stores the knowledge in the system. This is only at that moment that the knowledge becomes available to be used by \kl and similar commands.

When a\klcommand (or similar) is met, it is ‘executed’, and display informations are considered, and in particularstylesare called.

Somes consequences of this kind of this are as follows:

• autorefdirectives should not be used in the definition of astyle, since this would mean that there would be one anchor point for all the knowledges that use thisstyle. This is usually not the kind of behavior that we expect.

• configuring the default displays of the system (such as theintro style=in particular) has to be done through thestylemechanism.

• stylesuse less memory than macros.

3.3.7 Default directives: the\knowledgedefault command

It may happen that a sequence of consecutive \knowledge commands have to share the same list ofdirectives. The macro directivescan help solving this issue.

(25)

The default directives also go in this direction, using the \knowledgedefault- command:

\knowledgedefault*{directives}

When such a command is applied, then from that point, all\knowledgecommands will use the givendirectivesas default. This will stop when another \knowledg- edefaultcommand is met or the current group is closed. The optional star does not reset thedefault directivesbut simply add new ones.

3.4 The \kl command and variants

The\klcommand 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).

3.4.1 The standard syntax Hint. Note that the \kl-

command can often be re- placed by the"· · ·"notation, activated by the quotation option.

The\klcommand has one of the following syntaxes:

\kl(optional scope)[optional knowledge name]{text}

or \kl[optional knowledge name](optional scope){text} . 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 theoptional scope. The search process is as follows:

• if anoptional scopeis given, theknowledgeis searched in the corresponding scope.

• otherwise, thestack of visible scope instancesis processed through (starting from the inner most) until aknowledgeof name ‘knowledge name’ (or ‘text’ if not optionalknowledge namehas been given), of namespace‘default’, and this scope is found.

If the ‘knowledge name/text’ has not been found, thestyle‘kl unknown’ (or similar styles, as defined by theunknown style=orunknown style cont=) is used, and the text displayed.

• Otherwise, theknowledge is executed. If it is a link= or synonym defined knowledge, the link is followed, and the process continues.

• Finally, all the definitions involved in theknowledgeare processed, following astyle=if defined, theknowledgeis updated (essentially incrementing the counter of use), and theknowledgeis displayed.

This general mechanism is used also by other commands that arevariants of \kl such as\intro,\reintro,\kref,\kpageref, and so on.

3.4.2 The quotation notation

When activated, thequotation mode activates shorthand notations for the \kl and\intromacros. Possible syntaxes are as follows:

(26)

"text" uses theknowledge pointed to by ‘text’. Equivalent to\kl{text}.

"text@knowledge" uses the knowledge pointed to by ‘knowledge to display

‘text’. Equivalent to\kl[knowledge]{text}.

"text@@scope" uses theknowledgepointed to by ‘text’ inscope‘scope’ to display ‘text’. Equivalent to\kl(scope){text}.

"text@knowledge@scope" uses theknowledgepointed to by ‘knowledge inscope

‘scope’ to display ‘text’. Equivalent to\kl[knowledge](scope){text}.

""text"" introduces theknowledge pointed to by ‘text’. Equivalent to\intr- o{text}.

""text@knowledge"" introduces theknowledgepointed to by ‘knowledge while displaying ‘text’. Equivalent to\intro[knowledge]{text}.

""text@@scope"" introduces theknowledge pointed by ‘text’ in scope ‘scope’.

Equivalent to\intro(scope){text}.

""text@knowledge@scope"" introduces theknowledgepointed to by ‘knowledge inscope ‘scope’ while displaying ‘text’.

Equivalent to\intro[knowledge](scope){text}. Activating thequotation notationis obtained using:

\knowledgeconfigure{quotation} , and deactivating it is obtained using:

\knowledgeconfigure{quotation=false}. It can also be activated while loading the package.

It is sometimes the case that some packages do use the quote symbol, usually in some environment (this is the case of thetikzcdenvironment). Theknowledge package can be configured to deactivate always thequotation notation when en- tering the environment. This is obtained using theconfiguration optionprotect quotation=followed by a list of environments to be protected:

\knowledgeconfigure{protect quotation={env1,env2,...}}

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\klnotation:

• When nesting ofknowledgesis involved, or theknowledgeincludes the symbol ",

• whenquotationis deactivated (or not activated) because of a conflict

• in particular, this should be avoided in macros, in particular for the math mode, since these may be used one day or another in a tikzcd or similar environment for instance.

(27)

3.4.3 Variants of \kl

Several variants of the\kl-command are defined by default. The syntax for their use is the same (including scopes, . . . ). The following variants are linked to the autorefdirective:

• \introis used to introduce a knowledge.

• \reintrodisplays like for introducing the knowledge, but does not do it.

• \reklbehaves like\klacts as a modifier and transforms\introinto \reintro.

• \phantomintroperforms the introduction, but does display anything.

• \kref displays the number of the environment in which the introduction took place.

• \kpagerefdisplays the number of the page in which the knowledge introduction took place.

• \kcref,\kCref,\kcpageref,\kCpageref,\knamecref,\knameCref,\kn- amerefs, and \knameCrefs, display informations about the place of introduction of a knowledge, following the semantics of the corresponding func- tions in thecleverefpackage (see Section 3.8.4).

3.4.4 Defining your own variants of \kl

It may happen for several reasons that we may want to define new variants of the

\klmacros, that essentially perform the same task, but are configured differently.

Typical examples may be:

• several sets ofknowledgesmay intersect but should use differentnamespace,

• someknowledgesinvolve macros and for this reason should be non-expanded even if the\knowledge command is not met,

• the\knowledgecommand should be called implicitly,

• activate or deactivate the warnings or messages in thediagnose file.

In fact, several macros in this document are instantiation of this mechanism. This is the case for for instance for\intro,\phantomintro,\reintroor\mathkletc...

The macro for introducing a newvariant of \klis:

\knowledgenewvariant\variant{variant directives}

and is similar to the one for modifying the behavior of avariant of \kl:

\knowledgesetvariant\variant{variant directives} .

(28)

These command define/modify a/the macro\variantthat uses the same syntax as \kl. The variant directivesconsist of a comma separated list ofdirectives as follows:

namespace=namespace declares in which namespace(a string) the knowledges are to be searched. This means in particular that the\knowledgeconcerned should be defined using the the propernamespace= directive.

default style=, unknown style=,unknown style cont={list of style names}

declares the style name to be used (1) by default when the knowledge is found, (2) when it is not found for the first time, and (3) the subsequent times.

style directive={directive names list} defines a list (comma separated) of directives that can be used in a\knowledgecommand to modify the aspect (for instance, the\intro behavior is modified by theintro style=directive, while the \klcommand is configured using the style= directive). If thedirectivesdo not exist, these are created.

auto knowledge={directives} declares that the use of \variant should automatically execute a\knowledgecommand, and what should be the directives it uses. See examples below.

unknown warning=true/false activates or deactivates the warnings when aknowledgeis not found (for instance, these are deactivated inpaper mode). True by default.

unknown diagnose=true/false activates or deactivates the corresponding messages in thediagnose file. True by default.

suggestion={directives} configures the directivesto be suggested in the diagnose filewhen theknowledgeis unknown.

PDF string={code} gives a substitute text for hyperref to use for producing the bookmarks. This code has to be expandable. The code may use three parameters;]1is the main text of the command,]2is the optional parameter, and]3is the scope. The macro\IfNoValueTFof the packagexparsecan be used to test if the second and third arguments are present. By default, the code is{]1}. 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\texorpdfstringof thehyperrefpackage should be used.

display code= can be used to shortcut the standard code for display. See the code for more details. Typical examples are thevariants\kref,\kpageref and so on, which do not display the knowledge itself, but instead treat the underlying label associated.

The second feature is to usemodifiers. These correspond to the stared version of the command. For instance, one expects ‘\intro*\kl’ to reduce to ‘\intro’.

For this, one has to declare explicitly the reduction using:

\knowledgevariantmodifier{stared sequence}\variant ,

in which the stared sequence is of the form ‘variant1*variant2*. . . *vari- antk’. This sequence is declared to reduce to \variant. For instance,

\knowledgevariantmodifier{\intro*\kl}\intro declares ‘\intro*\kl’ to re-

(29)

duce to ‘\intro’.

3.4.5 Examples ofvariants of \kl

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\kland\introcommands as defined in thepackage. The second one is the code used in this documentation for displaying macros, defining the macros\csand\csintro.

The configuration of \kl and \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.

\knowledgestyle{autoref link}{autoref link}

\knowledgestyle{autoref target}{autoref target}

\knowledgestyle{invisible}{invisible}

\knowledgenewvariant\kl{

namespace=default,

default style={kl,autoref link}, unknown style= kl unknown,

unknown style cont= kl unknown cont, style directive= style

}

\knowledgenewvariant\intro{

namespace= default,

default style= {intro,autoref target}, unknown style= intro unknown,

unknown style cont= intro unknown cont, style directive= intro style

}

\knowledgevariantmodifier{\intro*\kl}\intro

Note that\reintroand\phantomintroare defined using similar code.

Displaying control sequences The second code example is used in this document (the documentation of the package) and consists of two macros\cs and

\csintrowhich have the following semantics:

• these correspond, and have the same syntax as,\kland\introrespectively,

• these are used to display control sequences without executing them,

• if \csintro{\command} is used, then it displays \command in color blue, and every occurrences of \cs{\command} yields \commandbeing displayed in dark blue and linking to the introduction point,

• if \csintro{\command} is never used, then \cs{\command} simply displays\commandin black,

(30)

• no\knowledgecommand is necessary, and no warning is issued if a command is unknown.

\knowledgestyle{cs}

{detokenize,remove space,typewriter,up,md,color=NavyBlue}

\knowledgestyle{cs unknown}

{detokenize,remove space,typewriter,up,md,color=black}

\knowledgenewvariant\cs{

namespace=cs,

default style={autoref link,cs}, unknown style=cs unknown,

unknown style cont=cs unknown, unknown warning=false,

unknown diagnose=false, suggestion=cs

}

\knowledgestyle{csintro}

{detokenize,remove space,typewriter,up,md,color=blue}

\knowledgestyle{csintro unknown}

{detokenize,remove space,typewriter,up,md,color=black}

\knowledgenewvariant\csintro{

namespace=cs,

auto knowledge={autoref,scope=document,also now}, default style={autoref target,csintro},

unknown style=csintro unknown, unknown style cont=csintro unknown, }

\knowledgevariantmodifier{\intro*\cs}\csintro

\knowledgevariantmodifier{\csintro*\cs}\csintro Several things can be noted about this code:

• thedirectivesdetokenize and remove space prevent the execution of the argument, and instead display its name, this is important since the argument is a control sequence,

• the directivestypewriter, up and md give a uniform aspect (no italic, no boldface) to the result in all contexts,

• thenamespaceis set to be different from the default one, avoiding possible clashes with\kl,

• when a\csintrocommand is met, the corresponding\knowledgecommand is automatically issued, in particular with ‘scope=document’ for guaranteeing the visibility of each command everywhere in the document,

• thealso nowdirective is necessary for the compilation to (possibly) stabilize in two iterations, since it uses the proper \label already at the first iteration (withoutalso 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).

• warnings and diagnose pieces of information are explicitly eliminated.

(31)

3.5 Scoping

3.5.1 Principles of scoping

When writing long documents, one often wantsknowledgesto be isolated in some subparts. For instance, one may want a temporary definition in a proof to not leak elsewhere in the document where the same term could be used with a different meaning. Some definitions may be only meaningful in, say, the current section/part.

Two separate things have to be understood: how to defineknowledgein a given scope(and createscopes), and how to accessknowledgefrom a givenscope.

Accessing knowledge attached to a given scope This can be done directly either using the parenthesis notations of \kland the second @of the quotation notation:

\kl(scope name){knowledge} or \kl(scope name)[knowledge]{text}

"knowledge@@scope" or "text@knowledge@scope"

It works also for\introand with double quotes.

Another option is to import the scope locally, using:

\knowledgeimport{scope name 1,scope name 2,...}

After this command, the knowledges will be searched automatically in the imported scopes. The import stops at the end of the current scoping environment.

Attaching knowledge to a given scope This can be done directly using the scope=directive, for instance in:

\knowledge{knowledge}{scope=scope name,directives} or, this is obtained usint the‘|’-notation using ‘@’ :

\knowledge{directives}

| knowledge@scope name 1

| synonym@scope name 2 ..

. ...

The other possibility is to define a knowledge inside ascopeenvironment:

\begin{scope}\label{label}

\knowledge{knowledge 1}{directives} ..

.

\end{scope}

In such a code, the knowledge defined is automatically visible in the environment, and from outside, using the scope namelabel. Indeed, the \labelis overloaded for doing automatically a\knowledgescopecommand.

In fact, it is possible to do even more: other environments can be defined to behave likescope.

(32)

3.5.2 Scoping by examples

Explicit scopingconsists in attaching a precise scope name to aknowledge using thescope=directive:

\knowledge{thing}{scope=s1,color=red}

\knowledge{thing}{scope=s2,color=green}

Here, "thing" and \kl{thing} are unknown.

But "thing@@s1" and \kl(s1){thing} are in red, and "thing@@s2" and \kl(s2){thing} are in green.

The ‘|’-notation can also be used forexplicit scoping. This is convenient, in particular for having synonyms in different scopes:

\knowledge{color=red}

| abelian group

| abelian groups

| Abelian groups

| group@abelian

| groups@abelian

| Groups@abelian

Here, general "groups" are not defined but "groups@@abelian" are, and correspond to "abelian groups".

\begin{scope}\knowledgeimport{abelian}

All "groups" here are abelian.

\end{scope}

Scopescan also be attached to areas in the code. It is convenient to use the usual\labelcommand to name them (though, in practive, two different naming spaces are used).

% We declare first in the preamble the environments that can have

% knowledges attached to them.

\knowledgeconfigureenvironment{theorem,lemma,proof}{}

% and now in the main body of the document.

\begin{theorem}\label{theorem:main}

\knowledge{rabbit}[rabbits]{notion}

In every hat, there is a \kl{rabbit},

\AP in which a \intro{rabbit} is a small animal with long ears.

\end{theorem}

Here a "rabbit" is an unknown knowledge.

But "rabbits@@theorem:main" point to Theorem \ref{theorem:main}.

\begin{proof}\knowledgeimport{theorem:main}

Now, "rabbit" is hyperlinked to Theorem \ref{theorem:main}.

\end{proof}

(33)

3.5.3 What is the structure ofscopes in a document

To start with, one needs to understand what are the possiblescopes. Scopes are aggregation of zones in the document.

• By default, all the body of the document belongs to a scope called

‘document’. The user can open new scopes using thescope environment:

\begin{scope}

\knowledge{local notion}{color=green}

Here is a \kl{local notion} that appears in green.

\end{scope}

But here the \kl{local notion} is undefined.

Note that scoping is independent from the grouping mechanism of L^ATEX.

The user can also declare environments such aslemma,theorem, remarkor proofto behave likescope. This is achieved using using\knowledgeconfigureenvironmentcommand.

• The use of thescopeconfiguration optiongoes one step further, and attaches scopesto sections, subsections, itemize, items, and so on. But be cautious, this feature, though working, may cause some compiling document to not compile anymore if some weird (and unnatural) nesting of scopes are used (this is the case for instance when using\bibitemand\thebibliography, and this has to be corrected by hand).

3.5.4 How is chosen the scope of aknowledge?

In general, when a\knowledge command is used, the system tries to figure out what should be itsscope:

• If the command occurs in the preamble, then the defaultscopewill be ‘document’.

• Otherwise, the information is searched for in the stack of visible scope in- stanceswhich means that theknowledgewill be defined at the level of the innermost surrounding scope that ‘attracts knowledges’. If thescope option is not activated (and the user did not perform its own configuration), this is the inner most scopeenvironment (or similar environment if \knowled- geconfigureenvironmenthas been used), or ‘document’ if the declaration is not in the scope. If thescope optionis used, this will be the innermost lemma, proof, or theorem in the context.

• This default behavior can be modified using the scope= directive. The scope=directive can be followed with a scope level, such as ‘section’, ‘sub- section’, ’chapter’ or ‘itemize’ (in particular in combination with thescope option), that will be looked for in the current context and will receive the knowledge. The directive can also be followed by a label name, and the active scope at the moment of this label will be used.