\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
% If the output is a PDF (avoids some display problems, in particular in arXiv).
\pdfoutput = 1

% This is the file 
%
%   knowledge-example.tex
%
% and is part of the LaTeX package _knowledge_.
% It can be used as a starting point for creating a document using the _knowledge_ package.
%
% The documentation of the _knowledge_ package can be found:
% - in your tex distribution, using the command
%        texdoc knowledge
% - or at the address
%.       https://ctan.org/pkg/knowledge
%
%
% Loading other packages before knowledge activates features.
% The most common use of knowledge makes use of hyperref and xcolor, and here also imakeidx:
\usepackage{imakeidx} % for creating an index
\makeindex
\usepackage[breaklinks,hidelinks]{hyperref} 
\usepackage{xcolor} 
%
% The package 'knowledge' has  now to be loaded.
% The options 'paper', 'electronic' or 'composition' (by default) activate the different rendering styles:
% - 'paper' produce a paper to be printed: text in black and white
% - 'electronic' highlights links using colors: for being read on an electronic device
% - 'composition' (or default) highlights missing knowledges as
%   provides other pieces of information. It should always
%   be used but when the paper is ready.
%
\usepackage{knowledge} % default
%\usepackage[scope,electronic]{knowledge} % final version to be read electronically
%\usepackage[scope,paper]{knowledge} % final version in black and white for printing
%

%
% The 'notion' configuration is commonly used for scientific papers. Here the default
% base color for intro is blue, and a darkened version of is used for uses.
%
\KnowledgeConfigureNotion[blue]{notion}
% The styles can be further changed by redefining the related styles, eg:
%  \knowledgestyle*{intro notion}{underline}
%  \knowledgestyle*{notion}{}
%

