Feature: refactoring to allow xref's to be fully qualified (or not)

[danhaywood]

If I have a.adoc and b.adoc in the same module, then I can reference b from a using xref:b.adoc[].

Sometimes that is what I want.

But it would be nice to have a refactoring or intention to allow this to be extended to include the module (xref:foo:b.adoc[]) or component (xref;bar:foo:b.adoc[]). And similarly back again.

This idea could also be an action applied to an entire code base, a bit like "optimise imports", eg "use fully qualified xrefs everywhere" or "use abbreviated xref's where possible".

[ahus1]

There is unfortunately a semantic difference between xref:b.adoc[] and xref:bar:foo:b.adoc[]:

• the short form will link to the page in the current component's version
• the long form will link to the page in the lastest component's version
• there is an "extra long form xref:{page-version}@bar:foo:b.adoc[] that would link to the page in the current component's version

If you would use the long version in all your docs, the user will switch to the latest release documentation (even after they selected a specific version). This would make your documentation quite unusable.

The conclusion I came to:

• links should always be as short as possible when navigating within a component
• components should be defined on the level where you create major/minor releases
• when users would navigate between modules and expect to stay within the version they have selected, these modules should be part of the same component

I haven't seen that written down as a best practice anywhere yet, maybe I should raise that to the maintainers.

See #418 for a previous discussion, especially https://github.com/asciidoctor/asciidoctor-intellij-plugin/issues/418#issuecomment-615989451. Dan writes:

If you want to specify the component name, but stay in the current version, you can use:

xref:{page-version}@component-name::index.adoc[]

While this is a technically correct syntax, this is quite hard to read/maintain IMHO.

The three semantically identical forms to toggle between would then be:

xref:b.adoc[]
xref:foo:b.adoc[]
xref:{page-version}@bar:foo:b.adoc[]

I'm a little hesitant to allow rotating between these link types. That's probably the reason why I haven't touched it yet.

I'd like to hear your thoughts.

[danhaywood]

Hi Alex, sorry I've sat on this for so long.

I must admit I didn't know of that distinction between latest vs current, and the fact that components are intended to have potentially different versions. It does make me wonder whether I've structured the docs for Apache Isis correctly ... because we don't currently intend to release those components with different release cadences. Something for me to mull on.

Anyway, to your question, should the plugin allow cycling between:

{code} xref:b.adoc[] xref:foo:b.adoc[] xref:{page-version}@bar:foo:b.adoc[] {code}

Actually, I would say that it should support this, even though the last form is, as you say, very ugly. Why? - because then this subtle feature of the xref model becomes more widely known/understood.

That's my 2c, anyway.