Re: [dev] Implement "ref" link types

[Nicolas Goaziou <n.goaziou@gmail.com>]

Hello,

Carsten Dominik <carsten.dominik@gmail.com> writes:

> On Feb 20, 2012, at 1:51 AM, Nicolas Goaziou wrote:

>> There are still a few limitations. For example, you cannot reference
>> a precise list item since items do not accept affiliated keywords.

> Ah, yes, this is right.

Thinking about it, there may exist a better alternative to [[ref:name]]
links: fuzzy links. In other words, "#+name: something" could be made an
alternate of "<<something>>", with a lower priority.

On the Org side, when a link like [[something]] or [[something][text]]
is encountered in a buffer, the search would go on like this:

  1. Search any "<<something>>" or "#+target: something"[1].
  2. If none is found, search any "#+name: something".
  3. If it fails, try to find the headline "* something".
  4. Eventually offer to create such headline. This step doesn't apply
     during export.

On the export side, it depends on the description part of the link:

  - If there's a description (i.e. [[something][description]]), display
    it and link to target if possible, whatever that target is.

  - If there's no description:

    1. A link to an invisible target will be replaced with _nothing_
       (that's the point of being invisible).

    2. A link to a target (i.e. <<something>>) will be replaced with the
       sequence number of the closest item or headline[2]. Examples:

       #+begin_src org
       - item one
       - item two
         - <<here>> item two dot one
       #+end_src

       Any link like [[here]] will be replaced with "2.1" during export.

       #+begin_src org
       * Headline one
       * Headline two
         * Headline two dot one

           Some paragraph.

           Another paragraph <<warning>>.
       #+end_src

       Here [[warning]] will also be replaced with "2.1" during export.
       Note that [[Headline two dot one]] would also be replaced with
       "2.1".

    3. An link to an element (i.e. "#+name: something") would return the
       sequence number of that element among elements of the same type
       with a caption, a name affiliated keyword, or both. Example:

       #+begin_src org
       #+name: letters
       #+caption: I know my alphabet.
       |a|b|c|

       |foo|bar|

       #+name: numbers
       |1|2|3|
       #+end_src

       Here, a [[numbers]] link would be replaced with 2, since middle
       table has no name nor caption.


To sum it up, at a quick glance, I can see the following:

  - Pros ::
    + No new syntax,
    + Possibly number every element, including items.
  - Cons ::
    + Fuzzy links are a bit overloaded, but, on the other hand, linking to
      headlines is not very useful since custom-id and id implementation.
    + There is more documentation to write.

Again, what do you think?


Regards,

[1] This is the replacement for invisible targets, since they cannot
live in comments anymore.

[2] If headlines are not numbered (i.e. num:nil), replace link with
headline's title instead.

-- 
Nicolas Goaziou