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:

• Restore completion for xref using legacy notation mostly as-is Fix completion after xref: for old double-square bracket notation #667
• Provide completion for short-hand and long-hand notation with same behavior than previously provided for legacy ref #648 provide completion short hand and long hand notation with similar scope of legacy #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
• Provide completion in the same document after typing << 648 provide completion after<<from same document #670
• Propose completion in the same document when starting a word proposing the <<id>> ?
• Insert path to the other document in the workspace when typing xref: Existing behavior was to insert only the id --> Fix completion after xref: for old double-square bracket notation #667 (comment)
• Provide completion for ids in referenced document when typing xref:my.adoc#
• Use VS Code file system API instead of Node fs Fix completion after xref: for old double-square bracket notation #667 (comment) ref #648 use vscode fs api instead of Node fs #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 Autocompletion for references #648 (comment)