Re: [O] [patch] Support CUSTOM_ID property in latex export

[Nicolas Goaziou]

Richard Lawrence <address@hidden> writes:

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

Fair enough.

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

I don't know any.

> Maybe I should just say the user should have a look at the regexp in
> org-export-solidify-link-text?

Besides alphanumeric characters, this function allows "_", ".", "-" and
":". I think it is safe to assume only these punctuation characters are
allowed.

Also, the docstring should insist on the fact that this limitation only
applies when the variable is non-nil.

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

Yes.

> Where should the name of the back-end option and its relationship to
> this variable be documented?

Probably in:

  (info "(org) Publishing options")

Unfortunately, only generic and html-specific options are described
there. We could add a LaTeX section (but it wouldn't contain much).


Regards,

-- 
Nicolas Goaziou