Re: [patch] Support CUSTOM_ID property in latex export

[Richard Lawrence <richard.lawrence@berkeley.edu>]

Hi Nicolas,

Nicolas Goaziou <n.goaziou@gmail.com> writes:

> Richard Lawrence <richard.lawrence@berkeley.edu> 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.)