[latex3-commits] [git/LaTeX3-latex3-latex2e] develop: added \Ref and \labelformat from varioref (ebb05fbf)
Frank Mittelbach
frank.mittelbach at latex-project.org
Fri Aug 23 16:22:27 CEST 2019
Repository : https://github.com/latex3/latex2e
On branch : develop
Link : https://github.com/latex3/latex2e/commit/ebb05fbfbe372f4887408ac579bc8c164b6d3f7a
>---------------------------------------------------------------
commit ebb05fbfbe372f4887408ac579bc8c164b6d3f7a
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date: Fri Aug 23 16:22:27 2019 +0200
added \Ref and \labelformat from varioref
>---------------------------------------------------------------
ebb05fbfbe372f4887408ac579bc8c164b6d3f7a
base/ltxref.dtx | 146 +++++++++++++++++++++++++++++++++++---------------------
1 file changed, 92 insertions(+), 54 deletions(-)
diff --git a/base/ltxref.dtx b/base/ltxref.dtx
index af626617..a890c11c 100644
--- a/base/ltxref.dtx
+++ b/base/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 at refundefinedtrue}
% \changes{v1.1i}{1995/12/07}{Renamed (back) from \cs{G at refundefined}}
% \begin{macro}{\@refundefined}
@@ -247,7 +291,6 @@
%
% \begin{macro}{\label}
% \changes{v1.1d}{1994/11/04}{(ASAJ)Added \cs{protected at write}}
-% \begin{macro}{\refstepcounter}
% \changes{v1.1d}{1994/11/04}{(ASAJ)Added \cs{protected at edef}}
% The commands |\label| and |\refstepcounter| have been changed to
% allow |\protect|'ed commands to work properly. For example,
@@ -263,7 +306,10 @@
{\string\newlabel{#1}{{\@currentlabel}{\thepage}}}%
\@esphack}
% \end{macrocode}
+% \end{macro}
%
+% \begin{macro}{\refstepcounter}
+% Step the counter and allow for labels to point to its current value.
% \begin{macrocode}
\def\refstepcounter#1{\stepcounter{#1}%
\protected at edef\@currentlabel
@@ -271,18 +317,60 @@
% By generating the second csname first the |\p at ...| command can
% grab it as an argument which can be helpful for more complicated
% typesetting arrangements.
-% \changes{v1.1l}{2019/08/22}{Allow \cs{p at ...} to have an argument}
+%
+% The trick is to ensure that |\csname the#1\endcsname| is turned
+% into a single token before |\p at ...| is expanded further. This
+% way, if the |\p at ...| 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 at ...| 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 at ...} to have an
+% argument}
% \begin{macrocode}
{\csname p@#1\expandafter\endcsname\csname the#1\endcsname}%
}
% \end{macrocode}
% \end{macro}
+%
+% \begin{macro}{\labelformat}
+% A shortcut to set the |\p at ...| 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\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}
+\DeclareRobustCommand\Ref[1]{\protected at edef\@tempa{\ref{#1}}%
+ \expandafter\MakeUppercase\@tempa}
+% \end{macrocode}
+% \end{macro}
%
-% \begin{macro}{\@currentlabel}
-% For |\label| commands that come before any environment
%
+% \begin{macro}{\@currentlabel}
+% Default for |\label| commands that come before any environment.
% \begin{macrocode}
\def\@currentlabel{}
% \end{macrocode}
@@ -292,56 +380,6 @@
%</2ekernel>
% \end{macrocode}
%
-% \subsection{An extension of counter referencing}
-%
-%
-% At the moment a reference to a counter |foo| will generate the
-% equivalent of |\p at 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 at 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:
-%
-%\begin{verbatim}
-%\def\refstepcounter#1{\stepcounter{#1}%
-% \protected at 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 at ...| is expanded further. This way, if the
-% |\p at ...| 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 at ...| 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{verbatim}
-%\CheckCommand*\refstepcounter[1]{\stepcounter{#1}%
-% \protected at edef\@currentlabel
-% {\csname p@#1\endcsname\csname the#1\endcsname}%
-%}
-%\renewcommand*\refstepcounter[1]{\stepcounter{#1}%
-% \protected at edef\@currentlabel
-% {\csname p@#1\expandafter\endcsname\csname the#1\endcsname}%
-%}
-%\end{verbatim}
%
% \Finale
%
More information about the latex3-commits
mailing list