emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
* [PATCH] Allow LaTeX reference command (\ref) to be customised
@ 2021-06-06 18:19 Timothy
  2021-06-06 18:29 ` Juan Manuel Macías
                   ` (2 more replies)
  0 siblings, 3 replies; 9+ messages in thread
From: Timothy @ 2021-06-06 18:19 UTC (permalink / raw)
  To: org-mode-email

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


^ permalink raw reply related	[flat|nested] 9+ messages in thread

* Re: [PATCH] Allow LaTeX reference command (\ref) to be customised
  2021-06-06 18:19 [PATCH] Allow LaTeX reference command (\ref) to be customised Timothy
@ 2021-06-06 18:29 ` Juan Manuel Macías
  2021-06-06 18:39 ` Bruce D'Arcus
  2021-06-09  2:11 ` Timothy
  2 siblings, 0 replies; 9+ messages in thread
From: Juan Manuel Macías @ 2021-06-06 18:29 UTC (permalink / raw)
  To: Timothy; +Cc: orgmode

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 


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Allow LaTeX reference command (\ref) to be customised
  2021-06-06 18:19 [PATCH] Allow LaTeX reference command (\ref) to be customised Timothy
  2021-06-06 18:29 ` Juan Manuel Macías
@ 2021-06-06 18:39 ` Bruce D'Arcus
  2021-06-09  2:11 ` Timothy
  2 siblings, 0 replies; 9+ messages in thread
From: Bruce D'Arcus @ 2021-06-06 18:39 UTC (permalink / raw)
  To: Timothy; +Cc: org-mode-email

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

^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Allow LaTeX reference command (\ref) to be customised
  2021-06-06 18:19 [PATCH] Allow LaTeX reference command (\ref) to be customised Timothy
  2021-06-06 18:29 ` Juan Manuel Macías
  2021-06-06 18:39 ` Bruce D'Arcus
@ 2021-06-09  2:11 ` Timothy
  2021-06-09 11:52   ` Nicolas Goaziou
  2 siblings, 1 reply; 9+ messages in thread
From: Timothy @ 2021-06-09  2:11 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: org-mode-email


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


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Allow LaTeX reference command (\ref) to be customised
  2021-06-09  2:11 ` Timothy
@ 2021-06-09 11:52   ` Nicolas Goaziou
  2021-06-09 13:36     ` Timothy
  0 siblings, 1 reply; 9+ messages in thread
From: Nicolas Goaziou @ 2021-06-09 11:52 UTC (permalink / raw)
  To: Timothy; +Cc: org-mode-email

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


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Allow LaTeX reference command (\ref) to be customised
  2021-06-09 11:52   ` Nicolas Goaziou
@ 2021-06-09 13:36     ` Timothy
  2021-06-09 15:08       ` Nicolas Goaziou
  0 siblings, 1 reply; 9+ messages in thread
From: Timothy @ 2021-06-09 13:36 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: org-mode-email


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.


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Allow LaTeX reference command (\ref) to be customised
  2021-06-09 13:36     ` Timothy
@ 2021-06-09 15:08       ` Nicolas Goaziou
  2021-06-09 17:38         ` Timothy
  0 siblings, 1 reply; 9+ messages in thread
From: Nicolas Goaziou @ 2021-06-09 15:08 UTC (permalink / raw)
  To: Timothy; +Cc: org-mode-email

Timothy <tecosaur@gmail.com> writes:

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

Sure, LGTM!

Regards,


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Allow LaTeX reference command (\ref) to be customised
  2021-06-09 15:08       ` Nicolas Goaziou
@ 2021-06-09 17:38         ` Timothy
  2021-06-11 16:44           ` Nicolas Goaziou
  0 siblings, 1 reply; 9+ messages in thread
From: Timothy @ 2021-06-09 17:38 UTC (permalink / raw)
  To: Nicolas Goaziou; +Cc: org-mode-email


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


^ permalink raw reply	[flat|nested] 9+ messages in thread

* Re: [PATCH] Allow LaTeX reference command (\ref) to be customised
  2021-06-09 17:38         ` Timothy
@ 2021-06-11 16:44           ` Nicolas Goaziou
  0 siblings, 0 replies; 9+ messages in thread
From: Nicolas Goaziou @ 2021-06-11 16:44 UTC (permalink / raw)
  To: Timothy; +Cc: org-mode-email

Hello,

Timothy <tecosaur@gmail.com> writes:

> Cool :) Merged.

Thank you.

Regards,
-- 
Nicolas Goaziou


^ permalink raw reply	[flat|nested] 9+ messages in thread

end of thread, other threads:[~2021-06-11 16:46 UTC | newest]

Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-06-06 18:19 [PATCH] Allow LaTeX reference command (\ref) to be customised Timothy
2021-06-06 18:29 ` Juan Manuel Macías
2021-06-06 18:39 ` Bruce D'Arcus
2021-06-09  2:11 ` Timothy
2021-06-09 11:52   ` Nicolas Goaziou
2021-06-09 13:36     ` Timothy
2021-06-09 15:08       ` Nicolas Goaziou
2021-06-09 17:38         ` Timothy
2021-06-11 16:44           ` Nicolas Goaziou

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).