emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed

* LaTeX export of section links
@ 2009-11-20 11:34 Francesco Pizzolante
  2009-11-20 12:42 ` Bernt Hansen
  2009-11-20 14:13 ` Carsten Dominik
  0 siblings, 2 replies; 6+ messages in thread
From: Francesco Pizzolante @ 2009-11-20 11:34 UTC (permalink / raw)
  To: mailing-list-org-mode

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

^ permalink raw reply	[flat|nested] 6+ messages in thread

• * Re: LaTeX export of section links
    2009-11-20 11:34 LaTeX export of section links Francesco Pizzolante
  @ 2009-11-20 12:42 ` Bernt Hansen
    2009-11-20 14:13 ` Carsten Dominik
    1 sibling, 0 replies; 6+ messages in thread
  From: Bernt Hansen @ 2009-11-20 12:42 UTC (permalink / raw)
    To: Francesco Pizzolante; +Cc: mailing-list-org-mode
  
  
  
  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
  
  ^ permalink raw reply	[flat|nested] 6+ messages in thread

• * Re: LaTeX export of section links
    2009-11-20 11:34 LaTeX export of section links Francesco Pizzolante
    2009-11-20 12:42 ` Bernt Hansen
  @ 2009-11-20 14:13 ` Carsten Dominik
         [not found]   ` <361B87B2-29D2-465C-84BE-A82376059D35-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
    1 sibling, 1 reply; 6+ messages in thread
  From: Carsten Dominik @ 2009-11-20 14:13 UTC (permalink / raw)
    To: Francesco Pizzolante; +Cc: mailing-list-org-mode
  
  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
  
  ^ permalink raw reply	[flat|nested] 6+ messages in thread

• • [parent not found: <361B87B2-29D2-465C-84BE-A82376059D35-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

  • • * Re: LaTeX export of section links
             [not found]   ` <361B87B2-29D2-465C-84BE-A82376059D35-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
      @ 2009-11-20 15:14     ` Francesco Pizzolante
        2009-11-20 15:18       ` Carsten Dominik
        0 siblings, 1 reply; 6+ messages in thread
      From: Francesco Pizzolante @ 2009-11-20 15:14 UTC (permalink / raw)
        To: Carsten Dominik; +Cc: mailing-list-org-mode
      
      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
      
      ^ permalink raw reply	[flat|nested] 6+ messages in thread

    • • * Re: LaTeX export of section links
          2009-11-20 15:14     ` Francesco Pizzolante
        @ 2009-11-20 15:18       ` Carsten Dominik
               [not found]         ` <224945F4-65E4-4904-9065-ADF3FE9F4DD2-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
          0 siblings, 1 reply; 6+ messages in thread
        From: Carsten Dominik @ 2009-11-20 15:18 UTC (permalink / raw)
          To: Francesco Pizzolante; +Cc: mailing-list-org-mode
        
        
        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
        
        ^ permalink raw reply	[flat|nested] 6+ messages in thread

      • • [parent not found: <224945F4-65E4-4904-9065-ADF3FE9F4DD2-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

        • • * Re: LaTeX export of section links
                   [not found]         ` <224945F4-65E4-4904-9065-ADF3FE9F4DD2-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
            @ 2009-11-20 15:23           ` Francesco Pizzolante
              0 siblings, 0 replies; 6+ messages in thread
            From: Francesco Pizzolante @ 2009-11-20 15:23 UTC (permalink / raw)
              To: Carsten Dominik; +Cc: mailing-list-org-mode
            
            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
            
            ^ permalink raw reply	[flat|nested] 6+ messages in thread

end of thread, other threads:[~2009-11-20 15:23 UTC | newest]

Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2009-11-20 11:34 LaTeX export of section links Francesco Pizzolante
2009-11-20 12:42 ` Bernt Hansen
2009-11-20 14:13 ` Carsten Dominik
     [not found]   ` <361B87B2-29D2-465C-84BE-A82376059D35-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2009-11-20 15:14     ` Francesco Pizzolante
2009-11-20 15:18       ` Carsten Dominik
     [not found]         ` <224945F4-65E4-4904-9065-ADF3FE9F4DD2-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
2009-11-20 15:23           ` Francesco Pizzolante

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).