knowledge (3oct19)

git-svn-id: svn://tug.org/texlive/trunk@52273 c570f23f-e606-0410-a88d-b1316a301751

6 files changed, 1195 insertions, 488 deletions

diff --git a/Master/texmf-dist/doc/latex/knowledge/README.md b/Master/texmf-dist/doc/latex/knowledge/README.md
index ca7c3285918..f67514e9aea 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.16
-  date: 2019/02/15
+  version: v1.17
+  date: 2019/10/03
   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
index ebf4ac86a14..cc7bc268353 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 fb3f98f009c..642cb98a852 100644
--- a/Master/texmf-dist/doc/latex/knowledge/knowledge.tex
+++ b/Master/texmf-dist/doc/latex/knowledge/knowledge.tex
@@ -145,7 +145,7 @@
 
 
 
-\knowledge{@token}{wrap=\Robustdisplay,up,md,typewriter,color=NavyBlue}
+\knowledge{{@token}}{wrap=\Robustdisplay,up,md,typewriter,color=NavyBlue}
 
 
 
@@ -159,6 +159,7 @@
 \knowledgestyle{style}{typewriter,up,md,color=NavyBlue}
 \knowledgestyle{intro style}{typewriter,up,md,color=blue}
 
+
 \begin{scope}\label{style}
   \knowledge{notion}{notion style}
   \knowledge{intro notion}{notion style}
@@ -187,6 +188,7 @@
 
 
 \knowledgeconfigure{quotation=false}
+\knowledge{LaTeX}[latex|LATEX|Latex]{text=\LaTeX, color=black}
 \knowledge"{text=\quotesymbol}
 \knowledge{""}{text=\quotesymbol\quotesymbol}
 \knowledgeconfigure{quotation=true}
@@ -202,12 +204,12 @@
 \ExplSyntaxOn
 \knowledge{"..."}{kquotation,text=\kl{"}$\cdots$\kl{"}}
 \knowledge{""...""}{kquotation,text=\kl{""}$\cdots$\kl{""}}
-\knowledge{"...@..."}{kquotation,text=\kl{"}$\cdots\arobas\cdots$\kl{"}}
-\knowledge{""...@...""}{kquotation,text=\kl{""}$\cdots\arobas\cdots$\kl{""}}
-\knowledge{"...@@..."}{kquotation,text=\kl{"}$\cdots\arobas\cdots\arobas\cdots$\kl{"}}
-\knowledge{""...@@...""}{kquotation,text=\kl{""}$\cdots\arobas\cdots\arobas\cdots$\kl{""}}
-\knowledge{"...@...@..."}{kquotation,text=\kl{"}$\cdots\arobas\cdots\arobas\cdots$\kl{"}}
-\knowledge{""...@...@...""}{kquotation,text=\kl{""}$\cdots\arobas\cdots\arobas\cdots$\kl{""}}
+\knowledge{{"...@..."}}{kquotation,text=\kl{"}$\cdots\arobas\cdots$\kl{"}}
+\knowledge{{""...@...""}}{kquotation,text=\kl{""}$\cdots\arobas\cdots$\kl{""}}
+\knowledge{{"...@@..."}}{kquotation,text=\kl{"}$\cdots\arobas\cdots\arobas\cdots$\kl{"}}
+\knowledge{{""...@@...""}}{kquotation,text=\kl{""}$\cdots\arobas\cdots\arobas\cdots$\kl{""}}
+\knowledge{{"...@...@..."}}{kquotation,text=\kl{"}$\cdots\arobas\cdots\arobas\cdots$\kl{"}}
+\knowledge{{""...@...@...""}}{kquotation,text=\kl{""}$\cdots\arobas\cdots\arobas\cdots$\kl{""}}
 
 
 \ExplSyntaxOn
@@ -215,7 +217,7 @@
 \makeatletter
 \let\arobas @
 \makeatother
-\knowledge{@}{kcommand,text=\arobas}
+\knowledge{{@}}{kcommand,text=\arobas}
 
 
 \knowledge{tex}{text=\TeX}
@@ -315,6 +317,7 @@
 \knowledge{index key=}{directive}
 \knowledge{index parent key=}{directive}
 \knowledge{index style=}{directive}
+\knowledge{bar suggestion=}{directive}
 \knowledge{color=}{directive}
 \knowledge{cyclic color}{directive}
 \knowledge{colorbox=}{directive}
@@ -330,7 +333,6 @@
 \knowledge{invisible=}[invisible]{directive}
 \knowledge{detokenize}{directive}
 \knowledge{remove space}{directive}
-
 \begin{scope}\label{option}
   \knowledge{hyperref}{option}
   \knowledge{xcolor}{option}
@@ -355,6 +357,7 @@
 \knowledge{hyperlinks=}{option}
 \knowledge{fix hyperref twocolumn}{option}
 \knowledge{diagnose line=}[diagnose line]{option}
+\knowledge{bar suggestion=}[bar suggestion]{option}
 
 
 \knowledge{active}{option}
