Commit 3210bcb5 authored by Thomas Colcombet's avatar Thomas Colcombet
Browse files

v1.24

parent c192c4fc
......@@ -23,7 +23,7 @@
%
% \iffalse
%<head>\usepackage{expl3}
%<head>\ProvidesExplPackage{knowledge}{2020/03/05}{1.23}{}
%<head>\ProvidesExplPackage{knowledge}{2020/09/22}{1.24}{}
%<*driver>
\def\knowledgecode{active}
\input{knowledge.tex}
......@@ -56,6 +56,7 @@
% \changes{1.21}{2020/01/26}{bug fix} %
% \changes{1.22}{2020/03/05}{improvements} %
% \changes{1.23}{2020/04/25}{minor change} %
% \changes{1.24}{2020/09/22}{silent option} %
% \GetFileInfo{knowledge.sty} %
% \DoNotIndex{}
%
......@@ -75,8 +76,8 @@ This directory contains the package
name: knowledge
license: LaTeX Project Public License version 1.2 or above
version: v1.23
date: 2020/04/25
version: v1.24
date: 2020/09/22
author: Thomas Colcombet
mail: thomas.colcombet@irif.fr
web: https://www.irif.fr/~colcombe/knowledge_en.html
......@@ -200,10 +201,11 @@ This directory contains the package
% \begin{macrocode}
\cs_new:Nn\knowledge_info:n
{\msg_info:nnn{knowledge}{knowledge~info}{#1}}
\cs_new:Nn\knowledge_warning:n
{\msg_warning:nnn{knowledge}{knowledge~warning}{#1}}
\cs_new:Nn\knowledge_warning:n{
\msg_warning:nnn{knowledge}{knowledge~warning}{#1}
}
\cs_new:Nn\knowledge_error:n
{\msg_error:nnn{knowledge}{knowledge~error}{#1}}
{\msg_error:nnn{knowledge}{knowledge~error}{#1}}
% \end{macrocode}
% The command \csintro{\knowledge_werror:Nn} takes a boolean as argument, and behaves like \cs{\knowledge_error:n} if it is true, and \cs{\knowledge_warning:n} otherwise.
% \begin{macrocode}
......@@ -220,6 +222,33 @@ This directory contains the package
\cs_generate_variant:Nn\knowledge_warning:n{x}
\cs_generate_variant:Nn\knowledge_error:n{x}
% \end{macrocode}
%
% \begin{macrocode}
\cs_new:Npn\knowledge_warning:nn{
\bool_if:NTF\knowledge_warningsilent_bool
\use_none:nn
\msg_warning:nn
}
\cs_new:Npn\knowledge_warning:nnn{
\bool_if:NTF\knowledge_warningsilent_bool
\use_none:nnn
\msg_warning:nnn
}
\cs_new:Npn\knowledge_warning:nnnn{
\bool_if:NTF\knowledge_warningsilent_bool
\use_none:nnnn
\msg_warning:nnnn
}
\cs_generate_variant:Nn\knowledge_warning:nnnn{nnxx}
\cs_new:Npn\knowledge_warning:nnnnn{
\bool_if:NTF\knowledge_warningsilent_bool
\use_none:nnnnn
\msg_warning:nnnnn
}
\cs_generate_variant:Nn\knowledge_warning:nnnnn{nnxxx}
% \end{macrocode}
%
%
%\AP We provide now the `official' messages \csintro{knowledge~recursion}, \csintro{knowledge~unknown},
% \csintro{knowledge~unknown~in~scope}, \csintro{knowledge~unknown~label}, \csintro{package~required} and \csintro{knowledge~exists}.
% \begin{macrocode}
......@@ -440,6 +469,11 @@ This directory contains the package
\KnowledgeConfigureBooleanOption[\knowledge_warningstrict_bool]{strict}
% \end{macrocode}
% \begin{macrocode}
\bool_new:N\knowledge_warningsilent_bool
\bool_set_false:N\knowledge_warningsilent_bool
\KnowledgeConfigureBooleanOption[\knowledge_warningsilent_bool]{silent}
% \end{macrocode}
% \begin{macrocode}
\bool_new:N\knowledge_configuration_quotation_bool
\KnowledgeConfigureBooleanOptionTF[\knowledge_configuration_quotation_bool]{quotation}{\klactivatequotation}{\kldeactivatequotation}
\KnowledgeConfigureTrigger{protect~quotation}{\kl_protect_environment_quotation:n{#1}}
......@@ -2799,7 +2833,7 @@ This directory contains the package
\cs_new:Nn\knowledge_kl_error_unknown_firsttime:
{\bool_if:cTF{\knowledge_variant_var:n{unknownwarning_bool}}
{\IfKnowledgePaperModeF{
\msg_warning:nnxxx{ knowledge }{ knowledge~unknown }
\knowledge_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{|}}}
......@@ -2833,7 +2867,7 @@ This directory contains the package
\cs_new:Nn\knowledge_kl_error_unknown_in_scope_firsttime:
{\bool_if:cTF{\knowledge_variant_var:n{unknownwarning_bool}}
{\IfKnowledgePaperModeF{
\msg_warning:nnxxx{ knowledge }{ knowledge~unknown~in~scope }
\knowledge_warning:nnxxx{ knowledge }{ knowledge~unknown~in~scope }
{\exp_not:V\knowledge_kl_key_tl}
{\exp_not:V\knowledge_kl_namespace_tl}
{\knowledge_kl_linkscope_tl}}}{}
......@@ -2869,7 +2903,7 @@ This directory contains the package
}
%
\IfKnowledgePaperModeF{
\msg_warning:nnxx{ knowledge }{ knowledge~unknown~label }
\knowledge_warning:nnxx{ knowledge }{ knowledge~unknown~label }
{\exp_not:V\knowledge_kl_key_tl}
{\knowledge_kl_linkscope_tl}}
%
......
\documentclass{article}
\usepackage[utf8]{inputenc}
\usepackage[T1]{fontenc}
%
% The documentation of the _knowledge package_ can be found at:
%
% http://www.irif.fr/~colcombe/knowledge_en.html
%
%
% Loading other packages before knowledge activates features.
% The most common use of knowledge makes use of hyperref and xcolor:
\usepackage[breaklinks,hidelinks]{hyperref}
\usepackage{xcolor}
%
% 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:
% 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[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.
\knowledgeconfigure{notion}
% The 'quotation' configuration is commonly used and triggers the "..." notation.
\knowledgeconfigure{quotation}
% 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}
%
% 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}
\knowledge{knowledge package}{notion,typewriter}
\knowledge{paper mode}{notion}
\knowledge{electronic mode}{notion}
\knowledge{composition mode}{notion}
% the synonym directive can replace the [...] syntax
\knowledge{knowledge}{notion}
\knowledge{knowledges}{synonym}
\knowledge{Knowledges}{synonym}
% Some other configurations are possible, such as external url's or replacement texts:
\knowledge{LaTeX}[latex|LATEX|Latex]{url={https://fr.wikipedia.org/wiki/LaTeX}, text=\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",
\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}
\date{}
\begin{document}
\maketitle
\begin{abstract}
\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".
% \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 `@' symbol allows some flexibility by having a displayed text different from the target:
\begin{quote}
\verb|"This kind of algebras@solvable groups"...|
\end{quote}
\knowledgeconfigure{quotation}
\AP These concepts are referred to as ""knowledges"". "Knowledges" are to be defined (in general in the preamble of the document) using a command of the form:
\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 finalizing the document.
\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".
\end{document}
\ No newline at end of file
......@@ -6,7 +6,7 @@
\usepackage{expl3}
\usepackage{hyperref}
%\usepackage{complexity}
\usepackage[quotation,scope]{knowledge}
\usepackage[quotation,scope,silent]{knowledge}
\knowledgeconfigure{visible anchor points=false}
\knowledgeconfigure{notion,diagnose line=false}
\GetFileInfo{knowledge.sty}
......@@ -295,6 +295,7 @@
\knowledge{protect link}{directive}
\knowledge{strict}{directive}
\knowledge{silent}{directive}
\knowledge{emphasize}{directive}
\knowledge{underline}{directive}
\knowledge{up}{directive}
......@@ -747,6 +748,7 @@ I have seen Till Tantau who explained me how to test whether a material is displ
\item[2020-03-05] No \texttt{hidelinks} and \texttt{breaklinks} are automatically activated unless the new option \kl{no patch} is activated. Doc update. V1.22 on CTAN.
\item[2020-04-25] Made the package compatible with 2016 versions of LaTeX. Useful when \texttt{knowledge.sty} is included with and compile in arXiv. V1.23 on CTAN.
\item[2020-05-02] Doc update ("acmart@@package" colors, thanks to Daniela Petri\c san).
\item[2020-09-21] Adding the "silent" option as suggested by Patrick Lambein-Monette.
\end{compactdesc}
\normalsize
%\restoregeometry
......@@ -1251,6 +1253,7 @@ 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[""silent""] is a Boolean option which, when activated, switches off all warnings during the compilation, but the recap ones at the end.
\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.
......@@ -2905,6 +2908,7 @@ If other kind of problems occur, report them to \texttt{thomas.colcombet@irif.fr
\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.
\item[{{\kl(option)[quotation]{quotation=}\textmd{\{true,false\}}}}] activates or deactivates the "quotation notation".
\item["silent"] is a Boolean option which, when activated, switches off all warnings during the compilation, but the recap ones at the end.
\item["strict"] is a Boolean which, when true, makes the compilation more restrictive by turning some of the warnings into errors (in particular in case of redefinition of knowledges).
\item[\kl{visible anchor points=}\textmd{\{true,false\}}] makes the \kl{anchor points} either visible or invisible.
\end{compactdesc}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment