Disable autocompletion for document attributes in contexts where they aren't processed

[anthonyvdotbe]

Description

Document attributes aren't processed in certain delimited blocks, namely: dash-delimited, dot-delimited, and plus-delimited blocks. So I propose to disable autocompletion within such blocks. This would also improve the use case of typing code samples within AsciiDoc documents, where currently I'm offered a rather unhelpful autocompletion whenever typing a left curly brace.

System Information

extension: 2.7.13 VS Code: 1.42.1 OS: Windows 10

To Reproduce

Type a left curly brace within a source code block:

[source,java]
----
{
----

Screenshots & Files

[danyill]

Thanks for filing this issue.

Unfortunately, it's not quite that simple -- the blocks you indicate can generally have attributes added to them to allow substitutions, try the following Asciidoc for example:

= Test
:testattr: hello

== Dash delimited

=== Four dashes (code block)

----
Attributes don't work by default, see: {testattr}
----

But they can work if the correct role is on:

[subs=attributes+]
----
Attributes can work {testattr}
----

=== Two dashes (open block)

--
Attributes do work here: {testattr}
--

=== Four pluses (passthrough)

++++
Attributes don't work here: {testattr}
++++

Attributes can be used in a pass through though:

[subs=attributes+]
++++
But they do work here {testattr}
++++

So what could we do? I'm open to ideas, here are some of mine:

1. We could offer a "disable autocompletion" option for this extension
2. We could try to offer a "disable autocompletion" on source blocks. This is not that easy because the Textmate language scopes are not accessible via the code API (see this issue). The other way to do this would be to run this through the Asciidoc processor and try to pull line-by-line information back on where attribute substitutions were enabled. This would be some effort (PR welcome!)
3. We could do nothing as it is possible for users to disable autocompletion manually, see this article and the vs code docs
4. Perhaps a better way to write code would be to use the include directive in your source block and then edit your e.g. java files separately in the code editor.

Thoughts?

[anthonyvdotbe]

Thanks for your ideas.

1. I don't think this is worth the effort since there's also option 3
2. this would be ideal, but I understand it's also a lot more effort compared to the alternatives (I didn't know about subs=attributes+, and don't have experience with extensions, so I wasn't able to judge the amount of effort this would take)
3. this is also sufficient for me. I found that I can disable the autocompletion just for AsciiDoc with the single setting below. And I can still trigger autocompletion with Ctrl+Space if I want to.

   "[asciidoc]": {
       "editor.suggestOnTriggerCharacters": false
   }

4. yes, I agree, but most of my AsciiDoc usage is "notepad usage", so I'd like to keep the Java bits & pieces embedded in the document

I have one more question about option 3: what are the other "trigger characters" of this extension, besides the left curly brace? And where is this in the source code? I tried searching the repo for things like "trigger" and "suggest", but to no avail.

[danyill]

Thanks for the feedback.

In vs-code this is called IntelliSense/Completions. We register a completion provider here, against the character {:

https://github.com/asciidoctor/asciidoctor-vscode/blob/ab6a20190dc4c02618549069844f86c172cdb73e/src/extension.ts#L44

And the completion is handled by:

https://github.com/asciidoctor/asciidoctor-vscode/blob/ab6a20190dc4c02618549069844f86c172cdb73e/src/features/attributeCompleter.ts

For more information, see the vs-code completion example:

https://github.com/microsoft/vscode-extension-samples/tree/master/completions-sample

At the moment this is the only completion provider.

I am planning to add more completions for the syntax, especially for the include, image, video, audio and icon macros/directives but that may be some time off. I'd like tab completion on paths to files and help for image options.

I'll leave this open for a little while and if I find some time I'll do a bit more research. There's been some brief, recent discussion on the Asciidoctor/Antora gitter channel about the processor exporting a "manifest" of information about a document to help extensions provide functionality and this kind of issue would seem to me like a good candidate.

A feasible alternative for now might be an extension which makes available the substitution information for each block (I think we can just call the subs method on each block) and this combined with the sourcemap might allow us to get a line number --> substitutions mapping. I might have a play with this if time allows.