Autocompletion for references

[jens-auer]

Similar to autocompletion for image and include files (#377), I would like to use autocompletion for internal and external references.

Details:

• Start typing << and an autosuggest should offer IDs in the current document
• Start typing xref: and an autosuggest should offer asciidoc files in the project. If the user selects a file foo.adoc, it should autocomplete to xref:foo.adoc# and then autosuggest IDs in the target document

Background: We import requirements from a requirement management tool and reference them in the text. Autocomplete would reduce errors and provide better efficiency.

[ggrossetie]

Are you talking specifically about Antora xref or AsciiDoc xref?

[jens-auer]

AsciiDoc xref (https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref)

[kharann]

Agreed! This would be a nice feature :)))

[apupier]

The IDs that can be referenced are these ones? https://docs.asciidoctor.org/asciidoc/latest/attributes/id/

@Mogztter Do we already have an utility parsing .adoc files to retrieve all IDs of a document?

I think that we can split this task with:

• [ ] Create utility method to retrieve IDs in a document
  • [ ] for simple case, only id defined in square bracket with shorthand syntax #
  • [ ] for simple case, only id defined in square bracket with longhand syntax id=
  • [ ] for simple case, only id defined in double square brackets with legacy syntax
  • [ ] for most advanced case when there are other things in square brackets like roles [quote.movie#roads,Dr. Emmett Brown]
• [ ] Provide completion in the same document after typing <<
• [ ] Propose completion in the same document when starting a word proposing the <<id>> ?
• [ ] Provide completion for other document in the workspace when typing xref: (should we restrict to .adoc document?) But maybe this one will need to be discussed a bit more because I feel like there are different ways to do it https://docs.asciidoctor.org/pdf-converter/latest/interdocument-xrefs/
• [ ] Provide completion for ids in referenced document when typing xref:my.adoc#

[ggrossetie]

Do we already have an utility parsing .adoc files to retrieve all IDs of a document?

I guess you can load the document and retrieve anchors using the catalog:

The processor always cataloged the following assets, regardless of this setting: block or inline anchors (key: :refs) (...) https://docs.asciidoctor.org/asciidoctor/latest/api/catalog-assets/#what-assets-are-cataloged

[ggrossetie]

Provide completion for other document in the workspace when typing xref: (should we restrict to .adoc document?)

Yes I think we should restrict to .adoc. This file extension will most likely be used in the mime-type registration.

[apupier]

After I discovered that some part was already implemented and based on first feedback on my 2 initial pull requests, Here is a new proposal to the split of tasks:

• [x] Restore completion for xref using legacy notation mostly as-is https://github.com/asciidoctor/asciidoctor-vscode/pull/667
• [x] Provide completion for short-hand and long-hand notation with same behavior than previously provided for legacy https://github.com/asciidoctor/asciidoctor-vscode/pull/668
• [ ] provide range for completion
• [ ] Increase priority of completion so that it doesn't appear at the end of all other non-specific to xref completions
• [x] Provide completion in the same document after typing << https://github.com/asciidoctor/asciidoctor-vscode/pull/670
• [ ] Propose completion in the same document when starting a word proposing the <<id>> ?
• [x] Insert path to the other document in the workspace when typing xref: Existing behavior was to insert only the id --> https://github.com/asciidoctor/asciidoctor-vscode/pull/667#issuecomment-1320857335
• [ ] Provide completion for ids in referenced document when typing xref:my.adoc#
• [x] Use VS Code file system API instead of Node fs https://github.com/asciidoctor/asciidoctor-vscode/pull/667#discussion_r1027072962 https://github.com/asciidoctor/asciidoctor-vscode/pull/669
• [ ] Support for most advanced case when there are other things in square brackets like roles [quote.movie#roads,Dr. Emmett Brown] (surely will be time to use load and catalog assets https://github.com/asciidoctor/asciidoctor-vscode/issues/648#issuecomment-1304542296