Using an include to another component with a specific version in an Antora resource id fails

[danyill]

Observed vs. expected behavior

I'm using the "Modules" feature in IntelliJ with Antora for many repositories which in general has worked seamlessly and well.
Thank you for this very excellent feature.

Currently, I have an issue in that an include to a specific component version specified by an attribute doesn't seem to function correctly.

I am specifying an include as:

include::{siprotec5-version}siprotec5:ROOT:partial$typicals.adoc[]

And receive a linter error as:

Can't resolve Antora prefix '1.1.0@siprotec5:ROOT:partial$' for target '1.1.0@siprotec5:ROOT:partial$typicals.adoc' (introduction.adoc, line 7)

It does appear that the attribute is being correctly resolved.

I have checked the component descriptor and I have:

mulhollandd@TP-5CG2442DK6 MINGW64 /c/Git/digital-substation/standard-packages/siprotec5 (v1.1.0)
$ cat antora.yml
name: siprotec5
title: SIPROTEC 5
version: 1.1.0
start_page: index.adoc
asciidoc:
  attributes:
    source-language: asciidoc@
    xrefstyle: short@
    example-caption: false
    listing-caption: Example@
    url-repo: https://gitlab.tpwiki.com/digital-substation/standard-packages/siprotec5
nav:
- modules/ROOT/nav.adoc
- modules/procedures/nav.adoc

The site builds and displays correctly but the IntelliJ linter complains and the preview doesn't function.

Built site:

IntelliJ screenshot

Note the:

• Linter error
• Preview doesn't function for include

I think I have correctly specified the coordinates as per https://docs.antora.org/antora/latest/page/resource-id-coordinates/

I have tried to:

• Restart IntelliJ
• Reload all from disk
• Invalidate caches and restart

Steps to reproduce

• Not sure - my playbook and projects are not public.
• Not sure how best to retrieve further diagnostic information (is there a way to see which components and versions have been "seen" by the extension?)
• If it seems worthwhile and I am not encountering a known limitation I can try and generate a reproduction playbook and project

Environment

Plugin Version: 0.38.20

IntelliJ Details:

IntelliJ IDEA 2022.1.1 (Community Edition)
Build #IC-221.5591.52, built on May 11, 2022
Runtime version: 11.0.14.1+1-b2043.45 amd64
VM: OpenJDK 64-Bit Server VM by JetBrains s.r.o.
Windows 10 10.0
GC: G1 Young Generation, G1 Old Generation
Memory: 2048M
Cores: 12
Non-Bundled Plugins:
com.github.bric3.excalidraw (0.3.2)
org.asciidoctor.intellij.asciidoc (0.38.20)

Kotlin: 221-1.6.21-release-337-IJ5591.52

[danyill]

Hmmm... I think I understand.

Having become quite confused I checked out that specific version of the component depended on and all my errors cleared.

Does this plugin only look at the current file system and so if a version is specified that must be the checked out version?

[ahus1]

Does this plugin only look at the current file system and so if a version is specified that must be the checked out version?

Yes, this is the way the plugin works. It doesn't have access to the Git history to retrieve the files. If you have cross-references like this, I recommend to set up a multi-module project as described in the docs.

AFAIK the plugin is a bit more lenient when it comes to xrefs that it can't resolve to version it doesn't know about. But with includes, they are shown as error.

I could skip showing an error if the component is unknown, and only show an error if the component is known but the file doesn't exist. WDYT?

[danyill]

Thank you for confirming.

I don't think this is especially important but I do think it would be nice if (in the absence of other git information) if the plugin could use the version available on the file system (i.e. drop the version in the resource id) and then perhaps provide an informative error that there was a mismatch (preferably just once per component).

This is useful anyway because sometimes it is necessary to specify a version but the version doesn't exist until publishing occurs (we usually use an attribute for this) and it would save the back and forth of having to change the attribute.

I am using the multi-module project feature and it's great (thanks 👍). But I think I assumed that as part of that feature that the plugin was accessing the git information.

[ahus1]

I do think it would be nice if (in the absence of other git information) if the plugin could use the version available on the file system (i.e. drop the version in the resource id)

I am a bit skeptical here as this might then show some content that doesn't exist when it is rendered. So I'll rather show a warning here, and a dummy text that the include wasn't found.

This is useful anyway because sometimes it is necessary to specify a version but the version doesn't exist until publishing occurs (we usually use an attribute for this) and it would save the back and forth of having to change the attribute.

You can use the .asciidoctorconfig file to set an attribute that is only visible in IntelliJ to handle the preview. Maybe this could help in your case.

[ahus1]

There is now pre-release 0.43.0 available which includes this change: It will no longer show an error in the editor, and will show a message "Unresolved Antora component" if the component is not found in the current project.

The plugin will show an error with the inspection about the Antora module resolve in the following case for an include:

• It is an Antora reference
• A version is specified
• The Antora component is known with the given version, but the module is not found.

Reasoning: If you specify a specific version and the component is known, but not the module, you've most likely misspelled the module name.

Please let me know how this works for you.

The pre-release of the plugin is available from GitHub releases and the IntelliJ AsciiDoc EAP repository.

[ahus1]

BTW, I just saw that you're running IntelliJ 2022.1.1. The preview version will require 2024.2 to run. Please let me know if you can still test this version.

[danyill]

I expect I can test on a different machine within the next couple of days, thanks for your work on this.

…

On Mon, Aug 12, 2024 at 8:20 AM Alexander Schwartz ***@***.***> wrote: BTW, I just saw that you're running IntelliJ 2022.1.1. The preview version will require 2024.2 to run. Please let me know if you can still test this version. — Reply to this email directly, view it on GitHub <#1660 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAFEXX5LJMWKOY7IQAWU2OLZQ7BO7AVCNFSM6AAAAABLXKU3YCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOBSHA3TONBVGI> . You are receiving this because you authored the thread.Message ID: ***@***.*** com>

--

-- Private or confidential message? Public Key available here <https://pgp.mit.edu/pks/lookup?search=dan.mulholland%40gmail.com&op=index> :

[danyill]

Thanks, I have tested, sorry for the delay.

I have no error in the editor window (the error shown is unrelated) when I have an incorrect version specifier and I am missing the content associated with the versioned include in the preview with an error message shown:

In this case siprotec-version is 1.1.1 but the siprotec component has a different version (dev).

While I'd rather have the preview shown (and the version dropped with an informative message) I think your alternative approach of using a .asciidoctorconfig may also be a good one.
Thanks for the tip!

[ahus1]

Thanks. I'm considering this resolved then. When you continue with the .asciidoctorconfig setting, note that it can only overwrite configurations that are soft-set in a playbook or component.

As it seems you upgraded to the very latest version of the plugin, I assume there is no need to backport. Let me know if this assumption is not correct.