From: Nicolas Goaziou <n.goaziou@gmail.com>
To: Richard Lawrence <richard.lawrence@berkeley.edu>
Cc: emacs-orgmode@gnu.org
Subject: Re: [patch] Support CUSTOM_ID property in latex export
Date: Sat, 22 Feb 2014 10:24:45 +0100 [thread overview]
Message-ID: <878ut31ov6.fsf@gmail.com> (raw)
In-Reply-To: <87ob20gsxv.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> (Richard Lawrence's message of "Fri, 21 Feb 2014 11:35:24 -0800")
Hello,
Richard Lawrence <richard.lawrence@berkeley.edu> writes:
> Here's a new patch that adds a variable org-latex-custom-id-as-label to
> control whether CUSTOM_ID should be used to generate labels during LaTeX
> export.
Thank you for this.
> Let me know what you think. In particular, I wasn't sure if I should
> provide more information in the defcustom statement beyond :group and
> :type (like :package-version?).
I think we should provide temporary (fake) values so we remember to
update them during the next merge.
:version "24.5"
:package-version '(Org . "8.3")
> Also, does the docstring represent the trade-offs of using this
> variable well enough?
The docstring is quite complete. I added a few suggestions. Also, you
need to escape backslashes (e.g., \\label).
> I wasn't sure how to get git format-patch to generate a single patch for
> the changes between my branch and master (since there are now two
> commits on my branch), so this was generated with git diff --patch. If
> you want me to send the commit message, etc. can you let me know how to
> do this in whatever way is most convenient for you?
You can first merge the two commits on your branch into a single one
with "git rebase -i". Within Magit, it boils down to use key E on the
first of the two commits, then use key s on the second one and
eventually C-c C-c. This will merge them and give you a chance to edit
the final commit message.
Then you can send it with git format-patch.
> diff --git a/lisp/ox-latex.el b/lisp/ox-latex.el
> index 5815874..df22768 100644
> --- a/lisp/ox-latex.el
> +++ b/lisp/ox-latex.el
> @@ -375,6 +375,47 @@ which format headlines like for Org version prior to 8.0."
> :package-version '(Org . "8.0")
> :type 'function)
>
> +(defcustom org-latex-custom-id-as-label nil
> + "Toggle use of CUSTOM_ID properties for generating section labels.
> +
> +If non-nil, Org will use the value of a headline's CUSTOM_ID
> +property as the argument to the \label command for the LaTeX
> +section corresponding to the headline.
I may be useful to add a note about the default behaviour:
By default, Org generates unique labels for all headlines. When this
variable is non-nil...
> +Setting this variable gives you control over how Org generates
> +labels for sections during LaTeX export. One reason to do this
> +is that it allows you to refer to headlines using a single label
> +both in Org's link syntax and in embedded LaTeX code.
> +
> +For example, when this variable is non-nil, a headline like this:
> +
> + ** Some section
> + :PROPERTIES:
> + :CUSTOM_ID: sec:foo
> + :END:
> + This is section [[#sec:foo]].
> + #+BEGIN_LATEX
> + And this is still section \ref{sec:foo}.
> + #+END_LATEX
> +
> +will be exported to LaTeX as:
> +
> + \subsection{Some section}
> + \label{sec:foo}
> + This is section \ref{sec:foo}.
> + And this is still section \ref{sec:foo}.
> +
> +Note, however, that when a headline defines a value for
> +CUSTOM_ID, Org simply passes this value to \label unchanged. You
> +are responsible for ensuring that the value is a valid LaTeX
> +\label key, that it is unique throughout the generated document,
> +etc.
I think you can remove "that it is unique throughout the generated
document", as it is already explained in the manual, and not specific to
this variable.
OTOH, it would be nice to specify what is a valid \label key (e.g.,
forbidden characters) and that the default value doesn't have this
limitation (otherwise, that wouldn't be much of a trade-off).
> + (let ((custom-label (and org-latex-custom-id-as-label
> + (org-element-property :CUSTOM_ID headline))))
There is one thing to consider here. We can define the new variable as
a back-end options, i.e., add
(:latex-manual-id nil nil org-latex-custom-id-as-label)
in the back-end definition (the name of the property doesn't matter
much, you can change it).
This is not strictly necessary, but it allows, for example, to change
its value for specific projects (in the publishing sense) without
setting the variable globally.
If you think it is useful to do so,
(and org-latex-custom-id-as-label
should become
(and (plist-get info :latex-manual-id)
> + (let* ((custom-label (and org-latex-custom-id-as-label
> + (org-element-property :CUSTOM_ID destination)))
Ditto.
What do you think?
Regards,
--
Nicolas Goaziou
next prev parent reply other threads:[~2014-02-22 9:24 UTC|newest]
Thread overview: 16+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-02-15 20:19 [patch] Support CUSTOM_ID property in latex export Richard Lawrence
2014-02-15 22:44 ` Nicolas Goaziou
2014-02-15 23:43 ` Richard Lawrence
2014-02-16 9:10 ` Nicolas Goaziou
2014-02-16 20:10 ` Richard Lawrence
2014-02-18 21:56 ` Nicolas Goaziou
2014-02-18 22:35 ` Richard Lawrence
2014-02-19 12:43 ` Nicolas Goaziou
2014-02-20 5:04 ` Richard Lawrence
2014-02-21 19:35 ` Richard Lawrence
2014-02-22 9:24 ` Nicolas Goaziou [this message]
2014-02-22 20:35 ` Richard Lawrence
2014-02-22 22:31 ` Nicolas Goaziou
2014-02-23 0:37 ` Richard Lawrence
2014-02-23 8:37 ` Nicolas Goaziou
2014-02-23 8:53 ` Achim Gratz
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.orgmode.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=878ut31ov6.fsf@gmail.com \
--to=n.goaziou@gmail.com \
--cc=emacs-orgmode@gnu.org \
--cc=richard.lawrence@berkeley.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).