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

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

[Timothy]

[-- 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

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

[Juan Manuel Macías]

Hi Timothy,

Timothy writes:

> 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.

I think it's a great idea. There are many options in LaTeX to manage
cross references, beyond the standar \ref. I use the varioref package a
lot (https://www.ctan.org/pkg/varioref).

Best regards,

Juan Manuel 

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

[Bruce D'Arcus]

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

+1

On Sun, Jun 6, 2021, 2:19 PM Timothy <tecosaur@gmail.com> wrote:

> 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
>
>

[-- Attachment #2: Type: text/html, Size: 973 bytes --]

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

[Timothy]

Hi Nicolas,

Since this is a fairly small thing and ox-latex seems to be your domain,
I'm wondering if you've had a chance to take a look yet? (just making
sure this hasn't slipped by, given your recent replies in other threads).

> 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

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

[Nicolas Goaziou]

Hello,

Timothy <tecosaur@gmail.com> writes:

> I'm wondering if you've had a chance to take a look yet? (just making
> sure this hasn't slipped by, given your recent replies in other
> threads).

I agree there is no good reason to hard-code "\ref", but, off the top of
my head, there may be a couple of things to consider:

1. There is still a dangling \ref in `org-latex-footnote-defined-format';

2. This change is already somewhat trivial using a link filter:

     (defun my-ref-link-filter (s &rest _)
       (replace-regexp-in-string (rx string-start "\\ref") "\\foo" s nil t))

     (add-to-list 'org-export-filter-link-functions #'my-ref-link-filter)

3. \hyperref is still hard-coded in `org-latex-link'; your patch could
   look like a partial solution.

Those are not strong objections, so if you think none of them is worth
considering, then I'm fine with your patch.

Regards,
-- 
Nicolas Goaziou

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

[Timothy]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> I agree there is no good reason to hard-code "\ref", but, off the top of
> my head, there may be a couple of things to consider:
>
> 1. There is still a dangling \ref in `org-latex-footnote-defined-format';

I noticed this, but looking at the usage I think the user would be
surprised if changing \ref for sections, figures etc. also changed how
footnotes looked.

> 2. This change is already somewhat trivial using a link filter:
>
>      (defun my-ref-link-filter (s &rest _)
>        (replace-regexp-in-string (rx string-start "\\ref") "\\foo" s nil t))
>
>      (add-to-list 'org-export-filter-link-functions #'my-ref-link-filter)

As are many things :P but I think it's worth making some more obvious to
users, and IMO this is worth it.

> 3. \hyperref is still hard-coded in `org-latex-link'; your patch could
>    look like a partial solution.

A reference with a named description does use hyperref, but I think
that would still be expected --- let me know if you think otherwise
though.

> Those are not strong objections, so if you think none of them is worth
> considering, then I'm fine with your patch.

If what I've said above makes sense, I think it would be good to merge 👍.

All the best,

Timothy.

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

[Nicolas Goaziou]

Timothy <tecosaur@gmail.com> writes:

> If what I've said above makes sense, I think it would be good to merge
> 👍.

Sure, LGTM!

Regards,

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

[Timothy]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Sure, LGTM!

Cool :) Merged.

Now the only other LaTeX PR I may poke you about in the future is the
latexmk one :P

--
Timothy

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

[Nicolas Goaziou]

Hello,

Timothy <tecosaur@gmail.com> writes:

> Cool :) Merged.

Thank you.

Regards,
-- 
Nicolas Goaziou