Proposal: Link Definition and Disambiguation

[jevakallio]

Masterstroke idea by @riccardoferretti! Super excited about this.

This is fully compatible with the existing Link Reference Definition Improvements proposal, with the exception that with this plan, it's no longer feasible to set LinkReferenceDefinitions: Off

[jojanaho]

Slapping comments here just by reading this from top to bottom, at this point got a question "disambiguate what"?

[jevakallio]

Pushed a disambiguation to this disambiguation :)

[jojanaho]

could autocomplete always be done with a combination of title and file path within the workspace - in a style of "My title - foo/bar/my-title.md"

[jevakallio]

Yes! Added this now.

[jojanaho]

Personally I would prefer the local links to use style [[foo/bar/my-title]] - would this be configurable?

[jevakallio]

@jojanaho, to clarify, do you mean you prefer foo/bar/my-title for just the disambiguated links in case of title conflicts, or always?

It could be configurable, since it's an arbitrary label. Options could include:

• file-name.md
• Title Cased File Name
• Document Title
• Arbitrary Label you write yourself

[jojanaho]

Always, since in my case it would improve readability - e.g [[book-summaries/war-and-peace]]

[jojanaho]

And to be exact, we have the freedom for arbitrary labels only when link ref defs are in use :)

[jojanaho]

Okay, so to disambiguate between the two or more title-cased wikilinks within a document. I think this solution would be okay if user wants to use title-cased wikilinks, which would lock them into link ref defs. Again personally I'd still like to use file paths to disambiguate - in many cases it could also be more readable (e.g. [[active/master-plan]] - [[obsolete/master-plan]] vs [[Master Plan]] - [[Master Plan:2]]

[valleyflowerbear]

If links are being revamped let's explicitly support aliasing too, something like [[some really long link|alias]]

[jojanaho]

If links are being revamped let's explicitly support aliasing too, something like [[some really long link|alias]]

Wouldn't note aliases be in the note frontmatter? Or do you mean alternative title for a link?

[valleyflowerbear]

Wouldn't note aliases be in the note frontmatter? Or do you mean alternative title for a link?

Alternative title for a link is a good way of putting it. For example, say I have a file called integration-methods.md and I want to use it in a sentence, I would do To solve this problem, you must first [[integration-methods|integrate]] this equation.

It's easier to read and allows the text to flow more naturally.

[jevakallio]

I would do To solve this problem, you must first [[integration-methods|integrate]] this equation.

It's easier to read and allows the text to flow more naturally.

I'm not very opinionated either way, but if we're talking about reading-friendliness, I'd rather put the bit that's meant to be read up-front: "you must first [[integrate:integration-methods]] this equation" -- that way my eyes can jump to the end of the block once I hit the delimiter.

Same could be achieved with syntax highlighting too.

Just thinking out loud.

[jevakallio]

@jojanaho and I had a discussion about this. I'm dropping our rough notes here, will integrate these as part of the proposal when I have time, but for now just to get @riccardoferretti up to speed.

Ideally, we would like to be able to support both style links

• [[Note title]]
  • In this case, disambiguation is necessary via link definitions
• [[path/to/literal-reference-to-file]]
  • We would no longer allow just [[literal-reference-to-file]] without path, unless of course the source document and target document are in the same directory, in which case [[literal-reference-to-file]] is a literal reference to file in the same directory
  • In this case, disambiguation is not necessary
  • As per Link Reference Definition Improvements spec, we should aim to support a "linkReferenceDefinitions: Off" approach

Now, I don't want to play the "please everyone" game, but I feel like these are both completely valid use cases, and I think actually not very complicated to implement:

Write time

• Always show autocomplete menu items in form of: Title path/to/file
  • The autocomplete list can be filtered by matching parts of either title or file name
• When autocomplete item is selected, expand the link label to either [[Title]] or [[path/to/file]] depending based on user preference
• Generate link definitions (or not) based on user preference

Read time

This same logic should work when constructing a graph, and when resolving the link target (e.g. Cmd+Click following the link):

• Check if the link has a corresponding reference definition
  • If it does, use the "target" from there
  • If not, treat the link label as literal path (extension optional)
  • If not found, warn the user (via linting)

---

I think we need to do a bit more thinking about this, but this would be an ideal outcome, if it doesn't introduce too much complexity.

Conceptually this makes perfect sense, when you think of link reference definitions as disambiguations. If the link doesn't require a disambiguation, it could be "autoreferenced", i.e. not have a link ref def

The setting for this could be something relatively user friendly, like: "linkFormat: title | path".

[jevakallio]

I regret to say this, but I think we need to write a specification :)

It doesn't need to be a formal document, but I think it should pull together a few currently disparate pieces of work:

• The link format (outlined in this PR and above GH discussions)
• Implementation (outlined in https://foambubble.github.io/foam/link-reference-definition-improvements)
• User experience
  • Explaining what the user flow for adding and interacting with links should be like
    • IMO GistPad does this extremely well, we should look at that as a baseline appoach
    • This could be demonstrated via actual GIFs of GistPad, or a prototyped approach based on it

I can work on this earliest next week, but if anyone else wants to take a stab of pulling a draft of such a specification document together, that would be fantastic and I can provide inputs for it -- just don't have concentrated time to work on it.

/cc @riccardoferretti @jojanaho

[jojanaho]

I think we need to write a specification ... but if anyone else wants to take a stab of pulling a draft of such a specification document together, that would be fantastic and I can provide inputs for it

I started to work on this, just first trying to write down all the aspects to consider

[jevakallio]

Closing in favour of foambubble/rfcs#3