[-- 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
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
[-- 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 --]
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
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
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.
Timothy <tecosaur@gmail.com> writes:
> If what I've said above makes sense, I think it would be good to merge
> 👍.
Sure, LGTM!
Regards,
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
Hello,
Timothy <tecosaur@gmail.com> writes:
> Cool :) Merged.
Thank you.
Regards,
--
Nicolas Goaziou