diff options
Diffstat (limited to 'macros/latex/contrib')
113 files changed, 2360 insertions, 817 deletions
diff --git a/macros/latex/contrib/acro/README b/macros/latex/contrib/acro/README index c9a69ddaee..f4872ad221 100644 --- a/macros/latex/contrib/acro/README +++ b/macros/latex/contrib/acro/README @@ -1,9 +1,9 @@ -------------------------------------------------------------------------- -the ACRO package v2.10 +the ACRO package v2.10a Typeset Acronyms -2019/09/23 +2019/10/02 -------------------------------------------------------------------------- Clemens Niederberger Web: https://bitbucket.org/cgnieder/acro diff --git a/macros/latex/contrib/acro/acro.sty b/macros/latex/contrib/acro/acro.sty index 2b5cde75b3..b1b4947018 100644 --- a/macros/latex/contrib/acro/acro.sty +++ b/macros/latex/contrib/acro/acro.sty @@ -31,8 +31,8 @@ \RequirePackage{expl3,xparse,l3keys2e,xtemplate,etoolbox} \ProvidesExplPackage {acro} - {2019/09/23} - {2.10} + {2019/10/02} + {2.10a} {Typeset Acronyms} % -------------------------------------------------------------------------- @@ -313,6 +313,7 @@ \bool_new:N \l__acro_custom_short_format_bool \bool_new:N \l__acro_custom_alt_format_bool \bool_new:N \l__acro_custom_long_format_bool +\bool_new:N \l__acro_override_list_format_bool \bool_new:N \l__acro_strict_bool \bool_new:N \l__acro_create_macros_bool \bool_new:N \l__acro_first_upper_bool @@ -435,7 +436,7 @@ % -------------------------------------------------------------------------- % small commands for use at various places -\cs_new:Npn \acro_no_break: { \tex_penalty:D \c_ten_thousand } +\cs_new:Npn \acro_no_break: { \tex_penalty:D 10000 \scan_stop: } \cs_new_protected:Npn \__acro_first_upper_case:n #1 { \tl_upper_case:n { \tl_head:n {#1} } \tl_tail:n {#1} } @@ -496,6 +497,8 @@ list-long-format .value_required:n = true , list-foreign-format .tl_set:N = \l__acro_foreign_list_format_tl , list-foreign-format .value_required:n = true , + override-list-format .bool_set:N = \l__acro_override_list_format_bool , + override-list-format .initial:n = true , extra-format .tl_set:N = \l__acro_extra_format_tl , extra-format .value_required:n = true , single .bool_set:N = \l__acro_use_single_bool , @@ -1403,16 +1406,25 @@ % #1: id \cs_new_protected:Npn \__acro_list_entry_short:n #1 { - \acro_hyper_target:nn - {#1} - { - \acro_acc_supp:nn - {#1} - { - \l__acro_list_short_format_tl - \__acro_get_property:nn {short} {#1} - } - } + \group_begin: + \acro_get:n {#1} + \acro_hyper_target:nn + {#1} + { + \acro_acc_supp:nn + {#1} + { + \bool_if:nTF + { + \l__acro_custom_short_format_bool && + \l__acro_override_list_format_bool + } + { \l__acro_custom_short_format_tl } + { \l__acro_list_short_format_tl } + \__acro_get_property:nn {short} {#1} + } + } + \group_end: } % #1: id @@ -3001,10 +3013,10 @@ end ~ end } - \luatex_directlua:D { \l__acro_tmpa_tl } + \lua_now:e { \l__acro_tmpa_tl } \cs_new_protected:Npn \acro_strcmp:nn #1#2 { - \luatex_directlua:D + \lua_now:e { acro.strcmp ( @@ -3015,11 +3027,11 @@ } \cs_new:Npn \__acro_escape_x:n #1 { - \luatex_luaescapestring:D - { \etex_detokenize:D \exp_after:wN { \luatex_expanded:D {#1} } } + \lua_escape:e + { \__kernel_tl_to_str:w \use:e { {#1} } } } } - { \cs_new_eq:NN \acro_strcmp:nn \pdftex_strcmp:D } + { \cs_new_eq:NN \acro_strcmp:nn \tex_strcmp:D } \AtBeginDocument { @@ -3042,7 +3054,7 @@ \acro_strcmp:nn { \str_fold_case:n {##1} } { \str_fold_case:n {##2} } - = - \c_one + = -1 } { \sort_return_same: } { \sort_return_swapped: } @@ -4533,7 +4545,7 @@ \c_acro_config_file_extension_tl } -\tex_endinput:D +\file_input_stop: % -------------------------------------------------------------------------- % HISTORY: 2012/06/22 v0.1 - first public release @@ -4770,9 +4782,4 @@ - new: `uppercase-short' - a change to how usage is determined (see def. of \acro_is_used:nTF) - -% -------------------------------------------------------------------------- -% TODO: -- extend option `macros' to also define uppercase macros, possibly as a choice -- add \ACF, \ACFP, \ACL and \ACLP that will print all words of the long form - capitalized +2019/10/02 v2.10 - fix newly introduced issue #135 diff --git a/macros/latex/contrib/acro/acro_en.pdf b/macros/latex/contrib/acro/acro_en.pdf Binary files differindex e816f76124..fe818a934f 100644 --- a/macros/latex/contrib/acro/acro_en.pdf +++ b/macros/latex/contrib/acro/acro_en.pdf diff --git a/macros/latex/contrib/asmeconf/README.md b/macros/latex/contrib/asmeconf/README.md index 54508416ac..ada302df57 100644 --- a/macros/latex/contrib/asmeconf/README.md +++ b/macros/latex/contrib/asmeconf/README.md @@ -1,7 +1,7 @@ #asmeconf: A template for ASME conference papers# - Version 1.11 dated 2019/07/08. + Version 1.12 dated 2019/10/02. ####Overview#### This class provides a template to format ASME Conference papers according to @@ -47,6 +47,10 @@ - provide automatic layout of author and addresses in one of two styles +- provide line numbers for editing and review + +- support balancing of columns on last page + ####Author#### @@ -62,7 +66,9 @@ --- ####Change log#### - + + v1.12: add support for line numbers for editing; add support for final column balancing; edit skips in nomenclature; adjust \\tolerance and \\emergencystretch (for line breaking); improve support for equation tags in captions; adopt standard \\maketitle and \\title commands; include \\versionfootnote for tracking revisions of draft. + v1.11: minor adjustments to title, author, and affiliation layout v1.1: revise several parts of the layout to match ASME's updated specifications from Summer 2019 (including author block, abstract font, placement of nomenclature, and minor spacings); add .bst support for online references and eprints; expand documentation significantly; guidance on fitting equations into columns. diff --git a/macros/latex/contrib/asmeconf/asmeconf-sample.bib b/macros/latex/contrib/asmeconf/asmeconf-sample.bib index c196934749..3b4e5194e2 100644 --- a/macros/latex/contrib/asmeconf/asmeconf-sample.bib +++ b/macros/latex/contrib/asmeconf/asmeconf-sample.bib @@ -1,4 +1,4 @@ -%% Revised 7 July 2019 +%% Revised 2 October 2019 @article{ning2002, title = {On the Sliding Friction Characteristics of Unidirectional Continuous FRP Deposits}, @@ -270,4 +270,42 @@ url = {https://ctan.org/pkg/mathalfa}, urldate = {27 April 2019}, } - + @online{tolusis, + author = {Sigitas Tolu{\v{s}}is}, + title = {The \textsf{flushend} package}, + year = {2017}, + organization = {Comprehensive \TeX\ Archive Network}, + url = {https://www.ctan.org/pkg/flushend}, + urldate = {October 1, 2019}, + version = {3.3}, +} + +@online{bottcher, + author = {Stephan I. B{\"o}ttcher and Uwe L{\"u}ck}, + title = {\textsf{lineno.sty}: A {\LaTeX} package to attach line numbers to paragraphs}, + year = {2005}, + organization = {Comprehensive \TeX\ Archive Network}, + url = {https://www.ctan.org/pkg/lineno}, + urldate = {August 17, 2019}, + version = {4.41}, +} + +@online{oostrum, + author = {Piet van Oostrum}, + title = {The \textsf{fancyhdr} and \textsf{extramarks} packages}, + year = {2019}, + organization = {Comprehensive \TeX\ Archive Network}, + url = {https://www.ctan.org/pkg/lineno}, + urldate = {August 17, 2019}, + version = {3.10}, +} + +@online{fairbairns, + author = {Robin Fairbairns and Sebastian Rahtz and Leonor Barroca}, + title = {A package for rotated objects in \LaTeX}, + year = {2016}, + organization = {Comprehensive \TeX\ Archive Network}, + url = {https://www.ctan.org/pkg/rotating}, + urldate = {October 2, 2019}, + version = {v2.16d}, +} diff --git a/macros/latex/contrib/asmeconf/asmeconf-template.pdf b/macros/latex/contrib/asmeconf/asmeconf-template.pdf Binary files differindex 998ba989a7..70a20a31a7 100644 --- a/macros/latex/contrib/asmeconf/asmeconf-template.pdf +++ b/macros/latex/contrib/asmeconf/asmeconf-template.pdf diff --git a/macros/latex/contrib/asmeconf/asmeconf-template.tex b/macros/latex/contrib/asmeconf/asmeconf-template.tex index a6c50517b7..f43b9524be 100644 --- a/macros/latex/contrib/asmeconf/asmeconf-template.tex +++ b/macros/latex/contrib/asmeconf/asmeconf-template.tex @@ -1,19 +1,19 @@ %% %% This file is asmeconf-template.tex, a template to format ASME Conference papers according to -%% the requirements on ASME's conference web pages. As of version 1.1, this template follows ASME's +%% the requirements on ASME's conference web pages. As of version 1.11, this template follows ASME's %% newer conference guidelines as posted in July 2019. %% %% The new guidelines have changed the request author block formatting. %% Nomenclature follows the abstract. Abstract is in italics. %% -%% This file is version 1.11 dated 2019/07/08 +%% This file is version 1.12 dated 2019/10/02 %% %% Author: John H. Lienhard V %% Department of Mechanical Engineering %% Massachusetts Institute of Technology %% Cambridge, MA 02139-4307 USA %% -%% Class options are described in the asmeconf.cls file. These include: +%% Class options are set up in the asmeconf.cls file. These include: %% %% * Math options from M. Sharpe's newtxmath package: upright integrals [upint]; and %% * varvw for a v and w that are better distinguished from greek nu; and also @@ -30,9 +30,23 @@ %% * An optional to use newtxtext's superiors font for footnotes [nodefaultsups] and an option %% * for slightly larger small capitals, largesc %% +%% * An option to balance the heights of columns on the last page [balance]. +%% * This option is NOT compatible with the [lineno] option. +%% +%% * An option to include line numbers [lineno]. The lineno package does not number equation +%% * lines, captions, tables, etc. You must run _twice_ for proper placement of the line numbers. +%% * This option will disable balancing column height on final page if that option has been invoked. +%% * The lineno package won't always number the lines preceding displayed math in a paragraph because +%% * paragraph has not ended. See that package's documentation for macros to address this problem, or +%% * just leave a blank line above the displayed equation while you are editing and then remove the +%% * blank line and [lineno] option when you move to your final version. +%% %% * An option to use the old grid arrangement of author names [oldauthors]. See Appendix B for usage, %% * because the authors and affiliations must be entered different in this case. %% +%% * An option to allow hyphenation of the typewriter font [hyphenate] +%% * Hyphenation is normally suppressed for typewriter mode because it is often used for code. +%% %% For details of newtxmath and mathalfa, refer to their documentation (available on CTAN: http://ctan.org). %% %% The use of commands defined or modified by the asmeconf class is illustrated below. In particular, @@ -64,8 +78,9 @@ %% Class options are described above. -\documentclass[varvw,largesc,upint,mathalfa=cal=euler,colorlinks]{asmeconf} % <=== remove colorlinks for submission to ASME +\documentclass[varvw,largesc,upint,mathalfa=cal=euler,colorlinks,hyphenate,balance]{asmeconf} % <=== remove colorlinks for submission to ASME +\pdfminorversion=7 % This selection is not required. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%% Fields to be completed %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -98,7 +113,7 @@ % enclosed in \NoCaseChange{...} to maintain lower case type % LaTeX will automatically set this in all capital letters. -\PaperTitle{Place Title Here: Place Subtitle After Colon} +\title{Place Title Here: Place Subtitle After Colon} % <=== change to YOUR title %% Put author names into the order you want. Use the same order for affiliations. @@ -117,7 +132,11 @@ \SetAffiliation{3}{Hampton Court Palace, Richmond, England} \SetAffiliation{4}{Massachusetts Institute of Technology, Cambridge, MA } -\MakeTitlePage +\maketitle + +%%% For tracking various versions of your draft. Change text to suit your own needs. Remove from final version. +%%% \date{..} is the same command. +\versionfootnote{Documentation for \texttt{asmeconf.cls}. Version 1.12; \today.}% <=== Delete before final submission. %%% Change these to your keywords. Keywords are automatically printed at the end of the abstract. @@ -172,15 +191,17 @@ The \texttt{.tex} file may be written using standard \LaTeX\ commands, although \subsection{Essential Initial Commands} To begin, fill in the fields to be completed at top of the \texttt{asmeconf-template.tex} file. These fields include the headers for your conference and your paper number. Specified metadata will be placed into the pdf file itself. -The title should be placed into \verb|\PaperTitle{..}|. +The title should be placed into \verb|\title{..}|. + +Put author names into the \verb|\SetAuthors{name, name,...}| command in the desired order; follow the syntax illustrated \texttt{asmeconf-template.tex} file. Put each distinct address sequentially into a separate \verb|\SetAffiliation{n}{address}|, where $n = 1,2,\ldots$ Tag each author with the right affiliation by putting \verb|\affil{n}| after that author's name inside the \verb|\SetAuthors{..| command. -Put author names into the \verb|\SetAuthors{name, name,...}| command in the desired order; follow the syntax illustrated \texttt{asmeconf-template.tex} file. Put each distinct address sequentially into a separate \verb|\SetAffiliation{n}{address}|, where $n = 1,2,\ldots$. Tag each author with the right affiliation by putting \verb|\affil{n}| after that author's name. Author addresses are to be kept short. List the author institution, and the City, State (US authors), City, Province, Canada (Canadian authors), or City, Country (other international authors). +Author addresses are to be kept short. List the author institution, and the City, State (US authors), City, Province, Canada (Canadian authors), or City, Country (other international authors). -One author (or more) may be designated as the \verb|\CorrespondingAuthor{email}| by placing the command at the end of the name. Two or more authors may be joint first authors with \verb|\JointFirstAuthor|. Either of these commands should come after \verb|\affil{#}|. +One author (or more) may be designated as the \verb|\CorrespondingAuthor{email}| by placing the command after \verb|\affil{#}|. Two or more authors may be joint first authors by putting \verb|\JointFirstAuthor| after \verb|\affil{#}|. -After setting up the headers, authors, and title, issue the \verb|\MakeTitlePage| command. +After setting up the headers, authors, and title, issue the \verb|\maketitle| command. -Keywords may optionally be including using the \verb|\keywords{..}| command; this command \textit{must} be issued before the abstract. The abstract text must be placed into \verb|\SetAbstract{..}|. The abstract will automatically be italized. +Keywords may optionally be including using the \verb|\keywords{..}| command. This command \textit{must} be issued before the abstract. The abstract text must be placed into \verb|\begin{abstract}..\end{abstract}|. The abstract will automatically be italicized. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -223,7 +244,7 @@ If you wish to override the default math format in captions, put \verb|\mathvers Subsections and sub-subsection headings should be entered in title case, with the first letter of primary words capitalized. Sub-subsections (i.e., paragraphs) are never numbered. \subsection{Colored hyperlinks} -ASME requires that all text be in black when the paper is submitted for publication. For other uses, authors make +ASME requires that all text be in black when the paper is submitted for publication. For other uses, authors may obtain colored hyperlinks with the [\texttt{colorlinks}] option. %%%%%%%%%%%%%%% begin simple table %%%%%%%%%%%%%%%%%%%%%%%%%% @@ -273,21 +294,28 @@ The class loads the \texttt{booktabs} package (used for horizontal rules in both Figure captions go below figures. Figure~\ref{fig:2} is an example of a figure that spans two columns and includes subfigures. The text in figures (and tables) should be no smaller than 6~point type. +Landscape figures and tables may be produced at full-page size by putting \verb|\usepackage[figuresright]{rotating}| in your \texttt{.tex} file's preamble and using the \texttt{sidewaystable*} and \texttt{sidewaysfigure*} environments~\cite{fairbairns}. + %%%%%%%%%%%%%%%%% begin wide figure %%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{figure*}[t] -\begin{minipage}[c]{0.5\textwidth} +\begin{subfigure}[t]{0.5\textwidth} %subfigure is basically the same as minipage +\vbox{ +\vspace*{1.7em} \centering{ \includegraphics{sample-figure-2a.pdf} +} +\vspace*{1.7em} +} \subcaption{Interior region\label{fig:interior-region}} -}\end{minipage} -%%%%%%%%%%%%% -\begin{minipage}[c]{0.5\textwidth} -\centering{ +\end{subfigure}% +%%%%%%%%%%%%% no spaces or line breaks between these two minipages +\begin{subfigure}[t]{0.5\textwidth} +\centering{% \includegraphics{sample-figure-2b.pdf} \subcaption{Exterior region\label{fig:exterior-region}} -}\end{minipage} +}\end{subfigure} \caption{A figure with two subfigures \cite{Lienhard2019b}}\label{fig:2} \end{figure*} @@ -324,8 +352,10 @@ Elementary support for \texttt{eprint} numbers is also included, generating a ur %% \section[More on math: u\cdot\omega=0]{More on math: $\vec{\mathrm{u}}\cdot\vec{\omega}=0$}\label{sec:moremath} -In most cases, the need for a wide equation can be eliminated by using one of the multiline equation environments defined by \texttt{amsmath}, such as \texttt{align}, \texttt{split}, or \texttt{multline}~\cite{amsmath}. The following equation is set with the \texttt{multline} environment: -\begin{multline} +In most cases, the need for a wide equation can be eliminated by using one of the multiline equation environments defined by +\texttt{amsmath}, such as \texttt{align}, \texttt{split}, or \texttt{multline}~\cite{amsmath}. The following equation is set with the +\texttt{multline} environment: +\begin{multline}\label{eqn:energy} \frac{\partial}{\partial t}\left[\rho\bigl(e + \lvert\vec{u}\rvert^2\big/2\bigr)\right] + \nabla\cdot\left[\rho\bigl(h + \lvert\vec{u}\rvert^2\big/2 \bigr)\vec{u}\right] \\ ={}-\nabla \cdot \vec{q} + \rho \vec{u}\cdot\vec{g}+ \frac{\partial}{\partial x_j}\left(d_{ji}u_i\right) + \dot{Q}_v \end{multline} @@ -348,17 +378,37 @@ The class file also provides upright sans-serif greek letters with \verb|\sfalph These math options are discussed further in the \texttt{asmejour-template.tex} file. In addition, many options for calligraphic, script, and fraktur fonts are available as options to the \texttt{mathalfa} package, which is also loaded. These may be invoked, for example, as -\begin{quote} +\begin{center} \verb|\documentclass[mathalfa=cal=euler]{asmeconf}| -\end{quote} +\end{center} which selects the Euler font for \verb|\mathcal| (this is our default). To find all the font options, refer to the \texttt{mathalfa} package documentation \cite{sharpe2}. The typewriter font loaded is \texttt{inconsolata} (which is sans serif), as suggested by the \texttt{newtx} package documentation. The class is not set up for use with the \texttt{fontspec} or \texttt{unicode-math} packages. +\section{Additional Options for \NoCaseChange{\texttt{asmeconf.cls}}} +The class accepts a number of options in addition to those already described. + +\subsection{Final Column Balancing} The option \texttt{[balance]} invokes the the \texttt{flushend} package~\cite{tolusis}. +This package will attempt to give equal height to the two columns on the last page. The performance of this package is sometimes inconsistent (with odd page layout or, very rarely, errors), so use this option with caution. + +\subsection{Line Numbers} The option \texttt{[lineno]} invokes the the \texttt{lineno} package~\cite{bottcher}. This option will produce line numbers in the margins. You must run \LaTeX\ twice for proper placement of the numbers. Tables, captions, and footnotes will not be numbered. Line numbers can be helpful for review and editing, but should not be used in your final manuscript. See the documentation of the \texttt{lineno} package for further commands to control line numbering. + +The \texttt{lineno} package is not compatible with the \texttt{flushend} package that makes final short columns the same height. Balancing is disabled when this option is called. + +\subsection{Changing the Footer Text} The option \texttt{[nofoot]} will omit the ASME copyright from the first page footer. +The footers are generated with the \texttt{fancyhdr} package~\cite{oostrum}, so you can change them in any way you like using the commands of that package. Only the default arrangement of footers matches ASME's style, however. + +\subsection{Superiors Font} The \texttt{newtxtext} package includes a superiors font (both numbers and letters) for use in footnote markers and superscripts. To enable this font, use the option \texttt{[nodefaultsups]}. + +\subsection{Old-style Author Grid} The option \texttt{[oldauthors]} invokes the old grid arrangement of author names. The authors and affiliations must be entered differently in this case. See Appendix \ref{appendix:b} for usage. + +\subsection{Hyphenation of Typewriter Font} The option \texttt{[hyphenate]} will allow hyphenation of the typewriter font. +Hyphenation is normally suppressed for typewriter mode because this font is often used for code. + %%%%%%%%%%%%%%% begin two column table %%%%%%%%%%%%%%%%%% \begin{table*}[t] -\caption{A table spanning two columns}\label{tab:3}% +\caption{A table spanning two columns\label{tab:3}}% \centering{% \begin{tabular*}{0.8\textwidth}{@{\hspace*{1.5em}}@{\extracolsep{\fill}}ccc!{\hspace*{3.em}}ccc@{\hspace*{1.5em}}} \toprule diff --git a/macros/latex/contrib/asmeconf/asmeconf.cls b/macros/latex/contrib/asmeconf/asmeconf.cls index 0453465e48..66554fa384 100644 --- a/macros/latex/contrib/asmeconf/asmeconf.cls +++ b/macros/latex/contrib/asmeconf/asmeconf.cls @@ -1,11 +1,11 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% %% This file provides the asmeconf class for formatting conference papers according to -%% ASME conference requirements as represented on ASME's conference web pages in March 2019. +%% ASME conference requirements as represented on ASME's conference web pages in mid-2019. %% %% Please note that ASME's journals follow specifications different from ASME conference papers. %% -%% This file is version 1.11 dated 2019/07/08. +%% This file is version 1.12 dated 2019/10/02. %% %% Author: John H. Lienhard V %% Department of Mechanical Engineering @@ -31,7 +31,7 @@ %% This class is not designed for unicode-math or fontspec, given that the ASME conference style is %% specific with respect to the font selections. %% -%% Options for the class are described on lines 79-126. +%% Options for the class are configured on lines 79-153. %% %% The class defines two environments: abstract and nomenclature. The latter has an optional argument to %% control the space between the entries and the definitions. @@ -39,7 +39,7 @@ %% New commands are described in the asmeconf-template.tex file. The \section[]{} command's optional %% argument is changed to better support pdf bookmarks, and \section* is modified similarly. %% -%% Commands for entering conference headers, title, abstract, and author names are specific to this class. +%% Commands for entering conference headers and author names are specific to this class. %% See asmeconf-template.tex for details. %% %% @@ -67,7 +67,7 @@ %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \NeedsTeXFormat{LaTeX2e} -\ProvidesClass{asmeconf}[2019/07/08 ASME Conference Paper Format] +\ProvidesClass{asmeconf}[2019/10/02 ASME Conference Paper Format] \LoadClass[twoside,twocolumn,10pt]{article} % Two-sided layout not used in ASME's specs, although that's how the papers are printed @@ -80,6 +80,10 @@ \setboolean{DefaultSups}{true} \newboolean{Oldauthors} \setboolean{Oldauthors}{false} +\newboolean{Balance} +\setboolean{Balance}{false} +\newboolean{lineno} +\setboolean{lineno}{false} \RequirePackage{kvoptions} @@ -100,6 +104,22 @@ \setboolean{DefaultSups}{#1} } +%%% set key [nodefaultsups] to obtain newtx superiors font for footnotes. +\define@key{asmeconf}{nodefaultsups}[false]{% + \setboolean{DefaultSups}{#1} +} + +%%% set key [balance] to balance column height on last page. +\define@key{asmeconf}{balance}[true]{% + \setboolean{Balance}{#1} + \ClassWarningNoLine{asmeconf}{Loading flushend package to balance column height on last page}% +} + +%%% set key [lineno] to obtain linenumbers. +\define@key{asmeconf}{lineno}[true]{% + \setboolean{lineno}{#1} +} + \ProcessKeyvalOptions* %% option to have colored hyperlinks @@ -124,8 +144,15 @@ %% option to use old authors \DeclareOption{oldauthors}{% \setboolean{Oldauthors}{true}% + \ClassWarningNoLine{asmeconf}{Selected option for a grid of author blocks}% } +%% Option to hyphenate the typewriter font [hyphenate] +\DeclareOption{hyphenate}{% + \PassOptionsToPackage{hyphenate}{inconsolata}% + \ClassWarningNoLine{asmeconf}{Allowing hyphenation of typewriter font}% +} + %% Suppress warnings about mathalfa keys as unused global options \DeclareOption*{} @@ -174,6 +201,15 @@ \RequirePackage{bm} % load after all math to give access to bold math +%% Ensure that the current font is used for equation tags, not \normalfont as set by amsmath +\def\maketag@@@#1{\hbox{\m@th#1}} + +% The article class calls \sloppy in two-column mode (\tolerance 9999, \emergencystretch 3em) +% These adjustments affect line breaking; the values below are intended to produce +% fewer lines with large spaces, without creating the problems of using \fussy in two-column mode. +\tolerance 2500 +\emergencystretch 3em + %%%% font size selection %%%%%%%% %%%% ASME's specs differ slightly from latex standard article-10 class %%% @@ -209,7 +245,7 @@ \renewcommand{\headrulewidth}{0pt} \renewcommand{\footrulewidth}{0pt} -%%%%%% foonotes %%%%%%% +%%%%%% footnotes %%%%%%% \RequirePackage{fnpos} \makeFNbottom @@ -328,9 +364,10 @@ %% Let's also add \footnote to the \TextUppercase exception list, so that footnote text won't be capitalized -%% if given in section headings +%% if given in section headings. Ditto for \eqref \RequirePackage{xpatch} \xpatchcmd{\@uclcnotmath}{\@nonchangecase\ref}{\@nonchangecase\ref\@nonchangecase\footnote}{}{} +\xpatchcmd{\@uclcnotmath}{\@nonchangecase\ref}{\@nonchangecase\eqref\@nonchangecase\footnote}{}{} %%% Create an optional argument for unnumbered sections and set pdf bookmark (thru \addcontentsline). @@ -352,6 +389,35 @@ } } +%%%%%%%%%%%%% Line numbering and balancing columns on last page %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +\ifthenelse{\boolean{lineno}}{% + \RequirePackage[switch,mathlines]{lineno} + \renewcommand{\linenumberfont}{\normalfont\footnotesize\color{red}} + \AtBeginDocument{\linenumbers} + \ClassWarningNoLine{asmeconf}{Package lineno loaded, so final column balancing is disabled} +%%% Allow line numbering in AMS math environments. +%%% postdisplaypenalty adjusted to avoid extra line number at end, see discussion here: https://tex.stackexchange.com/a/461192/ +%%% multline has some problem that puts an extra line number above it. +%%% Requires xparse and etoolbox +\NewDocumentCommand{\losepostpenalty}{}{\patchcmd{\linenomathWithnumbers}{\advance\postdisplaypenalty\linenopenalty}{}{}{}} + +\NewDocumentCommand{\FixAMSMath}{m}{% + \AtBeginEnvironment{#1}{\losepostpenalty\linenomath}% + \AtEndEnvironment{#1}{\endlinenomath}% + \AtBeginEnvironment{#1*}{\losepostpenalty\linenomath}% + \AtEndEnvironment{#1*}{\endlinenomath}% +} + +\NewDocumentCommand{\FixAll}{>{\SplitList{;}}m}{\ProcessList{#1}{\FixAMSMath}} +\FixAll{align;alignat;gather;flalign;multline} + + }{% + \ifthenelse{\boolean{Balance}}{\RequirePackage{flushend}}{\relax} % flushend is NOT compatible with lineno +} +\providecommand{\@LN@col}[1]{\relax} +\providecommand{\@LN}[2]{\relax} + %%%%%%%%%%%%% Define special environments %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% @@ -380,18 +446,19 @@ %% \newlength\nomenwidth +\newlength\savitemsep %% If second argument of \entry is omitted, will produce an italicized heading (e.g. "Greek letters") %% \DeclareDocumentCommand{\entry}{m g}{% \IfNoValueTF{#2}{% - \item[\itshape#1\hfill]\par\smallskip% + \itemsep3\p@ plus 1\p@ minus 1\p@% + \goodbreak\item[\itshape#1\hfill]\setlength\itemsep\savitemsep\nopagebreak% \smallskip }{% \item[#1\hfill]#2% } } - \DeclareDocumentEnvironment{nomenclature}{O{2em} O{Nomenclature}}{% \setlength\columnsep{2em} \setlength{\nomenwidth}{#1} @@ -404,6 +471,7 @@ \setlength{\labelwidth}{\nomenwidth}% \setlength{\leftmargin}{\labelwidth}% \addtolength{\leftmargin}{\labelsep}% + \setlength\savitemsep\itemsep }% }{\end{list}} @@ -703,6 +771,22 @@ \let\thefootnote\savethefootnote } +%%%%%%%%%% + +%% Provide compatibility with titling commands from standard LaTeX article class + +\RenewDocumentCommand{\maketitle}{}{\MakeTitlePage} +\RenewDocumentCommand{\title}{}{\PaperTitle} + +\RenewDocumentCommand{\thanks}{m}{\relax} %% disabling this standard command, as it is inconsistent with the format + +%% Produces an unmarked footnote about the version date, to replace "date" +%% This is for editing and should note be used in the final draft +\NewDocumentCommand{\versionfootnote}{m}{\begin{NoHyper}\gdef\@thefnmark{}\@footnotetext{#1}\end{NoHyper}} + +\RenewDocumentCommand{\date}{m}{\versionfootnote} %% in case someone wants to use \date this way. + + %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% Provide sans serif upright Greek letters, following a suggestion diff --git a/macros/latex/contrib/asmeconf/sample-figure-2a.pdf b/macros/latex/contrib/asmeconf/sample-figure-2a.pdf Binary files differindex e02f4c93f8..e1b735b036 100644 --- a/macros/latex/contrib/asmeconf/sample-figure-2a.pdf +++ b/macros/latex/contrib/asmeconf/sample-figure-2a.pdf diff --git a/macros/latex/contrib/asmeconf/sample-figure-2b.pdf b/macros/latex/contrib/asmeconf/sample-figure-2b.pdf Binary files differindex 94dad8d4f6..e71d416a0b 100644 --- a/macros/latex/contrib/asmeconf/sample-figure-2b.pdf +++ b/macros/latex/contrib/asmeconf/sample-figure-2b.pdf diff --git a/macros/latex/contrib/duckuments/duckuments.dtx b/macros/latex/contrib/duckuments/duckuments.dtx index 6359862efc..b4652dad2d 100644 --- a/macros/latex/contrib/duckuments/duckuments.dtx +++ b/macros/latex/contrib/duckuments/duckuments.dtx @@ -61,8 +61,8 @@ and the derived files duckuments.pdf, %<*driver|pkg> \RequirePackage{xparse}[2019-05-03] \RequirePackage{letltxmacro,l3keys2e} -\def\duckuments@version{0.4e} -\def\duckuments@date{2019-09-28} +\def\duckuments@version{0.5} +\def\duckuments@date{2019-10-03} %</driver|pkg> % %<*driver> @@ -117,9 +117,9 @@ and the derived files duckuments.pdf, % \maketitle % \tableofcontents % -% \begin{documentation}^^A>>> +% \begin{documentation}^^A>>= % -% \section{Introducktion}^^A>>> +% \section{Introducktion}^^A>>= % % This package was inspired by the question % \href{https://tex.stackexchange.com/questions/419751} @@ -139,14 +139,16 @@ and the derived files duckuments.pdf, % sources are hosted on % \href{https://github.com/Skillmon/ltx_duckuments}{github}. % -% \textbf{The package does currently only work on \pdfTeX, \LuaTeX, and \XeTeX}. -%^^A<<< +% \textbf{The package should support any engine.} However for engines other than +% \pdfTeX, \LuaTeX, and \XeTeX\ it requires |extractbb| to be legal in a +% shell-escape (which should normally be the case). +%^^A=<< % -% \section{Duckumentation}^^A>>> +% \section{Duckumentation}^^A>>= % -% \subsection{Ducky content}^^A>>> +% \subsection{Ducky content}^^A>>= % -% \begin{function}{\duckument}^^A>>> +% \begin{function}{\duckument}^^A>>= % \begin{syntax} % \cs{duckument}\oarg{key=value} % \end{syntax} @@ -155,55 +157,55 @@ and the derived files duckuments.pdf, % \env{itemize}, \env{enumerate}, and \env{description}, one only at top % level and one with 4~environments nested. The \meta{key=value}s accept every % key as explained in \autoref{sec:keys}, but not every key has an effect. -% \end{function}^^A<<< +% \end{function}^^A=<< % -% \begin{function}{\blindduck}^^A>>> +% \begin{function}{\blindduck}^^A>>= % \begin{syntax} % \cs{blindduck}\oarg{key=value} % \end{syntax} % Produces one paragraph of dummy content. The \meta{key=value}s accept every % key as explained in \autoref{sec:keys}, but not every key has an effect. -% \end{function}^^A<<< +% \end{function}^^A=<< % -% \begin{function}{\ducklist}^^A>>> +% \begin{function}{\ducklist}^^A>>= % \begin{syntax} % \cs{ducklist}\meta{*}\marg{environment} % \end{syntax} % Sets a list of the specified \meta{environment}, if \meta{*} is given % \cs{item}\oarg{dummy} is used instead of only \cs{item}. For |description| % the starred version is used automatically. -% \end{function}^^A<<< +% \end{function}^^A=<< % -% \begin{function}{\ducklistlist}^^A>>> +% \begin{function}{\ducklistlist}^^A>>= % \begin{syntax} % \cs{ducklistlist}\meta{*}\marg{list} % \end{syntax} % Sets 4~levels of a nested list of the specified \meta{environment}, if % \meta{*} is given \cs{item}\oarg{dummy} is used instead of only \cs{item}. % For |description| the starred version is used automatically. -% \end{function}^^A<<< +% \end{function}^^A=<< % -% \begin{function}{\duckitemize}^^A>>> +% \begin{function}{\duckitemize}^^A>>= % Abbreviation for \cs{ducklist}|{itemize}|. -% \end{function}^^A<<< +% \end{function}^^A=<< % -% \begin{function}{\duckenumerate}^^A>>> +% \begin{function}{\duckenumerate}^^A>>= % Abbreviation for \cs{ducklist}|{enumerate}|. -% \end{function}^^A<<< +% \end{function}^^A=<< % -% \begin{function}{\duckdescription}^^A>>> +% \begin{function}{\duckdescription}^^A>>= % Abbreviation for \cs{ducklist}|{description}|. -% \end{function}^^A<<< -%^^A<<< +% \end{function}^^A=<< +%^^A=<< % -% \subsection{Other Macros}^^A>>> +% \subsection{Other Macros}^^A>>= % -% \begin{function}{\duckumentsCreateExampleFiles}^^A>>> +% \begin{function}{\duckumentsCreateExampleFiles}^^A>>= % Creates the files \file{example-image-duck.tex} and % \file{example-image-duck-portrait.tex} in the current working directory. -% \end{function}^^A<<< +% \end{function}^^A=<< % -% \begin{function}{\duckumentsDrawRandomDucks}^^A>>> +% \begin{function}{\duckumentsDrawRandomDucks}^^A>>= % \begin{syntax} % \cs{duckumentsDrawRandomDucks}\meta{*}\oarg{count} % \end{syntax} @@ -213,10 +215,10 @@ and the derived files duckuments.pdf, % for the use in \file{example-image-duck.tex} and % \file{example-image-duck-portrait.tex}. If the optional star is given, the % images will be drawn in portrait orientation else in landscape. -% \end{function}^^A<<< -%^^A<<< +% \end{function}^^A=<< +%^^A=<< % -% \subsection{Patches}^^A>>> +% \subsection{Patches}^^A>>= % % The package patches \cs{includegraphics} if \pkg{graphicx} is loaded at the % time the patch is applied (see \autoref{sec:keys}, |immediate|). The patch @@ -227,9 +229,9 @@ and the derived files duckuments.pdf, % % The patch is done so that one can use \pkg{tikzducks} ducks without the need % of loading \pkg{tikz} in a minimal working duckument as example images. -%^^A<<< +%^^A=<< % -% \subsection{Options}\label{sec:keys}^^A>>> +% \subsection{Options}\label{sec:keys}^^A>>= % % The package and commands which take a \oarg{key=value} accept the following % options. Some of which only make sense as package options. The @@ -271,12 +273,12 @@ and the derived files duckuments.pdf, % \num{1} starts with the paragraph after the last used paragraph, cycling back % to the first after the last available paragraph. % \egroup -%^^A<<< -%^^A<<< +%^^A=<< +%^^A=<< % -% \end{documentation}^^A<<< +% \end{documentation}^^A=<< % -% \begin{implementation}^^A>>> +% \begin{implementation}^^A>>= % % \section{Implementation} % @@ -288,38 +290,12 @@ and the derived files duckuments.pdf, %<@@=duckuments> % \end{macrocode} % -% \subsection{Check for possible problems}^^A>>> +% \subsection{Check for possible problems}^^A>>= % -% Check which engine is used. -% \begin{macrocode}^^A>>> -\bool_if:nF - { - \sys_if_engine_luatex_p: - || \sys_if_engine_pdftex_p: - || \sys_if_engine_xetex_p: - } - {%>>> - \msg_new:nnnn { duckuments } { incompatible } - { - The~duckuments~package~is~currently~only~compatible~with~pdfTeX,~ - LuaTeX,~and~XeTeX! - } - { - \ ~_____________________________\\ - \ (Quack!~Sorry~for~that.~Quack!)\\ - \ ~"""""""""""""""""""""""""""""\\ - \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ \ ~\ ~\ ~\ ~\string\ \\ - \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ \ ~\ ~\ ~\ ~\ ~>()_\\ - \ \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ \ ~\ ~\ ~\ ~\ ~\ ~(__)__ - } - \msg_error:nn { duckuments } { incompatible } - \endinput - }%<<< -% \end{macrocode}^^A<<< % Check whether \file{example-image-duck.pdf} exists. -% \begin{macrocode}^^A>>> +% \begin{macrocode}^^A>>= \file_if_exist:nF { example-image-duck.pdf } - {%>>> + {%>>= % \end{macrocode} % If the current \cs{jobname} doesn't match \file{example-image-duck} throw an % error. @@ -343,12 +319,12 @@ and the derived files duckuments.pdf, in~the~current~working~directory. } } - }%<<< -% \end{macrocode}^^A<<< + }%=<< +% \end{macrocode}^^A=<< % And do the same for \file{example-image-duck-portrait.pdf}. -% \begin{macrocode}^^A>>> +% \begin{macrocode}^^A>>= \file_if_exist:nF { example-image-duck-portrait.pdf } - {%>>> + {%>>= \str_if_eq:VnF \c_sys_jobname_str { example-image-duck-portrait } { \msg_if_exist:nnF { duckuments } { missing~file } @@ -371,106 +347,179 @@ and the derived files duckuments.pdf, in~the~current~working~directory. } } - }%<<< -% \end{macrocode}^^A<<< -%^^A<<< + }%=<< +% \end{macrocode}^^A=<< +%^^A=<< % -% \subsection{Variables}^^A>>> +% \subsection{Variables}^^A>>= % -% \begin{variable}{\duckuments@randoms}^^A>>> +% \begin{variable}{\duckuments@randoms}^^A>>= % Stores the number of random ducks in \file{example-image-duck.pdf}. % \begin{macrocode} \newcommand*\duckuments@randoms{128} % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\l_duckuments_immediate_bool}^^A>>> +% \begin{variable}{\l_duckuments_immediate_bool}^^A>>= % Stores whether the patch is to be done during package load time. % \begin{macrocode} \bool_new:N \l_duckuments_immediate_bool % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\l_duckuments_toc_bool}^^A>>> +% \begin{variable}{\l_duckuments_toc_bool}^^A>>= % Stores whether to display a ToC in \cs{duckument}. % \begin{macrocode} \bool_new:N \l_duckuments_toc_bool % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\l_duckuments_math_inline_bool}^^A>>> +% \begin{variable}{\l_duckuments_math_inline_bool}^^A>>= % Stores whether to display inline math in \cs{blindduck}. % \begin{macrocode} \bool_new:N \l_duckuments_math_inline_bool % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\l_duckuments_math_display_bool}^^A>>> +% \begin{variable}{\l_duckuments_math_display_bool}^^A>>= % Stores whether to display displayed math in \cs{blindduck}. % \begin{macrocode} \bool_new:N \l_duckuments_math_display_bool % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\l_duckuments_blindduck_pars_bool}^^A>>> +% \begin{variable}{\l_duckuments_blindduck_pars_bool}^^A>>= % Stores whether each paragraph of \cs{blindduck} should end with a \cs{par}. % \begin{macrocode} \bool_new:N \l_duckuments_blindduck_pars_bool % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\l_duckuments_range_seq}^^A>>> +% \begin{variable}{\l_duckuments_range_seq}^^A>>= % Stores the paragraphs range for \cs{blindduck}. % \begin{macrocode} \seq_new:N \l_duckuments_range_seq % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\g_duckuments_blindduck_start_int}^^A>>> +% \begin{variable}{\g_duckuments_blindduck_start_int}^^A>>= % Stores the paragraph with which \cs{blindduck} should start. % \begin{macrocode} \int_new:N \g_duckuments_blindduck_start_int \int_gset:Nn \g_duckuments_blindduck_start_int { \c_one_int } % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\g_duckuments_blindduck_end_int}^^A>>> +% \begin{variable}{\g_duckuments_blindduck_end_int}^^A>>= % Stores the paragraph with which \cs{blindduck} should end. % \begin{macrocode} \int_new:N \g_duckuments_blindduck_end_int % \end{macrocode} -% \end{variable}^^A<<< -%^^A<<< +% \end{variable}^^A=<< +%^^A=<< % -% \subsection{Constants}^^A>>> +% \subsection{Constants}^^A>>= % -% \begin{variable}{\c_duckuments_example_regex}^^A>>> +% \begin{variable}{\c_duckuments_example_regex}^^A>>= % Regex against which the patch of \cs{includegraphics} is testing. % \begin{macrocode} \regex_const:Nn \c_duckuments_example_regex { - example-image-duck + example-image-duck |example-image-duck.pdf |example-image-duck-portrait |example-image-duck-portrait.pdf } % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\c_duckuments_range_regex}^^A>>> +% \begin{variable}{\c_duckuments_range_regex}^^A>>= % Regex against which the optional range in \cs{blindduck} is checked. % \begin{macrocode} \regex_const:Nn \c_duckuments_range_regex { (\d+|\d+-|-\d+|\d+-\d+|-) } % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\c_duckuments_blindduck_pars_int}^^A>>> +% \begin{variable}{\c_duckuments_blindduck_pars_int}^^A>>= % \begin{macrocode} \int_const:Nn \c_duckuments_blindduck_pars_int { 5 } % \end{macrocode} -% \end{variable}^^A<<< +% \end{variable}^^A=<< % -% \begin{variable}{\c_duckuments_example_pages_int}^^A>>> +% \begin{variable}{\c_duckuments_example_pages_int}^^A>>= +% Define a macro that gets the page count of a PDF (this is engine dependent): +% \begin{macrocode} +\sys_if_engine_pdftex:T + { + \cs_new_protected:Npn \duckuments_set_to_pdf_page_count:Nn #1 #2 + { + \group_begin: + \pdfximage { #2 } + \exp_args:NNNo + \group_end: + \int_set:Nn #1 { \the \pdflastximagepages } + } + } +\sys_if_engine_luatex:T + { + \cs_new_protected:Npn \duckuments_set_to_pdf_page_count:Nn #1 #2 + { + \group_begin: + \saveimageresource { #2 } + \exp_args:NNNo + \group_end: + \int_set:Nn #1 { \lastsavedimageresourcepages } + } + } +\sys_if_engine_xetex:T + { + \cs_new_protected:Npn \duckuments_set_to_pdf_page_count:Nn #1 #2 + { + \int_set:Nn #1 { \XeTeXpdfpagecount " #2 " } + } + } +\bool_lazy_any:nTF + { + { \sys_if_engine_luatex_p: } + { \sys_if_engine_pdftex_p: } + { \sys_if_engine_xetex_p: } + } + { \if_false: } + { \if_true: } + \group_begin: + \char_set_catcode_other:N \% + \cs_new_protected:Npn \duckuments_set_to_pdf_page_count:Nn #1 #2 + { + \group_begin: + \char_set_catcode_other:N \% + \char_set_catcode_letter:N \: + \char_set_catcode_ignore:n { 32 } + \ior_shell_open:Nn \g_tmpa_ior { extractbb ~ -O ~ #2 } + \ior_map_inline:Nn \g_tmpa_ior + { + \__duckuments_set_to_pdf_page_count_aux_a:w ##1 %%Pages: \q_stop + } + \ior_close:N \g_tmpa_ior + \exp_args:NNNo + \group_end: + \int_set:Nn #1 { \int_use:N \l_tmpa_int } + } + \cs_new_protected:Npn \__duckuments_set_to_pdf_page_count_aux_a:w + #1 %%Pages: #2 \q_stop + { + \tl_if_empty:nT { #1 } + { \__duckuments_set_to_pdf_page_count_aux_b:w #2 \q_stop } + } + \cs_new_protected:Npn \__duckuments_set_to_pdf_page_count_aux_b:w + #1 %%Pages: \q_stop + { + \int_set:Nn \l_tmpa_int { #1 } + \ior_map_break: + } + \group_end: +\fi: +% \end{macrocode} +% Setting the constant: % \begin{macrocode} \bool_if:nTF { @@ -480,38 +529,21 @@ and the derived files duckuments.pdf, { \int_const:Nn \c_duckuments_example_pages_int { \c_one_int } } { \group_begin: - \sys_if_engine_pdftex:T - { - \pdfximage{example-image-duck.pdf} - \int_set:Nn \l_tmpa_int { \the\pdflastximagepages } - \pdfximage{example-image-duck-portrait.pdf} - \int_set:Nn \l_tmpb_int { \the\pdflastximagepages } - } - \sys_if_engine_luatex:T - { - \saveimageresource{example-image-duck.pdf} - \int_set:Nn \l_tmpa_int { \lastsavedimageresourcepages } - \saveimageresource{example-image-duck-portrait.pdf} - \int_set:Nn \l_tmpb_int { \lastsavedimageresourcepages } - } - \sys_if_engine_xetex:T - { - \int_set:Nn \l_tmpa_int - { \XeTeXpdfpagecount "example-image-duck.pdf" } - \int_set:Nn \l_tmpb_int - { \XeTeXpdfpagecount "example-image-duck-portrait.pdf" } - } + \duckuments_set_to_pdf_page_count:Nn \l_tmpa_int + { example-image-duck.pdf } + \duckuments_set_to_pdf_page_count:Nn \l_tmpb_int + { example-image-duck-portrait.pdf } \int_const:Nn \c_duckuments_example_pages_int { \int_min:nn { \l_tmpa_int } { \l_tmpb_int } } \group_end: } % \end{macrocode} -% \end{variable}^^A<<< -%^^A<<< +% \end{variable}^^A=<< +%^^A=<< % -% \subsection{Messages}^^A>>> +% \subsection{Messages}^^A>>= % -% \begin{macrocode}^^A duckuments option~unknown >>> +% \begin{macrocode}^^A duckuments option~unknown >>= \msg_new:nnnn { duckuments } { option~unknown } { Unknown~option~'#1'~for~package~duckuments. @@ -524,8 +556,8 @@ and the derived files duckuments.pdf, \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~>()_\\ \ \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~(__)__ } -% \end{macrocode}^^A<<< -% \begin{macrocode}^^A duckuments non-boolean~toc >>> +% \end{macrocode}^^A=<< +% \begin{macrocode}^^A duckuments non-boolean~toc >>= \msg_new:nnnn { duckuments } { non-boolean~toc } { A~non-boolean~value~`#1`~was~received~for~the~`toc`~option~during~package~ @@ -540,8 +572,8 @@ and the derived files duckuments.pdf, \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~>()_\\ \ \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~(__)__ } -% \end{macrocode}^^A<<< -% \begin{macrocode}^^A duckuments out~of~range >>> +% \end{macrocode}^^A=<< +% \begin{macrocode}^^A duckuments out~of~range >>= \msg_new:nnnn { duckuments } { out~of~range } { You~requested~element~#3~out~of~the~range~#1~to~#2~of~array~'#4'.\\ @@ -555,12 +587,12 @@ and the derived files duckuments.pdf, \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~>()_\\ \ \ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~\ ~(__)__ } -% \end{macrocode}^^A<<< +% \end{macrocode}^^A=<< % -% \begin{macro}{\duckuments_patch_see_duckumentation:}^^A>>> +% \begin{macro}{\duckuments_patch_see_duckumentation:}^^A>>= % \begin{macrocode} \cs_new:Npn \duckuments_patch_see_duckumentation: - {%>>> + {%>>= \cs_set:Nn \msg_see_documentation_text:n { \\\\ @@ -570,16 +602,16 @@ and the derived files duckuments.pdf, documentation }~for~further~information. } - }%<<< + }%=<< \duckuments_patch_see_duckumentation: % \end{macrocode} -% \end{macro}^^A<<< -%^^A<<< +% \end{macro}^^A=<< +%^^A=<< % -% \subsection{Options and Configurations}^^A>>> +% \subsection{Options and Configurations}^^A>>= % \begin{macrocode} \keys_define:nn { duckuments } - {%>>> + {%>>= ,immediate .bool_set:N = \l_duckuments_immediate_bool ,immediate .default:n = true ,full .code:n = @@ -613,29 +645,29 @@ and the derived files duckuments.pdf, ,toc .default:n = true ,unknown .code:n = { \msg_error:nnx { duckuments } { option~unknown } { \l_keys_key_tl } } - }%<<< + }%=<< \ProcessKeysOptions { duckuments } \keys_define:nn { duckuments } - {%>>> + {%>>= ,toc .undefine: ,toc .bool_set:N = \l_duckuments_toc_bool ,toc .default:n = true ,unknown .code:n = \duckuments_blindduck_range_test:V \l_keys_key_tl - }%<<< + }%=<< \bool_if:NTF \l_duckuments_immediate_bool { \AtEndOfPackage { \duckuments_patch_includegraphics: } } { \AtBeginDocument { \duckuments_patch_includegraphics: } } % \end{macrocode} -%^^A<<< +%^^A=<< % -% \subsection{Functions}^^A>>> +% \subsection{Functions}^^A>>= % -% \subsubsection{Duckument Level}^^A>>> +% \subsubsection{Duckument Level}^^A>>= % -% \begin{macro}{\duckument}^^A>>> +% \begin{macro}{\duckument}^^A>>= % \begin{macrocode} \NewDocumentCommand \duckument { O{} } - {%>>> + {%>>= \group_begin: \keys_set:nn { duckuments } { #1 } \bool_if:NT \l_duckuments_toc_bool { \tableofcontents } @@ -650,27 +682,27 @@ and the derived files duckuments.pdf, \duckuments_list_example:n { enumerate } \duckuments_list_example:n { description } \group_end: - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\blindduck}^^A>>> +% \begin{macro}{\blindduck}^^A>>= % \begin{macrocode} \NewDocumentCommand \blindduck { O{} } - {%>>> + {%>>= \group_begin: \keys_set:nn { duckuments } { #1 } \duckuments@blindduck@text \bool_if:NT \l_duckuments_blindduck_pars_bool { \par } \group_end: - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\ducklist}^^A>>> +% \begin{macro}{\ducklist}^^A>>= % \begin{macrocode} \NewDocumentCommand \ducklist {s m} - {%>>> + {%>>= \begin{#2} \IfBooleanTF { #1 } {\ducklists@content@starred} @@ -680,13 +712,13 @@ and the derived files duckuments.pdf, \ducklists@content } \end{#2} - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< -% \begin{macro}{\ducklistlist}^^A>>> +% \end{macro}^^A=<< +% \begin{macro}{\ducklistlist}^^A>>= % \begin{macrocode} \NewDocumentCommand \ducklistlist { s m } - {%>>> + {%>>= \IfBooleanTF { #1 } { \duckuments@listlist@starred { #2 } } { @@ -694,31 +726,31 @@ and the derived files duckuments.pdf, { \duckuments@listlist@starred { description } } { \duckuments@listlist{#2} } } - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckenumerate}^^A>>> +% \begin{macro}{\duckenumerate}^^A>>= % \begin{macrocode} \newcommand*\duckenumerate{\ducklist{enumerate}} % \end{macrocode} -% \end{macro}^^A<<< -% \begin{macro}{\duckitemize}^^A>>> +% \end{macro}^^A=<< +% \begin{macro}{\duckitemize}^^A>>= % \begin{macrocode} \newcommand*\duckitemize{\ducklist{itemize}} % \end{macrocode} -% \end{macro}^^A<<< -% \begin{macro}{\duckdescription}^^A>>> +% \end{macro}^^A=<< +% \begin{macro}{\duckdescription}^^A>>= % \begin{macrocode} \newcommand*\duckdescription{\ducklist{description}} % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckumentsCreateExampleFiles}^^A>>> +% \begin{macro}{\duckumentsCreateExampleFiles}^^A>>= % Create example-image-duck.tex % \begin{macrocode} \newcommand*\duckumentsCreateExampleFiles - {%>>> + {%>>= \iow_new:N \duckuments_example_file_iow \iow_open:Nn \duckuments_example_file_iow { example-image-duck.tex } \iow_now:Nn \duckuments_example_file_iow @@ -752,27 +784,27 @@ and the derived files duckuments.pdf, \iow_now:Nn \duckuments_example_file_iow { \end{document} } \iow_close:N \duckuments_example_file_iow - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< -% \begin{macro}{\duckumentsDrawRandomDucks}^^A>>> +% \end{macro}^^A=<< +% \begin{macro}{\duckumentsDrawRandomDucks}^^A>>= % \begin{macrocode} \newcommand*\duckumentsDrawRandomDucks - {%>>> + {%>>= \@ifstar {\duckumentsDrawRandomDucks@portrait} {\duckumentsDrawRandomDucks@landscape}% - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< -%^^A<<< +% \end{macro}^^A=<< +%^^A=<< % -% \subsubsection{Intern}^^A>>> +% \subsubsection{Intern}^^A>>= % -% \begin{macro}{\duckuments@headings}^^A>>> +% \begin{macro}{\duckuments@headings}^^A>>= % \begin{macrocode} \newcommand*\duckuments@headings[1] - {%>>> + {%>>= \ifcase#1\relax \expandafter\chapter \or \expandafter\section @@ -782,14 +814,14 @@ and the derived files duckuments.pdf, \else \expandafter\@gobble \fi {\duckuments@headings@text{#1}} - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments@headings@level}^^A>>> +% \begin{macro}{\duckuments@headings@level}^^A>>= % \begin{macrocode} \newcommand*\duckuments@headings@level[1] - {%>>> + {%>>= ( \ifcase#1 chapter @@ -799,40 +831,40 @@ and the derived files duckuments.pdf, \or paragraph \fi ) - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments@ifinline}^^A>>> +% \begin{macro}{\duckuments@ifinline}^^A>>= % \begin{macrocode} \newcommand*\duckuments@ifinline[2][] { \bool_if:NTF \l_duckuments_math_inline_bool { #2 } { #1 } } % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments@ifdisplay}^^A>>> +% \begin{macro}{\duckuments@ifdisplay}^^A>>= % \begin{macrocode} \newcommand*\duckuments@ifdisplay[2][] { \bool_if:NTF \l_duckuments_math_display_bool { #2 } { #1 } } % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_list_example:n}^^A>>> +% \begin{macro}{\duckuments_list_example:n}^^A>>= % \begin{macrocode} \cs_new_protected_nopar:Npn \duckuments_list_example:n #1 - {%>>> + {%>>= \subsection{Example\ for\ ducks\ (#1)} \ducklist { #1 } \subsubsection{Nested\ ducks} \ducklistlist { #1 } - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments@enquote}^^A>>> +% \begin{macro}{\duckuments@enquote}^^A>>= % \begin{macrocode} \NewDocumentCommand \duckuments@enquote { s +m } - {%>>> + {%>>= \IfBooleanTF { #1 } { \cs_if_exist_use:NTF @@ -844,34 +876,34 @@ and the derived files duckuments.pdf, \enquote { { #2 } } {``#2''} } - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckumentsDrawRandomDucks@landscape}^^A>>> +% \begin{macro}{\duckumentsDrawRandomDucks@landscape}^^A>>= % \begin{macrocode} \newcommand*\duckumentsDrawRandomDucks@landscape[1][\duckuments@randoms] - {%>>> + {%>>= \foreach\x in {1,2,...,#1} {\duckumentsDrawRandomDucks@draw{6.47214}{4}{3.23607}{2}} - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckumentsDrawRandomDucks@portrait}^^A>>> +% \begin{macro}{\duckumentsDrawRandomDucks@portrait}^^A>>= % \begin{macrocode} \newcommand*\duckumentsDrawRandomDucks@portrait[1][\duckuments@randoms] - {%>>> + {%>>= \foreach\x in {1,2,...,#1} {\duckumentsDrawRandomDucks@draw{1.8541}{3}{.92705}{1.5}} - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckumentsDrawRandomDucks@draw}^^A>>> +% \begin{macro}{\duckumentsDrawRandomDucks@draw}^^A>>= % \begin{macrocode} \newcommand*\duckumentsDrawRandomDucks@draw[4] - {%>>> + {%>>= \begin{tikzpicture} \draw[fill=gray!50,use~as~bounding~box] (0,0) rectangle (#1,#2); \draw[gray,thin] (0,0) -- (#1,#2); @@ -881,14 +913,14 @@ and the derived files duckuments.pdf, \node at (#3,#4) {\tikz\randuck;}; \draw[black] (0,0) rectangle (#1,#2); \end{tikzpicture} - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_patch_includegraphics:}^^A>>> +% \begin{macro}{\duckuments_patch_includegraphics:}^^A>>= % \begin{macrocode} \cs_new_protected_nopar:Npn \duckuments_patch_includegraphics: - {%>>> + {%>>= \@ifpackageloaded { graphicx } { \LetLtxMacro\duckuments@includegraphicsBAK\includegraphics @@ -911,14 +943,14 @@ and the derived files duckuments.pdf, } } {} - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_blindduck_range_test:n}^^A>>> +% \begin{macro}{\duckuments_blindduck_range_test:n}^^A>>= % \begin{macrocode} \cs_new_protected:Npn \duckuments_blindduck_range_test:n #1 - {%>>> + {%>>= \regex_match:NnTF \c_duckuments_range_regex { #1 } { \seq_set_split:Nnn \l_duckuments_range_seq { - } { #1 } @@ -960,40 +992,40 @@ and the derived files duckuments.pdf, \exp_args:NnnV \msg_error:nnn { duckuments } { option~unknown } \l_keys_key_tl } - }%<<< + }%=<< \cs_generate_variant:Nn \duckuments_blindduck_range_test:n { V } % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_blindduck_set_text:nn}^^A>>> +% \begin{macro}{\duckuments_blindduck_set_text:nn}^^A>>= % \begin{macrocode} \cs_new:Npn \duckuments_blindduck_set_text:nn #1 #2 - {%>>> + {%>>= \def \duckuments@blindduck@text { \int_step_function:nnnN { #1 } { \c_one_int } { #2 } \duckuments_blindduck_par_loop:n \duckuments_blindduck_set_next_start:n { #2 } } - }%<<< + }%=<< \cs_generate_variant:Nn \duckuments_blindduck_set_text:nn { xx } % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_blindduck_set_next_start:n}^^A>>> +% \begin{macro}{\duckuments_blindduck_set_next_start:n}^^A>>= % \begin{macrocode} \cs_new:Npn \duckuments_blindduck_set_next_start:n #1 - {%>>> + {%>>= \int_gset:Nn \g_duckuments_blindduck_start_int { \int_mod:nn { #1 } { \c_duckuments_blindduck_pars_int } + \c_one_int } - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_blindduck_single_par:n}^^A>>> +% \begin{macro}{\duckuments_blindduck_single_par:n}^^A>>= % \begin{macrocode} \cs_new:Npn \duckuments_blindduck_single_par:n #1 - {%>>> + {%>>= \bool_if:nTF { \int_compare_p:nNn { #1 } > { \c_duckuments_blindduck_pars_int } @@ -1008,47 +1040,47 @@ and the derived files duckuments.pdf, { \use:c { duckuments@blindduck@text@ \int_to_roman:n { #1 } } } - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_blindduck_par_loop:n}^^A>>> +% \begin{macro}{\duckuments_blindduck_par_loop:n}^^A>>= % \begin{macrocode} \cs_new:Npn \duckuments_blindduck_par_loop:n #1 - {%>>> + {%>>= \duckuments_blindduck_single_par:n { #1 } \par - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_starred:n}^^A>>> +% \begin{macro}{\duckuments_starred:n}^^A>>= % \begin{macrocode} \cs_new_protected:Npn \duckuments_starred:n #1 - {%>>> + {%>>= \IfBooleanTF { #1 } { \def\ProcessedArgument{*} } { \def\ProcessedArgument{} } - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments_random_page:}^^A>>> +% \begin{macro}{\duckuments_random_page:}^^A>>= % \begin{macrocode} \cs_new:Npn \duckuments_random_page: { \int_rand:n { \c_duckuments_example_pages_int } } % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % % \begin{macrocode} \ExplSyntaxOff % \end{macrocode} % -% \begin{macro}{\duckuments@blindduck@text}^^A>>> +% \begin{macro}{\duckuments@blindduck@text}^^A>>= % \begin{macrocode} \newcommand*\duckuments@blindduck@text{\duckuments@blindduck@text@i} \newcommand*\duckuments@blindduck@text@i - {%>>> + {%>>= There once was a very smart but sadly blind duck. When it was still a small duckling it was renowned for its good vision. But sadly as the duck grew older it caught a sickness which caused its eyesight to worsen. It became so @@ -1060,26 +1092,26 @@ and the derived files duckuments.pdf, do its research any longer. It called for its underduckling and said: \duckuments@enquote{Go, find me the best eye ducktor there is. He shall heal me from my disease!}% - }%<<< + }%=<< \newcommand*\duckuments@blindduck@text@ii - {%>>> + {%>>= \duckuments@enquote{But my duck, how are you supposed to manage your daily routines without my visual guidance}, replied the underduckling. The smart duck's face turned grim in anger. \duckuments@enquote{You dare to talk back?} The underduckling blushed ashamed. How could he have objections after his duck gave strict orders? The underduckling was so embarrassed about his own behaviour he had to solve an equation.% - }%<<< + }%=<< \newcommand*\duckuments@blindduck@text@iii - {%>>> + {%>>= After the equation was solved and the underduckling prepared his leave for the next day it fell asleep in a shaky mood. It did not know what the journey had prepared for him and if he was prepared enough for it. His sleep was restless. The dreams he had that night were not calm and bright as they used to be for an innocent underduckling.% - }%<<< + }%=<< \newcommand*\duckuments@blindduck@text@iv - {%>>> + {%>>= Before dawn the underduckling woke. He didn't have the feeling of being well rested. But nonetheless he knew that this was the day he should leave. Except saying goodbye to his beloved ones there was nothing holding him @@ -1087,54 +1119,54 @@ and the derived files duckuments.pdf, inexperienced underduckling was ever sent on. He bid farewell to his mother, all his brothers and sisters, and finally from his duck. The bag was shouldered, the boots were tied, the underduckling left.% - }%<<< + }%=<< \newcommand*\duckuments@blindduck@text@v - {%>>> + {%>>= As the underduckling went along he saw a tree. It was so tall he couldn't even approximate its height. Oh, how small he felt. What should he, a small duckling whose plumage was still fluffy, achieve in this vast, gigantic world? He stuck his trembling wings under the straps of his backpack to calm his shaking limbs. Where should he start his search? How should he survive in the hostile nature surrounding the sheltered pond of his community? - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments@headings@text}^^A>>> +% \begin{macro}{\duckuments@headings@text}^^A>>= % \begin{macrocode} \newcommand*\duckuments@headings@text[1] {A friendly duck at level #1 \duckuments@headings@level{#1}} % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\ducklists@content}^^A>>> +% \begin{macro}{\ducklists@content}^^A>>= % \begin{macrocode} \newcommand*\ducklists@content - {%>>> + {%>>= \item First swims father drake \item Then floats mother duck \item After her paddles baby duckling \item And over there bathes uncle canard - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\ducklists@content@starred}^^A>>> +% \begin{macro}{\ducklists@content@starred}^^A>>= % \begin{macrocode} \newcommand*\ducklists@content@starred - {%>>> + {%>>= \item[drake] is the swimming father \item[duck] is the floating mother \item[duckling] is the paddling baby \item[canard] is the bathing uncle - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments@listlist}^^A>>> +% \begin{macro}{\duckuments@listlist}^^A>>= % \begin{macrocode} \newcommand*\duckuments@listlist[1] - {%>>> + {%>>= \begin{#1} \item swimming father drake \begin{#1} @@ -1151,14 +1183,14 @@ and the derived files duckuments.pdf, \end{#1} \item floating mother duck \end{#1}% - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< +% \end{macro}^^A=<< % -% \begin{macro}{\duckuments@listlist@starred}^^A>>> +% \begin{macro}{\duckuments@listlist@starred}^^A>>= % \begin{macrocode} \newcommand*\duckuments@listlist@starred[1] - {%>>> + {%>>= \begin{#1} \item[drake] is the swimming father \begin{#1} @@ -1175,30 +1207,30 @@ and the derived files duckuments.pdf, \end{#1} \item[duck] is the floating mother \end{#1}% - }%<<< + }%=<< % \end{macrocode} -% \end{macro}^^A<<< -%^^A<<< -%^^A<<< +% \end{macro}^^A=<< +%^^A=<< +%^^A=<< % % \begin{macrocode} \endinput % \end{macrocode} % -% \end{implementation}^^A<<< +% \end{implementation}^^A=<< % % \begin{macrocode} %</pkg> % \end{macrocode} % % \clearpage -% \section{The story of the duck}^^A>>> +% \section{The story of the duck}^^A>>= % % \bgroup % \ExplSyntaxOn % \newcount\duckuments_count_for_duckumentation_only % \cs_set:Nn \duckuments_blindduck_par_loop:n -% {^^A>>> +% {^^A>>= % \advance\duckuments_count_for_duckumentation_only1 % \llap % { @@ -1221,10 +1253,10 @@ and the derived files duckuments.pdf, % \vspace{-\baselineskip} % \duckuments_blindduck_single_par:n { #1 } % \par -% }^^A<<< +% }^^A=<< % \ExplSyntaxOff % \blindduck[full] -% \egroup^^A<<< +% \egroup^^A=<< % % -^^A vim: fdm=marker foldmarker=>>>,<<< +^^A vim: fdm=marker foldmarker=>>=,=<< diff --git a/macros/latex/contrib/duckuments/duckuments.pdf b/macros/latex/contrib/duckuments/duckuments.pdf Binary files differindex 02bce56712..72686220bc 100644 --- a/macros/latex/contrib/duckuments/duckuments.pdf +++ b/macros/latex/contrib/duckuments/duckuments.pdf diff --git a/macros/latex/contrib/duckuments/example-image-duck-portrait.pdf b/macros/latex/contrib/duckuments/example-image-duck-portrait.pdf Binary files differindex ef895dbf68..0371f86663 100644 --- a/macros/latex/contrib/duckuments/example-image-duck-portrait.pdf +++ b/macros/latex/contrib/duckuments/example-image-duck-portrait.pdf diff --git a/macros/latex/contrib/duckuments/example-image-duck.pdf b/macros/latex/contrib/duckuments/example-image-duck.pdf Binary files differindex 78924c0120..f6e7c99ed6 100644 --- a/macros/latex/contrib/duckuments/example-image-duck.pdf +++ b/macros/latex/contrib/duckuments/example-image-duck.pdf diff --git a/macros/latex/contrib/filehook/filehook.dtx b/macros/latex/contrib/filehook/filehook.dtx index 3db7301e64..efaeb3d5a8 100644 --- a/macros/latex/contrib/filehook/filehook.dtx +++ b/macros/latex/contrib/filehook/filehook.dtx @@ -26,10 +26,10 @@ %<*driver> \ProvidesFile{filehook.dtx}[% %<=*DATE> - 2019/08/19 + 2019/10/03 %<=/DATE> %<=*VERSION> - v0.5e + v0.6 %<=/VERSION> Hooks for input files] \documentclass{ydoc} @@ -55,7 +55,7 @@ %</driver> % \fi % -% \CheckSum{1051} +% \CheckSum{1093} % % \CharacterTable % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z @@ -95,6 +95,8 @@ % \changes{v0.5b}{2011/07/18}{Replaced \cs{@nameuse} for use with eTeX code to avoid the definition of non-existing hooks to \cs{relax}.} % \changes{v0.5c}{2011/10/07}{Added fall-back code for non-eTeX compilers.} % \changes{v0.5d}{2011/10/12}{Fix for fall-back code.} +% \changes{v0.5e}{2019/08/19}{Fix for new LaTeX format.} +% \changes{v0.6}{2019/10/03}{Fix for InputIfFileExists for LaTeX format 2019/10/01.} % % \GetFileInfo{filehook.dtx} % @@ -1106,39 +1108,28 @@ % This is always done inside a group to keep them temporary only. % The token register is used to avoid doubling of macro argument characters. % -% \begin{macro}{\oldlatex@InputIfFileExists} -% Original standard \LaTeX\ definition of \Macro\InputIfFileExists. % \begin{macrocode} -\long\def\oldlatex@InputIfFileExists#1#2{% - \IfFileExists{#1}% - {#2\@addtofilelist{#1}% - \@@input\@filef@und - }% -} +\newif\iffilehook@newfmt +\@ifl@t@r\fmtversion{2019/10/01}{\filehook@newfmttrue}{\filehook@newfmtfalse} % \end{macrocode} -% \end{macro} -% % % \begin{macro}{\latex@InputIfFileExists} -% Standard \`LaTeX\ definition of \Macro\InputIfFileExists starting from LaTeX Kernal 2019/02/07 v1.1n. +% Standard \LaTeX\ definition of \Macro\InputIfFileExists. % \begin{macrocode} -\long\def\newlatex@InputIfFileExists#1#2{% +\iffilehook@newfmt +\DeclareRobustCommand \latex@InputIfFileExists[2]{% \IfFileExists{#1}% {% \expandafter\@swaptwoargs\expandafter {\@filef@und}{#2\@addtofilelist{#1}\@@input}}} -% \end{macrocode} -% \end{macro} -% -% -% \begin{macro}{\latex@InputIfFileExists} -% Standard \`LaTeX\ definition of \Macro\InputIfFileExists starting from LaTeX Kernal 2019/02/07 v1.1n. -% \begin{macrocode} -\@ifundefined{@swaptwoargs}{% - \let\latex@InputIfFileExists\oldlatex@InputIfFileExists -}{% - \let\latex@InputIfFileExists\newlatex@InputIfFileExists -}% +\else +\long\def\latex@InputIfFileExists#1#2{% + \IfFileExists{#1}% + {#2\@addtofilelist{#1}% + \@@input\@filef@und + }% +} +\fi % \end{macrocode} % \end{macro} % @@ -1300,40 +1291,57 @@ \RequirePackage{filehook-memoir}% }% % \end{macrocode} -% % Finally, if no specific alternate definition is detected the original \LaTeX\ definition is checked for and a % error is given if any other unknown definition is detected. % The \opt{force} option will change the error into a warning and overwrite the macro with the default. % \begin{macrocode} -\ifcase - \ifx\InputIfFileExists\filehook@InputIfFileExists 0\else - \ifx\InputIfFileExists\newlatex@InputIfFileExists 1\else - \ifx\InputIfFileExists\oldlatex@InputIfFileExists 1\else - 9% - \fi\fi\fi +\def\@tempa{9}% +\ifx\InputIfFileExists\filehook@InputIfFileExists + \def\@tempa{0}% +\else + \iffilehook@force + \def\@tempa{1}% + \else + \iffilehook@newfmt + % check if both the robust \InputIfFileExist and its internal macro match the default LaTeX definition + \edef\@tempb{\noexpand\protect\expandafter\noexpand\csname InputIfFileExists\space\endcsname}% + \ifx\InputIfFileExists\@tempb + \expandafter\ifx\csname InputIfFileExists\space\expandafter\endcsname\csname latex@InputIfFileExists\space\endcsname + \def\@tempa{1}% + \fi + \fi + \else\ifx\InputIfFileExists\latex@InputIfFileExists + \def\@tempa{1}% + \fi\fi + \fi +\fi +% +\ifcase\@tempa \relax% 0 \or% 1 \let\filehook@InputIfFileExists\filehook@default@InputIfFileExists \let\filehook@@InputIfFileExists\filehook@@default@InputIfFileExists - \let\InputIfFileExists\filehook@InputIfFileExists -\else + \iffilehook@newfmt + \expandafter\let\csname InputIfFileExists\space\endcsname\filehook@InputIfFileExists + \else + \let\InputIfFileExists\filehook@InputIfFileExists + \fi \iffilehook@force - \let\filehook@InputIfFileExists\filehook@default@InputIfFileExists - \let\filehook@@InputIfFileExists\filehook@@default@InputIfFileExists - \let\InputIfFileExists\filehook@InputIfFileExists \PackageWarning{filehook}{Detected unknown definition of \string\InputIfFileExists.^^J% The 'force' option of 'filehook' is in effect. Macro is overwritten with default!}% - \else - \PackageError{filehook}{Detected unknown definition of \string\InputIfFileExists.^^J% - Use the 'force' option of 'filehook' to overwrite it.}{}% \fi +\else + \PackageError{filehook}{Detected unknown definition of \string\InputIfFileExists.^^J% + Use the 'force' option of 'filehook' to overwrite it.}{}% \fi % \end{macrocode} % \end{macro} % % \begin{macrocode} \AtBeginDocument{% - \ifx\InputIfFileExists\filehook@InputIfFileExists\else + % Check if definition got changed again. For the new LaTeX format we check again \InputIfFileExists<space>, + % for the old format to \InputIfFileExists directly. + \expandafter\ifx\csname InputIfFileExists\iffilehook@newfmt\space\fi\endcsname\filehook@InputIfFileExists\else \PackageWarning{filehook}{Macro \string\InputIfFileExists\space got redefined after 'filehook' was loaded.^^J% Certain file hooks might now be dysfunctional!} \fi diff --git a/macros/latex/contrib/filehook/filehook.pdf b/macros/latex/contrib/filehook/filehook.pdf Binary files differindex c63846379a..ce6afd430f 100644 --- a/macros/latex/contrib/filehook/filehook.pdf +++ b/macros/latex/contrib/filehook/filehook.pdf diff --git a/macros/latex/contrib/knowledge/README.md b/macros/latex/contrib/knowledge/README.md index ca7c328591..f67514e9ae 100644 --- a/macros/latex/contrib/knowledge/README.md +++ b/macros/latex/contrib/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/macros/latex/contrib/knowledge/knowledge-code.dtx b/macros/latex/contrib/knowledge/knowledge-code.dtx index 22bb364790..6f0c693028 100644 --- a/macros/latex/contrib/knowledge/knowledge-code.dtx +++ b/macros/latex/contrib/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/macros/latex/contrib/knowledge/knowledge-utils.dtx b/macros/latex/contrib/knowledge/knowledge-utils.dtx index af2d372a40..dc0f0deed7 100644 --- a/macros/latex/contrib/knowledge/knowledge-utils.dtx +++ b/macros/latex/contrib/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/macros/latex/contrib/knowledge/knowledge.pdf b/macros/latex/contrib/knowledge/knowledge.pdf Binary files differindex ebf4ac86a1..cc7bc26835 100644 --- a/macros/latex/contrib/knowledge/knowledge.pdf +++ b/macros/latex/contrib/knowledge/knowledge.pdf diff --git a/macros/latex/contrib/knowledge/knowledge.tex b/macros/latex/contrib/knowledge/knowledge.tex index fb3f98f009..642cb98a85 100644 --- a/macros/latex/contrib/knowledge/knowledge.tex +++ b/macros/latex/contrib/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/macros/latex/contrib/l3kernel/CHANGELOG.md b/macros/latex/contrib/l3kernel/CHANGELOG.md index 8196a8b410..ba11c32453 100644 --- a/macros/latex/contrib/l3kernel/CHANGELOG.md +++ b/macros/latex/contrib/l3kernel/CHANGELOG.md @@ -7,8 +7,18 @@ this project uses date-based 'snapshot' version identifiers. ## [Unreleased] +## [2019-10-02] + +### Fixed + +- Variants using `\exp_args` functions with more than 9 arguments (see #636) + ## [2019-09-30] +### Fixed + +- File searching using `\file_full_name:n` (see #634) + ## [2019-09-28] ### Changed @@ -529,7 +539,8 @@ this project uses date-based 'snapshot' version identifiers. - Step funcÂtions have been added for dim variÂables, e.g. `\dim_step_inÂline:nnnn` -[Unreleased]: https://github.com/latex3/latex3/compare/2019-09-30...HEAD +[Unreleased]: https://github.com/latex3/latex3/compare/2019-10-02...HEAD +[2019-10-02]: https://github.com/latex3/latex3/compare/2019-09-30...2019-10-02 [2019-09-30]: https://github.com/latex3/latex3/compare/2019-09-28...2019-09-30 [2019-09-28]: https://github.com/latex3/latex3/compare/2019-09-19...2019-09-28 [2019-09-19]: https://github.com/latex3/latex3/compare/2019-09-08...2019-09-19 diff --git a/macros/latex/contrib/l3kernel/README.md b/macros/latex/contrib/l3kernel/README.md index 8a0d11f63f..1d0566362a 100644 --- a/macros/latex/contrib/l3kernel/README.md +++ b/macros/latex/contrib/l3kernel/README.md @@ -1,7 +1,7 @@ LaTeX3 Programming Conventions ============================== -Release 2019-09-30 +Release 2019-10-02 Overview -------- diff --git a/macros/latex/contrib/l3kernel/expl3.dtx b/macros/latex/contrib/l3kernel/expl3.dtx index a311b7e3eb..7dfc70847b 100644 --- a/macros/latex/contrib/l3kernel/expl3.dtx +++ b/macros/latex/contrib/l3kernel/expl3.dtx @@ -23,7 +23,7 @@ % for those people who are interested. % %<*driver|generic|package> -\def\ExplFileDate{2019-09-30}% +\def\ExplFileDate{2019-10-02}% %</driver|generic|package> %<*driver> \documentclass[full]{l3doc} @@ -51,7 +51,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/expl3.pdf b/macros/latex/contrib/l3kernel/expl3.pdf Binary files differindex 8c789f813a..f3575a7c4e 100644 --- a/macros/latex/contrib/l3kernel/expl3.pdf +++ b/macros/latex/contrib/l3kernel/expl3.pdf diff --git a/macros/latex/contrib/l3kernel/interface3.pdf b/macros/latex/contrib/l3kernel/interface3.pdf Binary files differindex e7883a270c..b76f488d91 100644 --- a/macros/latex/contrib/l3kernel/interface3.pdf +++ b/macros/latex/contrib/l3kernel/interface3.pdf diff --git a/macros/latex/contrib/l3kernel/interface3.tex b/macros/latex/contrib/l3kernel/interface3.tex index a7469bf2ed..bfbfc02047 100644 --- a/macros/latex/contrib/l3kernel/interface3.tex +++ b/macros/latex/contrib/l3kernel/interface3.tex @@ -54,7 +54,7 @@ for those people who are interested. {latex-team@latex-project.org}% }% } -\date{Released 2019-09-30} +\date{Released 2019-10-02} \pagenumbering{roman} \maketitle diff --git a/macros/latex/contrib/l3kernel/l3alloc.dtx b/macros/latex/contrib/l3kernel/l3alloc.dtx index 0600b35399..7288e1b72a 100644 --- a/macros/latex/contrib/l3kernel/l3alloc.dtx +++ b/macros/latex/contrib/l3kernel/l3alloc.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3basics.dtx b/macros/latex/contrib/l3kernel/l3basics.dtx index 908aa45fdd..a6b92aff81 100644 --- a/macros/latex/contrib/l3kernel/l3basics.dtx +++ b/macros/latex/contrib/l3kernel/l3basics.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3bootstrap.dtx b/macros/latex/contrib/l3kernel/l3bootstrap.dtx index 6d6a3996d8..7f8da0b60b 100644 --- a/macros/latex/contrib/l3kernel/l3bootstrap.dtx +++ b/macros/latex/contrib/l3kernel/l3bootstrap.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3box.dtx b/macros/latex/contrib/l3kernel/l3box.dtx index 46c94babd2..f44b622fcd 100644 --- a/macros/latex/contrib/l3kernel/l3box.dtx +++ b/macros/latex/contrib/l3kernel/l3box.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3candidates.dtx b/macros/latex/contrib/l3kernel/l3candidates.dtx index e443aa27c4..6f50651ed8 100644 --- a/macros/latex/contrib/l3kernel/l3candidates.dtx +++ b/macros/latex/contrib/l3kernel/l3candidates.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3clist.dtx b/macros/latex/contrib/l3kernel/l3clist.dtx index 666b00f261..69e2fe6729 100644 --- a/macros/latex/contrib/l3kernel/l3clist.dtx +++ b/macros/latex/contrib/l3kernel/l3clist.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3coffins.dtx b/macros/latex/contrib/l3kernel/l3coffins.dtx index 92478082eb..916953285d 100644 --- a/macros/latex/contrib/l3kernel/l3coffins.dtx +++ b/macros/latex/contrib/l3kernel/l3coffins.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3color-base.dtx b/macros/latex/contrib/l3kernel/l3color-base.dtx index adde016182..d1ac9bdad4 100644 --- a/macros/latex/contrib/l3kernel/l3color-base.dtx +++ b/macros/latex/contrib/l3kernel/l3color-base.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3debug.dtx b/macros/latex/contrib/l3kernel/l3debug.dtx index 6d423a94ee..ab64345a3f 100644 --- a/macros/latex/contrib/l3kernel/l3debug.dtx +++ b/macros/latex/contrib/l3kernel/l3debug.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3deprecation.dtx b/macros/latex/contrib/l3kernel/l3deprecation.dtx index 56f2ac701d..c00c7f33cb 100644 --- a/macros/latex/contrib/l3kernel/l3deprecation.dtx +++ b/macros/latex/contrib/l3kernel/l3deprecation.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3doc.dtx b/macros/latex/contrib/l3kernel/l3doc.dtx index 050b192a16..c5df660008 100644 --- a/macros/latex/contrib/l3kernel/l3doc.dtx +++ b/macros/latex/contrib/l3kernel/l3doc.dtx @@ -79,7 +79,7 @@ and all files in that bundle must be distributed together. % % \title{The \cls{l3doc} class} % \author{\Team} -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % \maketitle % \tableofcontents % diff --git a/macros/latex/contrib/l3kernel/l3docstrip.dtx b/macros/latex/contrib/l3kernel/l3docstrip.dtx index a88fa12e46..b9c13c4ef8 100644 --- a/macros/latex/contrib/l3kernel/l3docstrip.dtx +++ b/macros/latex/contrib/l3kernel/l3docstrip.dtx @@ -63,7 +63,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3docstrip.pdf b/macros/latex/contrib/l3kernel/l3docstrip.pdf Binary files differindex fb042e2af1..9d18617c80 100644 --- a/macros/latex/contrib/l3kernel/l3docstrip.pdf +++ b/macros/latex/contrib/l3kernel/l3docstrip.pdf diff --git a/macros/latex/contrib/l3kernel/l3expan.dtx b/macros/latex/contrib/l3kernel/l3expan.dtx index 06c78048ad..fe85c98bd5 100644 --- a/macros/latex/contrib/l3kernel/l3expan.dtx +++ b/macros/latex/contrib/l3kernel/l3expan.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % @@ -2556,7 +2556,8 @@ % \cs{cs_new_protected:cpn} \cs{use:x} (for protected) or % \cs{cs_new:cpn} \cs{tex_expanded:D} (expandable) and the signature. If |p| % appears in the signature, or if the function to be defined is -% expandable and the primitive \tn{expanded} is not available, call +% expandable and the primitive \tn{expanded} is not available, or if there +% are more than $8$ arguments, call % some fall-back code that just puts the appropriate |\::| commands. % Otherwise, call \cs{@@_generate_internal_one_go:NNn} to construct % the \cs[no-index]{exp_args:N\dots} function as a macro taking up to @@ -2588,7 +2589,15 @@ { \cs_new_protected:Npn \@@_generate_internal_variant:NNn ##1##2##3 { - \@@_generate_internal_test:Nw ##2 ##3 + \if_catcode:w X \use_none:nnnnnnnn ##3 + \prg_do_nothing: \prg_do_nothing: \prg_do_nothing: + \prg_do_nothing: \prg_do_nothing: \prg_do_nothing: + \prg_do_nothing: \prg_do_nothing: X + \exp_after:wN \@@_generate_internal_test:Nw \exp_after:wN ##2 + \else: + \exp_after:wN \@@_generate_internal_test_aux:w \exp_after:wN #1 + \fi: + ##3 \q_mark { \use:x diff --git a/macros/latex/contrib/l3kernel/l3file.dtx b/macros/latex/contrib/l3kernel/l3file.dtx index 40a93f5715..5dd15d0e3d 100644 --- a/macros/latex/contrib/l3kernel/l3file.dtx +++ b/macros/latex/contrib/l3kernel/l3file.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3final.dtx b/macros/latex/contrib/l3kernel/l3final.dtx index 9565e313c5..520a329e0d 100644 --- a/macros/latex/contrib/l3kernel/l3final.dtx +++ b/macros/latex/contrib/l3kernel/l3final.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3flag.dtx b/macros/latex/contrib/l3kernel/l3flag.dtx index 013558817a..62f903934b 100644 --- a/macros/latex/contrib/l3kernel/l3flag.dtx +++ b/macros/latex/contrib/l3kernel/l3flag.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-assign.dtx b/macros/latex/contrib/l3kernel/l3fp-assign.dtx index e27e29a90b..5262f680b8 100644 --- a/macros/latex/contrib/l3kernel/l3fp-assign.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-assign.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % \maketitle % % \begin{documentation} diff --git a/macros/latex/contrib/l3kernel/l3fp-aux.dtx b/macros/latex/contrib/l3kernel/l3fp-aux.dtx index 755e5735b4..63aafee928 100644 --- a/macros/latex/contrib/l3kernel/l3fp-aux.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-aux.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-basics.dtx b/macros/latex/contrib/l3kernel/l3fp-basics.dtx index 0ab701078a..8764f0212b 100644 --- a/macros/latex/contrib/l3kernel/l3fp-basics.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-basics.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-convert.dtx b/macros/latex/contrib/l3kernel/l3fp-convert.dtx index 4a6de12835..a99f3215a9 100644 --- a/macros/latex/contrib/l3kernel/l3fp-convert.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-convert.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-expo.dtx b/macros/latex/contrib/l3kernel/l3fp-expo.dtx index f6e8809402..a19698934a 100644 --- a/macros/latex/contrib/l3kernel/l3fp-expo.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-expo.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-extended.dtx b/macros/latex/contrib/l3kernel/l3fp-extended.dtx index 5f8a75b080..1f267a7479 100644 --- a/macros/latex/contrib/l3kernel/l3fp-extended.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-extended.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-logic.dtx b/macros/latex/contrib/l3kernel/l3fp-logic.dtx index 88c9deea1b..3db19b3cfb 100644 --- a/macros/latex/contrib/l3kernel/l3fp-logic.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-logic.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-parse.dtx b/macros/latex/contrib/l3kernel/l3fp-parse.dtx index ee162e22d5..11ff1e4f27 100644 --- a/macros/latex/contrib/l3kernel/l3fp-parse.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-parse.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-random.dtx b/macros/latex/contrib/l3kernel/l3fp-random.dtx index 5c2237cb31..7975aa651c 100644 --- a/macros/latex/contrib/l3kernel/l3fp-random.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-random.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-round.dtx b/macros/latex/contrib/l3kernel/l3fp-round.dtx index 3e0bc28943..eb68ec0baf 100644 --- a/macros/latex/contrib/l3kernel/l3fp-round.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-round.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp-traps.dtx b/macros/latex/contrib/l3kernel/l3fp-traps.dtx index 90270c1668..f76616eef3 100644 --- a/macros/latex/contrib/l3kernel/l3fp-traps.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-traps.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % \maketitle % % \begin{documentation} diff --git a/macros/latex/contrib/l3kernel/l3fp-trig.dtx b/macros/latex/contrib/l3kernel/l3fp-trig.dtx index abfbb289b8..77af2e71ac 100644 --- a/macros/latex/contrib/l3kernel/l3fp-trig.dtx +++ b/macros/latex/contrib/l3kernel/l3fp-trig.dtx @@ -40,7 +40,7 @@ % {latex-team@latex-project.org}^^A % }^^A % } -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fp.dtx b/macros/latex/contrib/l3kernel/l3fp.dtx index d6a8270034..d4e5b7c31d 100644 --- a/macros/latex/contrib/l3kernel/l3fp.dtx +++ b/macros/latex/contrib/l3kernel/l3fp.dtx @@ -49,7 +49,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3fparray.dtx b/macros/latex/contrib/l3kernel/l3fparray.dtx index 4eabaaf227..8ca49335b4 100644 --- a/macros/latex/contrib/l3kernel/l3fparray.dtx +++ b/macros/latex/contrib/l3kernel/l3fparray.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3int.dtx b/macros/latex/contrib/l3kernel/l3int.dtx index 833f4b1e20..67c3542e55 100644 --- a/macros/latex/contrib/l3kernel/l3int.dtx +++ b/macros/latex/contrib/l3kernel/l3int.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3intarray.dtx b/macros/latex/contrib/l3kernel/l3intarray.dtx index 40f4cea35f..b8a33eb677 100644 --- a/macros/latex/contrib/l3kernel/l3intarray.dtx +++ b/macros/latex/contrib/l3kernel/l3intarray.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3kernel-functions.dtx b/macros/latex/contrib/l3kernel/l3kernel-functions.dtx index 47631ec4bc..66b763ed7b 100644 --- a/macros/latex/contrib/l3kernel/l3kernel-functions.dtx +++ b/macros/latex/contrib/l3kernel/l3kernel-functions.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3keys.dtx b/macros/latex/contrib/l3kernel/l3keys.dtx index b9bff1511f..aa2b4df82c 100644 --- a/macros/latex/contrib/l3kernel/l3keys.dtx +++ b/macros/latex/contrib/l3kernel/l3keys.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3legacy.dtx b/macros/latex/contrib/l3kernel/l3legacy.dtx index 06657dcddf..ca3c96d85d 100644 --- a/macros/latex/contrib/l3kernel/l3legacy.dtx +++ b/macros/latex/contrib/l3kernel/l3legacy.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3luatex.dtx b/macros/latex/contrib/l3kernel/l3luatex.dtx index 80ee007613..cbc3d7a4e2 100644 --- a/macros/latex/contrib/l3kernel/l3luatex.dtx +++ b/macros/latex/contrib/l3kernel/l3luatex.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3msg.dtx b/macros/latex/contrib/l3kernel/l3msg.dtx index 8335c43043..79a2ecc5ff 100644 --- a/macros/latex/contrib/l3kernel/l3msg.dtx +++ b/macros/latex/contrib/l3kernel/l3msg.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3names.dtx b/macros/latex/contrib/l3kernel/l3names.dtx index 0e130a5664..c11c837c6a 100644 --- a/macros/latex/contrib/l3kernel/l3names.dtx +++ b/macros/latex/contrib/l3kernel/l3names.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3prefixes.pdf b/macros/latex/contrib/l3kernel/l3prefixes.pdf Binary files differindex a7ec7b442a..3a7065aa91 100644 --- a/macros/latex/contrib/l3kernel/l3prefixes.pdf +++ b/macros/latex/contrib/l3kernel/l3prefixes.pdf diff --git a/macros/latex/contrib/l3kernel/l3prg.dtx b/macros/latex/contrib/l3kernel/l3prg.dtx index 34df225f22..f984c3aa76 100644 --- a/macros/latex/contrib/l3kernel/l3prg.dtx +++ b/macros/latex/contrib/l3kernel/l3prg.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3prop.dtx b/macros/latex/contrib/l3kernel/l3prop.dtx index 1e96ab3799..2ab8ea46df 100644 --- a/macros/latex/contrib/l3kernel/l3prop.dtx +++ b/macros/latex/contrib/l3kernel/l3prop.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3quark.dtx b/macros/latex/contrib/l3kernel/l3quark.dtx index faf90acf0c..c828aa1d49 100644 --- a/macros/latex/contrib/l3kernel/l3quark.dtx +++ b/macros/latex/contrib/l3kernel/l3quark.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3regex.dtx b/macros/latex/contrib/l3kernel/l3regex.dtx index 76415e1314..8d409b2dc5 100644 --- a/macros/latex/contrib/l3kernel/l3regex.dtx +++ b/macros/latex/contrib/l3kernel/l3regex.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3seq.dtx b/macros/latex/contrib/l3kernel/l3seq.dtx index ede24233ce..0e66adfd81 100644 --- a/macros/latex/contrib/l3kernel/l3seq.dtx +++ b/macros/latex/contrib/l3kernel/l3seq.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3skip.dtx b/macros/latex/contrib/l3kernel/l3skip.dtx index cc71cbd8f8..1e3962b393 100644 --- a/macros/latex/contrib/l3kernel/l3skip.dtx +++ b/macros/latex/contrib/l3kernel/l3skip.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3sort.dtx b/macros/latex/contrib/l3kernel/l3sort.dtx index 57df7c0fb5..129bcef456 100644 --- a/macros/latex/contrib/l3kernel/l3sort.dtx +++ b/macros/latex/contrib/l3kernel/l3sort.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3str-convert.dtx b/macros/latex/contrib/l3kernel/l3str-convert.dtx index c54db667d9..86cf7db469 100644 --- a/macros/latex/contrib/l3kernel/l3str-convert.dtx +++ b/macros/latex/contrib/l3kernel/l3str-convert.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3str.dtx b/macros/latex/contrib/l3kernel/l3str.dtx index 70f9623622..b961e89df8 100644 --- a/macros/latex/contrib/l3kernel/l3str.dtx +++ b/macros/latex/contrib/l3kernel/l3str.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3styleguide.pdf b/macros/latex/contrib/l3kernel/l3styleguide.pdf Binary files differindex df9dc880c8..f7c3292758 100644 --- a/macros/latex/contrib/l3kernel/l3styleguide.pdf +++ b/macros/latex/contrib/l3kernel/l3styleguide.pdf diff --git a/macros/latex/contrib/l3kernel/l3styleguide.tex b/macros/latex/contrib/l3kernel/l3styleguide.tex index 186fadcfde..0c30614d76 100644 --- a/macros/latex/contrib/l3kernel/l3styleguide.tex +++ b/macros/latex/contrib/l3kernel/l3styleguide.tex @@ -32,7 +32,7 @@ The released version of this bundle is available from CTAN. {latex-team@latex-project.org}% }% } -\date{Released 2019-09-30} +\date{Released 2019-10-02} \begin{document} diff --git a/macros/latex/contrib/l3kernel/l3syntax-changes.pdf b/macros/latex/contrib/l3kernel/l3syntax-changes.pdf Binary files differindex 02c06ac986..3f02f94e44 100644 --- a/macros/latex/contrib/l3kernel/l3syntax-changes.pdf +++ b/macros/latex/contrib/l3kernel/l3syntax-changes.pdf diff --git a/macros/latex/contrib/l3kernel/l3syntax-changes.tex b/macros/latex/contrib/l3kernel/l3syntax-changes.tex index 40060cf73c..f3fa98dbcd 100644 --- a/macros/latex/contrib/l3kernel/l3syntax-changes.tex +++ b/macros/latex/contrib/l3kernel/l3syntax-changes.tex @@ -32,7 +32,7 @@ The released version of this bundle is available from CTAN. {latex-team@latex-project.org}% }% } -\date{Released 2019-09-30} +\date{Released 2019-10-02} \newcommand{\TF}{\textit{(TF)}} diff --git a/macros/latex/contrib/l3kernel/l3sys.dtx b/macros/latex/contrib/l3kernel/l3sys.dtx index 7d696c2785..172d9507eb 100644 --- a/macros/latex/contrib/l3kernel/l3sys.dtx +++ b/macros/latex/contrib/l3kernel/l3sys.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3term-glossary.pdf b/macros/latex/contrib/l3kernel/l3term-glossary.pdf Binary files differindex c950debcf5..e816fc719d 100644 --- a/macros/latex/contrib/l3kernel/l3term-glossary.pdf +++ b/macros/latex/contrib/l3kernel/l3term-glossary.pdf diff --git a/macros/latex/contrib/l3kernel/l3term-glossary.tex b/macros/latex/contrib/l3kernel/l3term-glossary.tex index 4eb0ac92ab..4a2fd2aeb1 100644 --- a/macros/latex/contrib/l3kernel/l3term-glossary.tex +++ b/macros/latex/contrib/l3kernel/l3term-glossary.tex @@ -32,7 +32,7 @@ The released version of this bundle is available from CTAN. {latex-team@latex-project.org}% }% } -\date{Released 2019-09-30} +\date{Released 2019-10-02} \newcommand{\TF}{\textit{(TF)}} diff --git a/macros/latex/contrib/l3kernel/l3tl-analysis.dtx b/macros/latex/contrib/l3kernel/l3tl-analysis.dtx index 6f16f0c82e..3e34bfd8f9 100644 --- a/macros/latex/contrib/l3kernel/l3tl-analysis.dtx +++ b/macros/latex/contrib/l3kernel/l3tl-analysis.dtx @@ -44,7 +44,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3tl.dtx b/macros/latex/contrib/l3kernel/l3tl.dtx index e6f21cc21f..c6eb6aa3f2 100644 --- a/macros/latex/contrib/l3kernel/l3tl.dtx +++ b/macros/latex/contrib/l3kernel/l3tl.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3token.dtx b/macros/latex/contrib/l3kernel/l3token.dtx index e876b75260..51c7b597f0 100644 --- a/macros/latex/contrib/l3kernel/l3token.dtx +++ b/macros/latex/contrib/l3kernel/l3token.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/l3unicode.dtx b/macros/latex/contrib/l3kernel/l3unicode.dtx index 39f9948eed..78d3f1bdb9 100644 --- a/macros/latex/contrib/l3kernel/l3unicode.dtx +++ b/macros/latex/contrib/l3kernel/l3unicode.dtx @@ -43,7 +43,7 @@ % }^^A % } % -% \date{Released 2019-09-30} +% \date{Released 2019-10-02} % % \maketitle % diff --git a/macros/latex/contrib/l3kernel/source3.pdf b/macros/latex/contrib/l3kernel/source3.pdf Binary files differindex 528d4d7b07..9e90af917a 100644 --- a/macros/latex/contrib/l3kernel/source3.pdf +++ b/macros/latex/contrib/l3kernel/source3.pdf diff --git a/macros/latex/contrib/l3kernel/source3.tex b/macros/latex/contrib/l3kernel/source3.tex index ffed5ceede..f73c5b1798 100644 --- a/macros/latex/contrib/l3kernel/source3.tex +++ b/macros/latex/contrib/l3kernel/source3.tex @@ -53,7 +53,7 @@ for those people who are interested. {latex-team@latex-project.org}% }% } -\date{Released 2019-09-30} +\date{Released 2019-10-02} \pagenumbering{roman} \maketitle diff --git a/macros/latex/contrib/leadsheets/README b/macros/latex/contrib/leadsheets/README index 831b2a33b7..c984872ee3 100644 --- a/macros/latex/contrib/leadsheets/README +++ b/macros/latex/contrib/leadsheets/README @@ -1,5 +1,5 @@ -------------------------------------------------------------------------- -the LEADSHEETS package v0.5b 2017/09/26 +the LEADSHEETS package v0.6 2019/10/02 typesetting leadsheets and songbooks @@ -8,7 +8,7 @@ Clemens Niederberger Web: https://github.com/cgnieder/leadsheets E-Mail: contact@mychemistry.eu -------------------------------------------------------------------------- -Copyright 2014-2017 Clemens Niederberger +Copyright 2014--2019 Clemens Niederberger This work may be distributed and/or modified under the conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheet.cls b/macros/latex/contrib/leadsheets/leadsheet.cls index 7ea96cb2b5..2c5dadf4af 100644 --- a/macros/latex/contrib/leadsheets/leadsheet.cls +++ b/macros/latex/contrib/leadsheets/leadsheet.cls @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.chordnames.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.chordnames.code.tex index d43c840c60..113b9788a3 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.chordnames.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.chordnames.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -53,6 +53,7 @@ \tl_new:N \l__leadsheets_dim_tl \tl_new:N \l__leadsheets_add_tl \tl_new:N \l__leadsheets_major_seven_tl +\tl_new:N \l__leadsheets_major_nine_tl \tl_new:N \l__leadsheets_german_B_tl \tl_new:N \l__leadsheets_german_H_tl diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.chords.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.chords.code.tex index bda16e3ff2..11e8539cec 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.chords.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.chords.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.external.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.external.code.tex index f7d8f11ea4..77d414b410 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.external.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.external.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.musejazz.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.musejazz.code.tex index 6256c426f6..6f6ffb9052 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.musejazz.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.musejazz.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.musicsymbols.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.musicsymbols.code.tex index f94701cdf6..cce3dfbf76 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.musicsymbols.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.musicsymbols.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.properties.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.properties.code.tex index 44a69aaa25..ee01fbf3e9 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.properties.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.properties.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -42,7 +42,6 @@ \prop_gput:cnV {l__leadsheets_songs_#2_prop} {#1} \l__leadsheets_tmpa_tl } -\cs_generate_variant:Nn \prop_gput:cnn {cnV} \cs_generate_variant:Nn \leadsheets_set_property:nnn { nnx } \cs_new:Npn \leadsheets_get_property:nn #1#2 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.shorthands.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.shorthands.code.tex index 0f5a339e55..c3a2aac953 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.shorthands.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.shorthands.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2016 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.songs.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.songs.code.tex index 8a377a04ca..ca2c8cac7a 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.songs.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.songs.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -21,7 +21,7 @@ % % The Current Maintainer of this work is Clemens Niederberger. % -------------------------------------------------------------------------- -\LeadsheetsExplLibrary{songs}{2016/07/02 typesetting songs} +\LeadsheetsExplLibrary{songs}{2019/10/02 typesetting songs} % -------------------------------------------------------------------------- % messages: @@ -533,14 +533,16 @@ \bool_if:cF {l__leadsheets_#1_empty_bool} { \tl_use:c {l__leadsheets_#1_label_format_tl} - \bool_if:cT {l__leadsheets_#1_named_bool} - { - \leadsheets_translation:n {#1} - \bool_if:cT {l__leadsheets_#1_numbered_bool} { ~ } - } - \bool_if:cT {l__leadsheets_#1_numbered_bool} - { \use:c {the#1} } - \tl_use:c {l__leadsheets_#1_after_label_tl} + { + \bool_if:cT {l__leadsheets_#1_named_bool} + { + \leadsheets_translation:n {#1} + \bool_if:cT {l__leadsheets_#1_numbered_bool} {~} + } + \bool_if:cT {l__leadsheets_#1_numbered_bool} + { \use:c {the#1} } + \tl_use:c {l__leadsheets_#1_after_label_tl} + } } } @@ -790,3 +792,4 @@ 2016/06/29: - adapt to changed shorthand library - activate bar-shortcuts per default 2016/07/02: fix issue when \capo is used in a title template +2019/10/02: enable https://tex.stackexchange.com/q/442222/ diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.templates.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.templates.code.tex index c09744aa3e..9514a03f1e 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.templates.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.templates.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.translations.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.translations.code.tex index c3ecd3e151..d5992adcdb 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.translations.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.translations.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.library.transposing.code.tex b/macros/latex/contrib/leadsheets/leadsheets.library.transposing.code.tex index 2f0e428d94..91e21f0019 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.library.transposing.code.tex +++ b/macros/latex/contrib/leadsheets/leadsheets.library.transposing.code.tex @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/leadsheets/leadsheets.sty b/macros/latex/contrib/leadsheets/leadsheets.sty index 5e6464dfcc..382c436b7a 100644 --- a/macros/latex/contrib/leadsheets/leadsheets.sty +++ b/macros/latex/contrib/leadsheets/leadsheets.sty @@ -7,7 +7,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 @@ -27,8 +27,8 @@ % -------------------------------------------------------------------------- % package information: \ExplSyntaxOn -\tl_const:Nn \leadsheetsdate {2017/09/26} -\tl_const:Nn \leadsheetsversion {0.5b} +\tl_const:Nn \leadsheetsdate {2019/10/02} +\tl_const:Nn \leadsheetsversion {0.6} \tl_const:Nn \leadsheetsinfo {Typesetting leadsheets and songbooks} \ProvidesExplPackage @@ -60,10 +60,11 @@ \cs_generate_variant:Nn \seq_item:Nn { cV } \cs_generate_variant:Nn \int_to_arabic:n { V } \cs_generate_variant:Nn \tl_replace_once:Nnn { NnV } -\cs_generate_variant:Nn \prop_gput:Nnn { cxx , NVf } +\cs_generate_variant:Nn \prop_gput:Nnn { cnV , cxx , NVf } \cs_generate_variant:Nn \msg_error:nnn { nnV } \cs_generate_variant:Nn \msg_warning:nnn { nnV } \cs_generate_variant:Nn \vbox_set:Nn { NV } +\cs_generate_variant:Nn \prop_gput:Nnn { cnV } % -------------------------------------------------------------------------- % temporary variables: diff --git a/macros/latex/contrib/leadsheets/leadsheets_en.pdf b/macros/latex/contrib/leadsheets/leadsheets_en.pdf Binary files differindex 1c881907fa..264c7e5c75 100644 --- a/macros/latex/contrib/leadsheets/leadsheets_en.pdf +++ b/macros/latex/contrib/leadsheets/leadsheets_en.pdf diff --git a/macros/latex/contrib/leadsheets/leadsheets_en.tex b/macros/latex/contrib/leadsheets/leadsheets_en.tex index c11f660e5c..dbf744685c 100644 --- a/macros/latex/contrib/leadsheets/leadsheets_en.tex +++ b/macros/latex/contrib/leadsheets/leadsheets_en.tex @@ -1,7 +1,7 @@ -% !arara: pdflatex: { shell: on , action: nonstopmode } +% arara: pdflatex: { shell: on , action: nonstopmode } % arara: biber -% arara: pdflatex -% arara: pdflatex +% arara: pdflatex: { action: nonstopmode } +% arara: pdflatex: { action: nonstopmode } % -------------------------------------------------------------------------- % the LEADSHEETS package % @@ -11,7 +11,7 @@ % Clemens Niederberger % E-Mail: contact@mychemistry.eu % -------------------------------------------------------------------------- -% Copyright 2014-2017 Clemens Niederberger +% Copyright 2014--2019 Clemens Niederberger % % This work may be distributed and/or modified under the % conditions of the LaTeX Project Public License, either version 1.3 diff --git a/macros/latex/contrib/quiz2socrative/README.txt b/macros/latex/contrib/quiz2socrative/README.txt new file mode 100644 index 0000000000..f8dcd0c17f --- /dev/null +++ b/macros/latex/contrib/quiz2socrative/README.txt @@ -0,0 +1,25 @@ +This is the distribution directory for quiz2socrative, a LaTeX package for +preparing multiple choice, true/false and short answer questions. +The main purpouse is to offer a tool to easily insert rather complicated +mathematical stuff in socrative quizzes (see https://socrative.com). + +This is quiz2socrative version 1.0, October 2019. +quiz2socrative is distributed under the LaTeX Project Public License 1.3c. + + +*** Source files: + +quiz2socrative.sty The style file +quiz2socrative-IT.tex The documentation file +sample-quiz2socrative-socrativeQuiz+standalone.tex An example of a set of questions ready to prepare a socrative quiz. +sample-quiz2socrative-pdfQuiz.tex An example of a traditional pen and paper quiz. + + +*** Pdf files: + +quiz2socrative-IT.pdf The documentation (italian only) +sample-quiz2socrative-socrativeQuiz+standalone.pdf An example of a set of questions ready to prepare a socrative quiz. +sample-quiz2socrative-pdfQuiz.pdf An example of a traditional pen and paper quiz. + + +Paolo Lella (paolo.lella@polimi.it)
\ No newline at end of file diff --git a/macros/latex/contrib/quiz2socrative/quiz2socrative-IT.pdf b/macros/latex/contrib/quiz2socrative/quiz2socrative-IT.pdf Binary files differnew file mode 100644 index 0000000000..d3ec168565 --- /dev/null +++ b/macros/latex/contrib/quiz2socrative/quiz2socrative-IT.pdf diff --git a/macros/latex/contrib/quiz2socrative/quiz2socrative-IT.tex b/macros/latex/contrib/quiz2socrative/quiz2socrative-IT.tex new file mode 100644 index 0000000000..a72201a86e --- /dev/null +++ b/macros/latex/contrib/quiz2socrative/quiz2socrative-IT.tex @@ -0,0 +1,432 @@ +\documentclass[12pt]{article} +\usepackage[top=2.5cm, bottom=2cm, left=2cm, right=2cm]{geometry} +\geometry{a4paper} +\usepackage{graphicx} +\usepackage{amssymb,amsmath,amsthm} +\usepackage[italian]{babel} + +\usepackage{tikz} +\usetikzlibrary{shadows} +\usepackage[colorlinks]{hyperref} +\usepackage{mathpazo,helvet,courier} +\usepackage{fancyvrb} +\usepackage{pdfpages} + +\usepackage{quiz2socrative} + + + +\renewcommand{\baselinestretch}{1.2} + +\renewcommand*{\thefootnote}{\fnsymbol{footnote}} + +\title{Il package \texttt{quiz2socrative}} +\author{Paolo Lella\footnote{Per segnalazioni di errori o malfunzionamenti e/o per suggerimenti di estensioni delle funzionalit\`a del pacchetto, scrivere a \href{mailto:paolo.lella@polimi.it}{\tt paolo.lella@polimi.it}}} +\date{\it \small Versione 1.0, Ottobre 2019} + +\begin{document} + +\maketitle + +\begin{abstract} +Il package \texttt{quiz2socrative.sty} fornisce alcuni comandi utili per la preparazione di domande a risposta multipla, quesiti vero/falso e domande con risposta breve. Queste tre tipologie di domande sono le tipologie disponibili nell'applicazione \textsf{Socrative} (\url{www.socrative.com}). Tale applicazione non offre la possibilit\`a di inserire codice latex direttamente nel corpo di una domanda, pertanto le formule matematiche possono essere inserite solo sotto forma di immagine. Gli strumenti del package \texttt{quiz2socrative.sty} agevolano la produzione di immagini contenenti domande di contenuto matematico e il formato delle immagini \`e pensato appositamente per la fruizione del quiz tramite lo schermo di uno smartphone. +\end{abstract} + +\tableofcontents + +\newpage + +\section{Comandi} +L'applicazione \textsf{Socrative} offre tre tipologie di domande: +\begin{itemize} +\item domande a risposta multipla; +\item quesiti vero/falso; +\item domande con risposta breve. +\end{itemize} + + +\subsection{Domande a risposta multipla} +Il comando principale per la produzione di una domanda a risposta multipla \`e +\begin{center}\tt +\textbackslash socrativeMC\{\textit{<testo della domanda>}\}\{\textit{<lista delle risposte>}\} +\end{center} + dove le singole risposte nella {\tt \textit{<lista delle risposte>}} devono essere separate dalla stringa \texttt{\textbackslash !\textbackslash !}. Ad esempio il comando + \begin{center} + \parbox{16cm}{\tt +\textbackslash socrativeMC\{Di che colore \`e il cavallo bianco di Napoleone?\}\\ +\phantom{\textbackslash socrativeMC}\{Nero. \textbackslash !\textbackslash ! Bianco. \textbackslash !\textbackslash ! Rosso.\}\hspace{4cm}} + \end{center} +produce la domanda rappresentata in Figura \ref{fig:MC1} (\textsc{n.b.} gli spazi che precedono e seguono la stringa \texttt{\textbackslash !\textbackslash !} vengono ignorati). + +\showBorder +\begin{figure}[!ht] +\begin{center} +\socrativeMC{Di che colore \`e il cavallo bianco di Napoleone?}{Nero. \!\! Bianco. \!\! Rosso.} +\caption{\label{fig:MC1} Esempio di utilizzo del comando \texttt{\textbackslash socrativeMC}.} +\end{center} +\end{figure} + \hideBorder + + \newpage + + Sono disponibili ulteriori comandi per i casi particolari di: + \begin{itemize} + \item due risposte + \begin{center} + \parbox{14cm}{\tt \textbackslash socrativeTwoMC\{\textit{<testo della domanda>}\}\{\textit{<risposta 1>}\}\\ + \phantom{\textbackslash socrativeTwoMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 2>}\} + } + \end{center} + \item tre risposte + \begin{center} + \parbox{14cm}{\tt \textbackslash socrativeThreeMC\{\textit{<testo della domanda>}\}\{\textit{<risposta 1>}\}\\ + \phantom{\textbackslash socrativeThreeMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 2>}\}\\ + \phantom{\textbackslash socrativeThreeMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 3>}\} + } + \end{center} + \item quattro risposte + \begin{center} + \parbox{14cm}{\tt \textbackslash socrativeFourMC\{\textit{<testo della domanda>}\}\{\textit{<risposta 1>}\}\\ + \phantom{\textbackslash socrativeFourMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 2>}\}\\ + \phantom{\textbackslash socrativeFourMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 3>}\}\\ + \phantom{\textbackslash socrativeFourMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 4>}\} + } + \end{center} + \item cinque risposte + \begin{center} + \parbox{14cm}{\tt \textbackslash socrativeFiveMC\{\textit{<testo della domanda>}\}\{\textit{<risposta 1>}\}\\ + \phantom{\textbackslash socrativeFiveMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 2>}\}\\ + \phantom{\textbackslash socrativeFiveMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 3>}\}\\ + \phantom{\textbackslash socrativeFiveMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 4>}\}\\ + \phantom{\textbackslash socrativeFiveMC\{\textit{<testo della domanda>}\}}\{\textit{<risposta 5>}\} + } + \end{center} + \end{itemize} +In questa serie di comandi, ogni risposta \`e inserita come un singolo argomento. + +\subsection{Quesiti vero/falso} + +Per la produzione di un'immagine di un quesito vero/falso, il comando \`e +\begin{center}\tt +\textbackslash socrativeTF\{\textit{<testo della domanda>}\} +\end{center} + Ad esempio il comando + \begin{center}\tt +\textbackslash socrativeTF\{Un chilo di ferro pesa pi\`u di un chilo di piume.\} +\end{center} +produce la domanda rappresentata in Figura \ref{fig:TF1}. + +\showBorder +\begin{figure}[!ht] +\begin{center} +\socrativeTF{Un chilo di ferro pesa pi\`u di un chilo di piume.} +\caption{\label{fig:TF1} Esempio di utilizzo del comando \texttt{\textbackslash socrativeTF}.} +\end{center} +\end{figure} +\hideBorder + +\subsection{Domande con risposta breve} +Per la produzione di un'immagine di domanda con risposta breve, il comando \`e +\begin{center}\tt +\textbackslash socrativeSA\{\textit{<testo della domanda>}\} +\end{center} + Ad esempio il comando + \begin{center}\tt +\textbackslash socrativeSA\{Quanto pesa un chilo di ferro?\} +\end{center} +produce la domanda rappresentata in Figura \ref{fig:SA1}. + +\showBorder +\begin{figure}[!ht] +\begin{center} +\socrativeSA{Quanto pesa un chilo di ferro?}\vspace*{-6pt} +\caption{\label{fig:SA1} Esempio di utilizzo del comando \texttt{\textbackslash socrativeSA}.} +\end{center} +\end{figure} +\hideBorder + +\vspace*{-18pt} +\section{Opzioni globali} +Nella chiamata del package \texttt{quiz2socrative}, \`e possibile impostare tre opzioni: +\begin{description} +\item[\texttt{socrativeQuiz} / \texttt{pdfQuiz}] Con l'opzione \texttt{socrativeQuiz}\footnotemark[2]\vspace*{-1pt} +\begin{center}\tt +\textbackslash usepackage[socrativeQuiz]\{quiz2socrative\} +\end{center}\vspace*{-1pt} +ogni domanda viene stampata per essere ritagliata e inserita come immagine in un test \textsf{Socrative}. Le domande contenute nelle Figure \ref{fig:MC1}, \ref{fig:TF1} e \ref{fig:SA1} sono esempi prodotti con questa opzione. + +L'opzione \texttt{pdfQuiz}\footnotemark[2]\vspace*{-1pt} +\begin{center}\tt +\textbackslash usepackage[pdfQuiz]\{quiz2socrative\} +\end{center}\vspace*{-1pt} + \`e pensata invece per la preparazione di test cartacei. L'output dei comandi per produrre domande a risposta multipla rimane invariato, mentre nel caso di quesiti vero/falso vengono aggiunti due riquadri \lq\lq VERO\rq\rq--\lq\lq FALSO\rq\rq~e nel caso di domande con risposta breve viene aggiunto un riquadro con lo spazio per la risposta (vedi Figura \ref{fig:pdfQuiz}). + + \begin{figure}[!ht] +\begin{center} \showBorder \showSolution +\socrativeTF{Un chilo di ferro pesa pi\`u di un chilo di piume.}[2] +\hfill +\socrativeSA{Quanto pesa un chilo di ferro?}[ ]\hideBorder\hideSolution +\caption{\label{fig:pdfQuiz} Il quesito vero/falso e la domanda con risposta breve descritti in figura sono prodotti dai comandi utilizzati nelle Figure \ref{fig:TF1} e \ref{fig:SA1}, ma con l'opzione \texttt{pdfQuiz}.} +\end{center} +\end{figure} + +\item[\texttt{letters} / \texttt{numbers}] Con l'opzione \texttt{letters}\footnotemark[2]\vspace*{-1pt} +\begin{center}\tt +\textbackslash usepackage[letters]\{quiz2socrative\} +\end{center}\vspace*{-1pt} +le risposte delle domande a risposta multipla vengono enumerate con lettere maiuscole, mentre con l'opzione \texttt{numbers}\footnotemark[2]\vspace*{-1pt} +\begin{center}\tt +\textbackslash usepackage[numbers]\{quiz2socrative\} +\end{center}\vspace*{-1pt} +vengono enumerate con numeri (vedi Figura \ref{fig:MC2}). + +\showBorder +\begin{figure}[!ht] +\begin{center} +\socrativeMC{Di che colore \`e il cavallo bianco di Napoleone?}{Nero. \!\! Bianco. \!\! Rosso.} +\hfill\useNumbers +\socrativeMC{Di che colore \`e il cavallo bianco di Napoleone?}{Nero. \!\! Bianco. \!\! Rosso.}\useLetters +\caption{\label{fig:MC2} Una domanda a risposta multipla con l'opzione \texttt{letters} a sinistra e \texttt{numbers} a destra.} +\end{center} +\end{figure} +\hideBorder + +\item[\texttt{italian} / \texttt{english}] Queste due opzioni producono delle differenze se abbinate all'opzione \texttt{pdfQuiz}. Con l'opzione \texttt{italian}\footnotemark[2] +\begin{center}\tt +\textbackslash usepackage[italian,pdfQuiz]\{quiz2socrative\} +\end{center} +nei due riquadri per la risposta ai quesiti vero/falso viene scritto \lq\lq VERO\rq\rq~e \lq\lq FALSO\rq\rq, mentre con l'opzione \texttt{english}\footnotemark[2] +\begin{center}\tt +\textbackslash usepackage[english,pdfQuiz]\{quiz2socrative\} +\end{center} +viene scritto \lq\lq TRUE\rq\rq~e \lq\lq FALSE\rq\rq~(vedi Figura \ref{fig:TF2}). + +\showBorder\showSolution +\begin{figure}[!ht] +\begin{center} +\socrativeTF{$$\frac{1}{2} > \frac{2}{3}$$}[2] +\hfill \useEnglish +\socrativeTF{$$\frac{1}{2} > \frac{2}{3}$$}[2] \useItalian\vspace*{-18pt} +\caption{\label{fig:TF2} Un quesito vero/falso con l'opzione \texttt{italian} a sinistra e \texttt{english} a destra.} +\end{center} +\end{figure} +\hideBorder\hideSolution +\end{description} + +\footnotetext[2]{Le opzioni di default sono \texttt{socrativeQuiz,letters,italian}.} + +\section{Opzioni avanzate} + +\subsection{Larghezza del riquadro} +Tutti i comandi per la produzione di domande hanno un argomento opzionale che consente di variare la larghezza del riquadro (vedi Figura \ref{fig:MC3}): +\begin{center} +\parbox{12cm}{\tt \textbackslash socrativeMC[\textit{<larghezza>}]\{$\cdots$\} \\ + \textbackslash socrativeTwoMC[\textit{<larghezza>}]\{$\cdots$\} \\ + \textbackslash socrativeThreeMC[\textit{<larghezza>}]\{$\cdots$\} \\ + \textbackslash socrativeFourMC[\textit{<larghezza>}]\{$\cdots$\} \\ + \textbackslash socrativeFiveMC[\textit{<larghezza>}]\{$\cdots$\} \\ + \textbackslash socrativeTF[\textit{<larghezza>}]\{$\cdots$\} \\ + \textbackslash socrativeSA[\textit{<larghezza>}]\{$\cdots$\} } +\end{center} +L'argomento \texttt{\textit{<larghezza>}} deve essere un numero con unit\`a di misura (ad esempio \texttt{cm} o \texttt{pt}). La larghezza di default \`e $8$ cm. + + +\showBorder +\begin{figure}[!ht] +\begin{center} +\socrativeThreeMC[15cm]{Di che colore \`e il cavallo bianco di Napoleone?}{Nero.}{Bianco.}{Rosso.} +\caption{\label{fig:MC3} La domanda prodotta dal comando {\tt \textbackslash socrativeThreeMC[15cm]\{Di che colore \`e il cavallo bianco di Napoleone?\}\{Nero.\}\{Bianco.\}\{Rosso.\}}.} +\end{center} +\end{figure} +\hideBorder + +\subsection{Bordo del riquadro} + +Il bordo del riquadro contenente le domande pu\`o non essere mostrato (vedi Figura \ref{fig:MC4}), e la scelta di mostrarlo/non mostrarlo pu\`o essere modificata in ogni punto del file sorgente (anche pi\`u volte) con i comandi +\begin{center} +{\tt \textbackslash hideBorder}\qquad e \qquad {\tt \textbackslash showBorder}. +\end{center} +Con l'opzione \texttt{socrativeQuiz} l'impostazione iniziale \`e senza i bordi ({\tt \textbackslash hideBorder}), mentre con l'opzione \texttt{pdfQuiz} l'impostazione iniziale \`e con i bordi ({\tt \textbackslash showBorder}). + +\begin{figure}[!ht] +\begin{center} +\socrativeThreeMC{Di che colore \`e il cavallo bianco di Napoleone?}{Nero.}{Bianco.}{Rosso.} +\caption{\label{fig:MC4} La domanda prodotta dal comando utilizzato in Figura \ref{fig:MC1}, preceduto dal comando {\texttt{\textbackslash hideBorder}}.} +\end{center} +\end{figure} + +\subsection{Soluzioni} + +Esclusivamente con l'opzione \texttt{pdfQuiz}, \`e possibile produrre le soluzioni di un quiz, cio\`e stampare domande e quesiti risolti. + +Per prima cosa, \`e necessario aggiungere nella definizione della domanda l'informazione relativa alla soluzione. Tutti i comandi per la produzione di domande/quesiti hanno un ultimo argomento opzionale che consente di inserire la soluzione/risposta: +\begin{center} +\parbox{12cm}{\tt \textbackslash socrativeMC\{$\cdots$\}[\textit{<soluzione>}] \\ + \textbackslash socrativeTwoMC\{$\cdots$\}[\textit{<soluzione>}] \\ + \textbackslash socrativeThreeMC\{$\cdots$\}[\textit{<soluzione>}] \\ + \textbackslash socrativeFourMC\{$\cdots$\}[\textit{<soluzione>}] \\ + \textbackslash socrativeFiveMC\{$\cdots$\}[\textit{<soluzione>}] \\ + \textbackslash socrativeTF\{$\cdots$\}[\textit{<soluzione>}] \\ + \textbackslash socrativeSA\{$\cdots$\}[\textit{<soluzione>}] } +\end{center} +Per le domande a risposta multipla (vedi Figura \ref{fig:MC5}), l'argomento opzionale della soluzione \`e dato dal numero della risposta corretta o dalla lista dei numeri delle risposte corrette separati da \lq\lq,\rq\rq~(virgola): +\begin{center} +\parbox{13cm}{{\tt[\textit{<risposta corretta>}]} \qquad oppure \\ {\tt [\textit{<risposta corretta 1>,<risposta corretta 2>,\ldots}]}. } +\end{center} + +\begin{figure}[!ht] +\begin{center}\showSolution\showBorder +\socrativeThreeMC{Di che colore \`e il cavallo bianco di Napoleone?}{Nero.}{Bianco.}{Rosso.}[2]\hideSolution\hideBorder +\caption{\label{fig:MC5} La domanda prodotta dal comando {\tt \textbackslash socrativeThreeMC\{Di che colore \`e il cavallo bianco di Napoleone?\}\{Nero.\}\{Bianco.\}\{Rosso.\}[2]}, preceduto dal comando {\texttt{\textbackslash showSolution}}.} +\end{center} +\end{figure} + +Per i quesiti vero/falso (vedi Figura \ref{fig:TF3}), se la soluzione \`e \lq\lq VERO\rq\rq~va aggiunto l'argomento opzionale \texttt{[1]}, mentre se la soluzione \`e \lq\lq FALSO\rq\rq~ l'argomento opzionale \`e \texttt{[0]}. + +\begin{figure}[!ht] +\begin{center}\showSolution\showBorder +\socrativeTF{Un chilo di ferro pesa pi\`u di un chilo di piume.}[0]\hideSolution\hideBorder +\caption{\label{fig:TF3} La domanda prodotta dal comando {\tt \textbackslash socrativeTF\{Un chilo di ferro pesa pi\`u di un chilo di piume.\}[0]}, preceduto dal comando {\texttt{\textbackslash showSolution}}.} +\end{center} +\end{figure} + +Per le domande con risposta breve (vedi Figura \ref{fig:SA2}), l'argomento opzionale della soluzione \`e una qualsiasi porzione di testo. + +\begin{figure}[!ht] +\begin{center}\showSolution\showBorder +\socrativeSA{Quanto pesa un chilo di ferro?}[1000 grammi.]\hideSolution\hideBorder +\caption{\label{fig:SA2} La domanda prodotta dal comando {\tt \textbackslash socrativeSA\{Quanto pesa un chilo di ferro?\}[1000 grammi.]}, preceduto dal comando {\texttt{\textbackslash showSolution}}.} +\end{center} +\end{figure} + +La scelta di mostrare/non mostrare la soluzione pu\`o essere modificata in ogni punto del file sorgente (anche pi\`u volte) con i comandi +\begin{center} +{\tt \textbackslash showSolution}\qquad e \qquad {\tt \textbackslash hideSolution}. +\end{center} + + + +\subsection{La document class \texttt{standalone}} + +Per la produzione di immagini da inserire in un quiz \textsf{Socrative}, si raccomanda l'uso della document class \texttt{standalone} con l'opzione \texttt{tikz} +\begin{center} +\tt \textbackslash documentclass[tikz]\{standalone\} +\end{center} +In questo modo, l'output sar\`a un documento pdf con una domanda/quesito per ogni pagina (con il formato fornito dal pacchetto \texttt{quiz2socrative}). A questo punto sar\`a necessaria solo l'estrazione e la conversione di ogni pagina in formato \texttt{png} o \texttt{jpeg}. + +\newpage + + +\section{Esempi} + +\subsection{\texttt{socrativeQuiz} $+$ \texttt{standalone}} + +Il file \texttt{sample-quiz2socrative-socrativeQuiz+standalone.tex} +\begin{Verbatim}[fontsize=\small,frame=single,numbers=left,numbersep=4pt] +\documentclass[tikz]{standalone} + +\usepackage[socrativeQuiz]{quiz2socrative} + +\begin{document} + +\socrativeMC{Di che colore \`e il cavallo bianco di Napoleone?} + {Nero. \!\! Bianco. \!\! Rosso.} + +\socrativeTF{Un chilo di piume pesa pi\`u di un chilo di ferro.} + +\socrativeSA{Quanto pesa un chilo di ferro?} + +\end{document} +\end{Verbatim} +produce un documento pdf con tre pagine descritte nella Figura \ref{fig:ex1}. + +\begin{figure}[!ht] +\begin{tikzpicture} +\useasboundingbox (0,0); +\node at (8.45cm,-2.84cm) [minimum width=8cm,minimum height=4.7cm,rectangle,,drop shadow={shadow xshift=.75ex, shadow yshift=-.75ex},fill=white]{}; + +\node at (8.45cm,-8.04cm) [minimum width=8cm,minimum height=0.925cm,rectangle,,drop shadow={shadow xshift=.75ex, shadow yshift=-.75ex},fill=white]{}; + +\node at (8.45cm,-6.375cm) [minimum width=8cm,minimum height=1.45cm,rectangle,,drop shadow={shadow xshift=.75ex, shadow yshift=-.75ex},fill=white]{}; + +\end{tikzpicture} + +\begin{center}\showBorder + +\socrativeMC{Di che colore \`e il cavallo bianco di Napoleone?}{Nero. \!\! Bianco. \!\! Rosso.} + +\bigskip + +\socrativeTF{Un chilo di piume pesa pi\`u di un chilo di ferro.} + +\bigskip + +\socrativeSA{Quanto pesa un chilo di ferro?} + +\caption{\label{fig:ex1} Le pagine prodotte dal file {\tt sample-quiz2socrative-socrativeQuiz+ standalone.tex}.} +\end{center} +\end{figure} + +\subsection{\texttt{pdfQuiz}} + +Il file \texttt{sample-quiz2socrative-pdfQuiz.tex} +\begin{Verbatim}[fontsize=\small,frame=single,numbers=left,numbersep=4pt] +\documentclass[12pt]{article} + +\usepackage[pdfQuiz]{quiz2socrative} +\usepackage[a4paper]{geometry} + +\begin{document} +\thispagestyle{empty} + +\begin{center} +{\bf \Large Sample quiz} + +\socrativeMC[10cm]{Di che colore \`e il cavallo bianco di Napoleone?} + {Nero. \!\! Bianco. \!\! Rosso.} + +\bigskip + +\socrativeTF[10cm]{Un chilo di piume pesa pi\`u di un chilo di ferro.} + +\bigskip + +\socrativeSA[10cm]{Quanto pesa un chilo di ferro?} + +\vspace*{\stretch{1}} + +\showSolution +{\bf \Large Sample quiz} {\it (soluzioni)} + +\socrativeMC[10cm]{Di che colore \`e il cavallo bianco di Napoleone?} + {Nero. \!\! Bianco. \!\! Rosso.}[2] + +\bigskip + +\socrativeTF[10cm]{Un chilo di piume pesa pi\`u di un chilo di ferro.}[0] + +\bigskip + +\socrativeSA[10cm]{Quanto pesa un chilo di ferro?}[1000 g] +\end{center} +\end{document} +\end{Verbatim} +produce un documento pdf con una pagina descritta nella Figura \ref{fig:ex2}. + +\begin{figure}[!ht] +\begin{center} +\begin{tikzpicture} +\useasboundingbox (0,0); +\node at (0,-11.9cm) [minimum width=16.75cm,minimum height=23.75cm,rectangle,draw,drop shadow={shadow xshift=.75ex, shadow yshift=-.75ex},fill=white]{}; +\end{tikzpicture} + +\includegraphics[scale=0.8]{sample-quiz2socrative-pdfQuiz.pdf} + + +\caption{\label{fig:ex2} La pagina prodotta dal file {\tt sample-quiz2socrative-pdfQuiz.tex}.} +\end{center} +\end{figure} + + +\end{document} + diff --git a/macros/latex/contrib/quiz2socrative/quiz2socrative.sty b/macros/latex/contrib/quiz2socrative/quiz2socrative.sty new file mode 100644 index 0000000000..f03b5d9dbd --- /dev/null +++ b/macros/latex/contrib/quiz2socrative/quiz2socrative.sty @@ -0,0 +1,230 @@ +% +% quiz2socrative.sty -- preparing questions for socrative quizzes +% by Paolo Lella <paolo.lella@polimi.it> +% +% quiz2socrative.sty is a LaTeX package for preparing +% multiple choice, true/false and short answer questions. +% The main purpouse is to offer a tool to easily insert rather complicated +% mathematical stuff in socrative quizzes (see https://socrative.com). +% +% This is quiz2socrative version 1.0, October 2019. +% quiz2socrative is distributed under the LaTeX Project Public License 1.3c. + +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{quiz2socrative}[2019/10/01 version 1.0 (Paolo Lella)] + +\RequirePackage{calc} +\RequirePackage{tikz} +\RequirePackage{etoolbox} +\RequirePackage{pgfmath} +\RequirePackage{graphicx} +\RequirePackage{xcolor} +\RequirePackage{moresize} +\RequirePackage{listofitems} +\RequirePackage{xparse} +\RequirePackage{ifthen} + +\setsepchar{\!\!} + +\usetikzlibrary{positioning,shapes.misc,shapes.geometric,backgrounds,fit} + +\newcommand{\@showBorder}{0} +\newcommand{\showBorder}{\renewcommand{\@showBorder}{1}} +\newcommand{\hideBorder}{\renewcommand{\@showBorder}{0}} + +\newcommand{\@mode}{0} + +\DeclareOption{pdfQuiz}{ + \renewcommand{\@mode}{1} + \renewcommand{\@showBorder}{1} +} + +\DeclareOption{socrativeQuiz}{ + \renewcommand{\@mode}{0} + \renewcommand{\@showBorder}{0} +} + +\newcommand{\usePdf}{\renewcommand{\@mode}{1}} +\newcommand{\useSocrative}{\renewcommand{\@mode}{0}} + +\newcommand{\@enumType}{} + +\DeclareOption{numbers}{ + \renewcommand{\@enumType}{\arabic} +} + +\DeclareOption{letters}{ + \renewcommand{\@enumType}{\Alph} +} + +\newcommand{\useNumbers}{\renewcommand{\@enumType}{\arabic}} +\newcommand{\useLetters}{\renewcommand{\@enumType}{\Alph}} + +\newcommand{\@trueLabel}{} +\newcommand{\@falseLabel}{} + +\DeclareOption{italian}{ + \renewcommand{\@trueLabel}{VERO} + \renewcommand{\@falseLabel}{FALSO} +} + +\DeclareOption{english}{ + \renewcommand{\@trueLabel}{TRUE} + \renewcommand{\@falseLabel}{FALSE} +} + +\newcommand{\useItalian}{ + \renewcommand{\@trueLabel}{VERO} + \renewcommand{\@falseLabel}{FALSO} + } +\newcommand{\useEnglish}{ + \renewcommand{\@trueLabel}{TRUE} + \renewcommand{\@falseLabel}{FALSE} + } + +\ExecuteOptions{letters,italian,socrativeQuiz} +\ProcessOptions\relax + +\newcommand{\@showSolution}{0} +\newcommand{\showSolution}{\renewcommand{\@showSolution}{1} \renewcommand{\@mode}{1}} +\newcommand{\hideSolution}{\renewcommand{\@showSolution}{0}} + +\newcounter{rispostaCorrente} +\newcounter{rispostaGiusta} + + +\NewDocumentCommand{\socrativeTF}{O{8cm} m o}{ +\begin{tikzpicture}[node distance = 0mm] +\node (Q) at (0,0) [rectangle,minimum width=#1,inner ysep=0.25cm] {\parbox{#1-.5cm}{#2}}; +\ifnumcomp{\@mode}{=}{1}{ + \node (V) [below=of Q,xshift=-0.25*#1,minimum width=0.5*#1-0.5cm,minimum height=1cm,draw,rectangle,inner ysep=0.25cm] {\large\bf \@trueLabel}; + \node (F) [below=of Q,xshift=0.25*#1,minimum width=0.5*#1-0.5cm,minimum height=1cm,draw,rectangle,inner ysep=0.25cm] {\large\bf \@falseLabel}; + \ifnumcomp{\@showSolution}{=}{1}{ + \IfNoValueTF{#3}{ + \PackageError{quiz2socrative}{missing solution}{add [0] if the answer is FALSE and [1] if the answer is TRUE at the end of the command string} + }{ + \ifnumcomp{#3}{=}{1}{% + \node [below=of Q,xshift=-0.25*#1,minimum width=0.5*#1-0.5cm,minimum height=1cm,draw,cross out,thick] {}; + }{}% + \ifnumcomp{#3}{=}{0}{% + \node [below=of Q,xshift=0.25*#1,minimum width=0.5*#1-0.5cm,minimum height=1cm,draw,cross out,thick] {}; + }{}% + } + }{}% +}{} +\ifnumcomp{\@showBorder}{=}{1}{ + \ifnumcomp{\@mode}{=}{1}{ + \node (A) [below=of Q,minimum width=#1,minimum height=1.25cm,rectangle] {}; + \draw (Q.north east) -- (Q.north west) -- (A.south west) -- (A.south east) -- cycle; + }{ + \draw (Q.north east) -- (Q.north west) -- (Q.south west) -- (Q.south east) -- cycle; + } +}{} +\end{tikzpicture} +}% end \socrativeTF + +\NewDocumentCommand{\socrativeMC}{O{8cm} m m o}{ +\setsepchar{\!\!} +\readlist*\listaRisposte{#3} +\ifnumcomp{\@showSolution}{=}{1}{ + \IfNoValueTF{#4}{ + \PackageError{quiz2socrative}{missing solution}{add the list [ , ... , ] of the correct answers at the end of the command string} + }{ + \setsepchar{,} + \readlist*\listaRisposteCorrette{#4} + } +}{} +\setcounter{rispostaCorrente}{0} +\begin{tikzpicture}[node distance=0mm] +\node (0) at (0,0) [] {}; +\node (Q) [above=of 0,yshift=-0.3cm,rectangle,minimum width=#1,inner ysep=0.3cm] {\parbox[t]{#1-0.5cm}{#2}}; + +\foreach \i in {1,...,\listaRispostelen}{ +\addtocounter{rispostaCorrente}{1} +\node (0) [below=of 0,rectangle, minimum width=#1,minimum height=1cm,inner ysep=0.3cm] {\hspace*{0.75cm}\parbox[t]{#1-1.25cm}{\listaRisposte[\i]}}; +\node at (0.north west) [xshift=0.5cm,yshift=-0.5cm,rectangle,draw,minimum width=0.6cm,minimum height=0.6cm] {\bf\large \@enumType{rispostaCorrente}}; +\ifnumcomp{\@showSolution}{=}{1}{ + \setcounter{rispostaGiusta}{0} + \foreach \j in {1,...,\listaRisposteCorrettelen}{ + \ifnumcomp{\listaRisposteCorrette[\j]}{=}{\value{rispostaCorrente}}{\breakforeach}{\addtocounter{rispostaGiusta}{1}} + } + \ifnumcomp{\value{rispostaGiusta}}{<}{\listaRisposteCorrettelen}{ + \node at (0.north west) [xshift=0.5cm,yshift=-0.5cm,cross out,thick,draw,minimum width=0.5cm,minimum height=0.5cm] {\bf \phantom{\@enumType{rispostaCorrente}}}; + }{} +}{} +} + +\ifnumcomp{\@showBorder}{=}{1}{ + \draw (Q.north east) -- (Q.north west) -- (0.south west) -- (0.south east) -- cycle; +}{} +\end{tikzpicture} +}% end \socrativeMC + +\NewDocumentCommand{\socrativeTwoMC}{O{8cm} m m m o}{ +\IfNoValueTF{#5}{ + \socrativeMC[#1]{#2}{#3 \!\! #4} +}{ + \socrativeMC[#1]{#2}{#3 \!\! #4}[#5] +} +} + +\NewDocumentCommand{\socrativeThreeMC}{O{8cm} m m m m o}{ +\IfNoValueTF{#6}{ + \socrativeMC[#1]{#2}{#3 \!\! #4 \!\! #5} +}{ + \socrativeMC[#1]{#2}{#3 \!\! #4 \!\! #5}[#6] +} +} + +\NewDocumentCommand{\socrativeFourMC}{O{8cm} m m m m m o}{ +\IfNoValueTF{#7}{ + \socrativeMC[#1]{#2}{#3 \!\! #4 \!\! #5 \!\! #6} +}{ + \socrativeMC[#1]{#2}{#3 \!\! #4 \!\! #5 \!\! #6}[#7] +} +} + +\NewDocumentCommand{\socrativeFiveMC}{O{8cm} m m m m m m o}{ +\IfNoValueTF{#8}{ + \socrativeMC[#1]{#2}{#3 \!\! #4 \!\! #5 \!\! #6 \!\! #7} +}{ + \socrativeMC[#1]{#2}{#3 \!\! #4 \!\! #5 \!\! #6 \!\! #7}[#8] +} +} + +\NewDocumentCommand{\socrativeSA}{O{8cm} m o}{ +\begin{tikzpicture}[node distance = 0mm] +\node (Q) at (0,0) [rectangle,minimum width=#1,inner ysep=0.25cm] {\parbox{#1-.5cm}{#2}}; +\ifnumcomp{\@mode}{=}{1}{ + \IfNoValueTF{#3}{ + \ifnumcomp{\@showSolution}{=}{1}{ + \PackageError{quiz2socrative}{missing solution}{add the answer in square brackets at the end of the command string} + }{ + \node (A) [below=of Q,minimum width=#1-0.5cm,minimum height=1cm,rectangle,draw] {}; + } + }{ + \ifnumcomp{\@showSolution}{=}{1}{ + \node (A) [below=of Q,minimum width=#1-0.5cm,minimum height=1cm,rectangle,draw] {\parbox{#1-1cm}{#3}}; + }{ + \node (A) [below=of Q,minimum width=#1-0.5cm,minimum height=1cm,rectangle,draw,fill=white] {\parbox{#1-1cm}{\textcolor{white}{#3}}}; + } + } +}{} +\ifnumcomp{\@showBorder}{=}{1}{ + \ifnumcomp{\@mode}{=}{1}{ + \node (L) [below=of A,inner sep = 0pt,yshift=-0.15cm] {}; + \begin{pgfonlayer}{background} + \node [draw,rectangle,inner xsep=0,inner ysep=0.2pt,fit=(Q) (L)] {}; + \end{pgfonlayer} + }{ + \begin{pgfonlayer}{background} + \node [draw,rectangle,inner sep=0,fit=(Q)] {}; + \end{pgfonlayer} + } +}{} +\end{tikzpicture} +}% end \socrativeSA + + +\endinput + diff --git a/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-pdfQuiz.pdf b/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-pdfQuiz.pdf Binary files differnew file mode 100644 index 0000000000..7d2373fc95 --- /dev/null +++ b/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-pdfQuiz.pdf diff --git a/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-pdfQuiz.tex b/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-pdfQuiz.tex new file mode 100644 index 0000000000..0fc1adf1db --- /dev/null +++ b/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-pdfQuiz.tex @@ -0,0 +1,40 @@ +\documentclass[12pt]{article} + +\usepackage[pdfQuiz]{quiz2socrative} +\usepackage[a4paper]{geometry} + +\begin{document} +\thispagestyle{empty} + +\begin{center} +{\bf \Large Sample quiz} + +\socrativeMC[10cm]{Di che colore \`e il cavallo bianco di Napoleone?} + {Nero. \!\! Bianco. \!\! Rosso.} + +\bigskip + +\socrativeTF[10cm]{Un chilo di piume pesa pi\`u di un chilo di ferro.} + +\bigskip + +\socrativeSA[10cm]{Quanto pesa un chilo di ferro?} + +\vspace*{\stretch{1}} + +\showSolution +{\bf \Large Sample quiz} {\it (soluzioni)} + +\socrativeMC[10cm]{Di che colore \`e il cavallo bianco di Napoleone?} + {Nero. \!\! Bianco. \!\! Rosso.}[2] + +\bigskip + +\socrativeTF[10cm]{Un chilo di piume pesa pi\`u di un chilo di ferro.}[0] + +\bigskip + +\socrativeSA[10cm]{Quanto pesa un chilo di ferro?}[1000 g] +\end{center} +\end{document} + diff --git a/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-socrativeQuiz+standalone.pdf b/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-socrativeQuiz+standalone.pdf Binary files differnew file mode 100644 index 0000000000..b660223387 --- /dev/null +++ b/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-socrativeQuiz+standalone.pdf diff --git a/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-socrativeQuiz+standalone.tex b/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-socrativeQuiz+standalone.tex new file mode 100644 index 0000000000..a6ea33418f --- /dev/null +++ b/macros/latex/contrib/quiz2socrative/sample-quiz2socrative-socrativeQuiz+standalone.tex @@ -0,0 +1,15 @@ +\documentclass[tikz]{standalone} + +\usepackage[socrativeQuiz]{quiz2socrative} + +\begin{document} + +\socrativeMC{Di che colore \`e il cavallo bianco di Napoleone?} + {Nero. \!\! Bianco. \!\! Rosso.} + +\socrativeTF{Un chilo di piume pesa pi\`u di un chilo di ferro.} + +\socrativeSA{Quanto pesa un chilo di ferro?} + +\end{document} + |