Re: [patch] Support CUSTOM_ID property in latex export

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

Hi Nicolas and all,

Thanks for your feedback.  I have a couple of questions about your
comments:

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

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

True, it is explained that CUSTOM_ID must be unique, but not that the
generated label must be.  I have changed this to:

"You are responsible for ensuring that the value is a valid LaTeX
\\label key, and that no other \\label commands with the same key appear
elsewhere in your document."

That seems clearer to me; it forbids e.g. introducing labels with the
same key on a #+LATEX: line.  Sound good?

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

I can't actually find a clear explanation anywhere of exactly what is
and isn't allowed in a label key.  All the LaTeX documentation seems to
just say:

"A key can consist of any sequence of letters, digits, or punctuation
characters. Upper and lowercase letters are different."

But clearly, the issue is what sort of "punctuation" is allowed.  ":"
and "_" are OK, but "%" and "$" aren't...is there a definitive list
somewhere I should refer to?  Maybe I should just say the user should
have a look at the regexp in org-export-solidify-link-text?

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

OK, that sounds like a good idea, but are these the only changes that
would be necessary?  Where should the name of the back-end option and
its relationship to this variable be documented?

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.)