[PATCH] Allow LaTeX reference command (\ref) to be customised

[Timothy <tecosaur@gmail.com>]

[-- Attachment #1: Type: text/plain, Size: 523 bytes --]

Hi All,

I've started doing some more cross-referencing in documents exported to
LaTeX, and a hardcoded use of \ref has begun to stand out to me as a
rather annoying thing. Hypperef provides \autoref for adding helpful
prefixes (section, figure, etc.), and there are other packages which one
may want to use to generate 'clever' references (like cleveref with
\cref).

As such, I think that the hardcoded \ref should actually be turned into
a customisable format string, which is what the attached patch does.

--
Timothy


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-latex-Allow-reference-command-to-be-customised.patch --]
[-- Type: text/x-patch, Size: 2863 bytes --]

From db01398de3a29043dbb545ee66006b0b7c0f1368 Mon Sep 17 00:00:00 2001
From: TEC <tec@tecosaur.com>
Date: Mon, 7 Jun 2021 02:13:18 +0800
Subject: [PATCH] ox-latex: Allow reference command to be customised

* lisp/ox-latex.el (org-latex-reference-command): Create a new variable
so the user may modify the reference command used.
(org-latex-link): Make use of the new `org-latex-reference-command' when
generating references for labels without a description (previously using
\ref).
(org-latex-prefer-user-labels): Mention the new
`org-latex-reference-command' when describing the generated LaTeX
referencing labels.
---
 lisp/ox-latex.el | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
index c761cfd7f..940800750 100644
--- a/lisp/ox-latex.el
+++ b/lisp/ox-latex.el
@@ -381,6 +381,9 @@ (defcustom org-latex-prefer-user-labels nil
   This is section \\ref{sec:foo}.
   And this is still section \\ref{sec:foo}.
 
+A non-default value of `org-latex-reference-command' will change the
+command (\\ref by default) used to create label references.
+
 Note, however, that setting this variable introduces a limitation
 on the possible values for CUSTOM_ID and NAME.  When this
 variable is non-nil, Org passes their value to \\label unchanged.
@@ -400,6 +403,18 @@ (defcustom org-latex-prefer-user-labels nil
   :version "26.1"
   :package-version '(Org . "8.3"))
 
+(defcustom org-latex-reference-command "\\ref{%s}"
+  "Format string that takes a reference to produce a LaTeX reference command.
+
+The reference is a label such as sec:intro.  A format string of \"\\ref{%s}\"
+produces numbered references and will always work.  It may be desirable to make
+use of a package such as hyperref or cleveref and then change the format string
+to \"\\autoref{%s}\" or \"\\cref{%s}\" for example."
+  :group 'org-export-latex
+  :type 'string
+  :version "28.1"
+  :package-version '(Org . "9.5"))
+
 ;;;; Preamble
 
 (defcustom org-latex-default-class "article"
@@ -2608,7 +2623,7 @@ (defun org-latex-link (link desc info)
 	   (let ((label (org-latex--label destination info t)))
 	     (if (and (not desc)
 		      (org-export-numbered-headline-p destination info))
-		 (format "\\ref{%s}" label)
+		 (format org-latex-reference-command label)
 	       (format "\\hyperref[%s]{%s}" label
 		       (or desc
 			   (org-export-data
@@ -2616,7 +2631,7 @@ (defun org-latex-link (link desc info)
           ;; Fuzzy link points to a target.  Do as above.
 	  (otherwise
 	   (let ((ref (org-latex--label destination info t)))
-	     (if (not desc) (format "\\ref{%s}" ref)
+	     (if (not desc) (format org-latex-reference-command ref)
 	       (format "\\hyperref[%s]{%s}" ref desc)))))))
      ;; Coderef: replace link with the reference name or the
      ;; equivalent line number.
-- 
2.31.1