diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/base/ltxref.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/base/ltxref.dtx | 190 |
1 files changed, 133 insertions, 57 deletions
diff --git a/Master/texmf-dist/source/latex/base/ltxref.dtx b/Master/texmf-dist/source/latex/base/ltxref.dtx index a5c11bf21b6..27d32504137 100644 --- a/Master/texmf-dist/source/latex/base/ltxref.dtx +++ b/Master/texmf-dist/source/latex/base/ltxref.dtx @@ -1,6 +1,6 @@ % \iffalse meta-comment % -% Copyright 1993-2016 +% Copyright (C) 1993-2019 % The LaTeX3 Project and any individual authors listed elsewhere % in this file. % @@ -13,7 +13,7 @@ % The latest version of this license is in % https://www.latex-project.org/lppl.txt % and version 1.3c or later is part of all distributions of LaTeX -% version 2005/12/01 or later. +% version 2008 or later. % % This file has the LPPL maintenance status "maintained". % @@ -33,7 +33,7 @@ %<*driver> % \fi \ProvidesFile{ltxref.dtx} - [2014/09/29 v1.1k LaTeX Kernel (Cross Referencing)] + [2019/09/16 v1.1m LaTeX Kernel (Cross Referencing)] % \iffalse \documentclass{ltxdoc} \GetFileInfo{ltxref.dtx} @@ -126,6 +126,50 @@ % % \end{oldcomments} % +% \DescribeMacro\labelformat +% A reference via |\ref| produces by default the data associated with +% the corresponding |\label| command (typically a number); any +% additional formatting has to be provided by the user. If, for +% example, references to equations are always to be typeset as +% ``equation (\textit{number})'', one has to code +% ``\verb=equation (\ref{=\textit{key}\verb=})=''. With |\labelformat| +% there is a possibility to generate such +% frills automatically without resorting to low-level coding. +% The command takes two arguments: the first is +% the name of a counter and the second is its representation when +% referenced. This means that for a successful usage, one has to know +% the counter name being used for generating the label, though in +% practice this should not pose a problem. The current counter number +% is picked up as an argument. +% Here are two examples: +%\begin{verbatim} +% \labelformat{section}{section~#1} +% \labelformat{equation}{equation~(#1)}} +%\end{verbatim} +% +% \DescribeMacro\Ref +% A side effect of using |\labelformat| is that, depending on the +% defined formatting, it becomes impossible to use |\ref| at the +% beginning of a sentence (if its replacement text starts with a +% lowercase letter). To overcome this problem we +% introduce the command |\Ref| that behave like +% |\ref| except that it uppercases the first token +% of the generated string. +% + +% To make |\Ref| work properly the very first token in the second +% argument of |\labelformat| has to be a simple \textsc{ascii} or +% UTF-8 letter, otherwise the capitalization will fail or worse, you +% will end up with some error messages. If you actually need something +% more complicated in this place (e.g., an accented letter not written +% as a UTF-8 character) you have to explicitly surround it with +% braces, to identify the part that needs to be capitalized. For +% example, for figure references in the Hungarian language you might +% want to write |\labelformat{figure}{{\'a}bra~\thefigure}| or use +% |\labelformat{figure}{ábra~\thefigure}| which avoids the brace +% problem. +% +% % \begin{macro}{\G@refundefinedtrue} % \changes{v1.1i}{1995/12/07}{Renamed (back) from \cs{G@refundefined}} % \begin{macro}{\@refundefined} @@ -247,7 +291,6 @@ % % \begin{macro}{\label} % \changes{v1.1d}{1994/11/04}{(ASAJ)Added \cs{protected@write}} -% \begin{macro}{\refstepcounter} % \changes{v1.1d}{1994/11/04}{(ASAJ)Added \cs{protected@edef}} % The commands |\label| and |\refstepcounter| have been changed to % allow |\protect|'ed commands to work properly. For example, @@ -263,79 +306,112 @@ {\string\newlabel{#1}{{\@currentlabel}{\thepage}}}% \@esphack} % \end{macrocode} +% \end{macro} % % \begin{macrocode} +%</2ekernel> +%<*2ekernel|latexrelease> +%<latexrelease>\IncludeInRelease{2019/10/01}% +%<latexrelease> {\refstepcounter}{Add \labelformat and \Ref}% +% \end{macrocode} +% +% \begin{macro}{\refstepcounter} +% Step the counter and allow for labels to point to its current value. +% \begin{macrocode} \def\refstepcounter#1{\stepcounter{#1}% \protected@edef\@currentlabel - {\csname p@#1\endcsname\csname the#1\endcsname}% +% \end{macrocode} +% By generating the second csname first the |\p@...| command can +% grab it as an argument which can be helpful for more complicated +% typesetting arrangements. +% +% The trick is to ensure that |\csname the#1\endcsname| is turned +% into a single token before |\p@...| is expanded further. This +% way, if the |\p@...| command is a macro with one argument it will +% receive |\the...|. With the original kernel code (i.e., without the +% |\expandafter|) it will instead pick up |\csname| which would be +% disastrous. +% +% Using |\expandafter| instead of braces delimiting the argument is +% better because, assuming that the |\p@...| command is not defined +% as a macro with one argument, the braces will stay and prohibit +% kerning that might otherwise happen between the glyphs generated +% by |\the...| and surrounding glyphs. +% +% \changes{v1.1l}{2019/08/22}{Allow \cs{p@...} to have an +% argument} +% \begin{macrocode} + {\csname p@#1\expandafter\endcsname\csname the#1\endcsname}% } % \end{macrocode} % \end{macro} -% \end{macro} -% -% -% \begin{macro}{\@currentlabel} -% For |\label| commands that come before any environment % +% \begin{macro}{\labelformat} +% A shortcut to set the |\p@...| macro for a counter. It will pick +% up the counter representation as an argument so that it can be +% specially formatted. +% \changes{v1.1l}{2019/08/22}{Commanded moved from \texttt{varioref.sty}} % \begin{macrocode} -\def\@currentlabel{} +\def\labelformat#1{\expandafter\def\csname p@#1\endcsname##1} % \end{macrocode} % \end{macro} % +% \begin{macro}{\Ref} +% This macro expands the result of |\ref| and then uppercases the +% first token. Only useful if the label was generated via +% |\labelformat| and contains some lower case letter at its start. If +% the label starts with a complicated construct (e.g., an accented +% letter that is provided via a command, e.g., \verb=\"a= instead +% of a UTF-8 character like ä) one has to surround everything that +% needs uppercasing in +% a brace group in the definition of |\labelformat|.\footnote{There +% is one problem with this approach: the braces are kept in a +% normal \texttt{\textbackslash ref} which might spoil kerning. +% Perhaps one day this needs redoing.} +% \changes{v1.1l}{2019/08/22}{Commanded moved from \texttt{varioref.sty}} % \begin{macrocode} -%</2ekernel> +\DeclareRobustCommand\Ref[1]{\protected@edef\@tempa{\ref{#1}}% + \expandafter\MakeUppercase\@tempa} % \end{macrocode} +% \end{macro} % -% \subsection{An extension of counter referencing} % % -% At the moment a reference to a counter |foo| will generate the -% equivalent of |\p@foo\thefoo| although not quite in this form. For -% some applications it would be nice of one could have |\thefoo| being -% an argument to |\p@foo| to be able to put material before and after -% the number generated by |\thefoo|. This can be easily achieved with -% a small change to one of the kernel commands as follows: +% \changes{v1.1m}{2019/09/16}{Correctly revert the \cs{p@...} change} +% \begin{macrocode} +%</2ekernel|latexrelease> +%<latexrelease>\EndIncludeInRelease +%<latexrelease>\IncludeInRelease{0000/00/00}% +%<latexrelease> {\refstepcounter}{Add \labelformat and \Ref}% +%<latexrelease> +%<latexrelease>\def\refstepcounter#1{\stepcounter{#1}% +%<latexrelease> \protected@edef\@currentlabel +%<latexrelease> {\csname p@#1\endcsname\csname the#1\endcsname}% +%<latexrelease>} +%<latexrelease>\let\labelformat\@undefined +%<latexrelease>\let\Ref\@undefined +%<latexrelease> +%<latexrelease>\EndIncludeInRelease +%<*2ekernel> +% \end{macrocode} +% +% +% +% +% % -%\begin{verbatim} -%\def\refstepcounter#1{\stepcounter{#1}% -% \protected@edef\@currentlabel -% {\csname p@#1\expandafter\endcsname\csname the#1\endcsname}% -%} -%\end{verbatim} % -% The trick is to ensure that |\csname the#1\endcsname| is turned into -% a single token before |\p@...| is expanded further. This way, if the -% |\p@...| command is a macro with one argument it will receive -% |\the...|. With the kernel code (i.e., without the |\expandafter|) -% it will instead pick up |\csname| which would be disastrous. -% -% Using |\expandafter| instead of braces delimiting the argument is -% better because, assuming that the |\p@...| command is not defined as -% a macro with one argument, the braces will stay and prohibit kerning -% that might otherwise happen between the glyphs generated by -% |\the...| and surrounding glyphs. -% -% We have refrained from making this change in the kernel code -% although for existing documents it would be 100\% backward -% compatible. The reason being that any class or package making use of -% this functionality would then horribly fail with older \LaTeX{} -% installations. -% -% Instead we suggest that people who are interested in using this -% functionality in a document class or package add the redefinition to -% the class file. To ensure that this redefinition is properly applied -% they might want to test for the original definition first, e.g. +% \begin{macro}{\@currentlabel} +% Default for |\label| commands that come before any environment. +% \begin{macrocode} +\def\@currentlabel{} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +%</2ekernel> +% \end{macrocode} % -%\begin{verbatim} -%\CheckCommand*\refstepcounter[1]{\stepcounter{#1}% -% \protected@edef\@currentlabel -% {\csname p@#1\endcsname\csname the#1\endcsname}% -%} -%\renewcommand*\refstepcounter[1]{\stepcounter{#1}% -% \protected@edef\@currentlabel -% {\csname p@#1\expandafter\endcsname\csname the#1\endcsname}% -%} -%\end{verbatim} % % \Finale % |