From 8541433a4825598a33a8a03264a615d32186d9d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jani=20Ev=C3=A4kallio?= Date: Wed, 15 Jul 2020 16:11:49 +0100 Subject: [PATCH 1/4] proposal-link-definition-and-disambiguation: create --- ...osal-link-definition-and-disambiguation.md | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/proposal-link-definition-and-disambiguation.md diff --git a/docs/proposal-link-definition-and-disambiguation.md b/docs/proposal-link-definition-and-disambiguation.md new file mode 100644 index 000000000..e9278d0dd --- /dev/null +++ b/docs/proposal-link-definition-and-disambiguation.md @@ -0,0 +1,51 @@ +# Proposal: Link Definition and Disambiguation + +## Current status + +- We generate link ref defs from wiki-links inline +- Wiki links are expected to be the full source of truth, but we don't have enough infomration to conclusively disambiguate + +## Solution + +- Don't wipe out link ref defs. Only add/remove as needed. This can be our metadata for disambiguation. + +Let's say we have two documents in the workspace with the same title "Some Title" + +- We would have autocompletion base on title of the document + - This generates a link (typically a title, but could also have e.g. `:2` to disambiguate multiple links in the same file) + - The label doesn't matter, it could be used as a display label. We'll just auto-generate something sensible. Could even be a user setting. +- They would look like this: + ``` + [[Some File]] + [[Some File:2]] + ``` +- The link ref definitions become equivalent to import statements in a programming language, telling us where we are importing and what: + `[Some File]: some-file.md: "Some file in root directory"` + `[Some File:2]: subdirectory/some-file.md: "Some file in a subdirectory"` +- Here the title component of the link ref definition becomes optional since display name can be controlled by the label inside link. +- Note that we are adding .md here by default, but can omit that based on user preference as per @jojanaho's proposal + - Fixes GitHub UI rendering + - Breaks GitHub Pages links, but we'll override links in JavaScript as we do titles right now + - Going forward, Gatsby or other build tool can consume these directly +- This will also help us with anchor links, because we don't need to put them inline in the label anymore: + - `[Some File With Anchor Section]: some-file.md#anchor` +- This would also allow us to be more permissive of file names + - Markdown labels, the target needs to be a valid URI so we may needs to URI encode + - `[Some File With Anchor Section]: Some%20File%20With%20Anchor%20Section.md` +- For migrating into this structure, we'll need to do a bit of guesswork and/or manual editing, but we can build tooling to make this easier (e.g. in `foam-cli janitor/migrate`) and ensure lint consistency with `foam-cli lint` + - In VS Code we can surface any issues in the Problems/Diagnostic pane + - We could also show syntax errors (red squigglies) inline, with a `Quick Fix...` menu +- This all means that we will have to severely change Markdown Notes or replace it +- Take into account @digiguru's work on supporting accents etc. + +## Plan + +- CLI team is finishing first iteration of foam-cli janitor/migrate/lint + - This will not affect their work, and we'll ensure their work can be used in the new structure + - Link ref def parsing is already on their branch, let's try to land that ASAP +- Fix the .md generation @riccardo + - Change the way the links are generated in vs code + - Add a bit of javascript +- Start treating metadata as source of truth + - Definitions are already on https://github.com/foambubble/foam/pull/112/files +- For autocompletion, @jevakallio has started a spike, aim to get something prototyped by Friday \ No newline at end of file From d5d3036092d7962eeccdecd6207d68097cc10343 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jani=20Ev=C3=A4kallio?= Date: Wed, 15 Jul 2020 16:27:39 +0100 Subject: [PATCH 2/4] Update docs/proposal-link-definition-and-disambiguation.md Co-authored-by: Mathieu Dutour --- docs/proposal-link-definition-and-disambiguation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposal-link-definition-and-disambiguation.md b/docs/proposal-link-definition-and-disambiguation.md index e9278d0dd..45112e919 100644 --- a/docs/proposal-link-definition-and-disambiguation.md +++ b/docs/proposal-link-definition-and-disambiguation.md @@ -3,7 +3,7 @@ ## Current status - We generate link ref defs from wiki-links inline -- Wiki links are expected to be the full source of truth, but we don't have enough infomration to conclusively disambiguate +- Wiki links are expected to be the full source of truth, but we don't have enough information to conclusively disambiguate ## Solution @@ -48,4 +48,4 @@ Let's say we have two documents in the workspace with the same title "Some Title - Add a bit of javascript - Start treating metadata as source of truth - Definitions are already on https://github.com/foambubble/foam/pull/112/files -- For autocompletion, @jevakallio has started a spike, aim to get something prototyped by Friday \ No newline at end of file +- For autocompletion, @jevakallio has started a spike, aim to get something prototyped by Friday From 973ead6be438da6d59e2cd1a0afce3845924c693 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jani=20Ev=C3=A4kallio?= Date: Wed, 15 Jul 2020 17:41:56 +0100 Subject: [PATCH 3/4] Disambiguate the meaning of disambiguation --- docs/proposal-link-definition-and-disambiguation.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/proposal-link-definition-and-disambiguation.md b/docs/proposal-link-definition-and-disambiguation.md index 45112e919..e5b27f121 100644 --- a/docs/proposal-link-definition-and-disambiguation.md +++ b/docs/proposal-link-definition-and-disambiguation.md @@ -3,7 +3,9 @@ ## Current status - We generate link ref defs from wiki-links inline -- Wiki links are expected to be the full source of truth, but we don't have enough information to conclusively disambiguate +- Wiki links are expected to be the full source of truth, but we don't have enough information to conclusively disambiguate between files + - that have the same file name (in different directories) + - that have the same title (if autocompletion is by title) ## Solution From 11c65d7bda63d4a29303b32ba3617ebe53720150 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jani=20Ev=C3=A4kallio?= Date: Wed, 15 Jul 2020 17:43:37 +0100 Subject: [PATCH 4/4] Explain autocompletion entry format --- docs/proposal-link-definition-and-disambiguation.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/proposal-link-definition-and-disambiguation.md b/docs/proposal-link-definition-and-disambiguation.md index e5b27f121..f994cdd94 100644 --- a/docs/proposal-link-definition-and-disambiguation.md +++ b/docs/proposal-link-definition-and-disambiguation.md @@ -14,6 +14,8 @@ Let's say we have two documents in the workspace with the same title "Some Title" - We would have autocompletion base on title of the document + - Each autocompletion entry could be in format: + **Document title** - *path/to/document.md* - This generates a link (typically a title, but could also have e.g. `:2` to disambiguate multiple links in the same file) - The label doesn't matter, it could be used as a display label. We'll just auto-generate something sensible. Could even be a user setting. - They would look like this: