From mboxrd@z Thu Jan 1 00:00:00 1970 From: Richard Lawrence Subject: Re: [patch] Support CUSTOM_ID property in latex export Date: Sun, 16 Feb 2014 12:10:29 -0800 Message-ID: <871tz24y4q.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> References: <87y51cgmc5.fsf@aquinas.i-did-not-set--mail-host-address--so-tickle-me> <87mwhsro6c.fsf@gmail.com> <87vbwggcwb.fsf@berkeley.edu> <87iosfs9sb.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Return-path: Received: from eggs.gnu.org ([2001:4830:134:3::10]:50898) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WF84a-0000HL-1z for emacs-orgmode@gnu.org; Sun, 16 Feb 2014 15:12:25 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WF84U-00084o-J5 for emacs-orgmode@gnu.org; Sun, 16 Feb 2014 15:12:19 -0500 Received: from mail-pd0-f178.google.com ([209.85.192.178]:42599) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WF84U-00084V-AR for emacs-orgmode@gnu.org; Sun, 16 Feb 2014 15:12:14 -0500 Received: by mail-pd0-f178.google.com with SMTP id fp1so5309089pdb.23 for ; Sun, 16 Feb 2014 12:12:13 -0800 (PST) In-Reply-To: <87iosfs9sb.fsf@gmail.com> List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org Sender: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane.org@gnu.org To: Nicolas Goaziou Cc: emacs-orgmode@gnu.org Hi Nicolas, Nicolas Goaziou writes: > Richard Lawrence writes: > >> 1) Sometimes I need to refer to a section from within an embedded LaTeX >> block. In that case, I need to know the appropriate label to use at the >> LaTeX level, not just in Org. For example: >> >> * A headline >> :PROPERTIES: >> :CUSTOM_ID: sec:a-headline >> :END: >> >> # ... stuff ... >> >> #+BEGIN_LATEX >> % ... more stuff ... >> (see section~\ref{sec:a-headline}) >> #+END_LATEX > > I don't think this is a good idea, as the character set allowed in > \label{...} macros is only a subset of the character set allowed in > custom id value. Hence the `org-export-solidify-link-text' function. > > If you are cautious, this will not be a problem, but it could bite users > with little LaTeX knowledge. Well, I don't quite see the force of this. After all, isn't there a general rule to the effect that "if you override Org's default behavior, you're on your own, so be careful"? Users are expected to make sure that CUSTOM_ID is unique, for example. It seems to me that if you explicitly specify CUSTOM_ID with the intent of overriding Org's default labeling, you ought to have some idea what can go in a \label, and be prepared to debug your LaTeX compilation if there's an error. If you're not prepared to do that, you should limit yourself to the default behavior. But if you *are* prepared to do that, why should Org prevent you? >> This is not possible with the present section labeling in LaTeX export, >> because I have no way of forcing Org to use a particular label for a >> section. > > * A headline > #+latex: \label{my-section} > > #+BEGIN_LATEX > % ... more stuff ... > (see section~\ref{my-section}) > #+END_LATEX > > It also seems more consistent to me: since you want to explicitly write > the \ref{...}, you are also expected to explicitly write the \label{...} > part. But then I would not be able to take advantage of referring to that label from within plain Org text (i.e., outside an embedded LaTeX block) using links. The whole point of this is that I want to be able to refer to a *single*, unambiguous label from within both contexts. The strategy you suggest would result in multiple labels in the same location in the exported document. This is bad because it introduces ambiguity and is thus fragile. The exported document could have two sets of \refs which point to two different \labels. Initially, LaTeX would compile them to the same thing, but if one of the labels got moved or deleted, one set of refs would break. >> 2) I hope this doesn't happen, but there may come a time when I need to >> move away from Org and just use straight LaTeX. Having control over the >> labeling will make this transition much easier, because it means I won't >> have to worry about manually changing the labels in a long document from >> Org's default "sec-..." numbering to my own semantic labels. > > See above. You can even automate that with a hook (i.e., get the custom > id value and add a corresponding label at the beginning of the > headline). I realize that I could automate this if necessary. That in fact is why I wrote the patch: I'm trying to do the work of automating it now, rather than waiting until a moment when I realize in desperation that I have to convert to LaTeX. :) For the reasons I cited above, I wouldn't want to use multiple labels, which is why I prefer to implement my automation this way. Is it possible to use a hook to do what this patch does? i.e., to *replace* Org's default labeling with labels generated from CUSTOM_ID, and have links exported to \refs using that value instead of the default labeling? I sent the patch because I saw on the list that at least one other person wanted a feature like this. If it is not accepted, that's OK; I will work around it, probably using a derived export backend. But I have to imagine that other people are doing something similar. I know there are other people on this list using Org to write long documents that they compile with LaTeX, and they are probably facing a similar problem. >> 3) This will make the LaTeX exporter's behavior more consistent with the >> HTML exporter's behavior. The HTML exporter will use CUSTOM_ID if it is >> supplied to construct the id attributes of headlines and divs. If >> someone is relying on this behavior of the HTML exporter, they might be >> unpleasantly surprised by the LaTeX exporter's behavior. > > One relying on an implementation detail instead of the actual > specifications has to be prepared for surprises. Maybe so, but that's actually sort of my point. At the moment, my options are: 1) Use multiple labeling schemes, one accessible to Org, one accessible to LaTeX, and use the former in Org text and the latter in embedded LaTeX 2) Avoid using Org's labeling/linking entirely, and just explicitly specify all my \labels and \refs 3) Rely on my understanding of how Org will produce section labels when I \ref sections inside embedded LaTeX blocks Option 1 creates ambiguity, is fragile, and is thus not ideal. Option 2 means giving up the advantages of using Org references instead of LaTeX. Option 3 is clearly relying on an implementation detail in a problematic way: it will break as soon as my section numbering changes. The patch allows me to *avoid* relying on an implementation detail in this problematic way, while still getting the advantages of Org's labeling and linking capabilities. Having Org pass CUSTOM_ID through to \label does in a sense mean the user is relying on an implementation detail of the exporter, but in an explicit and predictable way, which makes it unproblematic. Consider an analogy: users who specify :options in an #+ATTR_LATEX declaration are also relying on the implementation details of the exporter (they are assuming it will export their options text unchanged), but this is not problematic because they are explicitly requesting that the default behavior (don't use options, or use some default options) be overridden. Isn't overriding labeling with CUSTOM_ID pretty much the same thing? Best, Richard (If possible, please encrypt your reply to me using my PGP key: Key ID: CF6FA646 Fingerprint: 9969 43E1 CF6F A646. See http://www.ocf.berkeley.edu/~rwl/encryption.html for more information.)