summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/ltxref.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-15 03:00:57 +0000
committerNorbert Preining <norbert@preining.info>2019-09-15 03:00:57 +0000
commitfed27f633aadbacbd3d1221da7993fed8d4efffe (patch)
tree3cae3cde89de26b178894a2e88d9ef5ba89dafcc /macros/latex-dev/base/ltxref.dtx
parent0eea86bf18826522b3686f54fc3afb8ddc31e62a (diff)
CTAN sync 201909150300
Diffstat (limited to 'macros/latex-dev/base/ltxref.dtx')
-rw-r--r--macros/latex-dev/base/ltxref.dtx189
1 files changed, 132 insertions, 57 deletions
diff --git a/macros/latex-dev/base/ltxref.dtx b/macros/latex-dev/base/ltxref.dtx
index a5c11bf21b..1d8c41c439 100644
--- a/macros/latex-dev/base/ltxref.dtx
+++ b/macros/latex-dev/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/08/22 v1.1l 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,111 @@
{\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:
+% \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\expandafter\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
%