Make asciidoc indexes and file names more consistent #1612

rhaetor · 2024-11-23T10:54:40Z

Changes to make automation of downstreaming easier.

Mostly about adding explicit anchors and id:s.

Some file renaming.

The occasional language fix.

Comments in nav

ppalaga · 2024-11-28T20:48:47Z

Thanks for the monumental work, @rhaetor. I hope I'll able to go through it in coming days.

ppalaga

Will cont. later

ppalaga · 2024-12-03T15:29:41Z

docs/modules/ROOT/nav.adoc

+** xref:release-notes/rn-3-15-0.adoc[3.15.0 LTS]
+** xref:release-notes/rn-3-14-0.adoc[3.14.0]
+** xref:release-notes/rn-3-13-1.adoc[3.13.1]
+** xref:release-notes/rn-3-13-0.adoc[3.13.0]
+** xref:release-notes/rn-3-12-0.adoc[3.12.0]
+** xref:release-notes/rn-3-11-1.adoc[3.11.1]
+** xref:release-notes/rn-3-11-0.adoc[3.11.0]
+** xref:release-notes/rn-3-10-0.adoc[3.10.0]
+** xref:release-notes/rn-3-9-0.adoc[3.9.0]
+** xref:release-notes/rn-3-8-6.adoc[3.8.6 LTS]
+** xref:release-notes/rn-3-8-5.adoc[3.8.5 LTS]
+** xref:release-notes/rn-3-8-4.adoc[3.8.4 LTS]
+** xref:release-notes/rn-3-8-3.adoc[3.8.3 LTS]
+** xref:release-notes/rn-3-8-2.adoc[3.8.2 LTS]
+** xref:release-notes/rn-3-8-1.adoc[3.8.1 LTS]
+** xref:release-notes/rn-3-8-0.adoc[3.8.0 LTS]
+** xref:release-notes/rn-2-7-1.adoc[2.7.1]
+** xref:release-notes/rn-2-7-0.adoc[2.7.0]
+** xref:release-notes/rn-2-6-1.adoc[2.6.1]
+** xref:release-notes/rn-2-6-0.adoc[2.6.0]
+** xref:release-notes/rn-2-5-0.adoc[2.5.0]
+** xref:release-notes/rn-2-4-0.adoc[2.4.0]
+** xref:release-notes/rn-2-3-1.adoc[2.3.1]
+** xref:release-notes/rn-2-3-0.adoc[2.3.0]
+** xref:release-notes/rn-2-2-2.adoc[2.2.2 LTS]
+** xref:release-notes/rn-2-2-1.adoc[2.2.1 LTS]
+** xref:release-notes/rn-2-2-0.adoc[2.2.0 LTS]


I would not mind the short prefix, but why not the verbatim version with dots in the name? It is much easier to copy/paste/search/replace when looking for/editing the stuff.

I had links break because of periods in the anchors, so wanted to avoid them completely. Not sure if this solution is all that brilliant.

ppalaga · 2024-12-03T15:32:13Z

docs/modules/ROOT/nav.adoc

 * xref:reference/index.adoc[Reference]
-// extensions: START


This markers may not be removed bc. they are used by a maven plugin generating this part of the navigation.

Extension come and go and the plugin helps to keep the nav. up to date. It is not such a big problem with QCXF, because we do not have that many extensions. I just copyied the approach from Camel Quarkus, where they are so many that there is no other way than doing it with a tool.

Is the plugin using the marks, or generating them?

ppalaga · 2024-12-03T15:32:38Z

docs/modules/ROOT/nav.adoc

@@ -74,4 +85,3 @@ endif::[]
 ** xref:reference/extensions/quarkus-cxf-services-sts.adoc[Security Token Service (STS)]
 ** xref:reference/extensions/quarkus-cxf-rt-transports-http-hc5.adoc[HTTP Async Transport]
 ** xref:reference/extensions/quarkus-cxf-xjc-plugins.adoc[XJC Plugins]
-// extensions: END


Same as previous, the marker has to come back.

ppalaga · 2024-12-03T15:35:07Z

docs/modules/ROOT/pages/index.adoc

+* xref:security-guide/index.adoc#security-guide-index[Security guide] - documents various security related aspects of {quarkus-cxf-project-name}, such as SSL/TLS, Authentication and Authorization
+* xref:release-notes/index.adoc#release-notes-index[Release notes] - Release notes documents for the past releases
+* xref:release-planning.adoc#release-planning[Release planning] - when new releases of {quarkus-cxf-project-name} are to be expected
+* xref:reference/index.adoc#reference-index[Reference] - the full list of supported specifications, use cases and configuration options


