LaTeX export of section links

LaTeX export of section links

[Francesco Pizzolante]

Hi,

I have a few questions about links to sections.

I've read that it is better to user IDs and CUSTOM_IDs to links to section...

Here's a small example with 4 cases:

--8<---------------cut here---------------start------------->8---
* First
  :PROPERTIES:
  :CUSTOM_ID: heading-a
  :END:

  Hello Toto!

* Second
# <<heading-b>>

  Hello Tata!

* Third
#+CUSTOM_ID: heading-c

  Hello Titi!

* Fourth
#+ID: heading-d

  Hello Tete!

[[heading-a]]
[[heading-b]]
[[heading-c]]
[[heading-d]]
--8<---------------cut here---------------end--------------->8---

Which give the following LaTeX code:

--8<---------------cut here---------------start------------->8---
\section{First}
\label{sec-1}
\label{heading-a}


  Hello Toto!

\section{Second}
\label{sec-2}
\label{heading-b}


  Hello Tata!

\section{Third}
\label{sec-3}


  Hello Titi!

\section{Fourth}
\label{sec-4}


  Hello Tete!

\hyperref[sec-1]{heading-a}
\hyperref[sec-2]{heading-b}
\hyperref[sec-3]{heading-c}
\hyperref[sec-4]{heading-d}
--8<---------------cut here---------------end--------------->8---

The first and second cases both generate labels which are not used in LaTeX.

The third and fourth cases are very elegant as they use only aliases (which
are dropped from the LaTeX code).

My questions are:

- what's the difference between using ID and CUSTOM_ID?

- the cases "Third" and "Fourth" are the more elegant from my point of view.
  Is this the right way of doing?

- what's the difference between cases "First" and "Second" (I mean between
  using PROPERTIES and # <<X>>)?

- in the documentation (section 4.2), we talk about "CUSTOM_ID property" does
  it mean that we should use it as in case 1?

Thanks.
Francesco


_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode-mXXj517/zsQ@public.gmane.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: LaTeX export of section links

[Bernt Hansen]

Francesco Pizzolante
<fpz-djc/iPCCuDYQheJpep6IedvLeJWuRmrY@public.gmane.org> writes:

> Hi,
>
> I have a few questions about links to sections.
>
> I've read that it is better to user IDs and CUSTOM_IDs to links to section...
>
> Here's a small example with 4 cases:
>
> --8<---------------cut here---------------start------------->8---
> * First
>   :PROPERTIES:
>   :CUSTOM_ID: heading-a
>   :END:
>
>   Hello Toto!
>
> * Second
> # <<heading-b>>
>
>   Hello Tata!
>
> * Third
> #+CUSTOM_ID: heading-c
>
>   Hello Titi!
>
> * Fourth
> #+ID: heading-d
>
>   Hello Tete!
>
> [[heading-a]]
> [[heading-b]]
> [[heading-c]]
> [[heading-d]]
> --8<---------------cut here---------------end--------------->8---
>
> Which give the following LaTeX code:
>
> --8<---------------cut here---------------start------------->8---
> \section{First}
> \label{sec-1}
> \label{heading-a}
>
>
>   Hello Toto!
>
> \section{Second}
> \label{sec-2}
> \label{heading-b}
>
>
>   Hello Tata!
>
> \section{Third}
> \label{sec-3}
>
>
>   Hello Titi!
>
> \section{Fourth}
> \label{sec-4}
>
>
>   Hello Tete!
>
> \hyperref[sec-1]{heading-a}
> \hyperref[sec-2]{heading-b}
> \hyperref[sec-3]{heading-c}
> \hyperref[sec-4]{heading-d}
> --8<---------------cut here---------------end--------------->8---
>
> The first and second cases both generate labels which are not used in LaTeX.
>
> The third and fourth cases are very elegant as they use only aliases (which
> are dropped from the LaTeX code).
>
> My questions are:
>
> - what's the difference between using ID and CUSTOM_ID?
>
> - the cases "Third" and "Fourth" are the more elegant from my point of view.
>   Is this the right way of doing?
>
> - what's the difference between cases "First" and "Second" (I mean between
>   using PROPERTIES and # <<X>>)?
>
> - in the documentation (section 4.2), we talk about "CUSTOM_ID property" does
>   it mean that we should use it as in case 1?

I use the CUSTOM_ID property for HTML exports (not LaTeX).

The ID property is automatically generated for me when I link to a task
and is a unique identifier for that heading across all of my org files.

