summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/zref-clever/zref-clever.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-12-08 03:02:13 +0000
committerNorbert Preining <norbert@preining.info>2021-12-08 03:02:13 +0000
commit0bfca40c9f89076ad634464a530fcc3e55d1d4e1 (patch)
tree7114d7d6b3ef883e247cfa80d6d36d0938b7c4f0 /macros/latex/contrib/zref-clever/zref-clever.dtx
parent6336c19969656f3ee5f0b0fed00aaf64369a40e7 (diff)
CTAN sync 202112080302
Diffstat (limited to 'macros/latex/contrib/zref-clever/zref-clever.dtx')
-rw-r--r--macros/latex/contrib/zref-clever/zref-clever.dtx224
1 files changed, 123 insertions, 101 deletions
diff --git a/macros/latex/contrib/zref-clever/zref-clever.dtx b/macros/latex/contrib/zref-clever/zref-clever.dtx
index 024aa50a99..ac9d81f44e 100644
--- a/macros/latex/contrib/zref-clever/zref-clever.dtx
+++ b/macros/latex/contrib/zref-clever/zref-clever.dtx
@@ -24,7 +24,7 @@
% zref-clever.ins,
% zref-clever.tex,
% zref-clever-code.tex,
-% and the derived files listed in MANIFEST.md.
+% and the files listed in MANIFEST.md.
%
% The released version of this package is available from CTAN.
%
@@ -60,41 +60,54 @@
% \DoNotIndex{\c@,\cl@,\c@enumN,\p@}
% \DoNotIndex{\the}
%
+% \NewDocumentCommand\githubissue{m}{^^A
+% issue~\href{https://github.com/gusbrs/zref-clever/issues/#1}{\##1}}
+%
+% ^^A Currently just for keeping semantic markup on this.
+% \NewDocumentCommand\contributor{m}{#1}
%
% \NewDocumentCommand\opt{m}{\texttt{#1}}
%
-% \pdfstringdefDisableCommands{%
+% \pdfstringdefDisableCommands{^^A
% \def\opt#1{#1}
% }
%
% ^^A Have the Index at 'section' level rather than 'part'. Otherwise it is
% ^^A just the same definition from 'l3doc.cls'.
-% \IndexPrologue{%
+% \IndexPrologue{^^A
% \section*{Index}
% \markboth{Index}{Index}
% \addcontentsline{toc}{section}{Index}
% The italic numbers denote the pages where the corresponding entry is
% described, numbers underlined point to the definition, all others indicate
-% the places where it is used.%
+% the places where it is used.^^A
% }
%
%
% \GetFileInfo{zref-clever.sty}
%
-% \title{%
-% The \pkg{zref-clever} package implementation%
-% \thanks{This file describes \fileversion, released \filedate.}%
+% \title{^^A
+% The \pkg{zref-clever} package^^A
+% \thanks{This file describes \fileversion, released \filedate.}^^A
+% \texorpdfstring{\\{}\medskip{}}{ - }^^A
+% Code documentation^^A
+% \texorpdfstring{\medskip{}}{}^^A
% }
%
-% \author{%
-% Gustavo Barros%
-% \thanks{\url{https://github.com/gusbrs/zref-clever}}%
+% \author{^^A
+% Gustavo Barros^^A
+% \thanks{\url{https://github.com/gusbrs/zref-clever}}^^A
% }
%
% \date{\filedate}
%
% \maketitle
%
+% \begin{center}
+% \textbf{EXPERIMENTAL}
+% \end{center}
+%
+%
% \tableofcontents
%
%
@@ -120,14 +133,14 @@
% release). Finally, a couple of changes came with the 2021-11-15 kernel
% release, which are important here. First, a fix was made to the new hook
% management system (\pkg{ltcmdhooks}), with implications to the hook we add
-% to \cs{appendix} (see \url{https://tex.stackexchange.com/q/617905} and
-% \url{https://github.com/latex3/latex2e/pull/699}, thanks Phelype Oleinik).
-% Second, the support for \cs{@currentcounter} has been improved, including
-% \cs{footnote} and \pkg{amsmath} (see
-% \url{https://github.com/latex3/latex2e/issues/687}, thanks Frank Mittelbach
-% and Ulrike Fischer). Hence, since we would not be able to go much backwards
-% without special handling anyway, we make the cut at the 2021-11-15 kernel
-% release.
+% to \cs{appendix} (by \contributor{Phelype Oleinik} at
+% \url{https://tex.stackexchange.com/q/617905} and
+% \url{https://github.com/latex3/latex2e/pull/699}). Second, the support for
+% \cs{@currentcounter} has been improved, including \cs{footnote} and
+% \pkg{amsmath} (by \contributor{Frank Mittelbach} and \contributor{Ulrike
+% Fischer} at \url{https://github.com/latex3/latex2e/issues/687}). Hence,
+% since we would not be able to go much backwards without special handling
+% anyway, we make the cut at the 2021-11-15 kernel release.
%
% \begin{macrocode}
\providecommand\IfFormatAtLeastTF{\@ifl@t@r\fmtversion}
@@ -146,7 +159,7 @@
%
% Identify the package.
% \begin{macrocode}
-\ProvidesExplPackage {zref-clever} {2021-11-24} {0.1.0-alpha}
+\ProvidesExplPackage {zref-clever} {2021-12-07} {0.1.1-alpha}
{Clever LaTeX cross-references based on zref}
% \end{macrocode}
%
@@ -200,9 +213,9 @@
% \emph{more reliable} than \cs{@currentcounter}, \texttt{thecounter} is meant
% to be kept as an \emph{option} (\opt{ref} option), in case there's need to
% use \pkg{zref-clever} together with \cs{labelformat}. Based on the
-% definition of \cs{@currentlabel} done inside \cs{refstepcounter} in `texdoc
-% source2e', section `ltxref.dtx'. We just drop the \cs[no-index]{p@...}
-% prefix.
+% definition of \cs{@currentlabel} done inside \cs{refstepcounter} in
+% \texttt{texdoc source2e}, section \texttt{ltxref.dtx}. We just drop the
+% \cs[no-index]{p@...} prefix.
%
% \begin{macrocode}
\zref@newprop { thecounter }
@@ -360,9 +373,9 @@
% call. I'll stay with the \texttt{e} variant, since conceptually it is what
% I want (\texttt{x} itself is not expandable), and this package is anyway not
% compatible with older kernels for which the performance penalty of the
-% \texttt{e} expansion would ensue (see also
-% \url{https://tex.stackexchange.com/q/611370/#comment1529282_611385}, thanks
-% Enrico Gregorio, aka `egreg').
+% \texttt{e} expansion would ensue (helpful comment by \contributor{Enrico
+% Gregorio}, aka `egreg' at
+% \url{https://tex.stackexchange.com/q/611370/#comment1529282_611385}).
% \begin{macrocode}
\cs_generate_variant:Nn \@@_get_enclosing_counters_value:n { e }
% \end{macrocode}
@@ -1560,9 +1573,9 @@
% existence of the property itself, as far as \pkg{zref} is concerned. This
% because typesetting relies on the check \cs{zref@ifrefcontainsprop}, which
% \emph{presumes} the property is defined and silently expands the \emph{true}
-% branch if it is not (see \url{https://github.com/ho-tex/zref/issues/13},
-% thanks Ulrike Fischer). Therefore, before adding anything to
-% \cs{l_@@_ref_property_tl}, check if first here with
+% branch if it is not (insightful comments by \contributor{Ulrike Fischer} at
+% \url{https://github.com/ho-tex/zref/issues/13}). Therefore, before adding
+% anything to \cs{l_@@_ref_property_tl}, check if first here with
% \cs{zref@ifpropundefined}: close it at the door.
%
%
@@ -2018,10 +2031,11 @@
% polluting the markup too much given that, for languages that need it, it may
% get to be used frequently.
%
-% Thanks \texttt{@samcarter} and Alan Munn for useful comments about
-% declension on the TeX.SX chat. Also, Florent Rougon's efforts in this area,
-% with the \pkg{xcref} package (\url{https://github.com/frougon/xcref}), have
-% been an insightful source to frame the problem in general terms.
+% \contributor{\texttt{@samcarter}} and \contributor{Alan Munn} provided
+% useful comments about declension on the TeX.SX chat. Also,
+% \contributor{Florent Rougon}'s efforts in this area, with the \pkg{xcref}
+% package (\url{https://github.com/frougon/xcref}), have been an insightful
+% source to frame the problem in general terms.
%
% \begin{macrocode}
\tl_new:N \l_@@_ref_decl_case_tl
@@ -2137,7 +2151,8 @@
% \url{https://tex.stackexchange.com/a/489570}). It can be set in \cs{zcref}
% and, for global settings, with \cs{zcsetup}. Note that, technically, the
% ``raw'' options are already available as \cs{@raw@opt@\meta{package}.sty}
-% (see \url{https://tex.stackexchange.com/a/618439}, thanks David Carlisle).
+% (helpful comment by \contributor{David Carlisle} at
+% \url{https://tex.stackexchange.com/a/618439}).
%
% \begin{macrocode}
\tl_new:N \l_@@_ref_typeset_font_tl
@@ -2258,6 +2273,26 @@
}
% \end{macrocode}
%
+% One interesting comment I received (by \contributor{Denis Bitouzé}, at
+% \githubissue{1}) about the most appropriate type for \texttt{paragraph} and
+% \texttt{subparagraph} counters was that the reader of the document does not
+% care whether that particular document structure element has been introduced
+% by \cs{paragraph} or, e.g.\ by the \cs{subsubsection} command. This is a
+% difference the author knows, as they're using \LaTeX{}, but to the reader
+% the difference between them is not really relevant, and it may be just
+% confusing to refer to them by different names. In this case the type for
+% \texttt{paragraph} and \texttt{subparagraph} should just be
+% \texttt{section}. I don't have a strong opinion about this, and the matter
+% was not pursued further. Besides, I presume not many people would set
+% \texttt{secnumdepth} so high to start with. But, for the time being, I left
+% the \texttt{paragraph} type for them, since there is actually a visual
+% difference to the reader between the \cs{subsubsection} and \cs{paragraph}
+% in the standard classes: up to the former, the sectioning commands break a
+% line before the following text, while, from the later on, the sectioning
+% commands and the following text are part of the same line. So,
+% \cs{paragraph} is actually different from ``just a shorter way to write
+% \cs{subsubsubsection}''.
+%
%
% \subsubsection*{\opt{counterresetters} option}
%
@@ -2577,9 +2612,10 @@
% value'' (\texttt{key}). This distinction is captured internally by the
% lower-level key parsing, but must be made explicit at \cs{keys_set:nn} by
% means of the \texttt{.default:V} property of the key in \cs{keys_define:nn}.
-% For the technique and some discussion about it, see
-% \url{https://tex.stackexchange.com/q/614690} (thanks Jonathan P.\ Spratte,
-% aka `Skillmon', and Phelype Oleinik) and
+% For the technique, by \contributor{Jonathan P.\ Spratte}, aka `Skillmon',
+% and some discussion about it, including further insights by
+% \contributor{Phelype Oleinik}, see
+% \url{https://tex.stackexchange.com/q/614690} and
% \url{https://github.com/latex3/latex3/pull/988}.
%
% \begin{macrocode}
@@ -3490,20 +3526,21 @@
% One further thing to discuss here -- to keep this ``on record'' -- is
% inhibition of compression for individual labels. It is not difficult to
% handle it at the infrastructure side, what gets sloppy is the user facing
-% syntax to signal such inhibition. For some possible alternatives for this
-% (and good ones at that) see \url{https://tex.stackexchange.com/q/611370}
-% (thanks Enrico Gregorio, Phelype Oleinik, and Steven B.\ Segletes). Yet
-% another alternative would be an option receiving the label(s) not to be
-% compressed, this would be a repetition, but would keep the syntax clean.
-% All in all, probably the best is simply not to allow individual inhibition
-% of compression. We can already control compression of each \cs{zcref} call
-% with existing options, this should be enough. I don't think the small extra
-% flexibility individual label control for this would grant is worth the
-% syntax disruption it would entail. Anyway, it would be easy to deal with
-% this in case the need arose, by just adding another condition (coming from
-% whatever the chosen syntax was) when we check for
-% \cs{@@_labels_in_sequence:nn} in \cs{@@_typeset_refs_not_last_of_type:}.
-% But I remain unconvinced of the pertinence of doing so.
+% syntax to signal such inhibition. For some possible alternatives for this,
+% suggested by \contributor{Enrico Gregorio}, \contributor{Phelype Oleinik},
+% and \contributor{Steven B.\ Segletes} (and good ones at that) see
+% \url{https://tex.stackexchange.com/q/611370}. Yet another alternative would
+% be an option receiving the label(s) not to be compressed, this would be a
+% repetition, but would keep the syntax clean. All in all, probably the best
+% is simply not to allow individual inhibition of compression. We can already
+% control compression of each \cs{zcref} call with existing options, this
+% should be enough. I don't think the small extra flexibility individual
+% label control for this would grant is worth the syntax disruption it would
+% entail. Anyway, it would be easy to deal with this in case the need arose,
+% by just adding another condition (coming from whatever the chosen syntax
+% was) when we check for \cs{@@_labels_in_sequence:nn} in
+% \cs{@@_typeset_refs_not_last_of_type:}. But I remain unconvinced of the
+% pertinence of doing so.
%
%
% \subsection*{Variables}
@@ -4991,9 +5028,10 @@
% the command being hooked at contains a double hash mark (\texttt{\#\#}) the
% patch to add the hook, if it needs to be done with the \cs{scantokens}
% method, may fail noisily (see \url{https://tex.stackexchange.com/q/617905},
-% thanks Phelype Oleinik). The 2021-11-15 kernel release already handle this
-% gracefully (see \url{https://github.com/latex3/latex2e/pull/699}, thanks
-% Phelype Oleinik).
+% with a detailed explanation and possible workaround by \contributor{Phelype
+% Oleinik}). The 2021-11-15 kernel release already handles this gracefully,
+% thanks to fix by \contributor{Phelype Oleinik} at
+% \url{https://github.com/latex3/latex2e/pull/699}.
%
%
% \subsection{\opt{appendices}}
@@ -5716,8 +5754,17 @@
%
% \section{Dictionaries}
%
+% Initial values for the English, German, French, Portuguese, and Spanish,
+% dictionaries have been provided by the author. Translations available for
+% document elements' names in other packages have been an useful reference for
+% the purpose, namely: \pkg{babel}, \pkg{cleveref}, \pkg{translator}, and
+% \pkg{translations}.
+%
+%
% \subsection{English}
%
+% English dictionary has been initially provided by the author.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage { english }
@@ -5786,12 +5833,6 @@ type = appendix ,
Name-pl = Appendices ,
name-pl = appendices ,
-type = subappendix ,
- Name-sg = Appendix ,
- name-sg = appendix ,
- Name-pl = Appendices ,
- name-pl = appendices ,
-
type = page ,
Name-sg = Page ,
name-sg = page ,
@@ -5946,6 +5987,8 @@ type = solution ,
%
% \subsection{German}
%
+% German dictionary has been initially provided by the author.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage
@@ -6065,21 +6108,6 @@ type = appendix ,
Name-sg = Anhangs ,
Name-pl = Anhänge ,
-type = subappendix ,
- gender = m ,
- case = N ,
- Name-sg = Anhang ,
- Name-pl = Anhänge ,
- case = A ,
- Name-sg = Anhang ,
- Name-pl = Anhänge ,
- case = D ,
- Name-sg = Anhang ,
- Name-pl = Anhängen ,
- case = G ,
- Name-sg = Anhangs ,
- Name-pl = Anhänge ,
-
type = page ,
gender = f ,
case = N ,
@@ -6430,6 +6458,14 @@ type = solution ,
%
% \subsection{French}
%
+% French dictionary has been initially provided by the author, and has been
+% improved thanks to Denis Bitouzé (\githubissue{1}) and participants of the
+% Groupe francophone des Utilisateurs de \TeX{} (GUTenberg) (at
+% \url{https://groups.google.com/g/gut_fr/c/rNLm6weGcyg}) and the
+% \texttt{fr.comp.text.tex} (at
+% \url{https://groups.google.com/g/fr.comp.text.tex/c/Fa11Tf6MFFs}) mailing
+% lists.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage [ gender = { f , m } ] { french }
@@ -6497,20 +6533,13 @@ type = appendix ,
Name-pl = Annexes ,
name-pl = annexes ,
-type = subappendix ,
- gender = f ,
- Name-sg = Annexe ,
- name-sg = annexe ,
- Name-pl = Annexes ,
- name-pl = annexes ,
-
type = page ,
gender = f ,
Name-sg = Page ,
name-sg = page ,
Name-pl = Pages ,
name-pl = pages ,
- rangesep = {\textendash} ,
+ rangesep = {-} ,
type = line ,
gender = f ,
@@ -6641,11 +6670,11 @@ type = algorithm ,
name-pl = algorithmes ,
type = listing ,
- gender = f ,
- Name-sg = Liste ,
- name-sg = liste ,
- Name-pl = Listes ,
- name-pl = listes ,
+ gender = m ,
+ Name-sg = Listing ,
+ name-sg = listing ,
+ Name-pl = Listings ,
+ name-pl = listings ,
type = exercise ,
gender = m ,
@@ -6670,6 +6699,11 @@ type = solution ,
%
% \subsection{Portuguese}
%
+% Portuguese dictionary provided by the author, who's a native speaker of
+% (Brazilian) Portuguese. I do expect this to be sufficiently general, but if
+% Portuguese speakers from other places feel the need for a Portuguese
+% variant, please let me know.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage [ gender = { f , m } ] { portuguese }
@@ -6740,13 +6774,6 @@ type = appendix ,
Name-pl = Apêndices ,
name-pl = apêndices ,
-type = subappendix ,
- gender = m ,
- Name-sg = Apêndice ,
- name-sg = apêndice ,
- Name-pl = Apêndices ,
- name-pl = apêndices ,
-
type = page ,
gender = f ,
Name-sg = Página ,
@@ -6923,6 +6950,8 @@ type = solution ,
%
% \subsection{Spanish}
%
+% Spanish dictionary has been initially provided by the author.
+%
% \begin{macrocode}
%<*package>
\zcDeclareLanguage [ gender = { f , m } ] { spanish }
@@ -6986,13 +7015,6 @@ type = appendix ,
Name-pl = Apéndices ,
name-pl = apéndices ,
-type = subappendix ,
- gender = m ,
- Name-sg = Apéndice ,
- name-sg = apéndice ,
- Name-pl = Apéndices ,
- name-pl = apéndices ,
-
type = page ,
gender = f ,
Name-sg = Página ,