I see why these *-index anchors are needed. We break the external links, but it is perhaps not that important in this specific case. Hence I am fine with the change.

I am open to suggestions on how to solve the problem another way. At the time I had no better idea.

ppalaga · 2024-12-03T15:37:08Z

docs/modules/ROOT/nav.adoc

+** xref:user-guide/ssl-tls-https.adoc[SSL, TLS and HTTPS]
+** xref:user-guide/authentication-authorization.adoc[Authentication and authorization]
+** xref:security-guide/ws-securitypolicy-authentication-authorization.adoc[WS-SecurityPolicy Authentication]


We would have to add page-aliases attribute set to the old name, so that Antora cares for redirects. (I need to test how well page-aliases work at all.) Otherwise we'd break external links, which I'd prefer to avoid.

I think page-alias should work, but I can't swear to it.

Why I changed it is so we have consistent main headers, file names and links. Maybe I went overboard here.

docs/modules/ROOT/pages/reference/extensions/quarkus-cxf-integration-tracing-opentelemetry.adoc

docs/modules/ROOT/pages/reference/extensions/quarkus-cxf-rt-features-metrics.adoc

docs/modules/ROOT/pages/reference/extensions/quarkus-cxf-rt-transports-http-hc5.adoc

ppalaga

I have now looked through the whole change set. Thank a lot @rhaetor for the effort!

Generally it looks great. Some details commented above need some minor work.

The only thing I am not especially keen on is the requirement to have the #fragment in every single every page xref. It is rather cumbersome to do and will be hard to enforce over time.

I wonder whether you cannot script that on your side? If you merge all pages to a single document, you need to change the file name in all xrefs anyway, no? Can't you run some regex replacement like s|/([^/.]).adoc|/single.adoc#$1| when importing the pages?

rhaetor

I will revert the #anchor for all the doc links. I agree that it creates more work. Not having them makes it more important that the anchors, headlines, and filenames match, though. (as with ssl-tls-https)

rhaetor · 2024-12-03T16:50:30Z

docs/modules/ROOT/nav.adoc

+** xref:user-guide/ssl-tls-https.adoc[SSL, TLS and HTTPS]
+** xref:user-guide/authentication-authorization.adoc[Authentication and authorization]
+** xref:security-guide/ws-securitypolicy-authentication-authorization.adoc[WS-SecurityPolicy Authentication]


I think page-alias should work, but I can't swear to it.

Why I changed it is so we have consistent main headers, file names and links. Maybe I went overboard here.

rhaetor · 2024-12-03T16:52:09Z

docs/modules/ROOT/nav.adoc

+** xref:release-notes/rn-3-15-0.adoc[3.15.0 LTS]
+** xref:release-notes/rn-3-14-0.adoc[3.14.0]
+** xref:release-notes/rn-3-13-1.adoc[3.13.1]
+** xref:release-notes/rn-3-13-0.adoc[3.13.0]
+** xref:release-notes/rn-3-12-0.adoc[3.12.0]
+** xref:release-notes/rn-3-11-1.adoc[3.11.1]
+** xref:release-notes/rn-3-11-0.adoc[3.11.0]
+** xref:release-notes/rn-3-10-0.adoc[3.10.0]
+** xref:release-notes/rn-3-9-0.adoc[3.9.0]
+** xref:release-notes/rn-3-8-6.adoc[3.8.6 LTS]
+** xref:release-notes/rn-3-8-5.adoc[3.8.5 LTS]
+** xref:release-notes/rn-3-8-4.adoc[3.8.4 LTS]
+** xref:release-notes/rn-3-8-3.adoc[3.8.3 LTS]
+** xref:release-notes/rn-3-8-2.adoc[3.8.2 LTS]
+** xref:release-notes/rn-3-8-1.adoc[3.8.1 LTS]
+** xref:release-notes/rn-3-8-0.adoc[3.8.0 LTS]
+** xref:release-notes/rn-2-7-1.adoc[2.7.1]
+** xref:release-notes/rn-2-7-0.adoc[2.7.0]
+** xref:release-notes/rn-2-6-1.adoc[2.6.1]
+** xref:release-notes/rn-2-6-0.adoc[2.6.0]
+** xref:release-notes/rn-2-5-0.adoc[2.5.0]
+** xref:release-notes/rn-2-4-0.adoc[2.4.0]
+** xref:release-notes/rn-2-3-1.adoc[2.3.1]
+** xref:release-notes/rn-2-3-0.adoc[2.3.0]
+** xref:release-notes/rn-2-2-2.adoc[2.2.2 LTS]
+** xref:release-notes/rn-2-2-1.adoc[2.2.1 LTS]
+** xref:release-notes/rn-2-2-0.adoc[2.2.0 LTS]


