XDoc conversion from Javadoc do not relativize links and break previous document version

[rnveach]

As seen in https://checkstyle.sourceforge.io/version/10.15.0/checks/coding/declarationorder.html#DeclarationOrder

Code Conventions for the Java Programming Language

Link generated is https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852 and breaks out of the version documentation. Link's generated source from the macro is at

checkstyle/src/xdocs/checks/coding/declarationorder.xml

Line 15 in 45cbedf

<a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852">

.

We should be kept in the specific version as much as possible.

This link comes from

checkstyle/src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/DeclarationOrderCheck.java

Line 38 in 45cbedf

* <a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852">

.

Javadoc should stay absolute, but conversion to xdoc should make it relative. It looks like ~12 pages do this in total.

[romani]

Please share image or some more details , I don't understand issue.

[rnveach]

There is no image.

Our xdoc's links need to be relative so we don't break out of version documentation. I pasted the link to one example in the first post and showed the text of the link. It is not relative, and will take user out of version documentation.

It is the same as #14876 except these links are connected to our templates.

Edit: Our doxia macros have no connection here. I thought there was. We should still look into our javadoc and xdoc synchronizer test and maybe somehow ensure xdoc's links are always relative.

[romani]

will take user out of version documentation.

Do you mean that link should point to the same domain checkstyle.sourceforge.io ?

[rnveach]

No, it shouldn't point to any domain. A specific domain would be an absolute link, not a relative one.

https://kb.blackbaud.com/knowledgebase/Article/67574

[romani]

Absolute link is defined in template

checkstyle/src/xdocs/checks/coding/declarationorder.xml.template

Line 15 in 45cbedf

<a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852">

If we fix it to be relative, problem might be resolved.

[romani]

after 2 PRs merged. we have no more absolute links in xdoc

✔ ~/java/github/checkstyle/checkstyle [master|✔] 
15:27 $ ag "checkstyle.org/styleguides"
src/main/java/com/puppycrawl/tools/checkstyle/checks/naming/AbbreviationAsWordInNameCheck.java
40: * <a href="https://checkstyle.org/styleguides/google-java-style-20220203/javaguide.html#s5.3-camel-case">

src/main/java/com/puppycrawl/tools/checkstyle/checks/indentation/CommentsIndentationCheck.java
38: * <a href="https://checkstyle.org/styleguides/google-java-style-20220203/javaguide.html#s4.8.6.1-block-comment-style">

src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/MultipleVariableDeclarationsCheck.java
36: * href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc5.html#a2992">

src/main/java/com/puppycrawl/tools/checkstyle/checks/coding/DeclarationOrderCheck.java
38: * <a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852">
43: * <a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852">

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/naming/AbbreviationAsWordInNameCheck.xml
10: &lt;a href="https://checkstyle.org/styleguides/google-java-style-20220203/javaguide.html#s5.3-camel-case"&gt;

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/indentation/CommentsIndentationCheck.xml
11: &lt;a href="https://checkstyle.org/styleguides/google-java-style-20220203/javaguide.html#s4.8.6.1-block-comment-style"&gt;

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/coding/DeclarationOrderCheck.xml
10: &lt;a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852"&gt;
15: &lt;a href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc2.html#a1852"&gt;

src/main/resources/com/puppycrawl/tools/checkstyle/meta/checks/coding/MultipleVariableDeclarationsCheck.xml
13: href="https://checkstyle.org/styleguides/sun-code-conventions-19990420/CodeConventions.doc5.html#a2992"&gt;

only in javadoc and in meta.

avadoc content is distributed as zip in maven, so we should not use their relative links.
metadata is also content that can be copied to any place in plugin and be viewed from unpredictable location.