summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/knowledge/knowledge-example.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/knowledge/knowledge-example.tex')
-rw-r--r--Master/texmf-dist/doc/latex/knowledge/knowledge-example.tex65
1 files changed, 49 insertions, 16 deletions
diff --git a/Master/texmf-dist/doc/latex/knowledge/knowledge-example.tex b/Master/texmf-dist/doc/latex/knowledge/knowledge-example.tex
index 878036ef03d..842d6fbd0e2 100644
--- a/Master/texmf-dist/doc/latex/knowledge/knowledge-example.tex
+++ b/Master/texmf-dist/doc/latex/knowledge/knowledge-example.tex
@@ -15,15 +15,18 @@
% The package 'knowledge' has now to be loaded.
% The options
% 'paper', 'electronic' or 'composition' (default)
-% can be used. These activates different rendering styles.
-% - paper produce a paper to be printed
-% - electronic highlights links using color
-% - composition (or default) highlights missing knowledges as
-% well as other information. It should always be used but when the paper is ready.
+% can be used. These activates 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
+% well as agives other pieces of information. It should always
+% be used but when the paper is ready.
%
-\usepackage{knowledge} % default
-%\usepackage[electronic]{knowledge} % final version to be read electronically
-%\usepackage[paper]{knowledge} % final version in black and white for printing
+\usepackage[scope]{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.
@@ -34,10 +37,12 @@
-% The following
-% It is convenient now to provide a list of \knowledge in the preamble:
+% It is convenient now to provide a list of \knowledge in the preamble
+% (or in an external file) according to the following syntax:
+%
% \knowledge{knowledge text}[synonym 1|synonym 2|...]{directives}
-% Most common in a science paper are 'notion' knowledges that
+%
+% The most common directive in a science paper is 'notion': knowledges that
% are used in the body with \intro and \kl commands/""...""" and "..." notatation:
\knowledge{anchor point}[anchor points|Anchor points]{notion}
\knowledge{diagnose file}{notion}
@@ -53,7 +58,21 @@
% Some other configurations are possible, such as:
\knowledge{LaTeX}[latex|LATEX|Latex]{url={https://fr.wikipedia.org/wiki/LaTeX}, text=\LaTeX}
-\knowledge{pdflatex}{url={https://en.wikipedia.org/wiki/PdfTeX}, typewriter}
+
+% Configurations can also be made contextual. For instance, the
+% following knowledge is only accessible directly in the introduction.
+% It can nevertheless be used from elswhere using "pdflatex@@section:introduction",
+\knowledge{pdflatex}{scope={section:example},url={https://en.wikipedia.org/wiki/PdfTeX}, typewriter}
+% or \kl(section:introduction){pdflatex}. See 'scoping' in the documetation for more details.
+
+% Scoping can be used in the preamble. For instance:
+\begin{scope}\label{package}
+ \knowledge{knowledge}{link=knowledge package,link scope}
+\end{scope}
+
+
+
+
\title{Mini example for the \texttt{knowledge} package}
@@ -61,9 +80,23 @@
\begin{document}
\maketitle
\begin{abstract}
-\AP This document provides an elementary example of the ""knowledge package"" for "latex".
+\AP This document provides an elementary example of the "knowledge package" for "latex".
\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 the index 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", 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. Try then compiling it in ""paper mode"" (an option of the "knowledge package"); 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".
@@ -89,8 +122,8 @@ The `@' symbol allows some flexibility by having a displayed text different from
\begin{quote}
\verb|\knowledge|\texttt{\{name\}[synonym1|synonym2|...]\{directives\}}
\end{quote}
-However, using undefined "knowledges" will not cause compile time errors, but be displayed as in the following `"unknown knowledge"' (i.e. in non-"paper mode" in 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 finalising the document.
+However, using undefined "knowledges" will not cause compile time errors, but be displayed as in the following `"unknown knowledge"' (i.e. in non-"paper mode" in 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.
-\AP Small red corners are visible in the margin. These are called ""anchor points"", are introduced
-using the \texttt{\detokenize{\AP}}command usually 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 Small red corners are visible in the margin. These are called ""anchor points"" and 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".
\end{document} \ No newline at end of file