From e0464890d25b3299ff008d946e49d3fcf657694b Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Fri, 2 Aug 2019 12:27:47 +0100
Subject: [PATCH] mdwref.dtx: Add a useful output-formatting hook.

Rather than have `\xref@@' produce the output directly, because it's
very hairy and hard to replace, have it call a new macro,
`\formatxfref', to actually put the pieces together.  This can be
overridden comfortably, even by novices.

Have the default `\formatxref' notice that `hyperref' is available and
do use its fancier features to include the category name in the link.
---
 mdwref.dtx | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/mdwref.dtx b/mdwref.dtx
index f1da45c..58bec2e 100644
--- a/mdwref.dtx
+++ b/mdwref.dtx
@@ -103,6 +103,18 @@
 %\newcommand{\Xref}[1]{\xref[\toupper]{#1}}
 % \end{listing}
 %
+% \DescribeMacro\formatxref
+% The reference itself is typeset by calling
+% \syntax{"\\formatxref{"<mangle>"}{"<string>"}{"<label>"}"}, which can do as
+% it pleases: the \<mangle> token is from the |\xref| invocation; the
+% \<string> is category of thing being referred to (as established by
+% |\defxref| below); and \<label> is the label, again from |\xref| .  The
+% default behaviour is to print
+% \syntax{<mangle>"{"<string>"}~\\ref{"<label>"}"}, but this can be
+% overridden.
+% (Not quite true: in fact, the default does something better if
+% \package{hyperref} is detected, but the idea is basically the same.)
+%
 % All that remains is to define the strings to be typeset for various kinds
 % of labels.
 % \DescribeMacro\defxref
@@ -158,6 +170,16 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\formatxref}
+% Output a cross-reference in the right way.
+%    \begin{macrocode}
+\def\formatxref#1#2#3{%
+  \ifx\hyperref\@@undefined #1{#2}~\ref{#3}%
+  \else \hyperref[#3]{#1{#2}~\ref*{#3}}\fi%
+}
+%    \end{macrocode}
+% \end{macro}
+%
 % \begin{macro}{\xref}
 % We're meant to typeset a reference.  The first job is to see whether
 % there's an optional argument.  If so, grab it; otherwise |\relax| will do.
@@ -183,9 +205,9 @@
     \ifx\@tempa\relax%
       \PackageError{xref}{Unknown ref kind `#2'}%
     \else%
-      \toks@{#1}\toks\tw@\expandafter{\@tempa}%
-      \edef\next@{\the\toks@{\the\toks\tw@}}%
-      \next@~\ref{#2:#3}%
+      \toks@\expandafter{\@tempa}%
+      \edef\next@##1{##1{\the\toks@}}%
+      \next@{\formatxref{#1}}{#2:#3}%
     \fi%
   \fi%
 }
-- 
2.11.0