Transformation turns link:npm[] into <<npm,>>

[hohwille]

In AsciiDoc it is allowed and quite common to omit the linktext if same as the link itself. So link:npm[] renders as a link named npm pointing to .npm.
I just used devon-docgen 2.0.0 again and figured out that it seems to be broken with this scenario:
It transforms link:npm[] into <<npm,>> what creates a link without linktext that is therefore invisible.
As I never used this angled-bracked syntax that does not seemed to come from my changes... No clue why this worked for devon4j documentation (or maybe nobdoy ever read the PDF in detail and it also has this bug).

[jdiazgon]

I am going to paste here what I answered you by e-mail:

Even though it was some time ago, I remember that cross-references were a nightmare. As far as I remember, using link:… syntax was not working for internal cross references and the only way to make them work was by replacing them with <<…>> syntax. That's why I decided to replace them.

In order to fix your bug, I can see that Asciidoc allows using <<…>> while also omitting the link text. Please see the following example:

See <<paragraphs>> to learn how to write paragraphs.

Learn how to organize the document into <<section-titles,sections>>.

This comes from the official documentation https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#links

[jdiazgon]

In order to get aligned and find the correct solution, I have created a sample project to check whether to use link... or <<...>> syntax:

testing-docgen.zip

In the zip file from above, inside DOC_JumpTheQueue_Training.asciidoc, you will find two cross references:

. link:OASP4jComponents#createyourcomponents[External reference]

. link:DOC_JumpTheQueue_Training#OASP4JSGettingStarted[Internal reference]

One of them is a cross reference to an external document added with include::OASP4jComponents[] and the other one is an internal cross reference. These two links get converted to:

. <<OASP4jComponents#OASP4jComponents_createyourcomponents,External reference>>

. <<DOC_JumpTheQueue_Training#DOC_JumpTheQueue_Training_oasp4jsgettingstarted,Internal reference>>

As you can see, it converts them to <<...>> syntax, and also adds a prefix with the document name (DOC_JumpTheQueue_Training and OASP4jComponents).

I remember that I had to add this prefix in order to make them work properly, as sometimes you could have duplicated section names because we are combining multiple documents.

You can run mvn clean package and If you try the generated PDF, you will see that both links are working as expected.

In addition, I have also created a sample using only link:... syntax instead of <<...>>.

testing-docgen-links.zip

Please don't run mvn clean package and just mvn package. You will find the PDF using link:... syntax. In this case, cross references are not working.

[hohwille]

@jdiazgon thanks for your explanation.
I was referring to this change:
oasp/oasp-docgen@4ec3130#diff-600376dffeb79835ede4a0b285078036R86

So I am not saying that links do not need to be transformed. I am saying that before something like link:reference[] was transformed to xref:reference[] what was correct while it is now transformed into <<reference,>> what is wrong. Anyhow isnt the syntax <<...>> and xref:... more or less interchangeable? I will locally revet the rules to the old regex and test with that.
If that works for all cases, I will commit and push this. Then you can show or prove if there is still something wrong what requires us to use <<...>> instead and we can fix again. Otherwise we can just proceed with a release.

[hohwille]

BTW: what is the magic difference between the variables filename and currentfilename?

[jdiazgon]

If that works for all cases, I will commit and push this. Then you can show or prove if there is still something wrong what requires us to use <<...>> instead and we can fix again. Otherwise we can just proceed with a release.

Seems fair to me.

BTW: what is the magic difference between the variables filename and currentfilename?

I remember there was a case in which I needed both, but only on previous versions. Most probably I forgot to remove it :O

[hohwille]

I did the fixes and also clean-ups. I only require xref and could reduce the required logic. I tested this with:

* xref:anchor[]
* xref:anchor[linktext]
* link:page[]
* link:page#anchor[]
* link:page[linktext]
* link:page#anchor[linktext]

This gets converted to (the asciidoc file where I tested it was named features.asciidoc):

* xref:features_anchor[anchor]
* xref:features_anchor
* xref:page[page]
* xref:page_anchor[page#anchor]
* link:page[linktext]
* xref:page_anchor[linktext]

What is IMHO expected and renders + works fine.

[hohwille]

I would go for a 3.0.0 release so I can proceed with devonfw/ide#44
If there is anything still wrong, we can file a new issue, fix it and release 3.0.1.

[hohwille]

Fixed.