I had links break because of periods in the anchors, so wanted to avoid them completely. Not sure if this solution is all that brilliant.

rhaetor · 2024-12-03T16:53:04Z

docs/modules/ROOT/nav.adoc

 * xref:reference/index.adoc[Reference]
-// extensions: START


Is the plugin using the marks, or generating them?

rhaetor · 2024-12-03T16:54:18Z

docs/modules/ROOT/pages/index.adoc

+* xref:security-guide/index.adoc#security-guide-index[Security guide] - documents various security related aspects of {quarkus-cxf-project-name}, such as SSL/TLS, Authentication and Authorization
+* xref:release-notes/index.adoc#release-notes-index[Release notes] - Release notes documents for the past releases
+* xref:release-planning.adoc#release-planning[Release planning] - when new releases of {quarkus-cxf-project-name} are to be expected
+* xref:reference/index.adoc#reference-index[Reference] - the full list of supported specifications, use cases and configuration options


I am open to suggestions on how to solve the problem another way. At the time I had no better idea.

Don't use "Please" "Make sure" > "Ensure"

ppalaga · 2024-12-06T21:30:20Z

Closing in favor of #1655

rhaetor added 3 commits November 23, 2024 11:38

Make filename and asciidoc identifers consistent

40e9d71

Comments in nav

Make filename and asciidoc identifers consistent

d9fcea1

Comments in nav

Cleanup

478a590

rhaetor requested a review from a team as a code owner November 23, 2024 10:54

rhaetor added 23 commits November 23, 2024 11:58

Nav and index changes

e1ac54e

Minor fix

72bcb7c

Nav fix

6ec37ec

https://

dc9661c

https://

0115360

{version}

54babec

{version}

a607219

Another ID

55d905c

Another ID

6ba3f87

Implicit ID to explicit

5d42441

Implicit ID to explicit

a3aea78

Consistent crossreferences

b71ecc0

Typos

42fbb92

NOTE and IMPORTANT admonitions

491d5a5

Xref fix

6d90444

Error in tag replacement

1da092c

images

9d96f2a

Duplicate examples.

85dec0e

Duplicate id:s, language.

76f6bf3

Nav

e76940b

Nav

38903f7

NOTE

2953025

capitalization

43aa428

ppalaga reviewed Dec 3, 2024

View reviewed changes

rhaetor commented Dec 3, 2024

View reviewed changes

rhaetor added 5 commits December 3, 2024 19:03

Extensions markers in nav

80edd60

Removed link #fragments

7b84c30

IMPORTANT admonition

d5304bc

IMPORTANT admonition

53e3cb3

Documentation style guide rules:

2b1f499

Don't use "Please" "Make sure" > "Ensure"

ppalaga closed this Dec 6, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make asciidoc indexes and file names more consistent #1612

Make asciidoc indexes and file names more consistent #1612

rhaetor commented Nov 23, 2024 •

edited

Loading

ppalaga commented Nov 28, 2024

ppalaga left a comment

ppalaga Dec 3, 2024

rhaetor Dec 3, 2024

ppalaga Dec 3, 2024

rhaetor Dec 3, 2024

ppalaga Dec 3, 2024

ppalaga Dec 3, 2024

rhaetor Dec 3, 2024

ppalaga Dec 3, 2024

rhaetor Dec 3, 2024

ppalaga left a comment

rhaetor left a comment

rhaetor Dec 3, 2024

rhaetor Dec 3, 2024

rhaetor Dec 3, 2024

rhaetor Dec 3, 2024

ppalaga commented Dec 6, 2024

Make asciidoc indexes and file names more consistent #1612

Make asciidoc indexes and file names more consistent #1612

Conversation

rhaetor commented Nov 23, 2024 • edited Loading

ppalaga commented Nov 28, 2024

ppalaga left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ppalaga left a comment

Choose a reason for hiding this comment

rhaetor left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ppalaga commented Dec 6, 2024

rhaetor commented Nov 23, 2024 •

edited

Loading