@@ -371,6 +374,9 @@
 \knowledgedirective{package}{typewriter,color=DarkBlue}
 \knowledge{CTAN}{color=darkgray,url={https://www.ctan.org/}}
 \begin{scope}\label{package}
+   %\ExplSyntaxOn
+   %\def\mydebug{\tl_show:N\knowledge_knowledge_instance_tl}
+   %\ExplSyntaxOff
    \knowledge{knowledge}{doc notion, package}
    \knowledge{expl3}{package,url={https://www.ctan.org/pkg/expl3}}
    \knowledge{hyperref}{package,url={https://www.ctan.org/pkg/hyperref}}
@@ -384,6 +390,7 @@
    \knowledge{amssymb}{package,url={https://www.ctan.org/pkg/amssymb}}
 \end{scope}
 
+
 \knowledgedirective{environment}{typewriter}
 \begin{scope}\label{env}
    \knowledge{scope}{kenvironment}
@@ -408,7 +415,7 @@
   \knowledge {unknown diagnose=}{directive}
   \knowledge {suggestion=}{directive}
   \knowledge {PDF string=}{directive}
-  \knowledge {starred sequence}{doc notion}
+  \knowledge {stared sequence}{doc notion}
   \knowledge {modifier}[modifiers|Modifiers]{doc notion}
 \end{scope}
 
@@ -425,11 +432,28 @@
 \knowledge{configuration option}[configuration options|Configuration options]{link=package option}
 \knowledge{stack of visible scope instances}{notion}
 \knowledge{quotation notation}{doc notion}
-\knowledge{jobname.kaux}[kaux file]{doc notion}
+\ExplSyntaxOn
+\def\klqn#1{{\kl[quotation~notation]{\tl_to_str:n{#1}}}}
+\def\klbn#1{{\kl[`\vbar'-notation]{\tl_to_str:n{#1}}}}
+\ExplSyntaxOff
+
+\knowledge{`\vbar'-notation}{doc notion}
+\knowledge{doc notion}
+  |  jobname.kaux
+  |  kaux file
 \knowledge{undefined knowledge}[undefined knowledges|Undefined knowledges]{doc notion}
 \knowledge{Non introduced autoref knowledge}{doc notion}
 \knowledge{Duplicated intros}{doc notion}
-\knowledge{instance}[instances|Instances]{doc notion}
+\knowledge{doc notion}
+  | instance
+  |	instances
+  | Instances
+\knowledge{doc notion}
+  | explicit scope
+  |	explicit scoping
+  | Explicit scopes
+  | explicit scopes
+  | Explicit scoping
 \knowledge{directive}[directives|Directives]{doc notion}
 \knowledge{area}[areas|Areas]{doc notion}
 \knowledge{knowledge}[knowledges|Knowledges]{doc notion}
@@ -440,7 +464,17 @@
 \knowledge{knowledge style}[Knowledge styles|knowledge styles]{doc notion}
 \knowledge{style}[styles|Styles|display style|display styles]{link=knowledge style}
 \knowledge{category}[categories|Categories]{doc notion}
-\knowledge{scope}[scopes|Scopes]{doc notion} % separate the package 
+\knowledge{doc notion}
+  |  scope
+  |  scopes
+  |  Scopes
+\knowledge{doc notion}
+  | explicit scope
+  | Explicit scopes
+  | explicit scopes
+\knowledge{doc notion}
+  | scopetag
+  | scopetags
 \knowledge{namespace}[namespaces|Namespaces]{doc notion}
 \knowledge{vertical mode}{doc notion}
 \knowledge{debug mode}{doc notion}
@@ -450,10 +484,14 @@
 
 \knowledge {\knowledge namespace}{doc notion}
 \knowledge {\knowledge knowledge name}{doc notion}
+\knowledge {\knowledge optional scope}{doc notion}
+\knowledge {\knowledge synonym name}{doc notion}
 \knowledge {\knowledge synonyms}[\knowledge optional argument]{doc notion}
 \knowledge {\knowledge directives}[knowledge directive]{doc notion}
 
-\knowledge {composition mode}[composition]{option}
+\knowledge{option}
+  | composition mode
+  | composition
 \knowledge {paper mode}[paper]{option}
 \knowledge {electronic mode}[electronic]{option}
 
@@ -587,7 +625,6 @@ Eventually, it is intended to use the package for producing scientific semantic
 \texttt{CTAN:}&\url{https://www.ctan.org/pkg/knowledge}
 \end{tabular}
 \end{quote}
-This is still in beta version but close to a first definitive release. A lot of functionalities are perfectly operational, and the syntax is close to stable. At any rate, if changes happen, these will only affect a few lines in the configuration of the document.
 \newpage
 \knowledgeconfigure{protect links}
 \tableofcontents
@@ -603,6 +640,9 @@ This is essentially a list for personal referencing of what has to be done.
 \begin{asparaitem}
 \item deactivate quotation by default in the preamble in particular for avoiding clashes with commands such as \cs\DeclareMathDelimiter.
 \item make knowledge compatible with beamer (request of Patrick Aiyao He), probably use hypertarget and hyperlink instead of hyperlabel and hyperref.  Seems complicated because I do not know how to know if some material is going to be displayed, and this is necessary for a complete working solution.
+I have seen Till Tantau who explained me how to test whether a material is displayed. For this, one has to check that the material is displayed.
+This involves testing  the counter |beamer@coveringdepth| which if higher than one when 'not displayed'.
+|beamer@slideinframe| could also be intersting.
 \item make quotation work properly in the titles of section...,
 \item allow to protect quotation in commands, and not only environments (for instance xymatrix)
 \item remove the warnings about redefining commands
@@ -611,10 +651,12 @@ This is essentially a list for personal referencing of what has to be done.
  (for the moment, removing the aux file deactivates the kaux file. This is convenient but not sufficient.)
 \item proper code for \cs{\nointro}.
 \item improving the \cs{\AP} and \cs{\itemAP} commands. For the moment \cs{\AP} silently fails inside the
-  optional argument of \cs{\item}, and probably elsewhere too. See how this can be improved.
+  optional argument of \cs{\item}, and probably elsewhere too. See how this can be improved. I tried to use the \cs{inner_mode} test, but it also detects situations when where \cs{\AP} si allowed (like in minipage).
 \item solve the \kl(package){amsmath} problem that \cs{\label} is deactivated in unnumbered environment, while knowledge would nevertheless like to point to the place...
 \item Code export and import features.
 \item Pointing inside an external pdf document.
+\item Correct the use of parameters in a directive (see example 'highlight' below).
+\item Make the boolean parameters in knowledges to properly handle the false case (removing the default).
 \end{asparaitem}%
 }{}
 
@@ -656,7 +698,7 @@ This is essentially a list for personal referencing of what has to be done.
 \item[2017-04-09] Internal change of code, for "scope" handling and for the "quotation notation": slowly going toward an extended "quotation notation" that can make the "scope" of search explicit.
 \item[2017-04-09] Added the \kl{protect quotation} configure option, that is given a list of environments, and deactivates automatically the "quotation notation" when in there environments. This is a simple code for the moment. Typically, one can use \smallcode{\cs\knowledgeconfigure\{\kl{protect quotation}=tikzcd\}}. For the moment, it is not explained in the document.
 \item[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.
-\item[2017-04-20] The "electronic mode" has been added, and the `final mode` is now renamed into "paper mode". The \cs{\knowledgepackagemode} configuration variable is also available for easier scripting.
+\item[2017-04-20] The "electronic mode" has been added, and the `\texttt{final mode}' is now renamed into "paper mode". The \cs{\knowledgepackagemode} configuration variable is also available for easier scripting.
 \item[2017-06-06] FAQ on deactivating the quote in "Emacs" (thanks to Sylvain Perifel).
 \item[2017-06-08] Removed the \texttt{noknowledge} package and all references to it.
 \item[2017-06-08] Removed the \texttt{knowledgeutils.sty} and \texttt{scopearticle.sty} which are now integrated in the main file.
@@ -694,6 +736,10 @@ This is essentially a list for personal referencing of what has to be done.
 \item[2018-11-22] Corrected bug for "makeidx@@package" (thanks to Sylvain Schmitz). V1.14 on "CTAN".
 \item[2019-01-27] Minor improvement of the doc, and hiding links in it. V1.15.
 \item[2019-02-15] Correction of a placement problem with \cs\AP. V1.16.
+\item[2019-05-23] Adding of the "`\vbar'-notation" for the \cs{\knowledge} command.
+"Explicit scopes" are introduced. Updating of the documentation. "up" directive in math mode now silently does nothing, and \cs{\knowledgedirective} now forbids redefinitions by default (thanks to Léo Stefanesco).
+\item[2019-07-02] Removing the `\texttt{kl}' and `\texttt{intro}' styles that prevented a proper configuration of "intro notion@@style" (thanks to Léo Stefanesco). 
+\item[2019-07-02] Update of the documentation, and V1.17.
 \end{compactdesc}
 \normalsize
 %\restoregeometry
@@ -717,8 +763,9 @@ This is essentially a list for personal referencing of what has to be done.
 The "knowledge@@package" 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 implicitly \kl{knowledges} 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. The hyperlinks in this document have been generated using the "knowledge@@package" package.
-In the subsequent questions, a more detailed account of how the "package@knowledge@package" works and can be parameterized is given.
+We start by describing a certain number of problems/scenarii that a user may be confronted to, and show how to solve them. 
+%The hyperlinks in this document have been generated using the "knowledge@@package" package.
+In the subsequent sections, a more detailed account of how the "package@knowledge@package" works and can be parameterized is given.
 
 There is also a file \texttt{knowledge-example.tex} that can be used as a starting point.
 
@@ -740,9 +787,9 @@ You may use other options like \kl(option){xcolor} for allowing debugging with c
 \begin{code}[8cm]
 \cs{\usepackage}["hyperref@@package",\kl(option){quotation}]\{"knowledge@@package"\}
 \end{code}
-\noindent or:
+\noindent or even better:
 \begin{code}[8cm]
-\cs\usepackage\{\kl(package){hyperref}\}\\
+\cs\usepackage["hidelinks"]\{\kl(package){hyperref}\}\\
 \cs\usepackage[\kl(option){quotation}\footnote{If you want to use the \kl{"}$\cdots$\kl{"} notation.}]\{"knowledge@@package"\}
 \end{code}
 
@@ -755,7 +802,7 @@ This configures the text `\texttt{latex}' to be associated with the sole directi
 which means an hyperreference to this address.
 
 Finally in the body of the paper, the sole extra command \cs{\kl} (or the \kl"-symbol if the \kl(option){quotation} option is activated) is used,
-with as parameter a text. This text is searched for, and the directives attached to it (here the url),
+with as parameter a text. This text is searched for, and the directives attached to it (here "url="),
 are used for formatting its printing\footnote{This 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 \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 execution.}.
 Hence:
@@ -772,7 +819,7 @@ or, if the \kl(option){quotation} option is activated,
 This package has been written for use in \kl{"}latex\kl{"}.
 \end{code}\noindent
 yields
-\knowledge{urllatex}{url=https://en.wikipedia.org/wiki/LaTeX}
+\knowledge{urllatex}{url=https://en.wikipedia.org/wiki/LaTeX,color=black}
 \begin{PDFoutput}
 This package has been written for use in \kl[urllatex]{latex}.
 \end{PDFoutput}
@@ -783,8 +830,9 @@ This requires to load the package with the \kl(option){xcolor} option (for being
 extra "directives":
 \begin{code}[10.9cm]
 \cs\knowledge\{latex\}\{\kl{url=}https://en.wikipedia.org/wiki/LaTeX,\\
-\qquad\kl{text=}\cs\LaTeX,~\kl{color=}gray\}
-\end{code}\noindent
+\indent\qquad\kl{text=}\cs\LaTeX,~\kl{color=}gray\}
+\end{code}
+\noindent
 yields with the same text
 \knowledge{urllatexgray}{url=https://en.wikipedia.org/wiki/LaTeX, color=gray, text=\LaTeX}
 \begin{PDFoutput}
@@ -806,26 +854,28 @@ Another more systematic way to do it is to declare synonyms.
 This can be achieved using a `\vbar' separated list of texts in the \kl[\knowledge synonyms]{optional parameter} of the\cs{\knowledge} command, it is possible to add a list of `synonyms', such as in:
 %
 \marginpar{\begin{hint}
-This is a shorthand for a \kl{synonym} (or \kl{link=}) directive.\\For instance, with the code
-  \begin{code}[4.3cm]
-  \cs{\knowledge}\{D. Knuth\}\\~~~~\{\kl{link=}Knuth\}
-  \end{code}\noindent then \smallcode{\cs\kl\{D. Knuth\}}
-  would also point to the same url.
-  \begin{code}[4.3cm]
-  \cs{\knowledge}\{D. Knuth\}\\~~~~\{\kl{synonym}\}
-  \end{code}\noindent would also work if used just after the definition
-  of \texttt{Knuth}.\\
+  Another syntax (called the "`\vbar'-notation") is:
+  \begin{code}[4.35cm]
+  \cs{\knowledge}\{"url="\dots\}\\
+  \indent~\vbar~Donald Ervin Knuth\\
+  \indent~\vbar~Donald Knuth\\
+  \indent~\vbar~D. Knuth\\
+  \indent~\vbar~Knuth
+  \end{code}
+  Other possibilities are to use the
+  "synonym" or "link=" directives.
   \end{hint}}
 %
-\begin{code}
+\begin{code}[12.4cm]
 \cs{\knowledge}\{latex\}[LaTeX\vbar Latex\vbar LATEX]\\
-   \{\kl{url=}http://en.wikipedia.org/wiki/LaTeX,~\kl{text=}\cs{\LaTeX}, \kl{color=}gray\}
+\indent\qquad\{\kl{url=}http://en.wikipedia.org/wiki/LaTeX,\\
+\indent\qquad\kl{text=}\cs{\LaTeX}, \kl{color=}gray\}
 \end{code}
 This is interesting for people's name that can be displayed in various ways depending on the context. Hence
 %
-  \begin{code}[9.8cm]
-  \cs\knowledge\{Donald Ervin Knuth\}[Donald Knuth\vbar Knuth]
-     \{\kl{url=}https://fr.wikipedia.org/wiki/Donald\_Knuth\}
+  \begin{code}[12.4cm]
+  \cs\knowledge\{Donald Ervin Knuth\}[Donald Knuth\vbar Knuth]\\
+ \indent\qquad\{\kl{url=}https://fr.wikipedia.org/wiki/Donald\_Knuth\}
   \end{code}
 \noindent would allow 
 \begin{center}
@@ -833,24 +883,24 @@ This is interesting for people's name that can be displayed in various ways depe
 or simply \smallcode{\kl"Knuth\kl"}~~~as well as~~~\smallcode{\kl"Donald Knuth\kl"} and so on
 \end{center} to all point to the same web address.
 It is even more convenient to use it for nouns that are sometimes in plural form or at the beginning of a sentence. Hence:
-%\marginpar{%
-%  \begin{hint}
-%  Sometimes one wants to use a \kl{knowledge} by explicitly mentioning it:
-%  \begin{code}[4.3cm]
-%  \cs\kl[group]\{This object\}
-%  \\ is very important.
-%  \end{code}
-%  or
-%  \begin{code}[4.3cm]
-%  \kl"This object\kl{@}group\kl"
-%  \\ is very important.
-%  \end{code}
-%  \end{hint}}
-\begin{code}[10.6cm]
-\cs\knowledge\{group\}[groups\vbar Groups\vbar group morphism\vbar group morphisms\vbar Group morphisms]\\
-   \{\kl{url=}https://en.wikipedia.org/wiki/Group\_(mathematics)\}
+\begin{code}[12.4cm]
+\cs\knowledge\{group\}[groups\vbar Groups\vbar group morphism\\
+\indent~~~~~~~~~~\vbar group morphisms\vbar Group morphisms]\\
+\indent~~~~~  \{\kl{url=}https://en.wikipedia.org/wiki/Group\_(mathematics)\}
+\end{code}
+\noindent
+or the more readable and maintainable:
+\begin{code}[12.4cm]
+\cs\knowledge\{\kl{url=}https://en.wikipedia.org/wiki/Group\_(mathematics)\}
+\indent~~~\vbar~~group\\
+\indent~~~\vbar~~groups\\
+\indent~~~\vbar~~Groups\\
+\indent~~~\vbar~~group morphism\\
+\indent~~~\vbar~~group morphisms\\
+\indent~~~\vbar~~Group morphisms
 \end{code}
-\end{variation}\noindent
+\end{variation}
+\noindent
 makes it possible to use the notions in many contexts:
 \begin{code}
 \kl"Groups\kl" form a category when equipped with \kl"group morphisms\kl".
@@ -867,8 +917,8 @@ I am writing a long scientific document with many notions tied together
 (typically, I have made all my best for clarifying but nevertheless
 it remains obscure,
 or it is a long survey involving many subfields, or a book, or a PhD thesis\footnote{Reviewers should appreciate...}).
-I would like all the notions be linked inside the document for being able 
-in one click, whenever something is used, to jump to its definition.
+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.
 \end{problem}
 \medskip
@@ -919,7 +969,7 @@ $(M,\cdot,1)$ is a \kl[_semigroup]{semigroup} $(M,\cdot)$ together
 with a neutral element~$1$.
 \end{PDFoutput}
 \knowledgeconfigure{visible anchor points=false}%
-\kl{Undefined knowledges} are in brown (it is an important feature that the compilation does not fail: undefined knowledges should not interfere with the writing of the document, which is the purpose of all this).
+\kl{Undefined knowledges} are in brown (it is an important feature that the compilation does not fail: undefined knowledges should not interfere with the writing of the document, which is the main activity of the writer).
 One can now see the list of such problems in the file `\kl{filename.diagnose}'.
 One can in particular find in the "`Undefined knowledges' section":
 \begin{verbatim}
@@ -949,23 +999,47 @@ with a neutral element~$1$.
 %
 Clicking on `semigroup' now jumps to the place it was introduced, and very precisely at the
 location of the red corner depicting the presence of the \cs{\AP}-command.
-If now one adds the option \kl{electronic} while loading the package, then the colors and the red corner disappear. When using the option \kl{paper}, the links are still there, but all texts are in black.
+If now one adds the option \kl{electronic} while loading the package, then the red corners disappear as well as the brownish undefined knowledges which become black. When using the option \kl{paper}, the links are still there, but all texts are in black.
 
 \AP
 It is very often the case that for plain english (or other languages) some terms can be used in several forms; verbs can be conjugated; nouns can be plural, and so on.
-\marginpar{\hint{ The \kl[\knowledge directives]{directives} \kl{synonym} and "link=" can be also convenient.}}%
 So usually the lines added to the file look more like:
 \begin{code}[10.7cm]
 \cs\knowledge\{semigroup\}[semigroups\vbar Semigroups]\{\kl{notion}\}\\
 \cs\knowledge\{monoid\}[monoid\vbar Monoids]\{\kl{notion}\}
 \end{code}
 \noindent
-Now, using code like
+or, using the modre readable "`\vbar'-notation":
+\begin{code}[10.7cm]
+\cs\knowledge\{\kl{notion}\}\\
+\indent~~~\klbn|~~semigroup\\
+\indent~~~\klbn|~~semigroups\\
+\indent~~~\klbn|~~Semigroups\\
+\cs\knowledge\{\kl{notion}\}\\
+\indent~~~\klbn|~~monoid\\
+\indent~~~\klbn|~~monoids\\
+\indent~~~\klbn|~~Monoids
+\end{code}
+Now, using a text like
 \begin{code}[11cm]
-\kl"Monoids\kl" and \kl{"}semigroups\kl{"} play the same role from now.
+\kl"Monoids\kl" are simply \kl{"}semigroups\kl{"} in which\dots
 \end{code}
 \noindent will properly be linked to the definition of a semigroup and a monoid.
 
+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. The \cs{knowledge} commands are not easily adapted:
+\begin{code}[10.7cm]
+\cs\knowledge\{"notion","index="semigroup\}\\
+\indent~~~\vbar~~semigroup\\
+\indent~~~\vbar~~semigroups\\
+\indent~~~\vbar~~Semigroups\\
+\cs\knowledge\{"notion","index="monoid\}\\
+\indent~~~\vbar~~monoid\\
+\indent~~~\vbar~~monoids\\
+\indent~~~\vbar~~Monoids
+\end{code}
+See Section~\ref{subsection:makeidx option} 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. 
@@ -977,7 +1051,12 @@ Now, using code like
 \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:
-\marginpar{\begin{hint} Defining new macros is best done using \cs{\newrobustcmd} (of the \texttt{etoolbox} package), rather than the usual \cs{\newcommand} of \LaTeX. This remark is general in \LaTeX{}, unless you have very specific reason to have your macro expandable. This is even more true when using "knowledge@@package"\end{hint}.}
+\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{code}[7cm]
 \cs\newrobustcmd\kl[@token]\monoid\{\cs\mathcal\ M\}
 \end{code}\noindent
@@ -1049,15 +1128,15 @@ In this section, we review these ""package options"".
 The options that can be used in the optional parameter of \cs{\usepackage} when loading the "knowledge@@package" package belong to the following classes:
 \begin{compactdesc}
 \itemAP[Writing mode] The "paper", "electronic" or "composition" modes are possible ("composition" is by default) (see Section~\ref{subsubsection:writing modes} for more details).
-These modes change several default rendering settings.
-\itemAP[Other packages] some of the options concern the loading and the use of other packages (\kl(package){hyperref}, \kl(package){xcolor}, \kl (package){makeidx}, \dots). This is explained in Section~\ref{subsubsection:packages-loading}.
+These modes change several rendering settings.
+\itemAP[Other packages] some of the options concern the loading and the use of other packages (\kl(package){hyperref}, \kl(package){xcolor}, \kl (package){makeidx}, \dots). Note that these package can also be loaded before "knowledge@@package". This is explained in Section~\ref{subsubsection:packages-loading}.
 \itemAP[Configuration options] as used by the command \cs{\knowledgeconfigure} can be used when loading the package.
-\itemAP[Scoping] The \kl[scope option]{scope} "option@package option" makes the package aware at a fine level of the structure of the document (see Section~\ref{subsection:scoping} for explanations). This provides, for instance, the possibility to define pieces of "knowledge" that are attached to a section of the document.
+\itemAP[Scoping] The \kl[scope option]{scope} "option@package option" makes the package aware at a fine level of the structure of the document (see Section~\ref{subsection:scoping} for explanations). This provides, for instance, the possibility to define pieces of "knowledge" that are attached to a sections of the document.
 \end{compactdesc}
 
 \subsubsection{Writing mode}
 \label{subsubsection:writing modes}
-Other "package options" of "knowledge@@package" concern the ""writing modes"". There are three of them:
+There are three ""writing modes"" usable when loading the package "knowledge@@package":
 \begin{itemize}
 \itemAP In ""paper"" mode, the paper is rendered as for printing: in particular, no informative colors are visible. Hyperlinks are nevertheless present.
 \itemAP In ""electronic"" mode, the document has some colors witnessing the existence of the links for the reader to know that clicking is available.
@@ -1073,15 +1152,15 @@ or &\smallcode{\cs\usepackage[\kl{composition}]\{"knowledge@@package"\}}
 \begin{tabular}[t]{ll}
  &\smallcode{\cs\def\cs\knowledgepackagemode\texttt\{\kl{paper}\texttt\}}
 \end{tabular}\\
-The idea is that this can be used in automatic compilation scripts. For instance, launching in a terminal:\\
+The idea is that this can be used in automatic compilation scripts. For instance, using in a terminal:
 \begin{code}[12cm]
 \smallcode{\texttt{pdflatex} \quotesymbol\cs\def\cs\knowledgepackagemode% 
      \texttt\{\kl{electronic}\texttt\}\cs\input\texttt\{file.tex\texttt\}\quotesymbol}
 \end{code}
-would result in compiling `\texttt{file.tex}' using "knowledge@@package" in 
+\noindent would result in compiling `\texttt{file.tex}' using "knowledge@@package" in 
 "electronic mode". 
 
-The following primitives are available in order to be mode-dependent:\\
+The following primitives are available to the user for "writing mode"-sensitive configuration:
 \begin{code}[11.4cm]
 \AP
 \csintro\IfKnowledgePaperModeTF\texttt\{true code\texttt\}\texttt\{false code\texttt\}\\
@@ -1137,7 +1216,7 @@ Currently, the packages that can be loaded are:
 
 \subsubsection{Configuring and \cs{\knowledgeconfigure}}
 
-Some part of the configuration can be done outside of the \cs{\usepackage} command that loads the "knowledge@@package" package. \AP This is done using the
+Some part of the configuration can be done outside of the \cs{\usepackage} command that loads the "knowledge@@package" package. This is done using the
 \cs{\knowledgeconfigure} command:
 \begin{center}
 \smallcode{\csintro\knowledgeconfigure\{\kl{configuration directives}\}}
@@ -1155,8 +1234,9 @@ be used in the optional parameter of \cs{\usepackage} when loading the "knowledg
 This is typically useful around, e.g. the table of contents.
 \itemAP[\kl(option){quotation}] activates the "quotation notation", which allows to use \kl{"..."}, \kl{"...@..."} and \kl{"...@...@..."}
    instead of \cs{\kl} commands and \kl{""...""}, \kl{""...@...""} and \kl{""...@...@...""} instead of the \cs{\intro} command.
-\itemAP[""strict""] is a Boolean option which, when activated turns some warnings (for instance when a knowledge is redefined) into errors.
-\itemAP[\kl{visible anchor points}] is an option that makes visible or invisible the \kl{anchor points} of the \cs{\AP} and \cs{\itemAP} commands.
+\itemAP[""strict""] is a Boolean option which, when activated, turns some warnings (for instance when a knowledge is redefined) into errors.
+\itemAP[\kl{visible anchor points}] is an option that makes visible or invisible the \kl{anchor points} of the \cs{\AP} and \cs{\itemAP} commands. Usually, this is automatically set to true when the "composition mode" is used (the default),
+and to false when the "paper mode" or the "electronic mode" are used.
 \end{description}
 
 
@@ -1190,50 +1270,64 @@ The main one is \cs{\knowledge}. It can also be used in combination with \cs{\kn
 \subsubsection{General description of the \cs{\knowledge} command}
 
 The key command for introducing knowledges is \cs{\knowledge}.
-The syntax is:
+There are two syntaxes. The standard one is:
 \begin{center}
 \smallcode{\csintro\knowledge\{\kl[\knowledge knowledge name]{knowledge name}\}%
-  [\kl[\knowledge synonyms]{synonyms}]\{\kl[\knowledge directives]{directives}\}}
+  [\kl[\knowledge synonyms]{synonym 1}\vbar\kl[\knowledge synonyms]{synonym 2}\vbar\dots]\{\kl[\knowledge directives]{directives}\}}
 \end{center}
-
 \AP
-The \intro[\knowledge knowledge name]{knowledge name} is a string describing the knowledge. It may use any combination of symbols (well balanced with respect to brackets).
+The second one is the ""`\vbar'-notation""\footnote{%
+  This is a non-standard "LaTeX" syntax. The rule is that each knowledge appears in a distinguished line
+  that starts with some spaces and a `$\vbar$', 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.
+  }:
+\begin{code}[10cm]
+\csreintro\knowledge\{\kl[\knowledge directives]{directives}\}\\
+\indent~~~~\klbn|~\kl[\knowledge knowledge name]{knowledge name}@\kl[\knowledge optional scope]{optional scope}\\
+\indent~~~~\klbn|~\kl[\knowledge synonyms]{synonym 1}@\kl[\knowledge optional scope]{optional scope}\\
+\indent~~~~\klbn|~\kl[\knowledge synonyms]{synonym 2}@\kl[\knowledge optional scope]{optional scope}\\
+\indent~~~~~~~~$\cdots$
+\end{code}
+\AP
+The \intro[\knowledge knowledge name]{knowledge name} as well as the \intro[\knowledge synonyms]{synonyms} are plain text strings describing the knowledge. It may contain any combination of symbols, including accents or special characters as long as it well bracketted.
 This string will be used to fetch the \kl{knowledge}. Note  (and this is a standard \kl{tex} behavior) that several consecutive spaces is the same as one or a line feed.
-\AP The \intro[\knowledge synonyms]{synonyms} are  \kl[\knowledge knowledge name]{knowledge names} given in a `\vbar' separated list. This is a
-shorthand for writing `\kl{link=}' \kl[\knowledge directives]{directives}. (Note that there is another way to define synonyms using the \kl{synonym} directive).
+\AP In the normal syntax, \reintro[\knowledge synonyms]{synonyms} are given in a `\vbar' separated list, while in the "`\vbar'-notation" each of them has to be in a distinct line. \AP In the "`\vbar'-notation", an \intro[\knowledge optional scope]{optional scope} can be given after each \kl[\knowledge knowledge name]{knowledge name}/\kl[\knowledge synonyms]{synonym}.
+
+%This is a
+%shorthand for writing `\kl{link=}' \kl[\knowledge directives]{directives}. (Note that there is another way to %define synonyms using the \kl{synonym} directive).
 \AP
 The \intro[\knowledge directives]{directives} consists of `key=value' statements in a comma separated list.
-There are many \kl[\knowledge directives]{directives}. A list can be found in Section~\ref{subsection:directive list}. New ones can be defined using the \cs{\knowledgedirective} command.
+There are many \kl[\knowledge directives]{directives}. A list of them can be found in Section~\ref{subsection:directive list}. New ones can be defined using the \cs{\knowledgedirective} command.
 
 \AP
 The principle of the \cs{\knowledge} command is to introduce a new \kl{knowledge}, ready for being used.
 However, what it does exactly depends a lot on the situations.
-First, the \kl[\knowledge directives]{directives} (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 executed immediately or postponed to the next compilation phase.
-Only then, either the \kl{knowledge} is written in the \kl{kaux file} for execution during the next compilation phase, or it is executed immediately.
-Finally, \kl[\knowledge synonyms]{synonyms} are parsed and linked to the \kl{knowledge}.
+First, the \kl[\knowledge directives]{directives} (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 the \kl{kaux file}).
 
 \subsubsection{Targeting and the corresponding directives}
 
 The \cs{\knowledge} has to decide what to do when defining something. The basic behaviour is as follows.
 \begin{itemize}
 \item If the \cs{\knowledge} command is used in the preamble, then the \kl{knowledge} given as argument is defined immediately (the same effect can be obtained using the \kl{now} "directive"), and is accessible in the first compilation phase everywhere in the document (one extra phase is nevertheless required if \kl{autoref} or \kl{ref=} directives are used, for the "hyperref@@package" to do its job, or if "scope=" is used). This is the simplest way to use \cs\knowledge.
-\item Import/Export (\kl{not implemented}) writes a document containing a list of \cs{\knowledge} commands giving access to its content. This is to be imported by another document.
 \item Otherwise, the \kl{knowledge} is written in an external file (the \kl{jobname.kaux}  file), and the \kl{knowledge} will be really usable in the next compilation phase. This is particularly useful in conjunction with the \kl{scope option}: the \kl{knowledge} 	will have a scope depending on where it is introduced (for instance the document, or a theorem, or a lemma). The same \kl{knowledge name} can then point to different \kl{knowledges} depending on where it is used.
+\item Exporting (\kl{not implemented}) furthermore writes a document containing a list of \cs{\knowledge} commands giving access to its content. This is to be imported by another document.
 \end{itemize}
 
 The \intro{targeting directives} refine the above defined behaviour:
 \begin{description}
-\itemAP[\intro{scope=}] When using a \kl[\knowledge directives]{directive} `\kl{scope=}name', the scope of the definition can be modified.
-  \cs{\knowledge} will first check if there is an outer \kl{area} of this name, that accepts knowledge (only
+\itemAP[\intro{scope=} or `@' in the "`\vbar'-notation"]  When using a \kl[\knowledge directives]{directive} `\kl{scope=}name' or `@name' in the "`\vbar'-notation", the scope of the definition can be modified.
+  \cs{\knowledge} will first check if there is an outer \kl{area} of this name (\texttt{theorem}, \texttt{section}, \dots), that accepts knowledge (only
   "scope@@env" environments are subject to this unless \cs{\knowledgeconfigureenvironment} is used, or
   the "scope@@option" "package option" is used when loading the package).
 If this is the case, the knowledge will be associated to the corresponding \kl{instance}. For instance, inside a theorem, by default, the scope is the theorem, but adding the directive `\kl{scope=}section', the \kl{knowledge} becomes available in the whole section. 
 
-If no scope is found using the above search, a label of the given name is searched for, and if it exists, the corresponding scope is chosen.
-\itemAP[\intro{export=}] (\kl{not implemented}) When using this directive, the knowledge will be (furthermore) written in 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.
+If no scope is found using the above search, an "explicit scope" of the given name is used.
+
+\itemAP[\intro{export=}] (\kl{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.
 \itemAP[\intro{namespace=}] Allows to change the \kl{namespace}. In itself, this is useless. It has to be used in conjunction with new forms of \cs\kl-like commands.
 \itemAP[\intro{now}] requires the \kl{knowledge} to be defined immediately. This may save one compilation phase. The drawback is that the \kl{knowledge} cannot be accessed before the \cs{\knowledge} command that has been introduced. It may help for modularity considerations. (for instance a \kl{knowledge}
-is used inside a proof, it has no sense to make it available elsewhere, and it is better style to locally define it).
+is 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 \cs{\knowledge} command happens in the preamble.
 \itemAP[\intro{also now}] requires the \kl{knowledge} to be defined immediately as well as delayed to the next compilation phase. This is in particular how "auto references@autoref" should be handled. See the use of \cs{\knowledgenewvariant} for more examples.
 \end{description}
 
@@ -1247,7 +1341,7 @@ A certain number of Boolean directives are available without any options. These
 The general boolean \kl[\knowledge directives]{directives} are the following:
 \begin{description}
 \itemAP[\intro{emphasize}] forces the text to be emphasized using `\cs{\emph}',
-\itemAP[\intro{italic}/\intro{up}] forces/unforces italic (be it in math or text mode),
+\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),
 \itemAP[\intro{smallcaps}] forces small capitals,
 \itemAP[\intro{underline}] forces the text to be emphasized using `\cs{\underline}',
@@ -1278,7 +1372,7 @@ yield the corresponding standard \TeX{} spacing features in math mode,
 \AP The non-boolean general \kl[\knowledge directives]{directives} are the following:
 \begin{compactdesc}
 \itemAP[\intro{text=}\textmd{\{text\}}] will execute the \LaTeX{} code `text' instead of the key used for calling \cs\kl. For instance,
- \smallcode{\cs\knowledge \{latex\}\{\kl{text=}\cs{\LaTeX}\}} will typeset `\LaTeX{}' 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.
+ \smallcode{\cs\knowledge \{latex\}\{\kl{text=}\cs{\LaTeX}\}} will typeset `\LaTeX{}' 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.
 \itemAP[\intro{link=}\textmd{\{knowledge\}}] will continue searching the for linked \kl{knowledge}. Surrounding braces can be omitted if there are no commas.
   This directive is often bypassed by the use of the \kl[\knowledge optional argument]{optional argument} of \cs{\knowledge} defining synonyms or the \kl{synonym} directive.
 \itemAP[\intro{link scope=}\textmd{\{label\}}] will continue searching in the "scope" identified by the label. Surrounding braces can be omitted if there are no commas. If no "directive" "link=" is given, then the same key is searched for.
@@ -1286,11 +1380,12 @@ yield the corresponding standard \TeX{} spacing features in math mode,
   This directive is often bypassed by the use of the \kl[\knowledge optional argument]{optional argument} of \cs{\knowledge} defining synonyms or the \kl{synonym} directive.
 \itemAP[\intro{synonym}] defines the knowledge as a link to the previously defined knowledge (in fact, the most recently defined that was not using \kl{synonym}). For instance
 \begin{code}[11cm]
-\cs\knowledge\{Leslie Lamport\}\par
-~~~~~\{\kl{ref=}\{https://fr.wikipedia.org/wiki/Leslie\_Lamport\}\}\\
+\cs\knowledge\{Leslie Lamport\}\\
+\indent~~~~~\{\kl{ref=}\{https://fr.wikipedia.org/wiki/Leslie\_Lamport\}\}\\
 \cs\knowledge\{L. Lamport\}\{\kl{synonym}\}\\
 \cs\knowledge\{Lamport\}\{\kl{synonym}\}
-\end{code}\noindent
+\end{code}
+\noindent
 results in the two subsequent \kl{knowledge names} to point to the first one.
 \itemAP[\intro{style=}\textmd{\{knowledge style\}}] will 	adopt the styling option of the \kl{knowledge style}. Surrounding braces can be omitted if there are no commas.
 \itemAP[\intro{wrap=}\textmd{\robustdisplay\token}] will execute the macro `\textmd{\robustdisplay\token}' with as argument the knowledge text before displaying it. For instance,
@@ -1311,7 +1406,7 @@ The central command is \cs{\knowledgestyle}, that has the following syntax:
 \begin{center}
 \smallcode{\csintro{\knowledgestyle}*\{style name\}\{\kl[\knowledge directives]{directives}\}}
 \end{center}
-The optional star permits to overload an existing style (otherwise, this results in an error). The \kl[\knowledge directives]{directives} follow the same structure as for a normal \cs{\knowledge}
+The optional star \texttt* permits to overload an existing style (otherwise, this results in an error). The \kl[\knowledge directives]{directives} follow the same structure as for a normal \cs{\knowledge}
 command. When defined, a \kl{style} can be used in a \cs{\knowledge}
 command using the \kl[\knowledge directives]{directives} `\kl{style=}style name' (it will be used when a \cs{\kl} command calls for the \kl{knowledge}) or `\kl{intro style=}style name' (that will be used by \cs{\intro} commands).
 
@@ -1335,10 +1430,10 @@ 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:
 \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\}}
+ \smallcode{\csintro{\knowledgedirective}*\{name\}[optional parameter]\{directives\}}
 \end{center}
 After such a command has been issued, `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'. The `optional parameter' gives
+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}
 \cs\knowledgedirective\{highlight\}[brown]\{\kl{color=}\{\#1\},\kl{emphasize},\kl{md}\}\\{}
@@ -1364,12 +1459,14 @@ We shall now see \kl{notion A}, \kl{notion B}, \kl{notion C}, as well as the \kl
 \subsubsection{\cs{\knowledgestyle} versus \cs{\knowledgedirective}}
 \label{subsubsection:style versus macro}
 
+\AP 
 The two commands \cs{\knowledgestyle} and \cs{\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 \cs{\knowledge} command works.
 
+\AP 
 In general when a \cs{\knowledge} (or \cs{\knowledgestyle}) command is found, the \kl[\knowledge directives]{directives} are parsed and a new internal form of the \cs{\knowledge} command is written in the \kl{kaux file}, that will be executed during the next compilation of the document.
-In this phase, some first operations are performed. For instance, in an \kl{autoref} \kl[\knowledge directives]{directive}, an internal label name is constructed. Executing a \kl{knowledge macro} is done at this moment.
+In this phase, some first operations are performed. For instance, in an \kl{autoref} \kl[\knowledge directives]{directive}, 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 the \kl{now} directive is used). The execution effectively stores the \kl{knowledge} in the system. This is only at that moment that the \kl{knowledge} becomes available to be used by \cs{\kl} and similar commands.
 
@@ -1409,9 +1506,9 @@ The optional star does not reset the \kl{default directives} but simply add new
 The \cs{\kl} command has one of the following syntaxes:
 \begin{center}
 \begin{tabular}{cc}
-&\smallcode{\csintro{\kl}(\kl[klab]{optional label})[\kl[knowledge name]{optional knowledge name}]\{text\}}\\
+&\smallcode{\csintro{\kl}(\kl[klab]{optional scope})[\kl[knowledge name]{optional knowledge name}]\{text\}}\\
 or\quad&
-\smallcode{\csreintro{\kl}[\kl[knowledge name]{optional knowledge name}](\kl[klab]{optional label})\{text\}}\ .
+\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}.
@@ -1436,25 +1533,26 @@ This general mechanism is used also by other commands that are variations around
 When activated, the ""quotation@@option"" mode activates shorthand
 notations for the \cs{\kl} and \cs{\intro} macros. Possible syntaxes are as follows:
 \begin{description}
-\itemAP[\smallcode{\kl"text\kl"}]\phantomintro{"..."}% 
+\itemAP[\smallcode{\klqn"text\klqn"}]\phantomintro{"..."}% 
    uses the "knowledge" pointed to by `text'. Equivalent to~\texttt{\cs\kl\{text\}}.
-\itemAP[\smallcode{\kl"text@knowledge\kl"}]\phantomintro{"...@..."}%
+\itemAP[\smallcode{\klqn"text\klqn@knowledge\klqn"}]\phantomintro{"...@..."}%
     uses the "knowledge" pointed to by `knowledge to display `text'. Equivalent to~\texttt{\cs\kl[knowledge]\{text\}}.
-\itemAP[\smallcode{\kl"text@@label\kl"}]\phantomintro{"...@@..."}%
-     uses the "knowledge" pointed to by `text' in "scope" `scope' to display `text'. Equivalent to~\texttt{\cs\kl(label)\{text\}}.
-\itemAP[\smallcode{\kl"text@knowledge@label\kl"}]\phantomintro{"...@...@..."}%
-      uses the "knowledge" pointed to by `knowledge in "scope" `scope' to display `text'. Equivalent to~\texttt{\cs\kl[knowledge](label)\{text\}}.
-\itemAP[\smallcode{\kl{""}text\kl{""}}]\phantomintro{""...""}% 
+\itemAP[\smallcode{\klqn"text\klqn{@@}scope\klqn"}]\phantomintro{"...@@..."}%
+     uses the "knowledge" pointed to by `text' in "scope" `scope' to display `text'. Equivalent to~\texttt{\cs\kl(scope)\{text\}}.
+\itemAP[\smallcode{\klqn"text\klqn@knowledge\klqn@scope\klqn"}]\phantomintro{"...@...@..."}%
+      uses the "knowledge" pointed to by `knowledge in "scope" `scope' to display `text'. Equivalent to~\texttt{\cs\kl[knowledge](scope)\{text\}}.
+\itemAP[\smallcode{\klqn{""}text\klqn{""}}]\phantomintro{""...""}% 
    introduces the "knowledge" pointed to by `text'. Equivalent to~\texttt{\cs\intro\{text\}}.
-\itemAP[\smallcode{\kl{""}text@knowledge\kl{""}}]\phantomintro{""...@...""}%
+\itemAP[\smallcode{\klqn{""}text\klqn@knowledge\klqn{""}}]\phantomintro{""...@...""}%
     introduces the "knowledge" pointed to by `knowledge while displaying `text'. Equivalent to~\texttt{\cs\intro[knowledge]\{text\}}.
-\itemAP[\smallcode{\kl{""}text@@label\kl{""}}]\phantomintro{""...@@...""}%
-     introduces the "knowledge" pointed by `text' in "scope" `scope'. Equivalent to~\texttt{\cs\intro(label)\{text\}}.
-\itemAP[\smallcode{\kl{""}text@knowledge@label\kl{""}}]\phantomintro{""...@...@...""}%
-      introduces the "knowledge" pointed to by `knowledge in "scope" `scope' while displaying `text'. Equivalent to~\texttt{\cs\intro[knowledge](label)\{text\}}.
+\itemAP[\smallcode{\klqn{""}text\klqn{@@}scope\klqn{""}}]\phantomintro{""...@@...""}%
+     introduces the "knowledge" pointed by `text' in "scope" `scope'. Equivalent to~\texttt{\cs\intro(scope)\{text\}}.
+\itemAP[\smallcode{\klqn{""}text\klqn@knowledge\klqn@scope\klqn{""}}]\phantomintro{""...@...@...""}%
+      introduces the "knowledge" pointed to by `knowledge in "scope" `scope' while displaying `text'.\\
+      Equivalent to~\texttt{\cs\intro[knowledge](scope)\{text\}}.
 \end{description}
 
-\noindent\AP Activating and deactivating the "quotation notation" is obtained using:
+\noindent\AP Activating the "quotation notation" is obtained using:
 \begin{center}
 \smallcode{\cs\knowledgeconfigure\{"quotation@@option"\}}\ ,
 \end{center}
@@ -1488,8 +1586,8 @@ It may happen for several reasons that we may want to define new variants of the
 \item several sets of "knowledges" may intersect but should use different "namespace",
 \item some "knowledges" involve macros and for this reason should be non-expanded even if the \cs{\knowledge}
  command is not met,
-\item the \cs{\knowledge} command should be performed automatically,
-\item activate or desactivate the warnings or messages in the "diagnose file".
+\item the \cs{\knowledge} command should be called implicitly,
+\item activate or deactivate the warnings or messages in the "diagnose file".
 \end{itemize}
 In fact, several macros in this document are instantiation of this mechanism. This is the case for for instance for \cs{\intro}, \cs{\phantomintro}, \cs{\reintro} or \cs{\mathkl} etc...
 
@@ -1520,12 +1618,12 @@ when the "knowledge" is unknown.
 \end{compactdesc}
 \smallskip
 
-\AP The second feature is to use "modifiers@@variant". These correspond to the starred version of the command.
+\AP The second feature is to use "modifiers@@variant". These correspond to the stared version of the command.
 For instance, one expects `\cs{\intro}*\cs{\kl}' to reduce to `\cs{\intro}'. For this, one has to declare explicitly the reduction using:
 \begin{center}
-\smallcode{\csintro{\knowledgevariantmodifier}\{"starred sequence@@variant"\}\cs\variant}\ ,
-\end{center}
-in which the "starred sequence@@variant" is of the form `\cs{variant1}*\cs{variant2}*\dots*\cs{variantk}'.
+\smallcode{\csintro{\knowledgevariantmodifier}\{"stared sequence@@variant"\}\cs\variant}\ ,
+\end{center}\AP 
+in which the ""stared sequence@@variant"" is of the form `\cs{variant1}*\cs{variant2}*\dots*\cs{variantk}'.
 This sequence is declared to reduce to \cs{\variant}.
 For instance, \smallcode{\cs{\knowledgevariantmodifier}\{\cs\intro*\cs\kl\}\cs\intro} declares `\cs{\intro}*\cs{\kl}' to reduce to `\cs{\intro}'.
 
@@ -1619,14 +1717,115 @@ Several things can be noted about this code:
 \label{section:scopes}\label{subsection:scoping}
 \phantomintro{scoping}
 
-Rapidly, when long documents are in construction, one wants \kl{knowledges} to be isolated in some subparts. For instance, one may want that 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. This is in particular true when one aims to track single variables: Clearly, a variable named $x$ can occur in several lemmas, but each of them correspond to a distinct `introduction' location. For handling this situation, the "knowledge@@package" package possesses some scoping features. 
+\subsubsection{Principles of scoping}
+
+When writing long documents, one often wants \kl{knowledges} to 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 define "knowledge" in a given "scope" (and create "scopes"), and how to access "knowledge" from a given "scope".
+
+\paragraph{Accessing knowledge attached to a given scope}
+This can be done directly either using the parenthesis notations of \cs{\kl} and the second \klqn@ of
+the "quotation notation":
+\begin{center}
+\begin{tabular}{ccc}
+  \smallcode{\cs\kl(scope name)\{knowledge\}}%
+      &~or~&%
+   \smallcode{\cs\kl(scope name)[knowledge]\{displayed text\}}\\
+   \smallcode{\klqn"knowledge\klqn{@@}scope\klqn"}%
+      &~or~&%
+    \smallcode{\klqn"displayed text\klqn@knowledge\klqn@scope\klqn"}
+    \end{tabular}
+\end{center}
+It works also for \cs{\intro} and with double quotes.
+
+Another option is to import the scope locally, using:
+\begin{code}[10cm]
+\cs\knowledgeimport\{\textit{scope name 1,scope name 2,}\dots\}
+\end{code}
+After this command, the knowledges will be searched automatically in the imported scopes.
+The import stops at the end of the current scoping environment.
+
+\paragraph{Attaching knowledge to a given scope}
+This can be done directly using the "scope=" "directive", for instance in:
+\begin{code}[12cm]
+\cs\knowledge\{knowledge\}\{"scope="\textit{scope name},\textit{directives}\}
+\end{code}
+\noindent 
+or, this is obtained usint the "`\vbar'-notation" using `\klbn@'~:
+  \begin{code}[8cm]
+  \cs\knowledge\{\textit{directives}\}\\
+  \indent~~~\klbn|~~knowledge\klbn@\textit{scope name 1}\\
+  \indent~~~\klbn|~~synonym\klbn@\textit{scope name 2}\\
+  \indent~~~$\vdots$~~~~~~~~~~~~$\vdots$
+  \end{code}
+
+\AP
+The other possibility is to define a knowledge inside a "scope@@env" environment:
+\begin{code}[8cm]
+\cs\begin\{"scope@@env"\}\cs\label\{label\}\\
+\indent\quad\cs\knowledge\{knowledge 1\}\{\textit{directives}\}\\
+\indent\qquad$\vdots$\\
+\cs\end\{"scope@@env"\}
+\end{code}
+\noindent 
+In such a code, the knowledge defined is automatically visible in the environment,
+and from outside, using the scope name \texttt{label}. Indeed, the \cs{\label} is overloaded for doing automatically a \cs{\knowledgescope} command.
+
+In fact, it is possible to do even more: other environments can be defined to behave like "scope@@env".
+
+
+\subsubsection{Scoping by examples}
+
+""Explicit scoping"" consists in attaching a precise scope name to a "knowledge" using the "scope=" "directive":
+\begin{code}
+\cs\knowledge\{thing\}\{"scope="s1,"color="red\}\\
+\cs\knowledge\{thing\}\{"scope="s2,"color="green\}\\
+\\
+Here, \klqn"thing\klqn" and \cs\kl\{thing\} are unknown.\\
+But \klqn"thing\klqn{@@}s1\klqn" and \cs\kl(s1)\{thing\} are in red,\\
+and \klqn"thing\klqn{@@}s2\klqn" and \cs\kl(s2)\{thing\} are in green.
+\end{code}
+The "`\vbar'-notation" can also be used for "explicit scoping".
+This is convenient, in particular for having synonyms in different scopes:
+\begin{code}
+\cs\knowledge\{"color="red\}\\
+\indent~~\klbn|~~abelian group\\
+\indent~~\klbn|~~abelian groups\\
+\indent~~\klbn|~~Abelian groups\\
+\indent~~\klbn|~~group\klbn@abelian\\
+\indent~~\klbn|~~groups\klbn@abelian\\
+\indent~~\klbn|~~Groups\klbn@abelian\\
+
+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.\\
+\cs\end\{"scope@@env"\}
+\end{code}
+
 
-Note that the use of "scopes" may overconstrain the latex code, in particular if the "scope@@option" is used. The result is that a code that was compiling before activating the option, will not after doing it. This may happen for instance if one uses a \cs{\section} command inside a 
-a \cs{theorem} environment. Of course, though this is not forbidden by "latex", this is not something that one usually wants to do. At any rate, the scope handling of the "knowledge@@package" package --- at least in its current form --- complains in such a situation. Indeed, it attempts to reconstruct a full hierarchically decomposed  version of the document. In the above example, when the \cs{\section} command is met, the package attempts to close the outer section, but this would force the theorem also to be closed. However, closing a theorem requires an \cs{\end} command. Error...
+"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).
+\begin{code}
+\textcolor{gray}{\% We declare first in the preamble the environments that can have}\\
+\textcolor{gray}{\% knowledges attached to them.}\\
+\cs\knowledgeconfigureenvironment\{theorem,lemma,proof\}\{\}\\
+\\
+\textcolor{gray}{\% and now in the main body of the document.}\\
+\cs{\begin}\{theorem\}\cs\label\{theorem:main\}\\
+\indent~~ \cs\knowledge\{rabbit\}[rabbits]\{notion\}\\
+\indent~~ In every hat, there is a \cs\kl\{rabbit\},\\
+\indent~~ \cs\AP~in which a \cs\intro\{rabbit\} is a small animal with long ears.\\
+\cs{\end}\{theorem\}\\
+Here a \kl"rabbit\kl" is an "unknown knowledge".\\
+But \kl{"}rabbits\kl[quotation notation]{@@}theorem:main\kl{"}  point to Theorem~\cs\ref\{theorem:main\}.\\
+\cs\begin\{proof\}\cs\knowledgeimport\{theorem:main\}\\
+\indent~~ Now, \kl"rabbit\kl" is hyperlinked to Theorem~\cs\ref\{theorem:main\}.
+\cs\end\{proof\}
+\end{code}
 
 \subsubsection{What is the structure of \kl{scopes} in a document}
 
-To start with, one needs to understand what are the possible \kl{scopes}.
+To start with, one needs to understand what are the possible \kl{scopes}. Scopes are aggregation of zones in the document.
 \begin{itemize}
 \itemAP By default, all the body of the document belongs to a \kl{scope} called `\texttt{document}'.
          The user can open new scopes using the \intro(env){scope} environment:
@@ -1635,14 +1834,14 @@ To start with, one needs to understand what are the possible \kl{scopes}.
          ~~\cs\knowledge\{local notion\}\{\kl{color=}green\}\par
          ~~Here is a \cs\kl\{local notion\} that appears in green.\par
          \cs\end\{\kl(env){scope}\}\\
-         But this \cs\kl\{local notion\} is undefined.         
+         But here the \cs\kl\{local notion\} is undefined.         
          \end{code}
          Note that scoping is independent from the grouping mechanism of \LaTeX.
          
-         \AP The user can also declare an environment (existing or to exist)
-         to behave like \kl(env){scope} using the
-         command \cs{\knowledgeconfigureenvironment}.
- \itemAP The use of the ""scope@scope option"" \kl{configuration option} reconstructs the structure of the document, and \kl{scopes} will be created for 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.
+         \AP The user can also declare environments such as \texttt{lemma}, \texttt{theorem},
+         \texttt{remark} or \texttt{proof} to behave like \kl(env){scope}. This is achieved using using
+         \cs{\knowledgeconfigureenvironment} command.
+ \itemAP The use of the ""scope@scope option"" \kl{configuration option} goes one step further, and attaches "scopes" to 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 \cs{\bibitem} and \cs{\thebibliography}, and this has to be corrected by hand).
 \end{itemize}
 
 \subsubsection{How is chosen the \kl{scope} of a \kl{knowledge}?}
@@ -1660,8 +1859,8 @@ The following code (that requires the "scope option" for being functional) shoul
   \cs\knowledge\{one\}\{\kl{scope=}section,\kl{color=}green\}\par\noindent
   \cs\knowledge\{two\}\{\kl{scope=}some label,\kl{color=}green\}\par\noindent
   ~\par\noindent
-  \cs\begin\{\kl(env){scope}\}\cs\label\{some label\}\par\noindent
-  ~~Here \cs\kl\{one\} and \cs\kl\{two\} are defined.\par\noindent
+  \cs\begin\{\kl(env){scope}\}\cs\label\{some label\}\\
+  \indent~~Here \cs\kl\{one\} and \cs\kl\{two\} are defined.\\
   \cs\end\{\kl(env){scope}\}\par\noindent
   Here \cs\kl\{one\} is defined but \cs\kl\{two\} isn't.\par\noindent
   ~\par\noindent
@@ -1672,7 +1871,16 @@ The following code (that requires the "scope option" for being functional) shoul
   \end{code}
 \end{itemize}
 
-\subsubsection{Accessing other scopes, the \cs{\knowledgeimport} command}
+\subsubsection{Naming "scopes": the \cs{\knowledgeimport}, \cs{\knowledgescope} and \cs{label} commands
+}
+
+It is often the case in a text, that one has to locally break the nesting structure of a document, and refer to a object local in an environment. For instance, a comment may refer to a variables/concept that has been locally used in the proof. The "knowledge@@package" provides suitable mechanisms for complex referencing of scopes. Let us explain this through an example:
+\begin{code}
+\cs\begin{definition}\cs\label{}
+\indent~~\cs\knowledge{}
+\cs\end{definition}
+\end{code}
+
 
 Something important is missing so far: one rapidly wants to access to \kl{knowledges} that do not exist in the current \kl{scope}. For instance, a notion is used in a section of a document, and one would like to refer to it in the introduction. Another case is that of a notion or a mathematic variable that is introduced in the statement of a theorem, and should be accessible inside the proof. There are essentially two ways to access such distance \kl{knowledges}: either use the \smallcode{\cs\kl(label)\{text\}} command (or the equivalent \smallcode{\kl{"...@...@..."}} notation), or use the \cs{\knowledgeimport} command. We describe the second possibility now. The syntax is:
 \begin{center}
@@ -1699,6 +1907,7 @@ Here \$\cs\kl\verb|\alpha|\$ is unknown.\par\noindent
 \end{code}
 
 
+
 \subsubsection{Managing scoping environments}
 
  \AP The user can also declare an environment 
@@ -1725,9 +1934,9 @@ commands \cs{\begin} and \cs{\end}. Hence \cs{\proof}\dots\cs{\endproof} would
          would.
 \end{remark}
 
-\AP The ""scope directives"" are low level and advanced features. These should not be used in general. Their list is the following:
+\AP The ""scope directives"" are low level and advanced features. These should not be used in general. The list is the following:
 \begin{compactdesc}
-\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 behave like a scope).
+\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).
@@ -1754,16 +1963,27 @@ The detail of the problems are then gathered in the \kl{diagnose file}.
 \subsection{The \kl{diagnose file}}
 \label{subsection:diagnose file}
 
-The \intro{diagnose file} is a file that is created when the "knowledge@@package" package is used. It enormously eases the use of the package, and it is a good habit to sometimes check it. It gathers a certain number of informations, that can be warning, code to be used, or simply information. This file has the name of the tex document with the extension \kl{.diagnose}. Its content is divided into clearly identified parts. Depending on the used options, some of these parts may appear or disappear.
+The \intro{diagnose file} is a file that is created when the "knowledge@@package" package is used
+(note that another file, ""jobname.kaux"" is also created by the "knowledge@@package" package, for internal use). It enormously eases the use of the package, and it is a good habit to sometimes check it. It gathers a certain number of informations, that can be warning, code to be used, or simply information. This file has the name of the tex document with the extension \kl{.diagnose}. Its content is divided into clearly identified parts. Depending on the used options, some of these parts may appear or disappear.
 \begin{description}
-\itemAP[\intro{Undefined knowledges}] in this section are listed all the knowledges that have been unsuccessfully searched for. These are given in a line of code of the form \texttt{\cs{\knowledge}\{undefined knowledge\}\{\}}. One result of this way of describing is that copying the content of this section to the document itself will solve all problems of \kl{undefined knowledges}. It is an efficient way,
-when one has written a document without caring so much about knowledges to copy the content of this section, and then modify it/reorganize it, in order to suit ones purposes. By default, no suggestion is offered (i.e., the \texttt{\{\}} braces are empty). Suggestion can be automatically configured using the "suggestion=@@variant" "directive@@variant" of the macros \cs{\knowledgenewvariant} and \cs{\knowledgesetvariant}.
+\itemAP[\intro{Undefined knowledges}] in this section are listed all the knowledges that have been unsuccessfully searched for. These are given in lines either of the form 
+  \begin{quote}
+    \texttt{\cs{\knowledge}\{undefined knowledge\}\{\textit{suggested directives}\}}
+   \end{quote}
+ or of the form
+   \begin{quote}
+    \texttt{\cs{\knowledge}\{\textit{suggested directives}\}\\
+    \indent~~~\klbn|~~undefined knowledge}\textit{[\klbn@scope]}
+  \end{quote}
+  \AP Switching from one mode to another is obtained using the "configuration directive" ""bar suggestion=""\{true,false\} (default is true).  
+The intent is that copying the content of this section to the document itself will solve all problems of \kl{undefined knowledges}. It is an efficient way,
+when one has written a document without caring so much about knowledges to copy the content of this section, and then modify it/reorganize it, in order to suit ones purposes. By default, no suggestion is offered, or "notion" is suggested if the "notion@@option" directive has been used. Suggestion can be automatically configured using the "suggestion=@@variant" "directive@@variant" of the macros \cs{\knowledgenewvariant} and \cs{\knowledgesetvariant}.
 
 For instance, using:
 \begin{center}
 \smallcode{\cs\knowledgesetvariant\cs\kl\{"notion"\}}
 \end{center}
-the "directive" "notion" is suggested for more directly copying the content.
+the "directive" "notion@@option" is suggested for more directly copying the content.
 \itemAP[\intro{Autoref not introduced}] This section lists all \kl{knowledges} that were declared using the \kl{autoref} \kl[\knowledge directives]{directive} (this can be the case indirectly using, e.g.  "notion"), but have not been introduced in  the document . When a document reaches its final states, this section should be empty.
 Usually, one should add the corresponding \cs{\intro} or \cs{\phantomintro} command somewhere in the text.
 \itemAP[\intro{Autoref introduced twice}] In this section, all \kl{knowledges} that were declared using the \kl{autoref} \kl[\knowledge directives]{directive} and introduced using \cs{\intro} or \cs{\nointro}
@@ -1776,6 +1996,12 @@ This can be activated using the "diagnose line" boolean option:
 \begin{center}
 \smallcode{\cs\knowledgeconfigure\{""diagnose line=""true\}}
 \end{center}
+\AP By default, the "diagnose file" gives suggestions to be used with the normal \cs\knowledge\ syntax.
+A "`\vbar'-notation" suggestion can be activated using:
+This can be activated using the "diagnose line" boolean option:
+\begin{center}
+\smallcode{\cs\knowledgeconfigure\{""bar suggestion=""true\}}
+\end{center}
 
 \iffalse
 
@@ -1834,21 +2060,30 @@ It also offers two new directives:
  \end{center}
 \itemAP[\intro{colorbox=}] surrounds the text with a colorbox of given color (following the syntax of the "xcolor@@package" package).
 \end{description}
-Loading the package before is necessary for changing the options of the "xcolor@@package" package (for instance for using \kl{svgnames}).
+Loading the package before is necessary for changing
+the options of the "xcolor@@package" package
+(for instance for using \kl{svgnames}).
 
 \subsubsection{The \kl{hyperref option}}
  \label{subsection:hyperref option}
 
 \subsubsubsection{Activating the \kl{hyperref option}}
  
-The \intro{hyperref option} loads the \intro(package){hyperref} and triggers a certain number of link-related features. This is done either by the command:
-\marginpar{\begin{hint}
-  The "hyperref@@package" tends to surround links by boxes that do not help (this are visible in some viewers, and not in some others):  this is deactivated by the "knowledge@@package" package using the "hidelinks" option of "hyperref@@package".\end{hint}}
+The \intro{hyperref option} loads the \intro(package){hyperref}
+and triggers a certain number of link-related features.
+This is done either by the command:
+\marginpar{%
+  \begin{hint}
+     The "hyperref@@package" surrounds by default links by boxes that are graphically heavy
+     (this are visible in some viewers, and not in some others):  this is deactivated by the
+     "knowledge@@package" package using the "hidelinks" option of "hyperref@@package".
+  \end{hint}}
+%
 \begin{center}
-\smallcode{%
-\cs{\usepackage}[\kl(option){hyperref}]\{\kl(package){knowledge}\}}
-\end{center}\noindent
-or by loading the "hyperref@@package" before the "knowledge@@package" package.
+  \smallcode{%
+    \cs{\usepackage}[\kl(option){hyperref}]\{\kl(package){knowledge}\}}
+\end{center}
+\noindent or by loading the "hyperref@@package" before the "knowledge@@package" package.
 
 The \kl[\knowledge directives]{directives} activated by the package are:
 \begin{compactdesc}
@@ -2129,13 +2364,13 @@ I do not know to which extend it is compatible with various classes...
 
 \subsection{Predefined configuration}
 
-\subsubsection{The "notion" directive}
+\subsubsection{The "notion@@option" directive}
 
-The configuration option~\kl{notion} is activated using:
+The configuration option~\intro(option){notion} is activated using:
 \begin{center}
-\smallcode{\cs\knowledgeconfigure\{\intro[notion option]{notion}\}}
+\smallcode{\cs\knowledgeconfigure\{\intro(option){notion}\}}
 \end{center}\noindent
-It automatically configures a \kl[\knowledge directives]{directive} \intro{notion}
+\AP It automatically configures a \kl[\knowledge directives]{directive} \intro{notion}
 which is an \kl{autoref} displayed properly:
 \begin{itemize}
 \item In \kl{paper mode}, the \cs{\intro} commands (not in math mode) are emphasized, while the \cs{\kl} commands are displayed as normal. It has the aspect of a normal paper.
@@ -2151,13 +2386,13 @@ A typical document using notion could start by the following commands:
 \begin{code}
 \cs\documentclass\{article\}\\
 \cs\usepackage\{\kl(package){xcolor}\}\\
-\cs\usepackage\{\kl(package){hyperref}\}\\
-\cs\usepackage[\kl{paper}]\{"knowledge@@package"\}\\
+\cs\usepackage["hidelinks"]\{\kl(package){hyperref}\}\\
+\cs\usepackage[\kl{electronic}]\{"knowledge@@package"\}\\
 \cs\knowledgeconfigure\{"notion@@option"\}\\
 {[...]}\\
 \cs\knowledge\{some text\}\{notion\}
 \end{code}\noindent
-Then the paper is displayer in a colorful way. As soon as the \texttt{false} is replaced by \texttt{true}, the paper becomes black and seriously looking as it should.
+Then the paper is displayed in a colorful way. 
 
 \newpage
 
@@ -2172,7 +2407,7 @@ As usual with \LaTeX, a certain number of compilation phases are necessary for r
 
 \subsection{Problem with \cs{\item} parameters}
 
-\paragraph{The use of~\cs{\AP} inside \cs{\item} does not work.} Do not use \cs{\AP} inside the optional argument of \cs{\item}, and rather use the command \cs{\itemAP}.
+\paragraph{The use of~\cs{\AP} inside the optional parameter of \cs{\item} does not work.} Do not use \cs{\AP} inside the optional argument of \cs{\item}, and rather use the command \cs{\itemAP}.
 
 \paragraph{Argument of \cs{\kl} has an extra `\texttt\}'.} This is a problem of using optional parameters inside optional parameters such as in \smallcode{\cs\item[\cs\kl[test]\{Test\}]}. You can surround the content of the optional parameter by two level of curly braces as in \smallcode{\cs\item[\{\{\cs\kl[test]\{Test\}\}\}]}.
 The notation \kl{"..."} does not have this issue.
@@ -2274,7 +2509,7 @@ will deactivate the "quotation notation" in all the "tikzcd@@env" environments.
 \label{section:amsmath questions}
 
 \paragraph{The \cs{\intro} command does not work in \kl{align*} or similar environments}
-It happens that in starred environment (i.e., unnumbered), the package \kl(package){amsmath}
+It happens that in stared environment (i.e., unnumbered), the package \kl(package){amsmath}
 deactivates the labels. As a consequence the command \cs{\intro}, which internally uses {\cs\label} (at least so far), does not work. For the moment, there is no real solution, but a workaround which consists in introducing the \kl{knowledge} before
 the incriminated environment using \cs\phantomsection, and then use \cs{\reintro} inside the environment. Imagine for instance a command
 \texttt{\robustdisplay\SomeCommand}, that inside uses \texttt{\cs\kl[\robustdisplay{\Somecommand}]}, then:
@@ -2303,11 +2538,14 @@ the incriminated environment using \cs\phantomsection, and then use \cs{\reintro
 \subsection{Incorrect display}
 
 \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 in particularly happened for files compiled by the Arxiv system while the file on the local computer was not having any problem.
+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.
 
-A workaround is to use the \texttt{breaklinks} option of  \kl(package){hyperref}. The preamble thus looks like:
+The preamble thus looks like:
 \begin{code}[9cm]
+\cs\documentclass\{\kl{[...]}\}\par\noindent
+\cs\pdfoutput=1\par\noindent
 \kl{[...]}\par\noindent
 \cs\usepackage[\kl{breaklinks}]\{\kl(package){hyperref}\}\par\noindent
 \kl{[...]}\par\noindent
@@ -2328,7 +2566,7 @@ This is an annoying feature of the "hyperref@@package" package to surround all l
 \subsubsection{Problems in combination with \cs{\bibitem} and "thebibliography@@env"}
 
 
-The "scope option" of the package triggers some analysis of the code, and restrains the structure of the code (in particular, this is because "scopes" have to be nested, and thus some not so well nested part of \LaTeX{} yields error). In particular, the "scope option" does not allow to have a \cs{\section} command inside a list. 
+The "scope option" of the package triggers some analysis of the code, and restrains the structure of the code (in particular, this is because "scopes" have to be nested, and thus some not so well nested parts of \LaTeX{} yield errors). In particular, the "scope option" does not allow to have a \cs{\section} command inside a list. 
 However, this is what does the environment "thebibliography@@env", yielding a scoping error.
 
 A simple hack to treat this situation:
@@ -2467,7 +2705,9 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr
 
 \subsection{List of \kl{configuration directives} (to use with \cs{\knowledgeconfigure})}
 \label{subsection:configuration directive list}
+
 \begin{compactdesc}
+\item["bar suggestion="\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".
 \item["diagnose line="\textmd{\{true,false\}}] activates or deactivates the line numbering in the "diagnose file".
@@ -2476,7 +2716,7 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr
   and the two column mode.
 \item[\kl{hyperlinks=}\textmd{\{true,false\}}] activates or deactivates the hyperlinks.
 \item[{{\kl(option){notion}}}] activates the "notion" directive
-\item[\kl(option){quotation=}\textmd{\{true,false\}}] activates or deactivates the "quotation notation".
+\item[{{\kl(option)[quotation]{quotation=}\textmd{\{true,false\}}}}] activates or deactivates the "quotation notation".
 \item["paper"] switches to "paper mode",
 \item[\kl{protect link co} and \kl{unprotect link co}] starts and ends respectively a zone in which the "knowledge@@package" package does not create hyperlinks.
 \item[\kl{protect quotation=}\textmd{\{environment list\}}] declares a list of environment in which the "quotation notation" should be deactivated
diff --git a/Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx b/Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx
index 22bb3647905..6f0c6930287 100644
--- a/Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx
+++ b/Master/texmf-dist/source/latex/knowledge/knowledge-code.dtx
@@ -23,7 +23,7 @@
 %
 % \iffalse
 %<head>\usepackage{expl3}
-%<head>\ProvidesExplPackage{knowledge}{2019/02/16}{1.16}{}
+%<head>\ProvidesExplPackage{knowledge}{2019/10/03}{1.17}{}
 %<*driver>
 \def\knowledgecode{active}
 \input{knowledge.tex}
@@ -49,6 +49,7 @@
 % \changes{1.14}{2018/11/22}{bug fix} %
 % \changes{1.15}{2019/01/23}{doc change} %
 % \changes{1.16}{2019/02/15}{correct anchor point locations} %
+% \changes{1.17}{2019/10/03}{improvements} %
 % \GetFileInfo{knowledge.sty} %
 % \DoNotIndex{}
 %
@@ -68,8 +69,8 @@ This directory contains the package
 
   name: knowledge
   license: LaTeX Project Public License version 1.2 or above
-  version: v1.16
-  date: 2019/02/15
+  version: v1.17
+  date: 2019/10/03
   author: Thomas Colcombet
   mail: thomas.colcombet@irif.fr
   web: https://www.irif.fr/~colcombe/knowledge_en.html
@@ -117,7 +118,6 @@ Content of the file knowledge-sources.zip:
 \RequirePackage{l3keys2e}
 \RequirePackage{etoolbox}
 \RequirePackage{xparse}
-\RequirePackage{etoolbox}
 \bool_if_exist:NTF\knowledge_package_loaded_bool
  {\endinput}
  {\bool_new:N\knowledge_package_loaded_bool
@@ -163,6 +163,12 @@ Content of the file knowledge-sources.zip:
 \cs_generate_variant:Nn\tl_to_str:n{V}
 %    \end{macrocode}
 %
+%    \begin{macrocode}
+\tl_new:N\char_escape_tl
+\tl_set:Nx\char_escape_tl
+   {\expandafter\tl_head:n\expandafter{\string\escape}}
+%    \end{macrocode}
+%
 % \subsection{Messages of the package}
 %
 %\AP  First, some generic messages that are produced using \csintro{\knowledge_info:n},
@@ -219,6 +225,10 @@ Content of the file knowledge-sources.zip:
 \msg_new:nnn{ knowledge }{ knowledge~exists }
   { The~knowledge~'#1'~in~scope~'#2'~(namespace~'#3')~already~exists. }
 %    \end{macrocode}
+%    \begin{macrocode}
+\msg_new:nnn{ knowledge }{ knowledgedirective~redifinition }
+  { Directive~'#1'~already~exists~(\knowledgedirective~macro). }
+%    \end{macrocode}
 %
 %\AP The messages when there is a problem with scoping are \csintro{area~exists}, \csintro{area~not~exist},
 % \csintro{empty~pop}, \csintro{no~pushing~here}, \csintro{no~popping},
@@ -421,6 +431,12 @@ Content of the file knowledge-sources.zip:
 %    \end{macrocode}
 %
 %    \begin{macrocode}
+\bool_new:N\knowledge_configuration_barsuggestion_bool
+\bool_gset_false:N\knowledge_configuration_barsuggestion_bool
+\KnowledgeConfigureBooleanOption[\knowledge_configuration_barsuggestion_bool]{bar~suggestion}
+%    \end{macrocode}
+%
+%    \begin{macrocode}
 \bool_new:N\knowledge_configuration_visibleAP_bool
 \KnowledgeConfigureBooleanOption[\knowledge_configuration_visibleAP_bool]{visible~anchor~points}\KnowledgeConfigureBooleanOption[\knowledge_configuration_visibleAP_bool]{visible~AP}
 %    \end{macrocode}
@@ -444,7 +460,12 @@ Content of the file knowledge-sources.zip:
 \KnowledgeConfigureTrigger{ fix~hyperref~twocolumn }
   {\knowledgeFixHyperrefTwocolumn}
 \KnowledgeConfigureTrigger{ notion }
-  {\KnowledgeConfigureNotion{notion}}
+  {\KnowledgeConfigureNotion{notion}
+   \knowledgesetvariant\kl{suggestion=notion}
+   \knowledgesetvariant\intro{suggestion=notion}
+   \knowledgesetvariant\phantomintro{suggestion=notion}
+   \knowledgesetvariant\reintro{suggestion=notion}
+   }
 \KnowledgeConfigureTrigger{ protect~links }
   {\kl_kl_nesting_incr:}
 \KnowledgeConfigureTrigger{ unprotect~links }
@@ -626,9 +647,9 @@ Content of the file knowledge-sources.zip:
 % \item[\kl{categories}] are collections of \kl{areas} that share some common behaviours, for instance, the \kl{category} `\texttt{itemize-like}' will aggregate
 %   `\texttt{itemize}', `\texttt{enumerate}' \kl{areas}. In particular an `\texttt{item}'
 %   \kl{area} is required to have a parent that belongs to the \kl{category} `\texttt{itemize-like}'.
-% \item[\kl{instances}] are the realization of \kl{areas} in a document. Hence `section' is an \kl{area},
+% \item[\intro{instances}] are the realization of \kl{areas} in a document. Hence `section' is an \kl{area},
 %    but each section of a document is an \kl{instance}. 
-% \item[\kl{scopept instances}] stands for `phase two'. These are functions that are activated during
+% \item[\intro{scopept instances}] stands for `phase two'. These are functions that are activated during
 % the second compilation. (and also, under implementation, in the preamble)
 % \item[\kl{knowledges}] are the central notion
 % \end{description}
@@ -964,7 +985,7 @@ Content of the file knowledge-sources.zip:
   \seq_gpop:NNTF\scope_instances_stack_seq\l_tmpa_tl
      {\tl_gset_eq:NN\scope_top_instance_tl\l_tmpa_tl
      \int_gdecr:c{\scope_tl.area[\scope_top_area_tl].nesting_int}
-     \exp_args:NV\knowledge_pop_visible_instances_to:n\scope_top_instance_tl
+     \knowledge_pop_visible_instances_to_mark:
      \seq_get:NN\scope_instances_stack_seq\l_tmpa_tl
      \tl_gset_eq:NN\scope_top_instance_tl\l_tmpa_tl
      \tl_gset:Nx\scope_top_area_tl
@@ -1071,6 +1092,7 @@ Content of the file knowledge-sources.zip:
          {\scope_top_area_tl-\int_to_arabic:n{\int_use:c{\scope_tl.area[\scope_top_area_tl].count_int}}}}
     {\tl_gset_eq:NN\scope_top_instance_tl\scope_top_area_tl}
   %
+  \knowledge_push_visible_instance_mark:
   \exp_args:Nx\knowledge_push_visible_instance:n{\scope_top_instance_tl}
   \seq_gpush:Nx\scope_instances_stack_seq{\scope_top_instance_tl}
   %
@@ -1118,8 +1140,6 @@ Content of the file knowledge-sources.zip:
 % instance able to receive knowledges. 
 % This is done by inspecting the scope stack until reaching an instance
 % that has \kl{instance.attractsknowledge_bool} set to true (by default, this is `base').
-%
-% Searching for instances.
 %    \begin{macrocode}
 \cs_new:Nn\scope_get_attractive_instance:N
 {\tl_set:Nn#1{base}
@@ -1129,9 +1149,11 @@ Content of the file knowledge-sources.zip:
       {\tl_set:Nn#1{##1}\seq_map_break:}{}}
 }
 %    \end{macrocode}
-%
+% \csintro{\scope_get_labelizable_instance:N} takes a token list variable as input for holding the result.
+% It inspects the current stack of instances \cs{\scope_instances_stack_seq}, searching for an "instance"
+% of a "scope" which is labelizable, and returns it. The default is `base'.
 %    \begin{macrocode}
-\cs_new:Nn\scope_get_labelizable_instance:N
+\cs_new:Nn\scope_get_labelizable_instance:N 
 {\tl_set:Nn#1{base}
   \seq_map_inline:Nn\scope_instances_stack_seq
     {\bool_if:cTF
@@ -1139,15 +1161,19 @@ Content of the file knowledge-sources.zip:
       {\tl_set:Nn#1{##1}\seq_map_break:}{}}
 }
 %    \end{macrocode}
-%
-% The command \cs{\knowledge_scope_track_instance:Nn} tries to find a given instance in the current context,
+% The command \csintro{\knowledge_scope_track_instance:Nn} is the internal part od the "scope=" directive.
+% It takes as argument a token list variable for holding the result, and a text to be looked for.
+% If the text corresponds to a "scope" name (such as section, theorem, \dots), then it inspects the
+% content of the stacks for finding the target.
+% Otherwise, it uses it as a label.
 % and if it fails, it tries to find a label of this name that provides an instance. 
 %    \begin{macrocode}
-\cs_new:Nn\knowledge_scope_track_instance:Nn{
-    \scope_area_if_exist:nTF{#2}
-       {\knowledge_scope_track_instance_from_area:Nn#1{#2}}
-       {\knowledge_scope_track_instance_from_label:Nn#1{#2}}
-}
+%\cs_new:Nn\knowledge_scope_track_instance:Nn{
+%    \tl_show:n{#1:#2}
+%    \scope_area_if_exist:nTF{#2}
+%       {\knowledge_scope_track_instance_from_area:Nn#1{#2}}
+%       {\knowledge_scope_track_instance_from_scopetag:Nn#1{#2}}
+%}
 \cs_new:Nn\knowledge_scope_track_instance_from_area:Nn{
   \tl_set:Nn#1{}
   \seq_map_inline:Nn\scope_instances_stack_seq
@@ -1160,11 +1186,18 @@ Content of the file knowledge-sources.zip:
     {\msg_error:nnxx{scope}{area~not~in~context}{#2}{scope=}}
     {}
 }
-\cs_new:Nn\knowledge_scope_track_instance_from_label:Nn{
-  \tl_set:Nn#1{}
-  \scopept_label_instance_if_exist:nTF{#2}
-      {\tl_set:Nx#1{\scopept_label_instance_use:n{#2}}}
-      {\msg_warning:nnnn{scope}{unknown~label}{#2}{scope=}}
+%    \end{macrocode}
+% The command \cs{\knowledge_scope_track_scope:n}
+% is used to set the variable \cs{\knowledge_knowledge_instance_tl}.
+% If the argument is a scope name, then it is searched for in the context, and the corresponding "instance" is used.
+% Otherwise it is used as a "scopetag"; this "scopetag" being potentially
+% defined if necessary using \cs{\knowledge_scopetag_warn_if_unknown:n}.
+%    \begin{macrocode}
+\cs_new:Nn\knowledge_scope_track_scope:n{
+    \scope_area_if_exist:nTF{#1}
+       {\knowledge_scope_track_instance_from_area:Nn\knowledge_knowledge_instance_tl{#1}}
+       {\tl_set:Nn\knowledge_knowledge_instance_tl{explicit-scope:#1}
+        \knowledge_scopetag_warn_if_unknown:n{#1}}
 }
 %    \end{macrocode}
 %    \begin{macrocode}
@@ -1194,31 +1227,114 @@ Content of the file knowledge-sources.zip:
 %    \end{macrocode}
 %
 %
-%  \subsubsection{Label overloading}
+%  \subsubsection{Scope tags}
 %
-% In order to identify scopes, the standard \cs{\label} command is used.
-% This requires to overload it for it to write on the \kl{kaux file}.
-% Thus, the new \cs{\label} command executes the original code,
-% and furthermore writes in the \kl{kaux file} a \cs{\KAuxScopeLabel} command.
-% \iffalse
-% Note that in order to accelerate compilation, the label is both written on the "kaux file",
-% and directly in the memory. This
-% \fi
+% A ""scopetag"" is a name that can be used to identify a family of  "instances" that correspond to it.
+% It gets to have two variables attached to it:
+% \begin{description}
+% \itemAP[\cs{\knowledge_scopetag_tl}\texttt{{[TAG]}\_bool}] which tells whether it
+%    has been officially declared (it is false if it has been used but not declared by a \cs{\knowledgescope}
+%    or a \cs{\label} command).
+% \itemAP[\cs{\knowledge_scopetag_tl}\texttt{{[TAG]}\_seq}] is a sequence of
+%    "instances" that are attached to it. It always contains (as soon as created)
+% \end{description}
+%
+% In order to identify scopes, the command~\cs{\knowledgescope} (or \cs{\label} which is overloaded for this purpose).
+%
+% \par\noindent\AP\csintro{\knowledge_scopetag_tl} is a unique string for identifying "scopetags".
+% \par\noindent\AP\csintro{\knowledge_scopetag_if_exist:nTF} tests the existence of a "scopetag".
+% \par\noindent\AP\csintro{\knowledge_scopetag_ensure:n} guarantees that the "scopetag" is defined (by default, the boolean is set to false).
+% \par\noindent\AP\csintro{\knowledge_scopetag_warn_if_unknown:n} writes  \cs{\KAuxUndeclaredScopeTag} to the "kaux file" if the "scopetag" was never met before, then calls \cs{\knowledge_scopetag_ensure:n}.
+% \par\noindent\AP\csintro{\knowledge_scopetag_declares:n} creates the "scopetag" if necessary, and if it was not known before, declares and puts a \cs{\KAuxDeclaredScopeTag} command in the "kaux file".
+%    \begin{macrocode}
+\tl_const:Nn\knowledge_scopetag_tl{ScpT@g}
+%    \end{macrocode}
 %    \begin{macrocode}
-\NewDocumentCommand\scopeLabel{m}
-  { \kl_hide_begin:
+\cs_new:Npn\knowledge_scopetag_if_exist:nTF#1
+   {\tl_if_exist:cTF{\knowledge_scopetag_tl[#1]_bool}}
+\cs_new:Nn\knowledge_scopetag_ensure:n{
+   \knowledge_scopetag_if_exist:nTF{#1}{}
+      {\bool_new:c{\knowledge_scopetag_tl[#1]_bool}
+       \bool_gset_false:c{\knowledge_scopetag_tl[#1]_bool}
+       \seq_new:c{\knowledge_scopetag_tl[#1]_seq}
+       \seq_gput_right:cn{\knowledge_scopetag_tl[#1]_seq}{explicit-scope:#1}}}
+%    \end{macrocode}
+%    \begin{macrocode}   
+\cs_new:Nn\knowledge_scopetag_warn_if_unknown:n{
+    \knowledge_scopetag_if_exist:nTF{#1}{}
+      {\KAuxWriteX*{\exp_not:N\KAuxUndeclaredScopeTag{#1}}
+       \knowledge_scopetag_ensure:n{#1}}
+}
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Nn\knowledge_scopetag_declares:n{
+    \knowledge_scopetag_ensure:n{#1}
+    \bool_if:cTF{\knowledge_scopetag_tl[#1]_bool}
+      {}
+      {\KAuxWriteX*{\exp_not:N\KAuxDeclaredScopeTag{#1}}
+       \bool_gset_true:c{\knowledge_scopetag_tl[#1]_bool}}
+}
+%    \end{macrocode}
+% \AP The command \csintro{\knowledgescope} associates an "instance" to one or more "scopetags":
+%    \begin{macrocode}
+\NewDocumentCommand\knowledgescope{ >{\SplitList{,}}m }{
+	\kl_hide_begin:\group_begin:
+      \ProcessList{#1}\knowledge_knowledgescope_one:n
+    \group_end:\kl_hide_end:
+}
+\cs_new:Nn\knowledge_knowledgescope_one:n{
+    \knowledge_scopetag_declares:n{#1}
     \scope_get_labelizable_instance:N\l_tmpb_tl
-    \KAuxWriteX*{\exp_not:n{\KAuxScopeLabel}{\exp_not:n{#1}}{\l_tmpb_tl}}
-    %\tl_new:cx{\scopept_tl.label[#1].instance_tl}{\l_tmpb_tl}
-    \kl_hide_end:
-    \cs_if_exist:NTF\LaTeXlabel\LaTeXlabel\use_none:n{#1}}
+    \KAuxWriteX*{\exp_not:n{\KAuxNewLinkScopetagInstance}{\exp_not:n{#1}}{\l_tmpb_tl}}
+}
+%    \end{macrocode}
+%
+% \paragraph{Modified labels}
+% \AP The boolean \csintro{\knowledge_configuration_label_autoscope_bool}
+% activates or deactivates the automatic calling to \cs{knowlegescope} when \cs{\label} is used.
+%    \begin{macrocode}
+\bool_new:N\knowledge_configuration_label_autoscope_bool
+\bool_gset_true:N\knowledge_configuration_label_autoscope_bool
 %    \end{macrocode}
+% \noindent\AP\csintro{\scopeLabel} implicitly adds a call to \cs{\knowledgescope} (if \cs{\knowledge_configuration_label_autoscope_bool} is set to true), and then calls the original \cs{\label} code.
 %    \begin{macrocode}
+\NewDocumentCommand\scopeLabel{m}{
+    \kl_hide_begin:
+       \bool_if:NT
+         \knowledge_configuration_label_autoscope_bool
+         \knowledge_knowledgescope_one:n{#1}
+    \kl_hide_end:
+    \cs_if_exist:NTF\LaTeXlabel\LaTeXlabel\use_none:n{#1}
+}
 \let\label\scopeLabel
+%    \end{macrocode}
+% \AP In order to cicumvent this overloading, the normal \cs{\label} command
+% can be used using \csintro{\knowledge_latex_label:n}:
+%    \begin{macrocode}
 \cs_new:Npn\knowledge_latex_label:n{
   \cs_if_exist:NTF\LaTeXlabel\LaTeXlabel\label
 }
 %    \end{macrocode}
+% \par\noindent\csintro{\knowledge_scopetag_warn_if_unknown:n} takes a "scopetag" as input.
+% If it does not exist, it defines, and sets its boolean to false.
+%    \begin{macrocode}
+\NewKAuxCommand\KAuxUndeclaredScopeTag{m}
+   {Package~scope:~States~that~a~labelname~is~used~in~a~knowledge~definition.}
+\DeclareKAuxPhaseCommand\KAuxUndeclaredScopeTag{init}{}
+\NewKAuxCommand\KAuxDeclaredScopeTag{m}
+   {Package~scope:~States~that~a~labelname~has~been~declared.}
+\DeclareKAuxPhaseCommand\KAuxDeclaredScopeTag{init}{
+     \knowledge_scopetag_if_exist:nTF{#1}{}
+       {\bool_new:c{\knowledge_scopetag_tl[#1]_bool}}
+        \bool_gset_true:c{\knowledge_scopetag_tl[#1]_bool}
+   }
+\NewKAuxCommand\KAuxNewLinkScopetagInstance{mm}
+   {Package~scope:~Declares~that~a~label~is~declared~in~an~instance~of~a~scope.}
+\DeclareKAuxPhaseCommand\KAuxNewLinkScopetagInstance{init}{
+	\knowledge_scopetag_ensure:n{#1}
+	\seq_gput_right:cn{\knowledge_scopetag_tl[#1]_seq}{#2}
+}
+%    \end{macrocode}
 %
 %
 %\subsubsection{Processing the \kl{kaux file}}
@@ -1234,9 +1350,9 @@ Content of the file knowledge-sources.zip:
    \tl_new:cn{\scopept_tl.instance[#2].parent_tl}{#3}}
 %    \end{macrocode}
 %    \begin{macrocode}
-\NewKAuxCommand\KAuxScopeLabel{mm}
-  {Package~scope:~Links~a~label~to~the~scope~of~its~definition.}
-\DeclareKAuxPhaseCommand\KAuxScopeLabel{init}
+\NewKAuxCommand\KAuxScopeTag{mm}
+  {Package~scope:~Links~a~scopetag~to~an~instance~of~a~scope.}
+\DeclareKAuxPhaseCommand\KAuxScopeTag{init}
   {\tl_if_exist:cTF{\scopept_tl.label[\tl_to_str:n{#1}].instance_tl}{}
      {\tl_new:cn{\scopept_tl.label[\tl_to_str:n{#1}].instance_tl}{#2}}}
 %    \end{macrocode}
@@ -1511,9 +1627,9 @@ Content of the file knowledge-sources.zip:
 % We define now the basic macros that are used for accessing knowledges.
 % Each knowledge is identified by three parameters:
 % \begin{itemize}
-% \item the namespace name (no arobas in it), each different use of the "knowledge@@package" package can use a different namespace. For the moment, this is always `default'.
-% \item the \kl{instance} name (defining the scope, i.e. the region in which it is defined; no arobas in it), it is generated and dealt with by the \texttt{scope} package, 
-% \item the \kl{knowledge} text itself.
+% \itemAP the namespace name (no arobas in it), each different use of the "knowledge@@package" package can use a different namespace. For the moment, this is always `default'.
+% \itemAP the \kl{instance} name (defining the scope, i.e. the region in which it is defined; no arobas in it). "Instances" are automatically generated, and the used should never has access to it.
+% \itemAP the \kl{knowledge} text itself.
 % \end{itemize}
 %
 % The variable \cs{\knowledge_namespace_tl}
@@ -1568,7 +1684,7 @@ Content of the file knowledge-sources.zip:
   \exp_args:Nc\ktuple_if_exist:NTF{\knowledge_id:nnn{#1}{#2}{#3}}
 }
 \cs_generate_variant:Nn
-  \knowledge_knowledge_if_exist:nnnTF{VVVTF}
+  \knowledge_knowledge_if_exist:nnnTF{VVVTF,VnVTF}
 %    \end{macrocode}
 %
 %
@@ -1642,7 +1758,6 @@ Content of the file knowledge-sources.zip:
 % \iffalse
 %    \begin{macrocode}
 \NewDocumentCommand\NewKnowledgeParamTl{som}{
-  %\tl_show:n{#2}
   \IfNoValueTF{#2}
   {  \tl_set:Nn\l_tmpa_tl{#3}
      \tl_remove_all:Nn\l_tmpa_tl{~}
@@ -1745,7 +1860,7 @@ Content of the file knowledge-sources.zip:
 % \item[\cs{\knowledge_visible_instances_seq}] contains the sequence
 %    of instances that are visible right now. 
 % \item[\csintro{\knowledge_scope_track_instance:Nn}\cs\tokenlist\{scope name\}]
-%   sets \cs{\tokenlist} to the outermost instance of the scope name.
+%   sets \cs{\tokenlist} to the innermost instance of the scope name.
 %   Typically, if the request is `\texttt{subsection}', the answer will be `\texttt{subsection-3.1}',
 %   identifying the subsection currently in scope. 
 % \end{compactdesc}
@@ -1760,45 +1875,59 @@ Content of the file knowledge-sources.zip:
 %    Note that \cs{\knowledge_visible_instances_seq} may only be correct after one compilation.
 % \begin{compactdesc}
 % \item[\csintro{\knowledge_push_visible_instance:n}]
-% \item[\csintro{\knowledge_pop_visible_instance:}]
+% \item[\csintro{\knowledge_push_visible_instance_mark:}] Inserts in \cs{\knowledge_visible_instances_seq} a special marker,
+%   which is used when pushing a scope.
+% \item[\csintro{\knowledge_pop_visible_instances_to_mark:}] Pops everything till the special mark.
 % \item[\csintro{\knowledge_pop_visible_instances_to:n}]
 % \item[\csintro{\knowledge_show_visible_instances:}]
 % \end{compactdesc}
 % 
 %    \begin{macrocode}
 \seq_new:N\knowledge_visible_instances_seq
+%    \end{macrocode}
+% Special marks are introduced for remembering till where to pop when a "scope" ends.
+%    \begin{macrocode}
 \cs_new:Nn\knowledge_push_visible_instance:n
   {\seq_gpush:Nn\knowledge_visible_instances_seq{#1}}
-\cs_new:Npn\knowledge_pop_visible_instance:
-  {\seq_gpop:NN\knowledge_visible_instances_seq\l_tmpa_tl}
-\cs_new:Nn\knowledge_pop_visible_instances_to:n
+\cs_new:Nn\knowledge_push_visible_instance_mark:
+  {\seq_gpush:Nn\knowledge_visible_instances_seq{|}}
+%    \end{macrocode}
+% 
+%    \begin{macrocode}
+\cs_new:Nn\knowledge_pop_visible_instances_to_mark:
   {\seq_gpop:NNTF\knowledge_visible_instances_seq\l_tmpa_tl
-       {\exp_args:NV\tl_if_eq:nnTF\l_tmpa_tl{#1}
+       {\exp_args:NV\tl_if_eq:nnTF\l_tmpa_tl{|}
             {}
-            {\knowledge_pop_visible_instances_to:n{#1}}}
-       {\INTERNAL_ERROR_EMPTY_POP_VISIBLE}}
+            {\knowledge_pop_visible_instances_to_mark:}}
+       {\KNOWLEDGE_INTERNAL_ERROR:_stack_of_visible_instances_is_empty_while_popping}}
+%    \end{macrocode}
+%    \begin{macrocode}
 \cs_new:Nn\knowledge_show_visible_instances:
   {\tl_show:x
     {Visible~instances~<\seq_use:Nn\knowledge_visible_instances_seq{,}>}}
 %    \end{macrocode}
 %    \begin{macrocode}
-\cs_new:Nn\knowledge_import_instance:n
-  {\seq_if_in:NnTF\knowledge_visible_instances_seq{#1}
-      {}{\knowledge_push_visible_instance:n{#1}}}
+\NewDocumentCommand\knowledgeimport{ >{\SplitList{,}}m }{
+    \kl_hide_begin:
+    \ProcessList{#1}\knowledge_knowledgeimport:n
+    \kl_hide_end:
+}
 %    \end{macrocode}
 %    \begin{macrocode}
-\NewDocumentCommand\knowledgeimport{m}
-  {\kl_hide_begin:
-   \scopept_label_instance_if_exist:nTF{#1}
-    {\exp_args:Nx\knowledge_import_instance:n{\scopept_label_instance_use:n{#1}}}
-    {\msg_warning:nnnn{scope}{unknown~label}{#1}{\knowledgeimport}}
-   \kl_hide_end:
-}
+\cs_set:Nn\knowledge_knowledgeimport:n{
+   \knowledge_scopetag_warn_if_unknown:n{#1}
+   \knowledge_scopetag_ensure:n{#1}
+   \exp_args:Nc\seq_map_function:NN
+       {\knowledge_scopetag_tl[#1]_seq}
+       \knowledge_push_visible_instance:n
+ }
 %    \end{macrocode}
 %
 %
 % \subsubsection{The  knowledge targeting}
-%%
+%
+% We define now the "directives" that are used for choosing how the "knowledge" should be defined.
+%
 %    \begin{macrocode}
 \keys_define:nn { knowledge~directives } {
   namespace .code:n = { \tl_set:Nn\knowledge_knowledge_namespace_tl{#1} },
@@ -1814,16 +1943,18 @@ Content of the file knowledge-sources.zip:
   export / false .code:n = {\bool_set_false:N\knowledge_knowledge_export_bool},
   export / true .code:n = {\bool_set_true:N\knowledge_knowledge_export_bool},
   export .default:n = false,
-  instance .code:n =
-     { \tl_set:Nn\knowledge_knowledge_instance_tl{#1} },
+%  instance .code:n =
+%     { \tl_set:Nn\knowledge_knowledge_instance_tl{#1} },
+  link~instance .code:n =
+    { \tl_set:Nn\knowledge_knowledge_instance_tl{#1} },
   scope .code:n =
-     { \knowledge_scope_track_instance:Nn\knowledge_knowledge_instance_tl{#1} },
+  	{ \knowledge_scope_track_scope:n{#1}
+       \tl_gput_right:Nn\knowledge_knowledge_immediate_synonym_directives_tl{,scope = {#1}}},
   synonym .code:n =
      { \bool_set_true:N\knowledge_knowledge_is_synonym_bool
        \exp_args:Nnx\keys_set:nn { knowledge~directives }
-          {link={\exp_not:o\knowledge_knowledge_synonym_tl},
-           link~instance={\exp_not:o\knowledge_knowledge_synonyminstance_tl},
-           instance={\exp_not:o\knowledge_knowledge_synonyminstance_tl}}}
+          {link={\exp_not:o\knowledge_knowledge_synonymlink_tl},
+           link~instance={\exp_not:V\knowledge_knowledge_synonyminstance_tl}}},
 }
 %    \end{macrocode}
 %
@@ -1860,6 +1991,8 @@ Content of the file knowledge-sources.zip:
     {\knowledge_at:N\ktuple_new:N}
   \keys_set:nn { knowledgenow~directives } { #4 }
 }
+%    \end{macrocode}
+%    \begin{macrocode}
 \cs_new:Nn\knowledge_set_now:nnnn
  {\knowledge_sets_to:nnn{#1}{#2}{#3}
   \knowledge_at:N\ktuple_if_exist:NTF
@@ -1869,6 +2002,8 @@ Content of the file knowledge-sources.zip:
     {\knowledge_at:N\ktuple_new:N}
   \keys_set:nn { knowledgenow~directives } { #4 }
 }
+%    \end{macrocode}
+%    \begin{macrocode}
 \cs_generate_variant:Nn\knowledge_new_now:nnnn{nnVn}
 \cs_generate_variant:Nn\knowledge_set_now:nnnn{nnVn}
 %    \end{macrocode}
@@ -1879,13 +2014,13 @@ Content of the file knowledge-sources.zip:
 % using \cs{\KAuxWriteLocation}, and then proceeds with \cs{\__knowledge_knowledge}.
 %    \begin{macrocode}
 \NewDocumentCommand\knowledge{}
-  {\KAuxWriteLocation\__knowledge_knowledge}
+  {\KAuxWriteLocation\__knowledge_knowledge_init:w}
 %    \end{macrocode}
 % The command \csintro{\__knowledge_knowledge} is the center of the \cs{\knowledge}
 % command. It parses its arguments (in particular separating the synonyms using the "xparse@@package"), and executes \cs{\knowledge_knowledge_process:nn}
 %    \begin{macrocode}
-\NewDocumentCommand\__knowledge_knowledge{t! t+ m >{\SplitList{|}}o m } 
-{ \kl_hide_begin:
+\NewDocumentCommand\__knowledge_knowledge_init:w{t! t+ m m}{
+  \kl_hide_begin:
   \group_begin: 
   %
    \IfBooleanTF{#1}{%
@@ -1900,27 +2035,102 @@ Content of the file knowledge-sources.zip:
    \tl_set_eq:NN\knowledge_namespace_tl
       \knowledge_default_namespace_tl
   %
+  \tl_gset:Nn\knowledge_knowledge_immediate_synonym_directives_tl{synonym}
+  %
   \bool_gset_false:N\knowledge_knowledge_is_synonym_bool
   %
+  \tl_if_eq:nnTF{#4}{|}
+     {\__knowledge_knowledge_cont_newsyntax:nw{#3}|}
+     {\tl_if_eq:nnTF{#4}{[}
+          {\__knowledge_knowledge_cont_classical:nw{#3}[}
+          {\__knowledge_knowledge_cont_classical:nw{#3}{#4}}}
+}
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Nn\__knowledge_knowledge_recallsynonym:n{
+    \bool_if:NF\knowledge_knowledge_is_synonym_bool
+      {\tl_gset:Nn\knowledge_knowledge_synonymlink_tl{#1}
+       \tl_gset_eq:NN\knowledge_knowledge_synonyminstance_tl
+           \knowledge_knowledge_instance_tl}
+}
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Nn\__knowledge_knowledge_end:{
+  \group_end:
+  \kl_hide_end:
+}
+%    \end{macrocode}
+%    \begin{macrocode}
+\NewDocumentCommand\__knowledge_knowledge_cont_classical:nw{m >{\SplitList{|}}o m }{
+  \knowledge_knowledge_setparseat:NNn\l_tmpa_tl\l_tmpb_tl{#1}
+  %
   \use:x{
-    \exp_not:n{\knowledge_knowledge_process:nn{#3}}
-      {\exp_not:V\knowledge_knowledgedefault_tl,\exp_not:n{#5}}}
+    \exp_not:N\knowledge_knowledge_process:nn
+      {\exp_not:V\l_tmpa_tl}
+      {\exp_not:V\knowledge_knowledgedefault_tl,
+      \exp_not:n{#3},
+      \tl_if_empty:NTF\l_tmpb_tl{}{,scope={\exp_not:V\l_tmpb_tl}}}}
   %
-  \bool_if:NF\knowledge_knowledge_is_synonym_bool
-    {\tl_gset:Nn\knowledge_knowledge_synonym_tl{#3}
-     \tl_gset_eq:NN\knowledge_knowledge_synonyminstance_tl
-         \knowledge_knowledge_instance_tl}
+  \exp_args:NV\__knowledge_knowledge_recallsynonym:n\l_tmpa_tl
   %
-  \IfNoValueTF{#4}{}{
+  \IfNoValueTF{#2}{}{
     \cs_set:Nn\l_tmpa_cs:n
-      {\exp_args:Nnx\knowledge_knowledge_process:nn{##1}{synonym}}
-    \ProcessList{#4}\l_tmpa_cs:n
+      {\exp_args:Nnx\knowledge_knowledge_process:nn{##1}
+          {\exp_not:V\knowledge_knowledge_immediate_synonym_directives_tl}}
+    \ProcessList{#2}\l_tmpa_cs:n
     } 
   %
-  \group_end:
-  \kl_hide_end:
+  \__knowledge_knowledge_end:
+}
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Npn\knowledge_knowledge_newsyntax_firstline:n{}
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Npn\knowledge_knowledge_newsyntax_nextlines:n{}
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Npn\__knowledge_knowledge_cont_newsyntax:nw#1{
+	\cs_set:Nn\knowledge_knowledge_newsyntax_firstline:n
+	   {\knowledge{##1}{#1}
+        \cs_set_eq:NN
+	       \knowledge_knowledge_newsyntax_exec_line:n
+	       \knowledge_knowledge_newsyntax_nextlines:n}
+	\cs_set:Nn\knowledge_knowledge_newsyntax_nextlines:n
+	   {\exp_args:Nnx\knowledge{##1}
+	        {\exp_not:V\knowledge_knowledge_immediate_synonym_directives_tl}}
+	\cs_set_eq:NN
+	   \knowledge_knowledge_newsyntax_exec_line:n
+	   \knowledge_knowledge_newsyntax_firstline:n
+	\kl_newknowledge_parse:w
 }
 %    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Npn\kl_newknowledge_parse:w{
+	\peek_charcode_remove_ignore_spaces:NTF|
+		{\kl_insert_klendline:w\knowledge_knowledge_newsyntax_exec_line:w}
+		{\__knowledge_knowledge_end:}
+}
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Npn\knowledge_knowledge_newsyntax_exec_line:w#1\kl_end_line:{
+    \knowledge_knowledge_newsyntax_exec_line:n{#1}
+	\kl_newknowledge_parse:w
+}
+%    \end{macrocode}
+%    \begin{macrocode}
+\char_set_catcode_active:N\^^M
+\cs_gset:Npn\kl_insert_klendline:w{\group_begin:\catcode`\^^M=\active\kl_insert_klendline_:w}
+\cs_gset:Npn\kl_insert_klendline_:w#1^^M{\group_end:#1\kl_end_line:}
+\char_set_catcode_end_line:N\^^M
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Nn\knowledge_knowledge_setparseat:NNn
+	{\knowledge_knowledge_setparseat_:NNw#1#2#3@@\kl_end:}
+\cs_new:Npn\knowledge_knowledge_setparseat_:NNw#1#2#3@#4@#5\kl_end:
+	{\tl_set:Nx#1{\tl_trim_spaces:n{#3}}
+	\tl_set:Nx#2{\tl_trim_spaces:n{#4}}}
+%    \end{macrocode}
 %
 %\AP The boolean \cs{\knowledge_knowledgestyle_bool}
 % is set to true in order \cs{\knowledge_knowledge_process:nn}
@@ -1950,6 +2160,25 @@ Content of the file knowledge-sources.zip:
 %\AP The \cs{\knowledge_knowledge_process:nn} command is the internal 
 % version of \cs{\knowledge}. It takes two parameters:
 % the key, and the comma separated list of directives.
+% It uses internally the following `variables':
+% \begin{asparadesc}
+% \itemAP[\csintro{\knowledge_knowledgestyle_bool}] is it a \cs{\knowledgestyle} macro?
+% \itemAP[\csintro{\knowledge_knowledgestyle_override_bool}] has it been required to override a previous "knowledge"?
+% \itemAP[\csintro{\knowledge_knowledge_now_bool}] set if in the preamble or by the directive "now".
+% \itemAP[\csintro{\knowledge_knowledge_alsonow_bool}] set by directive "also now".
+% \itemAP[\csintro{\knowledge_knowledge_is_synonym_bool}] set by the "synonym" directive.
+% \itemAP[\csintro{\knowledge_knowledge_autoref_bool}] set by the "autoref" directive
+% \itemAP[\csintro{\knowledge_knowledge_clear_bool}] 
+% \itemAP[\csintro{\knowledge_knowledge_append_bool}]
+% \itemAP[\csintro{\knowledge_knowledge_export_bool}]
+% \itemAP[\csintro{\knowledge_knowledge_synonymlink_tl}] name of the "knowledge" to link to if a "synonym" directive is used.
+% \itemAP[\csintro{\knowledge_knowledge_synonyminstance_tl}] "instance" of the "knowledge" to link if a "synonym" directive is used.
+% \itemAP[\csintro{\knowledge_knowledge_immediate_synonym_directives_tl}] gathers the "directives" that have to be propagated to implicit synonyms.
+% \itemAP[\csintro{\knowledge_knowledge_key_tl}] the text for which the "knowledge" has to be defined.
+% \itemAP[\csintro{\knowledge_knowledge_namespace_tl}] the "namespace".
+% \itemAP[\csintro{\knowledge_knowledge_instance_tl}]
+% \itemAP[\csintro{\knowledge_knowledge_directives_tl}] gathers the "directives" that have to be executed for defining the "knowledge" (either to be executed now if \cs{\knowledge_knowledge_now_bool} is set, or to be propagated to the "kaux file" for execution during the next compilation phase)
+% \end{asparadesc}
 %    \begin{macrocode}
 \bool_new:N\knowledge_knowledgestyle_bool
 \bool_new:N\knowledge_knowledgestyle_override_bool
@@ -1959,8 +2188,9 @@ Content of the file knowledge-sources.zip:
 \bool_new:N\knowledge_knowledge_autoref_bool
 \bool_new:N\knowledge_knowledge_clear_bool
 \bool_new:N\knowledge_knowledge_append_bool
-\tl_clear_new:N\knowledge_knowledge_synonym_tl
+\tl_clear_new:N\knowledge_knowledge_synonymlink_tl
 \tl_clear_new:N\knowledge_knowledge_synonyminstance_tl
+\tl_clear_new:N\knowledge_knowledge_immediate_synonym_directives_tl
 \tl_clear_new:N\knowledge_knowledge_export_bool
 \tl_clear_new:N\knowledge_knowledge_key_tl
 \tl_clear_new:N\knowledge_knowledge_namespace_tl
@@ -2050,17 +2280,24 @@ Content of the file knowledge-sources.zip:
 % \subsubsection{The \cs{\knowledgedirective} command}
 %
 %    \begin{macrocode}
-\NewDocumentCommand\knowledgedirective{mom}{
+\NewDocumentCommand\knowledgedirective{smom}{
   \kl_hide_begin:
-  \cs_new:cn
-     {knowledgedirective_#1:n}
-     {\keys_set:nn{ knowledge~directives }{#3}}
-  \keys_define:nn{ knowledge~directives }
-    {#1 .code:n = {\use:c{knowledgedirective_#1:n}{##1}}}
-  \IfNoValueF{#2}
-    {\keys_define:nn{ knowledge~directives }{#1 .default:n = {#2}}}
+  \keys_if_exist:nnTF{ knowledge~directives }{ #2 }
+    {\IfBooleanTF{#1}
+       {\knowledgedirective:nnn{#2}{#3}{#4}}
+       {\msg_error:nnn{ knowledge }{  knowledgedirective~redifinition }{#2}}}
+    {\knowledgedirective:nnn{#2}{#3}{#4}}
   \kl_hide_end:
 }
+\cs_new:Nn\knowledgedirective:nnn{
+   \cs_set:cn
+       {knowledgedirective_#1:n}
+       {\keys_set:nn{ knowledge~directives }{#3}}
+     \keys_define:nn{ knowledge~directives }
+       {#1 .code:n = {\use:c{knowledgedirective_#1:n}{##1}}}
+     \IfNoValueF{#2}
+       {\keys_define:nn{ knowledge~directives }{#2 .default:n = {#2}}}
+}
 %    \end{macrocode}
 %
 % \subsubsection{The \cs{\knowledgedefault} command}
@@ -2170,14 +2407,12 @@ Content of the file knowledge-sources.zip:
 % or following \cs{\knowledge_kl_linkscope_tl} if the label exists.
 % It first works on whether a scope label is given or not:
 %    \begin{macrocode}
-\cs_set:Nn\knowledge_kl_find:{
+\cs_new:Nn\knowledge_kl_find:{
   \knowledge_kl_find_recursion_exceeded:TF
-  {\knowledge_kl_error_recursion:}
-  {\tl_if_empty:NTF\knowledge_kl_instance_tl
-    {\tl_if_empty:NTF\knowledge_kl_linkscope_tl
+     \knowledge_kl_error_recursion:
+     {\tl_if_empty:NTF\knowledge_kl_linkscope_tl
         \knowledge_kl_find_withoutscope:
-        \knowledge_kl_find_withscope:}
-    \knowledge_kl_find_withinstance:}
+        \knowledge_kl_find_withscopetag:}
 }
 %    \end{macrocode}
 %    \begin{macrocode}
@@ -2199,13 +2434,39 @@ Content of the file knowledge-sources.zip:
          \knowledge_kl_key_tl}
       { \knowledge_kl_error_unknown_in_scope_firsttime: }
 }
-\cs_new:Nn\knowledge_kl_find_withscope:{
-  \exp_args:NV
-  \scopept_label_instance_if_exist:nTF\knowledge_kl_linkscope_tl
-    { \tl_set:Nx\knowledge_kl_instance_tl
-        {\scopept_label_instance_use:n{\knowledge_kl_linkscope_tl}}
-     \knowledge_kl_find_withinstance: }
-    {  \knowledge_kl_error_label_unknown: }
+%    \end{macrocode}
+% \csintro{\knowledge_kl_find_withscopetag:} searches for the knowledge, with a given scopetag
+%    \begin{macrocode}
+\cs_new:Nn\knowledge_kl_find_withscopetag:{
+  \exp_args:NV\knowledge_scopetag_warn_if_unknown:n\knowledge_kl_linkscope_tl
+  \tl_clear:N\l_tmpa_tl
+  \exp_args:Nc\seq_map_function:NN
+        {\knowledge_scopetag_tl[\knowledge_kl_linkscope_tl]_seq}
+        \knowledge_kl_find_scopetag_tmpa:n
+   \tl_if_empty:NTF\l_tmpa_tl
+      {\knowledge_kl_error_unknown_in_scope_firsttime:}
+      {\knowledge_kl_exec:VVV
+         \knowledge_kl_namespace_tl
+         \l_tmpa_tl
+         \knowledge_kl_key_tl}
+}
+%    \end{macrocode}
+% \csintro{\knowledge_kl_find_scopetag:Nn} takes a token list for the result, and
+% a scopetag as argument. If the tl is empty, and a knowledge using scopetag as instance is found,
+% then the scopetag is transfered to the token list.
+%    \begin{macrocode}
+\cs_new:Nn\knowledge_kl_find_scopetag:Nn{
+  \tl_if_empty:NTF#1
+    {\knowledge_knowledge_if_exist:VnVTF
+        \knowledge_kl_namespace_tl
+        {#2}%instance
+        \knowledge_kl_key_tl
+        {\tl_set:Nn#1{#2}}
+        {}}
+    {}
+}
+\cs_new:Npn\knowledge_kl_find_scopetag_tmpa:n{
+   \knowledge_kl_find_scopetag:Nn\l_tmpa_tl
 }
 %    \end{macrocode}
 %    \begin{macrocode}
@@ -2220,16 +2481,17 @@ Content of the file knowledge-sources.zip:
       {\knowledge_kl_error_unknown_firsttime:}
 }
 %    \end{macrocode}
-% We now code the macro \cs{\knowledge_kl_find_in_scope:nnNTF}, that
-% takes the \kl{namespace}, and the \kl{knowledge}, and answers the \kl{instance} (if it exists),
-% and sets the tl-token (third argument) to contain the scope in which it has been found.
+% \cs{\knowledge_kl_find_in_scope:nNTF} introduces the namespace as
+% first argument in a call to \cs{\knowledge_kl_find_in_scope:nnNTF}
 %    \begin{macrocode}
 \cs_new:Npn\knowledge_kl_find_in_scope:nNTF{
    \exp_args:NV\knowledge_kl_find_in_scope:nnNTF
      \knowledge_kl_namespace_tl
 }
 %    \end{macrocode}
-%
+% We now code the macro \cs{\knowledge_kl_find_in_scope:nnNTF}, that
+% takes the \kl{namespace}, and the \kl{knowledge}, and answers the \kl{instance} (if it exists),
+% and sets the tl-token (third argument) to contain the scope in which it has been found.
 %    \begin{macrocode}
 \cs_new:Nn\knowledge_kl_find_in_scope:nnNTF{
    \group_begin:
@@ -2245,13 +2507,29 @@ Content of the file knowledge-sources.zip:
       {#5}
 }
 %    \end{macrocode}
+% \cs{\knowledge_kl_find_in_scope_test:n} tests the existence of a "knowledge" 
+% in the "scopetag" given as argument. For this it searches through all the instances associated to the
+% scopetag, and sets \cs{\g_tmpa_bool} when found.
+% One has to check that the visible instance is not the mark.
 %    \begin{macrocode}
 \cs_new:Nn\knowledge_kl_find_in_scope_test:n{
+	\tl_if_eq:nnTF{#1}{|}{}{
+	\knowledge_kl_find_in_scope_test_:n{#1}
+	\seq_if_exist:cTF{\knowledge_scopetag_tl[#1]_seq}
+	   {\exp_args:Nc\seq_map_function:NN
+	      {\knowledge_scopetag_tl[#1]_seq}
+	      \knowledge_kl_find_in_scope_test_:n
+	   }{}}
+}
+%    \end{macrocode}
+%    \begin{macrocode}
+\cs_new:Nn\knowledge_kl_find_in_scope_test_:n{
    \exp_args:Nc\ktuple_if_exist:NTF
      {\knowledge_id:nnV{\l_tmpa_tl}{#1}\l_tmpb_tl}
      {\bool_gset_true:N\g_tmpa_bool
       \tl_gset:Nn\g_tmpa_tl{#1}
-      \seq_map_break:}{}}
+      \seq_map_break:}{}
+}
 %    \end{macrocode}
 %    \begin{macrocode}
 \cs_generate_variant:Nn\knowledge_kl_find_in_scope:nnNTF{nVNTF}
@@ -2303,7 +2581,7 @@ Content of the file knowledge-sources.zip:
         \knowledge_kl_compute_code:
      }
 }
-\cs_generate_variant:Nn\knowledge_kl_exec:nnn{nnV}
+\cs_generate_variant:Nn\knowledge_kl_exec:nnn{nnV,VVV}
 %    \end{macrocode}
 %    \begin{macrocode}
 \cs_new:Nn\knowledge_kl_use_styles:n
@@ -2369,13 +2647,25 @@ Content of the file knowledge-sources.zip:
 %    \begin{macrocode}
 \DeclareKAuxPhaseCommand\KAuxErrorKnowledgeUnknown{diagnose-unknown-suggest}
 {  \knowledge_diagnose_line:
-   \tl_set_eq:Nc\l_tmpa_tl{knowledge_kl_\cs_to_str:N#5_suggestion_tl}
-   \tl_if_empty:nTF{#2}{}
-     {\tl_if_empty:NTF\l_tmpa_tl{}
-       {\tl_put_right:Nn\l_tmpa_tl{,}}
-      \tl_put_right:Nn\l_tmpa_tl{scope={#2}}}
-   \knowledge_diagnose:x
-      {\exp_not:n{\knowledge{#3}}{\exp_not:V\l_tmpa_tl}}
+    \tl_set_eq:Nc\l_tmpa_tl{knowledge_kl_\cs_to_str:N#5_suggestion_tl}
+    \tl_if_eq:nnTF{#1}{default}
+     {}
+     {\tl_if_empty:NTF\l_tmpa_tl{}{\tl_put_right:Nn\l_tmpa_tl{,}
+      \tl_put_right:Nn\l_tmpa_tl{namespace={#1}}}}
+      
+   \bool_if:NTF\knowledge_configuration_barsuggestion_bool{
+        %\knowledge_diagnose:x{\char_escape_tl knowledge{\exp_not:V\l_tmpa_tl}}
+        \tl_set:Nn\l_tmpa_tl{~~~|~~#3}
+        \tl_if_empty:nTF{#2}{}
+          {\tl_put_right:Nn\l_tmpa_tl{@#2}}
+        \knowledge_diagnose:x{\exp_not:V\l_tmpa_tl}
+   }{
+        \tl_if_empty:nTF{#2}{}
+          {\tl_if_empty:NTF\l_tmpa_tl{}{\tl_put_right:Nn\l_tmpa_tl{,}}
+           \tl_put_right:Nn\l_tmpa_tl{scope={#2}}}
+        \knowledge_diagnose:x
+          {\char_escape_tl knowledge\exp_not:n{{#3}}{\exp_not:V\l_tmpa_tl}}
+   }
 }
 %    \end{macrocode}
 % The code executed when an undefined knowledge is met. It 
@@ -2386,7 +2676,7 @@ Content of the file knowledge-sources.zip:
      \msg_warning:nnxxx{ knowledge }{ knowledge~unknown }
       {\exp_not:V\knowledge_kl_key_tl}
       {\exp_not:V\knowledge_kl_namespace_tl}
-      {\seq_use:Nn\knowledge_visible_instances_seq{~|~}}}
+      {\seq_use:Nn\knowledge_visible_instances_seq{|}}}
     }{}
    \bool_if:cTF{\knowledge_variant_var:n{unknowndiagnose_bool}}
     {\KAuxWriteX{
@@ -2514,36 +2804,38 @@ Content of the file knowledge-sources.zip:
 %    \end{macrocode}
 %    \begin{macrocode}
 \NewDocumentCommand\knowledgenewvariant{mm}{
-  \exp_args:Nc\tl_new:Nn
+  \tl_if_exist:cTF{knowledge_kl_\cs_to_str:N#1_command_tl}
+    {\knowledge_error:n{Variant~#1~already~exists~(in~\knowledgenewvariant).}}
+    {\exp_args:Nc\tl_new:Nn
       {knowledge_kl_\cs_to_str:N#1_command_tl}
       {#1}
-  %
-  %
-  \NewDocumentCommand#1{s}
-     {\knowledge_kl_modifiers_add:N#1
-      \IfBooleanF{##1}{\knowledge_kl:w}}
-  %
-   \tl_new_eq:cN
-      {knowledge_kl_\cs_to_str:N#1_namespace_tl}
-      \knowledge_default_namespace_tl
-   \tl_new:cx{knowledge_kl_\cs_to_str:N#1_suggestion_tl}{}
-   \bool_new_true:c{knowledge_kl_\cs_to_str:N#1_unknownwarning_bool}
-   \bool_new_true:c{knowledge_kl_\cs_to_str:N#1_unknowndiagnose_bool}
-   \tl_new:cn{knowledge_kl_\cs_to_str:N#1_default_style_tl}{}
-   \tl_new:cn{knowledge_kl_\cs_to_str:N#1_unknown_style_tl}{}
-   \tl_new:cn{knowledge_kl_\cs_to_str:N#1_unknown_style_cont_tl}{}
-   \tl_new:cx{knowledge_kl_\cs_to_str:N#1_autoknowledge_tl}{}
-   \tl_new:cx{knowledge_kl_\cs_to_str:N#1_styledirectives_tl}{}
-   %
-   \bool_if:NT\knowledge_hyperref_active_bool
-      {\exp_args:Nx\pdfstringdefDisableCommands
-             {\exp_not:N\def\exp_not:N#1
-                  {\exp_not:N\knowledge_variant_arg_absorber:Nw
-                   \exp_not:c{\cs_to_str:N#1_PDFstring}}}}
-   \exp_args:Nc\newcommand{\cs_to_str:N#1_PDFstring}[3]{##1}
-   %
-   \tl_new:cx{knowledge_kl_\tl_to_str:n{#1*} _init_tl}
-       {
+    %
+    %
+    \NewDocumentCommand#1{s}
+       {\knowledge_kl_modifiers_add:N#1
+        \IfBooleanF{##1}{\knowledge_kl:w}}
+    %
+    \tl_new_eq:cN
+        {knowledge_kl_\cs_to_str:N#1_namespace_tl}
+        \knowledge_default_namespace_tl
+    \tl_new:cx{knowledge_kl_\cs_to_str:N#1_suggestion_tl}{}
+    \bool_new_true:c{knowledge_kl_\cs_to_str:N#1_unknownwarning_bool}
+    \bool_new_true:c{knowledge_kl_\cs_to_str:N#1_unknowndiagnose_bool}
+    \tl_new:cn{knowledge_kl_\cs_to_str:N#1_default_style_tl}{}
+    \tl_new:cn{knowledge_kl_\cs_to_str:N#1_unknown_style_tl}{}
+    \tl_new:cn{knowledge_kl_\cs_to_str:N#1_unknown_style_cont_tl}{}
+    \tl_new:cx{knowledge_kl_\cs_to_str:N#1_autoknowledge_tl}{}
+    \tl_new:cx{knowledge_kl_\cs_to_str:N#1_styledirectives_tl}{}
+    %
+    \bool_if:NT\knowledge_hyperref_active_bool
+       {\exp_args:Nx\pdfstringdefDisableCommands
+              {\exp_not:N\def\exp_not:N#1
+                   {\exp_not:N\knowledge_variant_arg_absorber:Nw
+                    \exp_not:c{\cs_to_str:N#1_PDFstring}}}}
+    \exp_args:Nc\newcommand{\cs_to_str:N#1_PDFstring}[3]{##1}
+    %
+    \tl_new:cx{knowledge_kl_\tl_to_str:n{#1*} _init_tl}
+        {
         \exp_not:n{\tl_set_eq:NN\knowledge_kl_command_tl}
             \exp_not:c{knowledge_kl_\cs_to_str:N#1_command_tl}
         \exp_not:n{\tl_set_eq:NN\knowledge_kl_namespace_tl}
@@ -2558,10 +2850,11 @@ Content of the file knowledge-sources.zip:
             \exp_not:c{knowledge_kl_\cs_to_str:N#1 _styledirectives_tl}
         \exp_not:c{knowledge_kl_\cs_to_str:N#1 _autoknowledge_tl}
         }
-  % 
-  %\bool_if:NT\knowledge_hyperref_active_bool
-  %  {\pdfstringdefDisableCommands{\let#1\knowledge_fake_kl:n}}
-  %
+   % 
+   %\bool_if:NT\knowledge_hyperref_active_bool
+   %  {\pdfstringdefDisableCommands{\let#1\knowledge_fake_kl:n}}
+   %
+   }
   \knowledgesetvariant#1{#2}
 }
 \DeclareExpandableDocumentCommand\knowledge_variant_arg_absorber:Nw
@@ -2573,10 +2866,14 @@ Content of the file knowledge-sources.zip:
 \tl_new:N\knowledge_variant_command_tl
 \tl_new:N\knowledge_variant_key_tl
 \NewDocumentCommand\knowledgesetvariant{mm}{
-   \tl_set:Nn\knowledge_variant_command_tl{#1}
-   \tl_set:Nx\knowledge_variant_key_tl{\cs_to_str:N#1}
-   %
-   \keys_set:nn{ knowledge~configure~variant }{#2}
+  \tl_if_exist:cTF{knowledge_kl_\cs_to_str:N#1_command_tl}
+    {
+      \tl_set:Nn\knowledge_variant_command_tl{#1}
+      \tl_set:Nx\knowledge_variant_key_tl{\cs_to_str:N#1}
+      %
+      \keys_set:nn{ knowledge~configure~variant }{#2}
+    }
+    {\knowledge_error:n{Variant~#1~does~not~exist~(in~\knowledgesetvariant).}}
 }
 %    \end{macrocode}
 %    \begin{macrocode}
@@ -2738,7 +3035,7 @@ Content of the file knowledge-sources.zip:
 %
 %    \begin{macrocode}
 \NewKnowledgeParamTl*{link}
-\NewKnowledgeParamTl*{link~scope}
+\NewKnowledgeParamTl*[\knowledge_kl_linkscope_tl]{link~scope}
 \NewKnowledgeParamTl*[\knowledge_kl_instance_tl]{link~instance}
 \NewKnowledgeParamTl*[\knowledge_kl_forcedtext_tl]{text}
 \NewKnowledgeParamTl*{wrap}
@@ -2748,7 +3045,7 @@ Content of the file knowledge-sources.zip:
 %    \begin{macrocode}
 
 \NewKnowledgeParamBool*{UnKnoWn~KNowLedGE}\kl_unknown_knowledge_bool
-\bool_gset_false:N\kl_unknown_knowledge_bool
+\bool_set_false:N\kl_unknown_knowledge_bool
 \ktuple_new_int_index:n{countuse}
 \ktuple_countuse_expands_to:n{}
 \ktuple_new_int_index:n{countintro}
@@ -2839,7 +3136,7 @@ Content of the file knowledge-sources.zip:
    \int_compare:nNnT\kl_countuse_int>0
      {\int_compare:nNnT\kl_countintro_int=0
         {\knowledge_diagnose_line:
-         \knowledge_diagnose:n{\nointro{#1}{#2}{#3}}}}
+         \knowledge_diagnose:x{\char_escape_tl nointro{\exp_not:n{#1}}{\exp_not:n{#2}}{\exp_not:n{#3}}}}}
    \group_end:}
 \DeclareKAuxPhaseCommand\KAuxAutoref{autoref-introduced-not-used}
   {\group_begin:
@@ -2975,7 +3272,7 @@ Content of the file knowledge-sources.zip:
        \tl_set:Nx\l_tmpa_tl
              {\int_compare:nNnTF\l_tmpa_int=1
              {} {\int_to_alph:n\l_tmpa_int}}
-       \exp_args:Nx\label{\exp_not:V\knowledge_kl_autoref_tl\l_tmpa_tl}}
+       \exp_args:Nx\LaTeXlabel{\exp_not:V\knowledge_kl_autoref_tl\l_tmpa_tl}}
     \expandafter\ktuple_countintro_gincr:N
         \knowledge_kl_resourcetoken_tl
     \KAuxWriteX
@@ -2999,7 +3296,7 @@ Content of the file knowledge-sources.zip:
 %  {\bool_if:NTF\kl_fbox_bool{\exp_not:N\fbox{#1}}{#1}}
 %    \end{macrocode}
 %    \begin{macrocode}
-\cs_new:Npn\kl_up:n{\mode_if_math:TF\mathup\textup}
+\cs_new:Npn\kl_up:n{\mode_if_math:TF\use:n\textup}
 \cs_new:Npn\kl_md:n{\mode_if_math:TF\mathmd\textmd}
 \cs_new:Npn\kl_sc:n{\mode_if_math:TF\mathsc\textsc}
 \cs_new:Npn\kl_it:n{\mode_if_math:TF\mathit\textit}
@@ -3497,14 +3794,14 @@ Content of the file knowledge-sources.zip:
 
 \knowledgenewvariant\kl{
   namespace= default,
-  default style= {kl,autoref link},
+  default style= {autoref link},
   unknown style= kl unknown,
   unknown style cont= kl unknown cont,
-  style directive={style}
+  style directive= style
 }
 \knowledgenewvariant\intro{
   namespace= default,
-  default style= {intro,autoref target},
+  default style= {autoref target},
   unknown style= intro unknown,
   unknown style cont= intro unknown cont,
   style directive= intro style
@@ -3517,11 +3814,13 @@ Content of the file knowledge-sources.zip:
 }
 \knowledgenewvariant\reintro{
   namespace=default,
-  default style=intro,
+%  default style=intro,
   unknown style=intro unknown,
   unknown style cont=intro unknown cont,
   style directive=intro style
 }
+
+  
 \knowledgevariantmodifier{\intro*\kl}{\intro}
 \knowledgevariantmodifier{\reintro*\kl}{\reintro}
 
@@ -3544,27 +3843,27 @@ Content of the file knowledge-sources.zip:
 \ExplSyntaxOff
 % in paper mode, nothing is displayed
 \IfKnowledgePaperModeTF{
-  \knowledgestyle{kl}{}
+%  \knowledgestyle{kl}{}
   \knowledgestyle{kl unknown}{}
   \knowledgestyle{kl unknown cont}{}
-  \knowledgestyle{intro}{emphasize,index style=knowledgeIntroIndexStyle}
+%  \knowledgestyle{intro}{emphasize,index style=knowledgeIntroIndexStyle}
   \knowledgestyle{intro unknown}{emphasize}
   \knowledgestyle{intro unknown cont}{emphasize}
 }{}
   
 \IfKnowledgeCompositionModeTF{
   \IfXcolorTF{
-    \knowledgestyle{kl}{color={blue!70!black}}
+%    \knowledgestyle{kl}{color={blue!70!black}}
     \knowledgestyle{kl unknown}{color=orange}
     \knowledgestyle{kl unknown cont}{color=brown}
-    \knowledgestyle{intro}{emphasize,color=blue,index style=knowledgeIntroIndexStyle}
+%    \knowledgestyle{intro}{emphasize,color=blue,index style=knowledgeIntroIndexStyle}
     \knowledgestyle{intro unknown}{emphasize,color=orange}
     \knowledgestyle{intro unknown cont}{emphasize,color=brown}
    }{
-    \knowledgestyle{kl}{}
+%    \knowledgestyle{kl}{}
     \knowledgestyle{kl unknown}{underline}
     \knowledgestyle{kl unknown cont}{underline}
-    \knowledgestyle{intro}{emphasize,index style=introindexstyle}
+%    \knowledgestyle{intro}{emphasize,index style=introindexstyle}
     \knowledgestyle{intro unknown}{emphasize,underline}
     \knowledgestyle{intro unknown cont}{emphasize,underline}
    }
@@ -3572,17 +3871,17 @@ Content of the file knowledge-sources.zip:
 
 \IfKnowledgeElectronicModeTF{
   \IfXcolorTF{
-    \knowledgestyle{kl}{color={blue!70!black}}
+%    \knowledgestyle{kl}{color={blue!70!black}}
     \knowledgestyle{kl unknown}{}
     \knowledgestyle{kl unknown cont}{}
-    \knowledgestyle{intro}{emphasize,color=blue,index style=introindexstyle}
+%    \knowledgestyle{intro}{emphasize,color=blue,index style=introindexstyle}
     \knowledgestyle{intro unknown}{emphasize}
     \knowledgestyle{intro unknown cont}{emphasize}
    }{
-    \knowledgestyle{kl}{}
+%    \knowledgestyle{kl}{}
     \knowledgestyle{kl unknown}{}
     \knowledgestyle{kl unknown cont}{}
-    \knowledgestyle{intro}{emphasize,index style=introindexstyle}
+%    \knowledgestyle{intro}{emphasize,index style=introindexstyle}
     \knowledgestyle{intro unknown}{emphasize}
     \knowledgestyle{intro unknown cont}{emphasize}
    }
diff --git a/Master/texmf-dist/source/latex/knowledge/knowledge-utils.dtx b/Master/texmf-dist/source/latex/knowledge/knowledge-utils.dtx
index af2d372a40d..dc0f0deed7c 100644
--- a/Master/texmf-dist/source/latex/knowledge/knowledge-utils.dtx
+++ b/Master/texmf-dist/source/latex/knowledge/knowledge-utils.dtx
@@ -523,6 +523,18 @@
 %
 % \subsection{References}
 %
+% This is an old part of the code which is difficult to read.
+% It should probably be cleaned.
+%
+% When using \cs{\cell_new_type:nnn}, a new name space is created,
+% in which can be stored information. The first parameter is the name space. The second
+% is the description (expl3 style) of the parameters defining an entry, and the third is the
+% string of character (that can use the arguments defined) used to address this space.
+% For instance \verb|\cell_new_type:nnn{carots}{nn}{K@ROT:{#1}{#2}}|
+% define a cell type named `carot' that is indexed by two parameters.
+% In particular, it defines the macro \cs{\carot:Nnn} that takes a token, and parameters, that executes the
+% token with as first parameter the token identifying the location of the carot.
+% For instance, \verb|\carot_at:Nnn\show{A}{B}| will display the content of the carot defined by the parameters A and B.
 %    \begin{macrocode}
 \cs_new:Nn\cell_new_type:nnn
   {
@@ -532,7 +544,8 @@
       {\exp_not:n{\exp_after:wN\exp_args:Nc\exp_after:wN}
        ##1 \exp_not:c{#1_id_b:#2}}
   }
-
+%    \end{macrocode}
+%    \begin{macrocode}
 \cs_new:Nn\cell_specialize:nnn
   {\cs_new:cpx{#1_#2_id:#3}
       {\exp_not:c{#1_id:n#3}{#2}}
diff --git a/Master/texmf-dist/tex/latex/knowledge/knowledge.sty b/Master/texmf-dist/tex/latex/knowledge/knowledge.sty
index 2cb530221bd..35aaaea4b1d 100644
--- a/Master/texmf-dist/tex/latex/knowledge/knowledge.sty
+++ b/Master/texmf-dist/tex/latex/knowledge/knowledge.sty
@@ -23,12 +23,11 @@
 %% LaTeX version 1999/12/01 or later.
 %% 
 \usepackage{expl3}
-\ProvidesExplPackage{knowledge}{2019/02/16}{1.16}{}
+\ProvidesExplPackage{knowledge}{2019/10/03}{1.17}{}
 %%%%%%%%%%
 \RequirePackage{l3keys2e}
 \RequirePackage{etoolbox}
 \RequirePackage{xparse}
-\RequirePackage{etoolbox}
 \bool_if_exist:NTF\knowledge_package_loaded_bool
  {\endinput}
  {\bool_new:N\knowledge_package_loaded_bool
@@ -288,7 +287,6 @@
       {\exp_not:n{\exp_after:wN\exp_args:Nc\exp_after:wN}
        ##1 \exp_not:c{#1_id_b:#2}}
   }
-
 \cs_new:Nn\cell_specialize:nnn
   {\cs_new:cpx{#1_#2_id:#3}
       {\exp_not:c{#1_id:n#3}{#2}}
@@ -790,6 +788,9 @@
 \cs_new:Npn\klparse_if_novalue:NTF
   {\tl_if_eq:NNTF\klparse_novalue_tl}
 \cs_generate_variant:Nn\tl_to_str:n{V}
+\tl_new:N\char_escape_tl
+\tl_set:Nx\char_escape_tl
+   {\expandafter\tl_head:n\expandafter{\string\escape}}
 \cs_new:Nn\knowledge_info:n
   {\msg_info:nnn{knowledge}{knowledge~info}{#1}}
 \cs_new:Nn\knowledge_warning:n
@@ -817,6 +818,8 @@
   {In~order~to~use~directive~'#1',~please~load~package~or~use~option~'#2'.}
 \msg_new:nnn{ knowledge }{ knowledge~exists }
   { The~knowledge~'#1'~in~scope~'#2'~(namespace~'#3')~already~exists. }
+\msg_new:nnn{ knowledge }{ knowledgedirective~redifinition }
+  { Directive~'#1'~already~exists~(\knowledgedirective~macro). }
 \msg_new:nnn{scope}{area~exists}{Area~'#1'~already~exists.}
 \msg_new:nnn{scope}{area~not~exist}{Area~'#1'~does~not~exist.}
 \msg_new:nnn{scope}{empty~pop}{Attempt~to~pop~an~empty~area~stack.}
@@ -925,6 +928,9 @@
 \bool_new:N\knowledge_configuration_diagnoseline_bool
 \bool_set_false:N\knowledge_configuration_diagnoseline_bool
 \KnowledgeConfigureBooleanOption[\knowledge_configuration_diagnoseline_bool]{diagnose~line}
+\bool_new:N\knowledge_configuration_barsuggestion_bool
+\bool_gset_false:N\knowledge_configuration_barsuggestion_bool
+\KnowledgeConfigureBooleanOption[\knowledge_configuration_barsuggestion_bool]{bar~suggestion}
 \bool_new:N\knowledge_configuration_visibleAP_bool
 \KnowledgeConfigureBooleanOption[\knowledge_configuration_visibleAP_bool]{visible~anchor~points}\KnowledgeConfigureBooleanOption[\knowledge_configuration_visibleAP_bool]{visible~AP}
 \bool_new:N\knowledge_hyperlinks_active_bool
@@ -937,7 +943,12 @@
 \KnowledgeConfigureTrigger{ fix~hyperref~twocolumn }
   {\knowledgeFixHyperrefTwocolumn}
 \KnowledgeConfigureTrigger{ notion }
-  {\KnowledgeConfigureNotion{notion}}
+  {\KnowledgeConfigureNotion{notion}
+   \knowledgesetvariant\kl{suggestion=notion}
+   \knowledgesetvariant\intro{suggestion=notion}
+   \knowledgesetvariant\phantomintro{suggestion=notion}
+   \knowledgesetvariant\reintro{suggestion=notion}
+   }
 \KnowledgeConfigureTrigger{ protect~links }
   {\kl_kl_nesting_incr:}
 \KnowledgeConfigureTrigger{ unprotect~links }
@@ -1219,7 +1230,7 @@
   \seq_gpop:NNTF\scope_instances_stack_seq\l_tmpa_tl
      {\tl_gset_eq:NN\scope_top_instance_tl\l_tmpa_tl
      \int_gdecr:c{\scope_tl.area[\scope_top_area_tl].nesting_int}
-     \exp_args:NV\knowledge_pop_visible_instances_to:n\scope_top_instance_tl
+     \knowledge_pop_visible_instances_to_mark:
      \seq_get:NN\scope_instances_stack_seq\l_tmpa_tl
      \tl_gset_eq:NN\scope_top_instance_tl\l_tmpa_tl
      \tl_gset:Nx\scope_top_area_tl
@@ -1317,6 +1328,7 @@
          {\scope_top_area_tl-\int_to_arabic:n{\int_use:c{\scope_tl.area[\scope_top_area_tl].count_int}}}}
     {\tl_gset_eq:NN\scope_top_instance_tl\scope_top_area_tl}
   %
+  \knowledge_push_visible_instance_mark:
   \exp_args:Nx\knowledge_push_visible_instance:n{\scope_top_instance_tl}
   \seq_gpush:Nx\scope_instances_stack_seq{\scope_top_instance_tl}
   %
@@ -1366,11 +1378,6 @@
       {\scope_tl.area[\tl_use:c{\scope_tl.instance[##1].area_tl}].labelizable_bool}
       {\tl_set:Nn#1{##1}\seq_map_break:}{}}
 }
-\cs_new:Nn\knowledge_scope_track_instance:Nn{
-    \scope_area_if_exist:nTF{#2}
-       {\knowledge_scope_track_instance_from_area:Nn#1{#2}}
-       {\knowledge_scope_track_instance_from_label:Nn#1{#2}}
-}
 \cs_new:Nn\knowledge_scope_track_instance_from_area:Nn{
   \tl_set:Nn#1{}
   \seq_map_inline:Nn\scope_instances_stack_seq
@@ -1383,11 +1390,11 @@
     {\msg_error:nnxx{scope}{area~not~in~context}{#2}{scope=}}
     {}
 }
-\cs_new:Nn\knowledge_scope_track_instance_from_label:Nn{
-  \tl_set:Nn#1{}
-  \scopept_label_instance_if_exist:nTF{#2}
-      {\tl_set:Nx#1{\scopept_label_instance_use:n{#2}}}
-      {\msg_warning:nnnn{scope}{unknown~label}{#2}{scope=}}
+\cs_new:Nn\knowledge_scope_track_scope:n{
+    \scope_area_if_exist:nTF{#1}
+       {\knowledge_scope_track_instance_from_area:Nn\knowledge_knowledge_instance_tl{#1}}
+       {\tl_set:Nn\knowledge_knowledge_instance_tl{explicit-scope:#1}
+        \knowledge_scopetag_warn_if_unknown:n{#1}}
 }
 \bool_new:N\scopept_map_break_bool
 \cs_new:Nn\scopept_map_break:
@@ -1412,25 +1419,75 @@
     {\scopept_map_instance_ancestors_i:nN{##1}#2
      \bool_if:NTF\scopept_map_break_bool:{\seq_map_break:}{}}
 }
-\NewDocumentCommand\scopeLabel{m}
-  { \kl_hide_begin:
+\tl_const:Nn\knowledge_scopetag_tl{ScpT@g}
+\cs_new:Npn\knowledge_scopetag_if_exist:nTF#1
+   {\tl_if_exist:cTF{\knowledge_scopetag_tl[#1]_bool}}
+\cs_new:Nn\knowledge_scopetag_ensure:n{
+   \knowledge_scopetag_if_exist:nTF{#1}{}
+      {\bool_new:c{\knowledge_scopetag_tl[#1]_bool}
+       \bool_gset_false:c{\knowledge_scopetag_tl[#1]_bool}
+       \seq_new:c{\knowledge_scopetag_tl[#1]_seq}
+       \seq_gput_right:cn{\knowledge_scopetag_tl[#1]_seq}{explicit-scope:#1}}}
+\cs_new:Nn\knowledge_scopetag_warn_if_unknown:n{
+    \knowledge_scopetag_if_exist:nTF{#1}{}
+      {\KAuxWriteX*{\exp_not:N\KAuxUndeclaredScopeTag{#1}}
+       \knowledge_scopetag_ensure:n{#1}}
+}
+\cs_new:Nn\knowledge_scopetag_declares:n{
+    \knowledge_scopetag_ensure:n{#1}
+    \bool_if:cTF{\knowledge_scopetag_tl[#1]_bool}
+      {}
+      {\KAuxWriteX*{\exp_not:N\KAuxDeclaredScopeTag{#1}}
+       \bool_gset_true:c{\knowledge_scopetag_tl[#1]_bool}}
+}
+\NewDocumentCommand\knowledgescope{ >{\SplitList{,}}m }{
+\kl_hide_begin:\group_begin:
+      \ProcessList{#1}\knowledge_knowledgescope_one:n
+    \group_end:\kl_hide_end:
+}
+\cs_new:Nn\knowledge_knowledgescope_one:n{
+    \knowledge_scopetag_declares:n{#1}
     \scope_get_labelizable_instance:N\l_tmpb_tl
-    \KAuxWriteX*{\exp_not:n{\KAuxScopeLabel}{\exp_not:n{#1}}{\l_tmpb_tl}}
-    %\tl_new:cx{\scopept_tl.label[#1].instance_tl}{\l_tmpb_tl}
+    \KAuxWriteX*{\exp_not:n{\KAuxNewLinkScopetagInstance}{\exp_not:n{#1}}{\l_tmpb_tl}}
+}
+\bool_new:N\knowledge_configuration_label_autoscope_bool
+\bool_gset_true:N\knowledge_configuration_label_autoscope_bool
+\NewDocumentCommand\scopeLabel{m}{
+    \kl_hide_begin:
+       \bool_if:NT
+         \knowledge_configuration_label_autoscope_bool
+         \knowledge_knowledgescope_one:n{#1}
     \kl_hide_end:
-    \cs_if_exist:NTF\LaTeXlabel\LaTeXlabel\use_none:n{#1}}
+    \cs_if_exist:NTF\LaTeXlabel\LaTeXlabel\use_none:n{#1}
+}
 \let\label\scopeLabel
 \cs_new:Npn\knowledge_latex_label:n{
   \cs_if_exist:NTF\LaTeXlabel\LaTeXlabel\label
 }
+\NewKAuxCommand\KAuxUndeclaredScopeTag{m}
+   {Package~scope:~States~that~a~labelname~is~used~in~a~knowledge~definition.}
+\DeclareKAuxPhaseCommand\KAuxUndeclaredScopeTag{init}{}
+\NewKAuxCommand\KAuxDeclaredScopeTag{m}
+   {Package~scope:~States~that~a~labelname~has~been~declared.}
+\DeclareKAuxPhaseCommand\KAuxDeclaredScopeTag{init}{
+     \knowledge_scopetag_if_exist:nTF{#1}{}
+       {\bool_new:c{\knowledge_scopetag_tl[#1]_bool}}
+        \bool_gset_true:c{\knowledge_scopetag_tl[#1]_bool}
+   }
+\NewKAuxCommand\KAuxNewLinkScopetagInstance{mm}
+   {Package~scope:~Declares~that~a~label~is~declared~in~an~instance~of~a~scope.}
+\DeclareKAuxPhaseCommand\KAuxNewLinkScopetagInstance{init}{
+\knowledge_scopetag_ensure:n{#1}
+\seq_gput_right:cn{\knowledge_scopetag_tl[#1]_seq}{#2}
+}
 \NewKAuxCommand\KAuxScopeNewInstance{mmm}
   {Package~scope:~Declares~a~new~instance~of~a~scope.}
 \DeclareKAuxPhaseCommand\KAuxScopeNewInstance{init}
   {\tl_new:cn{\scopept_tl.instance[#2].area_tl}{#1}
    \tl_new:cn{\scopept_tl.instance[#2].parent_tl}{#3}}
-\NewKAuxCommand\KAuxScopeLabel{mm}
-  {Package~scope:~Links~a~label~to~the~scope~of~its~definition.}
-\DeclareKAuxPhaseCommand\KAuxScopeLabel{init}
+\NewKAuxCommand\KAuxScopeTag{mm}
+  {Package~scope:~Links~a~scopetag~to~an~instance~of~a~scope.}
+\DeclareKAuxPhaseCommand\KAuxScopeTag{init}
   {\tl_if_exist:cTF{\scopept_tl.label[\tl_to_str:n{#1}].instance_tl}{}
      {\tl_new:cn{\scopept_tl.label[\tl_to_str:n{#1}].instance_tl}{#2}}}
 \cs_new:Npn\scopept_label_instance_if_exist:nTF#1
@@ -1660,7 +1717,7 @@
   \exp_args:Nc\ktuple_if_exist:NTF{\knowledge_id:nnn{#1}{#2}{#3}}
 }
 \cs_generate_variant:Nn
-  \knowledge_knowledge_if_exist:nnnTF{VVVTF}
+  \knowledge_knowledge_if_exist:nnnTF{VVVTF,VnVTF}
 \NewDocumentCommand\NewKnowledgeParamBool{smm}{
     \ktuple_new_bool_index:n{#2}
     \bool_new:N#3
@@ -1690,7 +1747,6 @@
     }}
 }
 \NewDocumentCommand\NewKnowledgeParamTl{som}{
-  %\tl_show:n{#2}
   \IfNoValueTF{#2}
   {  \tl_set:Nn\l_tmpa_tl{#3}
      \tl_remove_all:Nn\l_tmpa_tl{~}
@@ -1748,28 +1804,29 @@
 \seq_new:N\knowledge_visible_instances_seq
 \cs_new:Nn\knowledge_push_visible_instance:n
   {\seq_gpush:Nn\knowledge_visible_instances_seq{#1}}
-\cs_new:Npn\knowledge_pop_visible_instance:
-  {\seq_gpop:NN\knowledge_visible_instances_seq\l_tmpa_tl}
-\cs_new:Nn\knowledge_pop_visible_instances_to:n
+\cs_new:Nn\knowledge_push_visible_instance_mark:
+  {\seq_gpush:Nn\knowledge_visible_instances_seq{|}}
+\cs_new:Nn\knowledge_pop_visible_instances_to_mark:
   {\seq_gpop:NNTF\knowledge_visible_instances_seq\l_tmpa_tl
-       {\exp_args:NV\tl_if_eq:nnTF\l_tmpa_tl{#1}
+       {\exp_args:NV\tl_if_eq:nnTF\l_tmpa_tl{|}
             {}
-            {\knowledge_pop_visible_instances_to:n{#1}}}
-       {\INTERNAL_ERROR_EMPTY_POP_VISIBLE}}
+            {\knowledge_pop_visible_instances_to_mark:}}
+       {\KNOWLEDGE_INTERNAL_ERROR:_stack_of_visible_instances_is_empty_while_popping}}
 \cs_new:Nn\knowledge_show_visible_instances:
   {\tl_show:x
     {Visible~instances~<\seq_use:Nn\knowledge_visible_instances_seq{,}>}}
-\cs_new:Nn\knowledge_import_instance:n
-  {\seq_if_in:NnTF\knowledge_visible_instances_seq{#1}
-      {}{\knowledge_push_visible_instance:n{#1}}}
-\NewDocumentCommand\knowledgeimport{m}
-  {\kl_hide_begin:
-   \scopept_label_instance_if_exist:nTF{#1}
-    {\exp_args:Nx\knowledge_import_instance:n{\scopept_label_instance_use:n{#1}}}
-    {\msg_warning:nnnn{scope}{unknown~label}{#1}{\knowledgeimport}}
-   \kl_hide_end:
+\NewDocumentCommand\knowledgeimport{ >{\SplitList{,}}m }{
+    \kl_hide_begin:
+    \ProcessList{#1}\knowledge_knowledgeimport:n
+    \kl_hide_end:
 }
-%%
+\cs_set:Nn\knowledge_knowledgeimport:n{
+   \knowledge_scopetag_warn_if_unknown:n{#1}
+   \knowledge_scopetag_ensure:n{#1}
+   \exp_args:Nc\seq_map_function:NN
+       {\knowledge_scopetag_tl[#1]_seq}
+       \knowledge_push_visible_instance:n
+ }
 \keys_define:nn { knowledge~directives } {
   namespace .code:n = { \tl_set:Nn\knowledge_knowledge_namespace_tl{#1} },
   append .choice:,
@@ -1784,16 +1841,16 @@
   export / false .code:n = {\bool_set_false:N\knowledge_knowledge_export_bool},
   export / true .code:n = {\bool_set_true:N\knowledge_knowledge_export_bool},
   export .default:n = false,
-  instance .code:n =
-     { \tl_set:Nn\knowledge_knowledge_instance_tl{#1} },
+  link~instance .code:n =
+    { \tl_set:Nn\knowledge_knowledge_instance_tl{#1} },
   scope .code:n =
-     { \knowledge_scope_track_instance:Nn\knowledge_knowledge_instance_tl{#1} },
+   { \knowledge_scope_track_scope:n{#1}
+       \tl_gput_right:Nn\knowledge_knowledge_immediate_synonym_directives_tl{,scope = {#1}}},
   synonym .code:n =
      { \bool_set_true:N\knowledge_knowledge_is_synonym_bool
        \exp_args:Nnx\keys_set:nn { knowledge~directives }
-          {link={\exp_not:o\knowledge_knowledge_synonym_tl},
-           link~instance={\exp_not:o\knowledge_knowledge_synonyminstance_tl},
-           instance={\exp_not:o\knowledge_knowledge_synonyminstance_tl}}}
+          {link={\exp_not:o\knowledge_knowledge_synonymlink_tl},
+           link~instance={\exp_not:V\knowledge_knowledge_synonyminstance_tl}}},
 }
 \NewKAuxCommand\KAuxKnowledge{mmmm}
   {Package~knowledge:~Declares~a~knowledge.~
@@ -1827,9 +1884,9 @@
 \cs_generate_variant:Nn\knowledge_new_now:nnnn{nnVn}
 \cs_generate_variant:Nn\knowledge_set_now:nnnn{nnVn}
 \NewDocumentCommand\knowledge{}
-  {\KAuxWriteLocation\__knowledge_knowledge}
-\NewDocumentCommand\__knowledge_knowledge{t! t+ m >{\SplitList{|}}o m }
-{ \kl_hide_begin:
+  {\KAuxWriteLocation\__knowledge_knowledge_init:w}
+\NewDocumentCommand\__knowledge_knowledge_init:w{t! t+ m m}{
+  \kl_hide_begin:
   \group_begin:
   %
    \IfBooleanTF{#1}{%
@@ -1844,26 +1901,81 @@
    \tl_set_eq:NN\knowledge_namespace_tl
       \knowledge_default_namespace_tl
   %
+  \tl_gset:Nn\knowledge_knowledge_immediate_synonym_directives_tl{synonym}
+  %
   \bool_gset_false:N\knowledge_knowledge_is_synonym_bool
   %
+  \tl_if_eq:nnTF{#4}{|}
+     {\__knowledge_knowledge_cont_newsyntax:nw{#3}|}
+     {\tl_if_eq:nnTF{#4}{[}
+          {\__knowledge_knowledge_cont_classical:nw{#3}[}
+          {\__knowledge_knowledge_cont_classical:nw{#3}{#4}}}
+}
+\cs_new:Nn\__knowledge_knowledge_recallsynonym:n{
+    \bool_if:NF\knowledge_knowledge_is_synonym_bool
+      {\tl_gset:Nn\knowledge_knowledge_synonymlink_tl{#1}
+       \tl_gset_eq:NN\knowledge_knowledge_synonyminstance_tl
+           \knowledge_knowledge_instance_tl}
+}
+\cs_new:Nn\__knowledge_knowledge_end:{
+  \group_end:
+  \kl_hide_end:
+}
+\NewDocumentCommand\__knowledge_knowledge_cont_classical:nw{m >{\SplitList{|}}o m }{
+  \knowledge_knowledge_setparseat:NNn\l_tmpa_tl\l_tmpb_tl{#1}
+  %
   \use:x{
-    \exp_not:n{\knowledge_knowledge_process:nn{#3}}
-      {\exp_not:V\knowledge_knowledgedefault_tl,\exp_not:n{#5}}}
+    \exp_not:N\knowledge_knowledge_process:nn
+      {\exp_not:V\l_tmpa_tl}
+      {\exp_not:V\knowledge_knowledgedefault_tl,
+      \exp_not:n{#3},
+      \tl_if_empty:NTF\l_tmpb_tl{}{,scope={\exp_not:V\l_tmpb_tl}}}}
   %
-  \bool_if:NF\knowledge_knowledge_is_synonym_bool
-    {\tl_gset:Nn\knowledge_knowledge_synonym_tl{#3}
-     \tl_gset_eq:NN\knowledge_knowledge_synonyminstance_tl
-         \knowledge_knowledge_instance_tl}
+  \exp_args:NV\__knowledge_knowledge_recallsynonym:n\l_tmpa_tl
   %
-  \IfNoValueTF{#4}{}{
+  \IfNoValueTF{#2}{}{
     \cs_set:Nn\l_tmpa_cs:n
-      {\exp_args:Nnx\knowledge_knowledge_process:nn{##1}{synonym}}
-    \ProcessList{#4}\l_tmpa_cs:n
+      {\exp_args:Nnx\knowledge_knowledge_process:nn{##1}
+          {\exp_not:V\knowledge_knowledge_immediate_synonym_directives_tl}}
+    \ProcessList{#2}\l_tmpa_cs:n
     }
   %
-  \group_end:
-  \kl_hide_end:
-}
+  \__knowledge_knowledge_end:
+}
+\cs_new:Npn\knowledge_knowledge_newsyntax_firstline:n{}
+\cs_new:Npn\knowledge_knowledge_newsyntax_nextlines:n{}
+\cs_new:Npn\__knowledge_knowledge_cont_newsyntax:nw#1{
+\cs_set:Nn\knowledge_knowledge_newsyntax_firstline:n
+   {\knowledge{##1}{#1}
+        \cs_set_eq:NN
+       \knowledge_knowledge_newsyntax_exec_line:n
+       \knowledge_knowledge_newsyntax_nextlines:n}
+\cs_set:Nn\knowledge_knowledge_newsyntax_nextlines:n
+   {\exp_args:Nnx\knowledge{##1}
+        {\exp_not:V\knowledge_knowledge_immediate_synonym_directives_tl}}
+\cs_set_eq:NN
+   \knowledge_knowledge_newsyntax_exec_line:n
+   \knowledge_knowledge_newsyntax_firstline:n
+\kl_newknowledge_parse:w
+}
+\cs_new:Npn\kl_newknowledge_parse:w{
+\peek_charcode_remove_ignore_spaces:NTF|
+{\kl_insert_klendline:w\knowledge_knowledge_newsyntax_exec_line:w}
+{\__knowledge_knowledge_end:}
+}
+\cs_new:Npn\knowledge_knowledge_newsyntax_exec_line:w#1\kl_end_line:{
+    \knowledge_knowledge_newsyntax_exec_line:n{#1}
+\kl_newknowledge_parse:w
+}
+\char_set_catcode_active:N\^^M
+\cs_gset:Npn\kl_insert_klendline:w{\group_begin:\catcode`\^^M=\active\kl_insert_klendline_:w}
+\cs_gset:Npn\kl_insert_klendline_:w#1^^M{\group_end:#1\kl_end_line:}
+\char_set_catcode_end_line:N\^^M
+\cs_new:Nn\knowledge_knowledge_setparseat:NNn
+{\knowledge_knowledge_setparseat_:NNw#1#2#3@@\kl_end:}
+\cs_new:Npn\knowledge_knowledge_setparseat_:NNw#1#2#3@#4@#5\kl_end:
+{\tl_set:Nx#1{\tl_trim_spaces:n{#3}}
+\tl_set:Nx#2{\tl_trim_spaces:n{#4}}}
 \NewDocumentCommand\knowledgestyle{ s m m  }
 { \kl_hide_begin:
   \group_begin:
@@ -1886,8 +1998,9 @@
 \bool_new:N\knowledge_knowledge_autoref_bool
 \bool_new:N\knowledge_knowledge_clear_bool
 \bool_new:N\knowledge_knowledge_append_bool
-\tl_clear_new:N\knowledge_knowledge_synonym_tl
+\tl_clear_new:N\knowledge_knowledge_synonymlink_tl
 \tl_clear_new:N\knowledge_knowledge_synonyminstance_tl
+\tl_clear_new:N\knowledge_knowledge_immediate_synonym_directives_tl
 \tl_clear_new:N\knowledge_knowledge_export_bool
 \tl_clear_new:N\knowledge_knowledge_key_tl
 \tl_clear_new:N\knowledge_knowledge_namespace_tl
@@ -1964,17 +2077,24 @@
     {\tl_set:Nn\knowledge_knowledge_directives_tl{#1}}
     {\tl_put_right:Nn\knowledge_knowledge_directives_tl{,#1}}}
 \cs_generate_variant:Nn\knowledge_delay_directive:n{x}
-\NewDocumentCommand\knowledgedirective{mom}{
+\NewDocumentCommand\knowledgedirective{smom}{
   \kl_hide_begin:
-  \cs_new:cn
-     {knowledgedirective_#1:n}
-     {\keys_set:nn{ knowledge~directives }{#3}}
-  \keys_define:nn{ knowledge~directives }
-    {#1 .code:n = {\use:c{knowledgedirective_#1:n}{##1}}}
-  \IfNoValueF{#2}
-    {\keys_define:nn{ knowledge~directives }{#1 .default:n = {#2}}}
+  \keys_if_exist:nnTF{ knowledge~directives }{ #2 }
+    {\IfBooleanTF{#1}
+       {\knowledgedirective:nnn{#2}{#3}{#4}}
+       {\msg_error:nnn{ knowledge }{  knowledgedirective~redifinition }{#2}}}
+    {\knowledgedirective:nnn{#2}{#3}{#4}}
   \kl_hide_end:
 }
+\cs_new:Nn\knowledgedirective:nnn{
+   \cs_set:cn
+       {knowledgedirective_#1:n}
+       {\keys_set:nn{ knowledge~directives }{#3}}
+     \keys_define:nn{ knowledge~directives }
+       {#1 .code:n = {\use:c{knowledgedirective_#1:n}{##1}}}
+     \IfNoValueF{#2}
+       {\keys_define:nn{ knowledge~directives }{#2 .default:n = {#2}}}
+}
 \tl_new:N\knowledge_knowledgedefault_tl
 \NewDocumentCommand\knowledgedefault{sm}{
   \kl_hide_begin:
@@ -2033,14 +2153,12 @@
 }
 \int_const:Nn\knowledge_kl_max_recursion_int{40}
 \int_new:N\knowledge_kl_recursion_int
-\cs_set:Nn\knowledge_kl_find:{
+\cs_new:Nn\knowledge_kl_find:{
   \knowledge_kl_find_recursion_exceeded:TF
-  {\knowledge_kl_error_recursion:}
-  {\tl_if_empty:NTF\knowledge_kl_instance_tl
-    {\tl_if_empty:NTF\knowledge_kl_linkscope_tl
+     \knowledge_kl_error_recursion:
+     {\tl_if_empty:NTF\knowledge_kl_linkscope_tl
         \knowledge_kl_find_withoutscope:
-        \knowledge_kl_find_withscope:}
-    \knowledge_kl_find_withinstance:}
+        \knowledge_kl_find_withscopetag:}
 }
 \cs_set:Npn\knowledge_kl_find_recursion_exceeded:TF{
   \int_decr:N\knowledge_kl_recursion_int
@@ -2057,13 +2175,31 @@
          \knowledge_kl_key_tl}
       { \knowledge_kl_error_unknown_in_scope_firsttime: }
 }
-\cs_new:Nn\knowledge_kl_find_withscope:{
-  \exp_args:NV
-  \scopept_label_instance_if_exist:nTF\knowledge_kl_linkscope_tl
-    { \tl_set:Nx\knowledge_kl_instance_tl
-        {\scopept_label_instance_use:n{\knowledge_kl_linkscope_tl}}
-     \knowledge_kl_find_withinstance: }
-    {  \knowledge_kl_error_label_unknown: }
+\cs_new:Nn\knowledge_kl_find_withscopetag:{
+  \exp_args:NV\knowledge_scopetag_warn_if_unknown:n\knowledge_kl_linkscope_tl
+  \tl_clear:N\l_tmpa_tl
+  \exp_args:Nc\seq_map_function:NN
+        {\knowledge_scopetag_tl[\knowledge_kl_linkscope_tl]_seq}
+        \knowledge_kl_find_scopetag_tmpa:n
+   \tl_if_empty:NTF\l_tmpa_tl
+      {\knowledge_kl_error_unknown_in_scope_firsttime:}
+      {\knowledge_kl_exec:VVV
+         \knowledge_kl_namespace_tl
+         \l_tmpa_tl
+         \knowledge_kl_key_tl}
+}
+\cs_new:Nn\knowledge_kl_find_scopetag:Nn{
+  \tl_if_empty:NTF#1
+    {\knowledge_knowledge_if_exist:VnVTF
+        \knowledge_kl_namespace_tl
+        {#2}%instance
+        \knowledge_kl_key_tl
+        {\tl_set:Nn#1{#2}}
+        {}}
+    {}
+}
+\cs_new:Npn\knowledge_kl_find_scopetag_tmpa:n{
+   \knowledge_kl_find_scopetag:Nn\l_tmpa_tl
 }
 \cs_new:Nn\knowledge_kl_find_withoutscope:{
   \knowledge_kl_find_in_scope:VNTF
@@ -2093,11 +2229,21 @@
       {#5}
 }
 \cs_new:Nn\knowledge_kl_find_in_scope_test:n{
+\tl_if_eq:nnTF{#1}{|}{}{
+\knowledge_kl_find_in_scope_test_:n{#1}
+\seq_if_exist:cTF{\knowledge_scopetag_tl[#1]_seq}
+   {\exp_args:Nc\seq_map_function:NN
+      {\knowledge_scopetag_tl[#1]_seq}
+      \knowledge_kl_find_in_scope_test_:n
+   }{}}
+}
+\cs_new:Nn\knowledge_kl_find_in_scope_test_:n{
    \exp_args:Nc\ktuple_if_exist:NTF
      {\knowledge_id:nnV{\l_tmpa_tl}{#1}\l_tmpb_tl}
      {\bool_gset_true:N\g_tmpa_bool
       \tl_gset:Nn\g_tmpa_tl{#1}
-      \seq_map_break:}{}}
+      \seq_map_break:}{}
+}
 \cs_generate_variant:Nn\knowledge_kl_find_in_scope:nnNTF{nVNTF}
 \cs_generate_variant:Nn\knowledge_kl_find_in_scope:nNTF{VNTF}
 \cs_new:Nn\knowledge_kl_exec:nnn{
@@ -2136,7 +2282,7 @@
         \knowledge_kl_compute_code:
      }
 }
-\cs_generate_variant:Nn\knowledge_kl_exec:nnn{nnV}
+\cs_generate_variant:Nn\knowledge_kl_exec:nnn{nnV,VVV}
 \cs_new:Nn\knowledge_kl_use_styles:n
   {\clist_map_function:nN{#1}\knowledge_kl_use_style:n}
 \cs_generate_variant:Nn\knowledge_kl_use_styles:n {x}
@@ -2179,13 +2325,25 @@
   {}
 \DeclareKAuxPhaseCommand\KAuxErrorKnowledgeUnknown{diagnose-unknown-suggest}
 {  \knowledge_diagnose_line:
-   \tl_set_eq:Nc\l_tmpa_tl{knowledge_kl_\cs_to_str:N#5_suggestion_tl}
-   \tl_if_empty:nTF{#2}{}
-     {\tl_if_empty:NTF\l_tmpa_tl{}
-       {\tl_put_right:Nn\l_tmpa_tl{,}}
-      \tl_put_right:Nn\l_tmpa_tl{scope={#2}}}
-   \knowledge_diagnose:x
-      {\exp_not:n{\knowledge{#3}}{\exp_not:V\l_tmpa_tl}}
+    \tl_set_eq:Nc\l_tmpa_tl{knowledge_kl_\cs_to_str:N#5_suggestion_tl}
+    \tl_if_eq:nnTF{#1}{default}
+     {}
+     {\tl_if_empty:NTF\l_tmpa_tl{}{\tl_put_right:Nn\l_tmpa_tl{,}
+      \tl_put_right:Nn\l_tmpa_tl{namespace={#1}}}}
+
+   \bool_if:NTF\knowledge_configuration_barsuggestion_bool{
+        %\knowledge_diagnose:x{\char_escape_tl knowledge{\exp_not:V\l_tmpa_tl}}
+        \tl_set:Nn\l_tmpa_tl{~~~|~~#3}
+        \tl_if_empty:nTF{#2}{}
+          {\tl_put_right:Nn\l_tmpa_tl{@#2}}
+        \knowledge_diagnose:x{\exp_not:V\l_tmpa_tl}
+   }{
+        \tl_if_empty:nTF{#2}{}
+          {\tl_if_empty:NTF\l_tmpa_tl{}{\tl_put_right:Nn\l_tmpa_tl{,}}
+           \tl_put_right:Nn\l_tmpa_tl{scope={#2}}}
+        \knowledge_diagnose:x
+          {\char_escape_tl knowledge\exp_not:n{{#3}}{\exp_not:V\l_tmpa_tl}}
+   }
 }
 \cs_new:Nn\knowledge_kl_error_unknown_firsttime:
   {\bool_if:cTF{\knowledge_variant_var:n{unknownwarning_bool}}
@@ -2193,7 +2351,7 @@
      \msg_warning:nnxxx{ knowledge }{ knowledge~unknown }
       {\exp_not:V\knowledge_kl_key_tl}
       {\exp_not:V\knowledge_kl_namespace_tl}
-      {\seq_use:Nn\knowledge_visible_instances_seq{~|~}}}
+      {\seq_use:Nn\knowledge_visible_instances_seq{|}}}
     }{}
    \bool_if:cTF{\knowledge_variant_var:n{unknowndiagnose_bool}}
     {\KAuxWriteX{
@@ -2286,36 +2444,38 @@
 \cs_new:Nn\knowledge_variant_var:n
   {knowledge_kl_\expandafter\cs_to_str:N\knowledge_kl_command_tl _#1}
 \NewDocumentCommand\knowledgenewvariant{mm}{
-  \exp_args:Nc\tl_new:Nn
+  \tl_if_exist:cTF{knowledge_kl_\cs_to_str:N#1_command_tl}
+    {\knowledge_error:n{Variant~#1~already~exists~(in~\knowledgenewvariant).}}
+    {\exp_args:Nc\tl_new:Nn
       {knowledge_kl_\cs_to_str:N#1_command_tl}
       {#1}
-  %
-  %
-  \NewDocumentCommand#1{s}
-     {\knowledge_kl_modifiers_add:N#1
-      \IfBooleanF{##1}{\knowledge_kl:w}}
-  %
-   \tl_new_eq:cN
-      {knowledge_kl_\cs_to_str:N#1_namespace_tl}
-      \knowledge_default_namespace_tl
-   \tl_new:cx{knowledge_kl_\cs_to_str:N#1_suggestion_tl}{}
-   \bool_new_true:c{knowledge_kl_\cs_to_str:N#1_unknownwarning_bool}
-   \bool_new_true:c{knowledge_kl_\cs_to_str:N#1_unknowndiagnose_bool}
-   \tl_new:cn{knowledge_kl_\cs_to_str:N#1_default_style_tl}{}
-   \tl_new:cn{knowledge_kl_\cs_to_str:N#1_unknown_style_tl}{}
-   \tl_new:cn{knowledge_kl_\cs_to_str:N#1_unknown_style_cont_tl}{}
-   \tl_new:cx{knowledge_kl_\cs_to_str:N#1_autoknowledge_tl}{}
-   \tl_new:cx{knowledge_kl_\cs_to_str:N#1_styledirectives_tl}{}
-   %
-   \bool_if:NT\knowledge_hyperref_active_bool
-      {\exp_args:Nx\pdfstringdefDisableCommands
-             {\exp_not:N\def\exp_not:N#1
-                  {\exp_not:N\knowledge_variant_arg_absorber:Nw
-                   \exp_not:c{\cs_to_str:N#1_PDFstring}}}}
-   \exp_args:Nc\newcommand{\cs_to_str:N#1_PDFstring}[3]{##1}
-   %
-   \tl_new:cx{knowledge_kl_\tl_to_str:n{#1*} _init_tl}
-       {
+    %
+    %
+    \NewDocumentCommand#1{s}
+       {\knowledge_kl_modifiers_add:N#1
+        \IfBooleanF{##1}{\knowledge_kl:w}}
+    %
+    \tl_new_eq:cN
+        {knowledge_kl_\cs_to_str:N#1_namespace_tl}
+        \knowledge_default_namespace_tl
+    \tl_new:cx{knowledge_kl_\cs_to_str:N#1_suggestion_tl}{}
+    \bool_new_true:c{knowledge_kl_\cs_to_str:N#1_unknownwarning_bool}
+    \bool_new_true:c{knowledge_kl_\cs_to_str:N#1_unknowndiagnose_bool}
+    \tl_new:cn{knowledge_kl_\cs_to_str:N#1_default_style_tl}{}
+    \tl_new:cn{knowledge_kl_\cs_to_str:N#1_unknown_style_tl}{}
+    \tl_new:cn{knowledge_kl_\cs_to_str:N#1_unknown_style_cont_tl}{}
+    \tl_new:cx{knowledge_kl_\cs_to_str:N#1_autoknowledge_tl}{}
+    \tl_new:cx{knowledge_kl_\cs_to_str:N#1_styledirectives_tl}{}
+    %
+    \bool_if:NT\knowledge_hyperref_active_bool
+       {\exp_args:Nx\pdfstringdefDisableCommands
+              {\exp_not:N\def\exp_not:N#1
+                   {\exp_not:N\knowledge_variant_arg_absorber:Nw
+                    \exp_not:c{\cs_to_str:N#1_PDFstring}}}}
+    \exp_args:Nc\newcommand{\cs_to_str:N#1_PDFstring}[3]{##1}
+    %
+    \tl_new:cx{knowledge_kl_\tl_to_str:n{#1*} _init_tl}
+        {
         \exp_not:n{\tl_set_eq:NN\knowledge_kl_command_tl}
             \exp_not:c{knowledge_kl_\cs_to_str:N#1_command_tl}
         \exp_not:n{\tl_set_eq:NN\knowledge_kl_namespace_tl}
@@ -2330,10 +2490,11 @@
             \exp_not:c{knowledge_kl_\cs_to_str:N#1 _styledirectives_tl}
         \exp_not:c{knowledge_kl_\cs_to_str:N#1 _autoknowledge_tl}
         }
-  %
-  %\bool_if:NT\knowledge_hyperref_active_bool
-  %  {\pdfstringdefDisableCommands{\let#1\knowledge_fake_kl:n}}
-  %
+   %
+   %\bool_if:NT\knowledge_hyperref_active_bool
+   %  {\pdfstringdefDisableCommands{\let#1\knowledge_fake_kl:n}}
+   %
+   }
   \knowledgesetvariant#1{#2}
 }
 \DeclareExpandableDocumentCommand\knowledge_variant_arg_absorber:Nw
@@ -2345,10 +2506,14 @@
 \tl_new:N\knowledge_variant_command_tl
 \tl_new:N\knowledge_variant_key_tl
 \NewDocumentCommand\knowledgesetvariant{mm}{
-   \tl_set:Nn\knowledge_variant_command_tl{#1}
-   \tl_set:Nx\knowledge_variant_key_tl{\cs_to_str:N#1}
-   %
-   \keys_set:nn{ knowledge~configure~variant }{#2}
+  \tl_if_exist:cTF{knowledge_kl_\cs_to_str:N#1_command_tl}
+    {
+      \tl_set:Nn\knowledge_variant_command_tl{#1}
+      \tl_set:Nx\knowledge_variant_key_tl{\cs_to_str:N#1}
+      %
+      \keys_set:nn{ knowledge~configure~variant }{#2}
+    }
+    {\knowledge_error:n{Variant~#1~does~not~exist~(in~\knowledgesetvariant).}}
 }
 \keys_define:nn{ knowledge~configure~variant }{
    namespace .code:n =
@@ -2437,13 +2602,13 @@
 \NewKnowledgeParamBool*{lowercase}\kl_lowercase_bool
 \NewKnowledgeParamBool*{uppercase}\kl_uppercase_bool
 \NewKnowledgeParamTl*{link}
-\NewKnowledgeParamTl*{link~scope}
+\NewKnowledgeParamTl*[\knowledge_kl_linkscope_tl]{link~scope}
 \NewKnowledgeParamTl*[\knowledge_kl_instance_tl]{link~instance}
 \NewKnowledgeParamTl*[\knowledge_kl_forcedtext_tl]{text}
 \NewKnowledgeParamTl*{wrap}
 
 \NewKnowledgeParamBool*{UnKnoWn~KNowLedGE}\kl_unknown_knowledge_bool
-\bool_gset_false:N\kl_unknown_knowledge_bool
+\bool_set_false:N\kl_unknown_knowledge_bool
 \ktuple_new_int_index:n{countuse}
 \ktuple_countuse_expands_to:n{}
 \ktuple_new_int_index:n{countintro}
@@ -2521,7 +2686,7 @@
    \int_compare:nNnT\kl_countuse_int>0
      {\int_compare:nNnT\kl_countintro_int=0
         {\knowledge_diagnose_line:
-         \knowledge_diagnose:n{\nointro{#1}{#2}{#3}}}}
+         \knowledge_diagnose:x{\char_escape_tl nointro{\exp_not:n{#1}}{\exp_not:n{#2}}{\exp_not:n{#3}}}}}
    \group_end:}
 \DeclareKAuxPhaseCommand\KAuxAutoref{autoref-introduced-not-used}
   {\group_begin:
@@ -2644,7 +2809,7 @@
        \tl_set:Nx\l_tmpa_tl
              {\int_compare:nNnTF\l_tmpa_int=1
              {} {\int_to_alph:n\l_tmpa_int}}
-       \exp_args:Nx\label{\exp_not:V\knowledge_kl_autoref_tl\l_tmpa_tl}}
+       \exp_args:Nx\LaTeXlabel{\exp_not:V\knowledge_kl_autoref_tl\l_tmpa_tl}}
     \expandafter\ktuple_countintro_gincr:N
         \knowledge_kl_resourcetoken_tl
     \KAuxWriteX
@@ -2664,7 +2829,7 @@
          }}{}
 }
 
-\cs_new:Npn\kl_up:n{\mode_if_math:TF\mathup\textup}
+\cs_new:Npn\kl_up:n{\mode_if_math:TF\use:n\textup}
 \cs_new:Npn\kl_md:n{\mode_if_math:TF\mathmd\textmd}
 \cs_new:Npn\kl_sc:n{\mode_if_math:TF\mathsc\textsc}
 \cs_new:Npn\kl_it:n{\mode_if_math:TF\mathit\textit}
@@ -2994,14 +3159,14 @@
 
 \knowledgenewvariant\kl{
   namespace= default,
-  default style= {kl,autoref link},
+  default style= {autoref link},
   unknown style= kl unknown,
   unknown style cont= kl unknown cont,
-  style directive={style}
+  style directive= style
 }
 \knowledgenewvariant\intro{
   namespace= default,
-  default style= {intro,autoref target},
+  default style= {autoref target},
   unknown style= intro unknown,
   unknown style cont= intro unknown cont,
   style directive= intro style
@@ -3014,11 +3179,11 @@
 }
 \knowledgenewvariant\reintro{
   namespace=default,
-  default style=intro,
   unknown style=intro unknown,
   unknown style cont=intro unknown cont,
   style directive=intro style
 }
+
 \knowledgevariantmodifier{\intro*\kl}{\intro}
 \knowledgevariantmodifier{\reintro*\kl}{\reintro}
 
@@ -3032,27 +3197,21 @@
 
 \ExplSyntaxOff
 \IfKnowledgePaperModeTF{
-  \knowledgestyle{kl}{}
   \knowledgestyle{kl unknown}{}
   \knowledgestyle{kl unknown cont}{}
-  \knowledgestyle{intro}{emphasize,index style=knowledgeIntroIndexStyle}
   \knowledgestyle{intro unknown}{emphasize}
   \knowledgestyle{intro unknown cont}{emphasize}
 }{}
 
 \IfKnowledgeCompositionModeTF{
   \IfXcolorTF{
-    \knowledgestyle{kl}{color={blue!70!black}}
     \knowledgestyle{kl unknown}{color=orange}
     \knowledgestyle{kl unknown cont}{color=brown}
-    \knowledgestyle{intro}{emphasize,color=blue,index style=knowledgeIntroIndexStyle}
     \knowledgestyle{intro unknown}{emphasize,color=orange}
     \knowledgestyle{intro unknown cont}{emphasize,color=brown}
    }{
-    \knowledgestyle{kl}{}
     \knowledgestyle{kl unknown}{underline}
     \knowledgestyle{kl unknown cont}{underline}
-    \knowledgestyle{intro}{emphasize,index style=introindexstyle}
     \knowledgestyle{intro unknown}{emphasize,underline}
     \knowledgestyle{intro unknown cont}{emphasize,underline}
    }
@@ -3060,17 +3219,13 @@
 
 \IfKnowledgeElectronicModeTF{
   \IfXcolorTF{
-    \knowledgestyle{kl}{color={blue!70!black}}
     \knowledgestyle{kl unknown}{}
     \knowledgestyle{kl unknown cont}{}
-    \knowledgestyle{intro}{emphasize,color=blue,index style=introindexstyle}
     \knowledgestyle{intro unknown}{emphasize}
     \knowledgestyle{intro unknown cont}{emphasize}
    }{
-    \knowledgestyle{kl}{}
     \knowledgestyle{kl unknown}{}
     \knowledgestyle{kl unknown cont}{}
-    \knowledgestyle{intro}{emphasize,index style=introindexstyle}
     \knowledgestyle{intro unknown}{emphasize}
     \knowledgestyle{intro unknown cont}{emphasize}
    }