Re: internal links not being followed; instead, offer to create new heading

[Brian van den Broek <brian.van.den.broek@gmail.com>]

On 10 February 2013 16:21, John Hendy <jw.hendy@gmail.com> wrote:
> On Sun, Feb 10, 2013 at 12:53 PM, Brian van den Broek
> <brian.van.den.broek@gmail.com> wrote:
>> Hi all,
>>
>> I am having trouble with following internal org links. After carefully
>> reading the documentation (especially 4.2 Internal Links
>> <http://orgmode.org/org.html#Internal-links>) with the following
>> test.org file, I would expect that C-c C-o on the link text in the bar
>> tree would jump to the corresponding text in the foo tree.
>
> I'd never heard of being able to do this, so I read the documentation
> as well and this how I parsed it:
>
> - Is link text a URL?
>   - If yes -> open url
>   - If no, check current file
>
> - Is link text a custom ID?
>   - If yes -> go to headline with matching ID
>   - If no, check for custom target
>
> - Is there a match between [[link text]] and an occurrence of <<link
> text>> (dedicated target)?
>   - If yes -> go to the dedicated target location
>   - If no, check file type
>
> - Is this a .org file?
>   - If yes, check for a *headline* (or possibly keywords/tags)
> matching the [[link text]] [1]
>   - If no, conduct a string search for the [[link text]]
>
> [1] Quote: "If no dedicated target exists, Org will search for a
> headline that is exactly the link text but may also include a TODO
> keyword and tags"

<snip>

> 1) The documentation is incorrect (maybe), or
> 2) I don't know how to do C-c C-o provided by Org in a non-org file
> correctly (more probable)
>

<snip>


Hi John,

Thanks for the reply.

This prodded me to investigate more thoroughly (and to learn how to
use git bisect). I had observed that org 6.33 behaved as I expected
from looking at the documentation.

Bisecting led to:

commit a84c8a2cba8c510acfa0c14487f6c993f664a406
Author: Carsten Dominik <carsten.dominik@gmail.com>
Date:   Fri Aug 6 08:34:33 2010 +0200

    Make internal links in Org files search for an exact headline match

    * lisp/org.el (org-link-search-must-match-exact-headline): New option.
    (org-link-search-inhibit-query): New variable.
    (org-link-search): Search for exact headline match in Org files
    * doc/org.texi (Internal links): Document the changes in internal links.

    Internal links used to do a fuzzy text search for the link text.  This
    patch changes the behavior for Org files.  Here a link [[My Target]]
    now searches for an exact headline match, i.e. for a headline that
    does look like "* My Target", optionally with TODO keyword, priority
    cookie and tags.

    The new option `org-link-search-must-match-exact-headline' is
    `query-to-create' by default.  This means that a failed link search
    will offer to create the headline as a top-level headline at the end
    of the buffer.  This corresponds to a wiki-like behavior where missing
    targets are automatically created.  If you do not like this behavior,
    change the option to t.


The commit alters the docs, evidently intending them to be read as you
(John) read them. I'd argue that this wasn't entirely pulled off, as
the passage "Links such as ‘[[My Target]]’ or ‘[[My Target][Find my
target]]’ lead to a text search in the current file" combined with my
memory of how org used to work gave me a different expectation.

At any rate, to my cursory testing,

(setq org-link-search-must-match-exact-headline nil)

in my .emacs appears to make org behave as I expect it to.

Thanks and best,

Brian vdB