%
% The 'quotation' configuration is commonly used and triggers the "..." notation.
\knowledgeconfigure{quotation}
% 
%
% It is convenient now to provide a list of \knowledge command in the preamble
% or even better in an external file with ending with ".kl", using eg:
%.      \input{knowledge-example.kl}
% 
% The |-notation for defining knowledge looks as follows:
%
%    \knowledge{directives}
%       | main knowledge [@scope]
%       | synonym_1 [@scope1]
%       | synonym_2 [@scope2]
%       | ...
% 
% Note: Consider using "knowledge-clustering" (https://github.com/remimorvan/Knowledge-Clustering)
% for automating the process of writing the \knowledge commands.
%

% Here, we use the directive "notion" defined above, as well as index.
\knowledge{notion, index={anchor point}}
 | anchor point 
 | anchor points 
 | Anchor points 
\knowledge{notion, index={diagnose file}}
 | diagnose file
\knowledge{notion, index={paper}, index parent key={mode}}
 | paper mode
 | paper@mode 
\knowledge{notion, index={electronic}, index parent key={mode}}
 | electronic mode
 | electronic@mode
\knowledge{notion, index={composition}, index parent key={mode}}
 | composition mode
 | composition@mode 
\knowledge{notion, index=knowledge}
 | knowledge
 | knowledges
 | Knowledges
\knowledge{notion,index={directive}}
 | directive
 | directives
 | Directives


%
% Let us use another display style for packages that use url links to elsewhere in the web.
\knowledgedirective{package}{url = {#1}, typewriter, md, color=teal}
%
\knowledge{package={https://ctan.org/pkg/knowledge}}
 | knowledge package
 | knowledge@package
\knowledge{package={https://github.com/remimorvan/Knowledge-Clustering}}
 | knowledge-clustering
\knowledge{package={https://ctan.org/pkg/makeidx}}
  | makeidx@package
\knowledge{package={https://ctan.org/pkg/imakeidx}}
  | imakeidx@package
\knowledge{package={https://ctan.org/pkg/xcolor}}
  | xcolor@package
\knowledge{package={https://en.wikipedia.org/wiki/PdfTeX}}
  | pdflatex@example

%
\knowledge{url={https://fr.wikipedia.org/wiki/LaTeX},
	text=\LaTeX, % the text is replaced when used
	index=\LaTeX, % the aspect in the index
	index key=latex % where it appears in the index
	}
 | LaTeX
 | latex
 | LATEX
 | Latex
% Configurations can also be made contextual. For instance, the
% following knowledge is only accessible directly in the introduction.
% It can nevertheless be used from elsewhere using "pdflatex@@section:introduction",

% or \kl(section:introduction){pdflatex}. See 'scoping' in the documetation for more details.




% We now start a document as usual.
\title{Mini example for the \texttt{knowledge} package}
\date{}



\begin{document}
\maketitle
\begin{abstract}
\AP  This document provides an elementary example of use of the "knowledge package" for "latex" and can be used as a starting point for creating one's own document.
\end{abstract}

\section{Introduction}
\label{section:introduction}

The package ""knowledge@@package"" is a package for "latex" that helps associating information to terms. This can be used for:
\begin{itemize}
\item managing external urls, for instance separating the file containing  the addresses from their use,
\item managing internal references's such as linking every use of a concept to the place of its introduction (in particular avoiding the use of labels),
\item managing one of more indexes in a centralized way,
\item replacing some macros for configuring the display.
\end{itemize}
Primarily, the goal of the "knowledge@@package" is for the production of scientific documents (the longer, the more interesting, such as a thesis or a book) in order to improve their readability on electronic devices. Ultimately, the goal is to produce documents that are more semantic-aware. Some capabilities (link handling the index) are not related to this purpose in particular.

\section{Example running}
\label{section:example}
Try compiling this document (two compilation phases to have proper links) using "pdflatex@@example", and see how some notions are hyperlinked to their introduction point (some viewers make it more obvious than others by displaying a preview of the target of a link inside a document; since there is only one page in this example, this may be worth zooming in this case).
\AP When the "paper mode" is not active, links are clearly identified in blue. By default, the document is compiled in ""composition mode"".
Try compiling it in ""paper mode"" (an option when loading the package "knowledge@@package"), and it now looks like a regular paper (but the links are still there). In ""electronic mode"",
the links are still colored, but some other hints disappear like "anchor points".

% \AP provides an anchor point: this will be the precise target of the hyperlink.
% It is good practice to use is at the beginning of every paragraph that contains
% \intro commands. If 'final=false', then these anchor points appear as a small
% corner (red with xcolor).


\knowledgeconfigure{quotation=false}% temporarily disables the " notation
\AP While writing a document, the two syntaxes \verb|"text"| and \verb|""text""| should be used each time some important concept is used or introduced respectively in the paper. For instance:
\begin{quote}
\verb|Define a ""group"" to be a "monoid" such that...|
\end{quote}
The `\texttt{@}' symbol allows some flexibility by having a displayed text different from the target:
\begin{quote}
\verb|This kind of "algebras@groups"...|
\end{quote}
The double `\texttt{@@}' symbols allow to specify a scope. For instance, if one wants to refer to group morphisms and avoid ambiguity with, eg, ring morphisms, one can write:
\begin{quote}
\verb|A "morphism@@group" ...|
\end{quote}
\knowledgeconfigure{quotation}


\AP These concepts are referred to as ""knowledge"". A "knowledge" is to be defined\footnote{These macros are usually put in the preamble of the document or in a dedicated file ending in ``\texttt{.kl}'' if you are using the very helpful script "knowledge-clustering" by Rémi Morvan.} using a command of the form:
\begin{verbatim}
  \knowledge{directives}
    | name[@scope]
    | synonym1[@scope1]
    | synonym2[@scope2]
    | ...
\end{verbatim}
\AP There is a long list of possible ""directives"", and the user can define its own ones. In this document, a "directive" ``\texttt{notion}'' has automatically configured, and can be used. For instance:
\begin{verbatim}
  \knowledge{notion} % assuming `notion' has been defined
    | morphism of group
    | morphisms of group
    | group morphism
    | group morphisms
    | morphism@group
    | morphisms@group
\end{verbatim}
It means that all these terms represent the same concept, that is assumed to be introduced once, and all other uses should link to it.

Note that using undefined "knowledge" will not cause compile time errors, but be displayed as in the following ``"unknown knowledge"'' (i.e. in non-"paper mode" in orange-brown, but in regular black in "paper@@mode" or "electronic mode"). \AP The ""diagnose file"" (that ends with a ``\texttt{.diagnose}'' extension) contains detailed information about these warnings, and should be read often when finalizing the document (here, the script "knowledge-clustering" is very useful since it automatically gathers unknown terms together according to linguistic resemblance).

\AP Small red corners called ""anchor points"" are visible in the margin, and represent the precise location in a pdf document where an internal link jumps. These are introduced
using the \texttt{\detokenize{\AP}}command, commonly at the beginning of each paragraph that introduce some concept, or even in the middle of the paragraph. The "anchor points" become invisible in "paper@paper mode" or "electronic mode".

\AP For making an index, if the packages "makeidx@@package" or "imakeidx@@package" are loaded before, one can use extra "directives". For instance 
\begin{verbatim}
  \knowledge{notion, index={morphism}, index parent key={group}} 
    | morphism of group
    | morphisms of group
    | group morphism
    | group morphisms
    | morphism@group
    | morphisms@group
\end{verbatim}
will insert the term ``morphism'' as a sub-key of the index entry ``group'', and all the uses of group morphisms will be referred to in the index, in boldface for the introduction place.

More details to be found in the documentation. To get it, run in your shell:
\begin{verbatim}
texdoc knowledge
\end{verbatim}
Happy texing!

\printindex

\end{document}