,----
| * Some Task
|   :PROPERTIES:
|   :ID:       1329fa08-3c1d-4b73-b984-bef414b0dd3d
|   :END:
`----

This allows me to have more than one 'Some Task' in my files and each
will have a unique ID so that linking to it finds the correct one.

CUSTOM_IDs are a way to create links using a user-defined name.  I use
this for my org-mode document at http://doc.norang.ca/org-mode.html so
that I can reference a section by name such as
http://doc.norang.ca/org-mode.html#Publishing

If I later insert a section before Publishing the link still goes to the
correct place.  Without the CUSTOM_ID property I get a link like
http://doc.norang.ca/org-mode.html#sec-13 which may stop working if the
document sections are moved around.

I'm not sure what this buys you in LaTeX since I don't think the
CUSTOM_ID names are exposed in the links (correct me if I'm wrong).

I don't think the

#+CUSTOM_ID: name
#+ID: name

forms are valid.  These should be properties.  The above names are
probably just ignored during the export process.

HTH,
Bernt

Re: LaTeX export of section links

[Carsten Dominik]

Hi Francesco,

On Nov 20, 2009, at 12:34 PM, Francesco Pizzolante wrote:

> Hi,
>
> I have a few questions about links to sections.
>
> I've read that it is better to user IDs and CUSTOM_IDs to links to  
> section...
>
> Here's a small example with 4 cases:
>
> --8<---------------cut here---------------start------------->8---
> * First
>  :PROPERTIES:
>  :CUSTOM_ID: heading-a
>  :END:
>
>  Hello Toto!
>
> * Second
> # <<heading-b>>
>
>  Hello Tata!
>
> * Third
> #+CUSTOM_ID: heading-c
>
>  Hello Titi!
>
> * Fourth
> #+ID: heading-d
>
>  Hello Tete!
>
> [[heading-a]]
> [[heading-b]]
> [[heading-c]]
> [[heading-d]]
> --8<---------------cut here---------------end--------------->8---
>
> Which give the following LaTeX code:
>
> --8<---------------cut here---------------start------------->8---
> \section{First}
> \label{sec-1}
> \label{heading-a}
>
>
>  Hello Toto!
>
> \section{Second}
> \label{sec-2}
> \label{heading-b}
>
>
>  Hello Tata!
>
> \section{Third}
> \label{sec-3}
>
>
>  Hello Titi!
>
> \section{Fourth}
> \label{sec-4}
>
>
>  Hello Tete!
>
> \hyperref[sec-1]{heading-a}
> \hyperref[sec-2]{heading-b}
> \hyperref[sec-3]{heading-c}
> \hyperref[sec-4]{heading-d}
> --8<---------------cut here---------------end--------------->8---
>
> The first and second cases both generate labels which are not used  
> in LaTeX.

There is no harm in defining labels that are not used.

>
> The third and fourth cases are very elegant as they use only aliases  
> (which
> are dropped from the LaTeX code).

Third and forth are non-existent syntax in Org, these lines are just  
treated as comments and are removed during export.

>
> My questions are:
>
> - what's the difference between using ID and CUSTOM_ID?

Custom ID is human-readable, ID is usually a sha1 hash.  ID's have
the advantage that in HTML, they can link from one file to another
one.

> - the cases "Third" and "Fourth" are the more elegant from my point  
> of view.
>  Is this the right way of doing?

No, see above

>
> - what's the difference between cases "First" and "Second" (I mean  
> between
>  using PROPERTIES and # <<X>>)?

Only in the way that the property might be conceived as cleaner - but  
this
is really a matter of taste at this point.

>
> - in the documentation (section 4.2), we talk about "CUSTOM_ID  
> property" does
>  it mean that we should use it as in case 1?

Yes.

HTH

- Carsten

Re: LaTeX export of section links

[Francesco Pizzolante]

Hi Carsten,

>> --8<---------------cut here---------------start------------->8---
>> * First
>>  :PROPERTIES:
>>  :CUSTOM_ID: heading-a
>>  :END:
>>
>>  Hello Toto!
>>
>> * Second
>> # <<heading-b>>
>>
>>  Hello Tata!
>>
>> * Third
>> #+CUSTOM_ID: heading-c
>>
>>  Hello Titi!
>>
>> * Fourth
>> #+ID: heading-d
>>
>>  Hello Tete!
>>
>> [[heading-a]]
>> [[heading-b]]
>> [[heading-c]]
>> [[heading-d]]
>> --8<---------------cut here---------------end--------------->8---
>>
>> Which give the following LaTeX code:
>>
>> --8<---------------cut here---------------start------------->8---
>> \section{First}
>> \label{sec-1}
>> \label{heading-a}
>>
>>
>>  Hello Toto!
>>
>> \section{Second}
>> \label{sec-2}
>> \label{heading-b}
>>
>>
>>  Hello Tata!
>>
>> \section{Third}
>> \label{sec-3}
>>
>>
>>  Hello Titi!
>>
>> \section{Fourth}
>> \label{sec-4}
>>
>>
>>  Hello Tete!
>>
>> \hyperref[sec-1]{heading-a}
>> \hyperref[sec-2]{heading-b}
>> \hyperref[sec-3]{heading-c}
>> \hyperref[sec-4]{heading-d}
>> --8<---------------cut here---------------end--------------->8---
>>
>> The third and fourth cases are very elegant as they use only aliases (which
>> are dropped from the LaTeX code).
>
> Third and forth are non-existent syntax in Org, these lines are just treated
> as comments and are removed during export.

OK. But the information in these 2 comments is correctly used to replace the
alias (heading-c and heading-d) with the label generated by org during the
export. See the last 2 references in my example: these references are correct.
They thus have been correctly processed from heading-c and heading-d to sec-3
and sec-4... these comments are thus not simply removed... right?

In the case of the :CUSTOM_ID: property, the property is also used to convert
the alias to the label (heading-a to sec-1) but additionally an extra label
(heading-a) is created and not used.

That's why, when creating references to sections I found the #+CUSTOM_ID very
elegant... But apparently I don't have to use such syntax...

I wanted to know the recommended way of doing references...

Thanks a lot for your help.

Francesco


_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode-mXXj517/zsQ@public.gmane.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: LaTeX export of section links

[Carsten Dominik]

On Nov 20, 2009, at 4:14 PM, Francesco Pizzolante wrote:

> Hi Carsten,
>
>>> --8<---------------cut here---------------start------------->8---
>>> * First
>>> :PROPERTIES:
>>> :CUSTOM_ID: heading-a
>>> :END:
>>>
>>> Hello Toto!
>>>
>>> * Second
>>> # <<heading-b>>
>>>
>>> Hello Tata!
>>>
>>> * Third
>>> #+CUSTOM_ID: heading-c
>>>
>>> Hello Titi!
>>>
>>> * Fourth
>>> #+ID: heading-d
>>>
>>> Hello Tete!
>>>
>>> [[heading-a]]
>>> [[heading-b]]
>>> [[heading-c]]
>>> [[heading-d]]
>>> --8<---------------cut here---------------end--------------->8---
>>>
>>> Which give the following LaTeX code:
>>>
>>> --8<---------------cut here---------------start------------->8---
>>> \section{First}
>>> \label{sec-1}
>>> \label{heading-a}
>>>
>>>
>>> Hello Toto!
>>>
>>> \section{Second}
>>> \label{sec-2}
>>> \label{heading-b}
>>>
>>>
>>> Hello Tata!
>>>
>>> \section{Third}
>>> \label{sec-3}
>>>
>>>
>>> Hello Titi!
>>>
>>> \section{Fourth}
>>> \label{sec-4}
>>>
>>>
>>> Hello Tete!
>>>
>>> \hyperref[sec-1]{heading-a}
>>> \hyperref[sec-2]{heading-b}
>>> \hyperref[sec-3]{heading-c}
>>> \hyperref[sec-4]{heading-d}
>>> --8<---------------cut here---------------end--------------->8---
>>>
>>> The third and fourth cases are very elegant as they use only  
>>> aliases (which
>>> are dropped from the LaTeX code).
>>
>> Third and forth are non-existent syntax in Org, these lines are  
>> just treated
>> as comments and are removed during export.
>
> OK. But the information in these 2 comments is correctly used to  
> replace the
> alias (heading-c and heading-d) with the label generated by org  
> during the
> export. See the last 2 references in my example: these references  
> are correct.
> They thus have been correctly processed from heading-c and heading-d  
> to sec-3
> and sec-4... these comments are thus not simply removed... right?

This is only by chance, because a simple text search does match these  
two lines.
if you'd happen to have the string headline-a anywhere in the file,  
the link would point to the enclosing section.

>
> In the case of the :CUSTOM_ID: property, the property is also used  
> to convert
> the alias to the label (heading-a to sec-1) but additionally an  
> extra label
> (heading-a) is created and not used.
>
> That's why, when creating references to sections I found the # 
> +CUSTOM_ID very
> elegant... But apparently I don't have to use such syntax...
>

Not if you want to have reliable links, no.

- Carsten


> I wanted to know the recommended way of doing references...
>
> Thanks a lot for your help.
>
> Francesco

- Carsten

Re: LaTeX export of section links

[Francesco Pizzolante]

Carsten,

>> OK. But the information in these 2 comments is correctly used to replace the
>> alias (heading-c and heading-d) with the label generated by org during the
>> export. See the last 2 references in my example: these references are
>> correct.
>> They thus have been correctly processed from heading-c and heading-d 
>> to sec-3
>> and sec-4... these comments are thus not simply removed... right?
>
> This is only by chance, because a simple text search does match these two
> lines.
> if you'd happen to have the string headline-a anywhere in the file, the link
> would point to the enclosing section.
>
>> That's why, when creating references to sections I found the #
>> +CUSTOM_ID very
>> elegant... But apparently I don't have to use such syntax...
>
> Not if you want to have reliable links, no.

It's understood now.

Thanks a lot for your detailed answers.

Francesco


_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode-mXXj517/zsQ@public.gmane.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode