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

[John Hendy <jw.hendy@gmail.com>]

On Sun, Feb 10, 2013 at 4:28 PM, Brian van den Broek
<brian.van.den.broek@gmail.com> wrote:
> 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.
>

Nice digging! I saw that as well... one interpretation could be that
it should fall back to a full text search of the document. Another
interpretation is that if it's not a URL it falls back to a "text
search" in which "text" = a unique ID, dedicated <<target>> or
headline. Definitely not clear, though.

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

Awesome, and at the end of the day, having the functionality you *are*
looking for is what really matters. Glad you found that variable!


John

>
> Thanks and best,
>
> Brian vdB