diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md | 28 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md | 38 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf | bin | 1040673 -> 1069860 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex | 2 | ||||
| -rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf | bin | 305580 -> 306402 bytes | |||
| -rw-r--r-- | Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex | 310 |
6 files changed, 208 insertions, 170 deletions
diff --git a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md index e190d38d68c..5a5addd47ee 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md +++ b/Master/texmf-dist/doc/latex/zref-clever/CHANGELOG.md @@ -1,15 +1,39 @@ # Changelog -## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.1.1-alpha...HEAD) +## [Unreleased](https://github.com/gusbrs/zref-clever/compare/v0.1.2-alpha...HEAD) + +## [v0.1.2-alpha](https://github.com/gusbrs/zref-clever/compare/v0.1.1-alpha...v0.1.2-alpha) (2022-01-10) + +### Added +- Provided Dutch language file (see PR + [#5](https://github.com/gusbrs/zref-clever/pull/5)). + +### Changed +- The `gender` key in `\zcLanguageSetup` and in the built-in language files + can receive a comma separated list as value to support types with multiple + valid genders. +- The `cap` and `abbrev` options can now be set also in `\zcRefTypeSetup` and + `\zcLanguageSetup`, so that fine grained control per-type and per-language + is now possible for these options. +- Abandoned the "dictionary/translation" metaphor to refer to language + specific options. Mostly housekeeping, affecting the name-scheme of + functions and variables, but aiming at a clearer documentation in this area, + specially in the longer term. + +### Deprecated +- The reference format options `refpre` and `refpos` have been deprecated in + favor or the more aptly named `preref` and `postref`, respectively. ## [v0.1.1-alpha](https://github.com/gusbrs/zref-clever/compare/v0.1.0-alpha...v0.1.1-alpha) (2021-12-07) ### Changed - Improvements to the French dictionary (see issue [#1](https://github.com/gusbrs/zref-clever/issues/1)). -- Dropped the `subappendix` reference type. - Improvements to documentation. +### Removed +- Dropped the `subappendix` reference type. + ## [v0.1.0-alpha](https://github.com/gusbrs/zref-clever/releases/tag/v0.1.0-alpha) (2021-00-24) ### Added diff --git a/Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md b/Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md index e40fb05bf09..a52c56a9ee0 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md +++ b/Master/texmf-dist/doc/latex/zref-clever/MANIFEST.md @@ -42,11 +42,12 @@ The files created by ‘unpacking’ the package sources. This typically include `.sty` and `.cls` files created from DocStrip `.dtx` files. * zref-clever.sty † -* zref-clever-english.dict † -* zref-clever-french.dict † -* zref-clever-german.dict † -* zref-clever-portuguese.dict † -* zref-clever-spanish.dict † +* zref-clever-dutch.lang † +* zref-clever-english.lang † +* zref-clever-french.lang † +* zref-clever-german.lang † +* zref-clever-portuguese.lang † +* zref-clever-spanish.lang † ### Typeset documents @@ -82,8 +83,6 @@ different engines (pdfTeX, XeTeX, LuaTeX, etc.). * zc-compat-memoir01.lvt * zc-compat-subcaption01.lvt * zc-compat-subfig01.lvt -* zc-dictionaries01.lvt -* zc-dictionaries02.lvt * zc-howto-amsmath01.lvt * zc-howto-enumitem01.lvt * zc-howto-listings01.lvt @@ -98,6 +97,8 @@ different engines (pdfTeX, XeTeX, LuaTeX, etc.). * zc-howto-newtheorem04.lvt * zc-howto-zref-xr01.lvt * zc-label-options01.lvt +* zc-langfiles01.lvt +* zc-langfiles02.lvt * zc-languages01.lvt * zc-opt-check01.lvt * zc-opt-d01.lvt @@ -219,12 +220,6 @@ different engines (pdfTeX, XeTeX, LuaTeX, etc.). * zc-compat-subfig01.tlg * zc-compat-subfig01.xetex.tlg * zc-compat-subfig01.xetexdev.tlg -* zc-dictionaries01.tlg -* zc-dictionaries02.luatex.tlg -* zc-dictionaries02.luatexdev.tlg -* zc-dictionaries02.tlg -* zc-dictionaries02.xetex.tlg -* zc-dictionaries02.xetexdev.tlg * zc-howto-amsmath01.luatex.tlg * zc-howto-amsmath01.luatexdev.tlg * zc-howto-amsmath01.tlg @@ -293,6 +288,12 @@ different engines (pdfTeX, XeTeX, LuaTeX, etc.). * zc-label-options01.luatex.tlg * zc-label-options01.luatexdev.tlg * zc-label-options01.tlg +* zc-langfiles01.tlg +* zc-langfiles02.luatex.tlg +* zc-langfiles02.luatexdev.tlg +* zc-langfiles02.tlg +* zc-langfiles02.xetex.tlg +* zc-langfiles02.xetexdev.tlg * zc-languages01.tlg * zc-opt-check01.luatex.tlg * zc-opt-check01.luatexdev.tlg @@ -419,11 +420,12 @@ All files included in the `zref-clever/source` directory. All files included in the `zref-clever/tex` directory. -* zref-clever-english.dict -* zref-clever-french.dict -* zref-clever-german.dict -* zref-clever-portuguese.dict -* zref-clever-spanish.dict +* zref-clever-dutch.lang +* zref-clever-english.lang +* zref-clever-french.lang +* zref-clever-german.lang +* zref-clever-portuguese.lang +* zref-clever-spanish.lang * zref-clever.sty ### Doc files (TDS) diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf Binary files differindex f8d0003a960..b955c4c59f6 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.pdf diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex index a4ebabd625e..edc439e5c31 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever-code.tex @@ -4,7 +4,7 @@ % % This file is part of the LaTeX package "zref-clever". % -% Copyright (C) 2021 Gustavo Barros +% Copyright (C) 2021-2022 Gustavo Barros % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf Binary files differindex 84f9a28b55e..1c64f52147e 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.pdf diff --git a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex index 4da3b2453d1..a4e3ab8638f 100644 --- a/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex +++ b/Master/texmf-dist/doc/latex/zref-clever/zref-clever.tex @@ -4,7 +4,7 @@ % % This file is part of the LaTeX package "zref-clever". % -% Copyright (C) 2021 Gustavo Barros +% Copyright (C) 2021-2022 Gustavo Barros % % It may be distributed and/or modified under the conditions of the % LaTeX Project Public License (LPPL), either version 1.3c of this @@ -56,8 +56,6 @@ \usepackage{listings} \usepackage{microtype} -% TEMP work-around for https://github.com/schlcht/microtype/issues/4 -\microtypesetup{nopatch=item} \hypersetup{hidelinks} @@ -523,9 +521,10 @@ The option given without a value is equivalent to \texttt{range=true} (in the \DescribeOption{nocap} % \DescribeOption{capfirst} % The \opt{cap} option controls whether the reference type names should be -capitalized or not. It is a boolean option, and the package's default is -\texttt{cap=false}. The option given without a value is equivalent to -\texttt{cap=true}. The \opt{nocap} option is a convenience alias for +capitalized or not. It can receive values \texttt{true} or \texttt{false}, +and it can also be set for specific reference types or languages (see +\zcref{sec:reference-format}). The option given without a value is equivalent +to \texttt{cap=true}. The \opt{nocap} option is a convenience alias for \texttt{cap=false}. The \opt{capfirst} option ensures that the reference type name of the \emph{first} type block is capitalized, even when \opt{cap} is set to \texttt{false}. @@ -534,9 +533,10 @@ to \texttt{false}. \DescribeOption{noabbrev} % \DescribeOption{noabbrevfirst} % The \opt{abbrev} option controls whether to use abbreviated reference type -names when they are available. It is a boolean option, and the package's -default is \texttt{abbrev=false}. The option given without a value is -equivalent to \texttt{abbrev=true}. The \opt{noabbrev} option is a +names when they are available. It can receive values \texttt{true} or +\texttt{false}, and it can also be set for specific reference types or +languages (see \zcref{sec:reference-format}). The option given without a +value is equivalent to \texttt{abbrev=true}. The \opt{noabbrev} option is a convenience alias for \texttt{abbrev=false}. The \opt{noabbrevfirst} ensures that the reference type name of the \emph{first} type block is never abbreviated, even when \opt{abbrev} is set to \texttt{true}. @@ -592,8 +592,8 @@ the second reference none of them will. The package's default is equivalent to \texttt{nameinlink=true}. \DescribeOption{preposinlink} % -The \opt{preposinlink} option controls whether the \opt{refpre} and -\opt{refpos} reference format options (see \zcref{sec:reference-format}) are +The \opt{preposinlink} option controls whether the \opt{preref} and +\opt{postref} reference format options (see \zcref{sec:reference-format}) are included in the reference hyperlink or not. It is a boolean option. The package's default is \texttt{preposinlink=false}, and the option given without a value is equivalent to \texttt{preposinlink=true}. @@ -650,15 +650,15 @@ is the way to tell \cs{zcref} you know it's a singular and so not to nudge if a compression to singular occurs, but to nudge if the contrary occurs, that is, when a plural type name form is employed. The \texttt{gender} nudge must be combined with option \opt{g}, and depends on the language having support -for it. In essence language dictionaries can store the gender of each type -name (this is done for built-in dictionaries, but can also be done with +for it. In essence language files can store the gender(s) of each type name +(this is done for built-in language files, but can also be done with \cs{zcLanguageSetup} for languages declared to support it). The \opt{g} option let's you specify the gender you expect for that particular reference and the nudge is triggered if there is a mismatch between \opt{g} and the -gender for the type name in the dictionary. Both the \texttt{comptosing} and -the \texttt{gender} nudges have a type block as its scope. See -\zcref{sec:internationalization} for more details and intended use cases of -the ``nudging'' feature. +gender(s) for the type name in the language file. Both the +\texttt{comptosing} and the \texttt{gender} nudges have a type block as its +scope. See \zcref{sec:internationalization} for more details and intended use +cases of the ``nudging'' feature. \DescribeOption{font} % The \opt{font} option can receive font styling commands to change the @@ -822,7 +822,7 @@ contrary may also happen, a \emph{counter} may be defined but we have no these reference types are available for use out of the box.\footnote{There may be slight availability differences depending on the language, but \pkg{zref-clever} strives to keep this complete list available for the - languages it has built-in dictionaries.} And, in any case, it is always + languages it has built-in language files.} And, in any case, it is always easy to setup custom reference types with \cs{zcRefTypeSetup} or \cs{zcLanguageSetup} (see \zcref{sec:user-interface, sec:reference-format, sec:internationalization}). @@ -883,71 +883,75 @@ less overarching effects, and some precedence rules to regulate the relation of settings given in each of these scopes. There are four scopes in which reference formatting can be specified by the user, in the following precedence order: i) as \emph{general options}; ii) as \emph{type-specific options}; iii) -as \emph{language-specific and type-specific translations}; and iv) as -\emph{default translations} (that is, language-specific but not -type-specific). Besides those, there's a fifth \emph{internal} scope, with -the least priority of all, a ``fallback'', for the cases where it is -meaningful to provide some value, even for an unknown language. The package -itself places the default setup for reference formatting at low precedence -levels, and the users can easily and conveniently override them as desired. - -``General options'' (i) can be given by the user in the optional argument of +as \emph{language- and type-specific options}; and iv) as +\emph{language-specific default options}. Besides those, there's a fifth +\emph{internal} scope, with the least priority of all, a ``fallback'', for the +cases where it is meaningful to provide some value, even for an unknown +language. The package itself places the default setup for reference +formatting at low precedence levels, and the users can easily and conveniently +override them as desired. + +``General'' options (i) can be given by the user in the optional argument of \cs{zcref}, but also set through \cs{zcsetup} or even, depending on the case, as package options at load-time (see \zcref{sec:options}).\footnote{The use of \cs{zcsetup} for global reference format settings is recommended though. Whether you can use load-time options or not depends on the values of the options: due to how \LaTeX{} handles package options, if the values of the options you are setting include \emph{commands} you can't set them at - load-time, and rather \emph{must} use \cs{zcsetup}.} ``Type-specific -options'' (ii) are handled by \cs{zcRefTypeSetup} (see -\zcref{sec:user-interface}). ``Language-specific translations'', be they -``type-specific'' (iii) or ``default'' (iv) have their user interface in -\cs{zcLanguageSetup}, and have their values populated by the package's -built-in dictionaries (see \zcref{sec:internationalization}). Not all -reference format specifications can be given in all of these scopes, though. -Some of them can't be type-specific, others must be type-specific, so the set -available in each scope depends on the pertinence of the case. -\zcref{tab:reference-format} introduces the available reference format -options, which will be discussed in more detail soon, and lists the scopes in -which each is available. + load-time, and rather \emph{must} use \cs{zcsetup}.} ``Type'' specific +options (ii) are handled by \cs{zcRefTypeSetup} (see +\zcref{sec:user-interface}). ``Language'' options, whether ``type'' specific +(iii) or ``default'' (iv) have their user interface in \cs{zcLanguageSetup}, +and have their values populated by the package's built-in language files (see +\zcref{sec:internationalization}). Not all reference format specifications +can be given in all of these scopes, though. Some of them can't be +type-specific, others must be type-specific, so the set available in each +scope depends on the pertinence of the case. \zcref{tab:reference-format} +introduces the available reference format options, which will be discussed in +more detail soon, and lists the scopes in which each is available. \begin{table}[htb] \centering \begin{tabular}{l>{\ttfamily}lcccc} \toprule - & & General & Type & Type-specific & Default \\ - & & options & options & translations & translations \\ - & & (i) & (ii) & (iii) & (iv) \\ + & & General & Type & \multicolumn{2}{c}{Language} \\ + \cmidrule(lr){5-6} + & & & & Type & Default \\ + & & (i) & (ii) & (iii) & (iv) \\ \midrule - Necessarily not & tpairsep & $\bullet$ & & & $\bullet$ \\ - type-specific & tlistsep & $\bullet$ & & & $\bullet$ \\ - & tlastsep & $\bullet$ & & & $\bullet$ \\ - & notesep & $\bullet$ & & & $\bullet$ \\ + Typesetting & tpairsep & $\bullet$ & & & $\bullet$ \\ + (necessarily not & tlistsep & $\bullet$ & & & $\bullet$ \\ + type-specific) & tlastsep & $\bullet$ & & & $\bullet$ \\ + & notesep & $\bullet$ & & & $\bullet$ \\ \addlinespace - Possibly & namesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ - type-specific & pairsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ - & listsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ - & lastsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ - & rangesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ - & refpre & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ - & refpos & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ + Typesetting & namesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ + (possibly & pairsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ + type-specific) & listsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ + & lastsep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ + & rangesep & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ + & preref & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ + & postref & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ \addlinespace - Necessarily & Name-sg & & $\bullet$ & $\bullet$ & \\ - type-specific & name-sg & & $\bullet$ & $\bullet$ & \\ - & Name-pl & & $\bullet$ & $\bullet$ & \\ - & name-pl & & $\bullet$ & $\bullet$ & \\ - & Name-sg-ab & & $\bullet$ & $\bullet$ & \\ - & name-sg-ab & & $\bullet$ & $\bullet$ & \\ - & Name-pl-ab & & $\bullet$ & $\bullet$ & \\ - & name-pl-ab & & $\bullet$ & $\bullet$ & \\ + Typesetting & Name-sg & & $\bullet$ & $\bullet$ & \\ + (necessarily & name-sg & & $\bullet$ & $\bullet$ & \\ + type-specific) & Name-pl & & $\bullet$ & $\bullet$ & \\ + & name-pl & & $\bullet$ & $\bullet$ & \\ + & Name-sg-ab & & $\bullet$ & $\bullet$ & \\ + & name-sg-ab & & $\bullet$ & $\bullet$ & \\ + & Name-pl-ab & & $\bullet$ & $\bullet$ & \\ + & name-pl-ab & & $\bullet$ & $\bullet$ & \\ \addlinespace - Font & namefont & $\bullet$ & $\bullet$ & & \\ - options & reffont & $\bullet$ & $\bullet$ & & \\ + Font & namefont & $\bullet$ & $\bullet$ & & \\ + & reffont & $\bullet$ & $\bullet$ & & \\ + + \addlinespace + Other & cap & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ + & abbrev & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\ \bottomrule \end{tabular} \caption{Reference format options and their scopes} @@ -963,7 +967,7 @@ that which a standard \LaTeX{} \cs{ref} would typeset. A \pkg{zref-clever} \begin{refformat} \item \reffmt{ref-block} \(\equiv\) -\item \reffmt{refpre} \reffmt{ref} \reffmt{refpos} +\item \reffmt{preref} \reffmt{ref} \reffmt{postref} \end{refformat} A \texttt{ref-block} is built for \emph{each} label given as argument to @@ -1037,48 +1041,48 @@ typeset output is built as: \item \reffmt{type-block-group} \reffmt{notesep} \reffmt{note} \end{refformat} -Reference format options can yet be divided in two general categories: i) -``string'' options, the ones which we have seen thus far, as ``building -blocks'' of the reference; and ii) ``font'' options, which control font -attributes of parts of the reference, namely \opt{namefont} and \opt{reffont}. -These options set the font, respectively, for the \texttt{type-name} and for -\texttt{ref} (to set the font for the whole reference, see the \opt{font} -option in \zcref{sec:options}). ``String'' options is not really a strict -denomination for the first category, but this set of options is intended -exclusively for typesetting material: things you expect to see in the output -of your references. The ``font'' options, on the other hand, are intended -exclusively for commands that only change font attributes: style, family, -shape, weight, size, color, etc. In either case, anything other than their -intended uses is not supported. +Reference format options can yet be divided in three general categories: i) +``typesetting'' options, the ones which we have seen thus far, as ``building +blocks'' of the reference; ii) ``font'' options, which control font attributes +of parts of the reference, namely \opt{namefont} and \opt{reffont}; and iii) +``other'' options. ``Typesetting'' options are intended exclusively for +typesetting material: things you expect to see in the output of your +references. ``Font'' options set the font, respectively, for the +\texttt{type-name} and for \texttt{ref} (to set the font for the whole +reference, see the \opt{font} option in \zcref{sec:options}). These options +are intended exclusively for commands that only change font attributes: style, +family, shape, weight, size, color, etc. In either case, anything other than +their intended uses is not supported. Finally, a comment about the internal ``fallback'' reference format values mentioned above. These ``last resort'' option values are required by \pkg{zref-clever} for a clear particular case: if the user loads either \pkg{babel} or \pkg{polyglossia}, or explicitly sets a language, with a -language that \pkg{zref-clever} does not know and has no dictionary for, it +language that \pkg{zref-clever} does not know and has no language file for, it cannot guess what language that is, and thus has to provide some reasonable ``language agnostic'' default, at least for the options for which this makes -sense (all the ``string'' options, except for the \texttt{[Nn]ame-} ones). -Users do not need to have access to this scope, since they know the language -of their document, or know the values they want for those options, and can set -them as general options, type-specific options, or language options through -the user interface provided for the purpose. But the ``fallback'' options are -documented here so that you can recognize when you are getting these values -and change them appropriately as desired. Though hopefully reasonable, they -may not be what you want. The ``fallback'' option values are the following: +sense (all the ``typesetting'' options, except for the \texttt{[Nn]ame-} +ones). Users do not need to have access to this scope, since they know the +language of their document, or know the values they want for those options, +and can set them as general options, type-specific options, or language +options through the user interface provided for the purpose. But the +``fallback'' options are documented here so that you can recognize when you +are getting these values and change them appropriately as desired. Though +hopefully reasonable, they may not be what you want. The ``fallback'' option +values are the following: \begin{zcexample}[escapeinside=`'] -tpairsep = {,`\textvisiblespace{}'} , -tlistsep = {,`\textvisiblespace{}'} , -tlastsep = {,`\textvisiblespace{}'} , -notesep = {`\textvisiblespace{}'} , -namesep = {\nobreakspace} , -pairsep = {,`\textvisiblespace{}'} , -listsep = {,`\textvisiblespace{}'} , -lastsep = {,`\textvisiblespace{}'} , -rangesep = {\textendash} , -refpre = {} , -refpos = {} , +tpairsep = {,`\textvisiblespace{}'} , +tlistsep = {,`\textvisiblespace{}'} , +tlastsep = {,`\textvisiblespace{}'} , +notesep = {`\textvisiblespace{}'} , +namesep = {\nobreakspace} , +pairsep = {,`\textvisiblespace{}'} , +listsep = {,`\textvisiblespace{}'} , +lastsep = {,`\textvisiblespace{}'} , +rangesep = {\textendash} , +preref = {} , +postref = {} , \end{zcexample} @@ -1090,12 +1094,11 @@ refpos = {} , of these language packages, or to a language specified directly by the user. This is primarily relevant for reference format options, particularly reference type \emph{names} (though not only, since most reference format -options can have language-specific values, or ``translations'', see -\zcref{sec:reference-format}). But other features of the package also cater -for language specific needs. +options can have language-specific values see \zcref{sec:reference-format}). +But other features of the package also cater for language specific needs. As far as language selection is concerned, if the language is declared and -\pkg{zref-clever} has a built-in ``dictionary'' for it, most use cases will +\pkg{zref-clever} has a built-in ``language file'' for it, most use cases will likely be covered by the \opt{lang} option (see \zcref{sec:options}), and its values \texttt{current} and \texttt{main}. When the \opt{lang} option is set to \texttt{current} or \texttt{main}, \pkg{zref-check} will use, respectively, @@ -1108,17 +1111,17 @@ the \emph{current} or \emph{main} language of the document, as defined by will note that \zcref{tab:languages-and-aliases} contains only \pkg{babel} language names.} Users can also set \opt{lang} to a specific language directly, in which case \pkg{babel} and \pkg{polyglossia} are disregarded. -\pkg{zref-clever} provides a number of built-in ``dictionaries'', for the +\pkg{zref-clever} provides a number of built-in ``language file'', for the languages listed in \zcref{tab:languages-and-aliases}, which also includes the declared aliases to those languages. -\pkg{zref-clever}'s ``dictionaries'' are loaded sparingly and lazily. A -dictionary for a single language -- that specified by user options in the +\pkg{zref-clever}'s ``language files'' are loaded sparingly and lazily. A +language file for a single language -- that specified by user options in the preamble, which by default is the current document language -- is loaded at -\texttt{begindocument}. If any other dictionary is needed, it is loaded on +\texttt{begindocument}. If any other language file is needed, it is loaded on the fly, if and when required. Of course, in either case, conditioned on availability. In sum, \pkg{zref-clever} loads as little as possible, but -allows for convenient on the fly loading of dictionaries if the values are +allows for convenient on the fly loading of language files if the values are indeed required, without users having to worry about it at all. \begin{table} @@ -1155,7 +1158,7 @@ indeed required, without users having to worry about it at all. & brazil \\ & portuges \\ spanish & \\ - & \\ + dutch & \\ \bottomrule \end{tabular} \caption{Declared languages and aliases} @@ -1163,11 +1166,11 @@ indeed required, without users having to worry about it at all. \end{table} -But if the built-in dictionaries do not cover your language, or if you'd like -to adjust some of the default language-specific options, this can be done with -\cs{zcDeclareLanguage}, \cs{zcDeclareLanguageAlias}, and +But if the built-in language files do not cover your language, or if you'd +like to adjust some of the default language-specific options, this can be done +with \cs{zcDeclareLanguage}, \cs{zcDeclareLanguageAlias}, and \cs{zcLanguageSetup}.\footnote{Needless to say, if you'd like to contribute a - dictionary or improve an existing one, that is much welcome at + language file or improve an existing one, that is much welcome at \url{https://github.com/gusbrs/zref-clever/issues}.} \begin{function}{\zcDeclareLanguage} @@ -1190,13 +1193,13 @@ in \cs{zcLanguageSetup}. There is no default presumed in this case. Finally, capitalized for grammatical reasons. For a language declared with the \opt{allcaps} option, the \opt{cap} reference option (see \zcref{sec:options}) is disregarded, and \cs{zcref} always uses the capitalized type name forms. -This means that dictionaries for languages with such a trait can be halved in -size, and that user customization for them is simplified, only requiring the -capitalized name forms. On the other hand, the non-capitalized \texttt{name-} -reference format options are rendered no-op for the language in question. -\zcref[S]{tab:language-options} presents an overview of the options in effect -for the languages declared by \pkg{zref-clever}. \cs{zcDeclareLanguage} is -preamble only. +This means that language files for languages with such a trait can be halved +in size, and that user customization for them is simplified, only requiring +the capitalized name forms. On the other hand, the non-capitalized +\texttt{name-} reference format options are rendered no-op for the language in +question. \zcref[S]{tab:language-options} presents an overview of the options +in effect for the languages declared by \pkg{zref-clever}. +\cs{zcDeclareLanguage} is preamble only. \begin{table} \centering @@ -1209,6 +1212,7 @@ preamble only. german & N,A,D,G & f,m,n & yes \\ portuguese & -- & f,m & -- \\ spanish & -- & f,m & -- \\ + dutch & -- & f,m,n & -- \\ \bottomrule \end{tabular} \caption{Options for declared languages} @@ -1245,12 +1249,13 @@ for reference type \texttt{foo}. Similarly, after \texttt{case=X} (provided first occurrence of either \opt{type} or \opt{case} default values are set. For \opt{case} this means the default declension case, which is the first element of the list provided to the \opt{declension} option in -\cs{zcDeclareLanguage}. For \opt{type} this means ``default translations'', -which are language-specific but not type-specific option values (see -\zcref{sec:reference-format}). An empty valued \texttt{type=} key can also -``unset'' the type. The \opt{gender} key sets the gender of the current -\texttt{type} (provided the value it receives is one of the declared genders -for \meta{language}). \cs{zcLanguageSetup} is preamble only. +\cs{zcDeclareLanguage}. For \opt{type} this means language-specific but not +type-specific option values (see \zcref{sec:reference-format}). An empty +valued \texttt{type=} key can also ``unset'' the type. The \opt{gender} key +sets the gender of the current \texttt{type} (provided the value it receives +is one of the declared genders for \meta{language}). For \texttt{type}s which +have multiple valid genders for a given language, the option can also receive +a comma separated list. \cs{zcLanguageSetup} is preamble only. A couple of examples to illustrate the syntax of \cs{zcLanguageSetup}: @@ -1292,7 +1297,7 @@ their typeset output automated. For reference type names, the declension cases for each language must be declared with \cs{zcDeclareLanguage}, and the name reference format options -must be provided for each case, which is done for built-in dictionaries of +must be provided for each case, which is done for built-in language files of languages which have noun declension, and can be done by the user with \cs{zcLanguageSetup}, as we've seen. \pkg{zref-clever} does not try to guess or infer the case though, you must tell it to \cs{zcref}. And this is done by @@ -1328,11 +1333,11 @@ is comprised of multiple type blocks. \opt{comptosing} when multiple labels of the same type block have been compressed into a single one and, hence, the type name used is singular. Finally, \opt{gender} nudges when there is a mismatch between the gender specified in \cs{zcref} with the \opt{g} option -and the gender of the type name, as stored in the dictionary or language -settings, for each type block. Which nudges to use is configurable with the -option \opt{nudgeif}. And, if you're sure of the results for a particular -\cs{zcref} call, you can always silence the nudges locally with the -\opt{nonudge} option. +and the gender of the type name, as set in the language file or with +\cs{zcLanguageSetup}, for each type block. Which nudges to use is +configurable with the option \opt{nudgeif}. And, if you're sure of the +results for a particular \cs{zcref} call, you can always silence the nudges +locally with the \opt{nonudge} option. The main reason to watch for multiple type references with the \opt{multitype} nudge is that bundling together automatically a list of type blocks is less @@ -1384,14 +1389,14 @@ example, that implies that the reference to it changes gender and the likely preceding article will no longer pass to the reference. The \opt{gender} nudge requires that the gender of each type name and of each reference be explicitly specified. For the type names, this is done for the built-in -dictionaries of languages were this matters, and can be done with +language files of languages were this matters, and can be done with \cs{zcLanguageSetup} as well. For the references, that is the purpose of the \opt{g} option. When there is a mismatch between the two for any type block, the nudge is triggered. Of couse, this means that the gender markup has to be -supplied in the document at each reference. And considering such type changes -may not be frequent for you, or considered not particularly problematic, -you'll have to balance if doing so is worth it. Still, the feature is -available, and it's up to you. +supplied in the document at each reference. And given such type changes may +not be frequent for you, or considered not particularly problematic, you'll +have to balance if doing so is worth it. Still, the feature is available, and +it's up to you. \section{How-tos} @@ -1402,10 +1407,10 @@ set around a cross-reference ``task'' we'd like to perform with \pkg{zref-clever}. -\subsection{Context sensitive references} +\subsection{Context sensitive page references} -\zctask{Make cross-references which are sensitive to the relative position - between the reference and the label being referred to.} +\zctask{Make cross-references to pages which are sensitive to the relative + position between the reference and the label being referred to.} It is frequently useful to make a reference to both a document element and its page. For example: @@ -1436,12 +1441,12 @@ corrected. Evidently, this does not fully automate the typeset results, but it does automate the checking that the reference context is the intended one. And to make use of this feature, one does not need to rely on compiling the -document, make one such reference according to the current state of things, -and then adjusting them over and over, as the document gets edited. This -feature is best used within a certain workflow, which starts by making a -standard reference, but adding the \texttt{pagegap} check to it: +document, make the reference according to the current state of things, and +then adjusting it over and over, as the document gets edited. This feature is +best used within a certain workflow, which starts by making a standard +reference with a page reference, but adding the \texttt{pagegap} check to it: \begin{zcexample} -\zcref[check=pagegap]{fig:1} on \zcpageref{fig:1} +\zcref{fig:1} on \zcpageref[check=pagegap]{fig:1} \end{zcexample} During the initial editing of the document, this reference will be formally @@ -1586,8 +1591,8 @@ cross-references in multiple languages, in which case you'd require \cs{zcLanguageSetup}, the most convenient way to setup a reference type is \cs{zcRefTypeSetup}. In most cases, what we really need to provide for a custom type are the ``type names'' and other reference format options can rely -on default translations already provided by the package (assuming the language -is supported). +on default language options already provided by the package (assuming the +language is supported). \begin{zchowto}[caption={\cs{newtheorem}, custom type}] \documentclass{article} @@ -2202,7 +2207,7 @@ were generously provided by (in chronological order): % 2021-10-10: https://tex.stackexchange.com/questions/618434/#comment1544401_618439 Frank Mittelbach, % 2021-10-14: https://github.com/latex3/latex2e/issues/687 - \texttt{@samcarter}, + `\texttt{samcarter}', % 2021-10-14: https://chat.stackexchange.com/transcript/message/59361777#59361777 % 2021-10-21: https://chat.stackexchange.com/transcript/message/59418309#59418309 Alan Munn, @@ -2215,12 +2220,19 @@ were generously provided by (in chronological order): % 2021-11-25: https://github.com/gusbrs/zref-clever/issues/1 Marcel Krüger, % 2021-11-26: https://github.com/latex3/l3build/issues/215 - and Jürgen Spitzmüller. + Jürgen Spitzmüller, % 2021-11-28: https://github.com/gusbrs/zref-clever/issues/2 + and `\texttt{niluxv}'. + % 2022-01-05: https://github.com/gusbrs/zref-clever/issues/4 + % 2022-01-05: https://github.com/gusbrs/zref-clever/pull/5 -The package's dictionaries have been provided or improved thanks to: - Denis Bitouzé (French). +The package's language files have been provided or improved thanks to: + Denis Bitouzé (French), % 2021-11-25: https://github.com/gusbrs/zref-clever/issues/1 + François Lagarde (French), % 'flagarde' + % 2021-12-09: discussion at https://github.com/gusbrs/zref-clever/issues/1 + and `\texttt{niluxv}' (Dutch). + % 2022-01-09: https://github.com/gusbrs/zref-clever/pull/5 If I have inadvertently left anyone off the list I apologize, and please let me know, so that I can correct the oversight. |