matrei opened a new issue, #16475: URL: https://github.com/apache/grails-core/issues/16475
## Summary The user guide is published twice: as one page per chapter (`guide/<chapter>.html`) and as `guide/single.html`. Many cross references only work in one of them, or in neither. ### Cross references to another chapter break on the chapter pages Asciidoctor renders `<<unitTesting>>` as `href="#unitTesting"`. In `single.html` every section is on the page, so that works. On a chapter page, a target in another chapter isn't on the page, so the link goes nowhere. The guide's own JavaScript doesn't resolve these links either. On 8.0.x, this affects 14 links: - `upgrading.html`: `<<unitTesting>>`, `<<sqlInjection>>` (twice), `<<multiTenancy>>`, `<<makingChangesToADeployedApplication>>` and `<<quartzDynamicScheduling>>` - `introduction.html` (What's New): `<<unitTesting>>`, `<<quartzLongRunningJobs>>`, `<<upgrading80x>>` (twice) and `<<security>>` - `spring.html`: `<<unitTesting>>` - `security.html`: `<<interceptors>>` - `services.html`: `<<multipleDatasources>>` Some pages avoid this by naming the chapter page, for example `link:theWebLayer.html#restfulMappings[...]`, but then the link leaves `single.html`. New content keeps adding plain `<<...>>` references to other chapters, because they look right in `single.html`. ### Cross references whose target doesn't exist on any page These links are broken in both versions of the guide: - **Spring Security:** `<<voters>>` (twice), `<<configuration>>` (CAS, LDAP and REST) and `<<installation>>` were written for the standalone plugin docs. In the guide, those sections have prefixed IDs such as `core-voters` and `cas-configuration`. `<<installation>>` does resolve in `single.html`, but to the Installation section of the Testing chapter, not to the Spring Security one. - **Spring Security:** `xref:springSecurityCore.adoc#springSecurityCore[...]`, and the same for `springSecurityAcl` and `springSecurityCas`, render as links to `springSecurityCore.html` and so on. Those pages don't exist, because these sections are part of `security.html`. This affects 8 links. - **Getting Started:** `link:commandLine.html#customCommands[...]` and `link:testing.html#integrationTests[...]` use fragments that don't exist. The sections are `creatingCustomCommands` and `integrationTesting`. - **What's New (8.0.x only):** `xref:testing/functionalTesting[...]`, `xref:deployment/deploymentAot[...]`, `xref:deployment/deploymentAotCache[...]`, `xref:conf/applicationClass/customizing[...]` and `xref:staticTypeCheckingAndCompilation/grailsCompileStatic[...]` render as `href="#testing/functionalTesting"` and so on. - **Plugins (8.0.x only):** `<<Ship plugin commands as a companion -cli artifact>>` is a natural cross reference to a section whose title contains markup (`` `-cli` ``), so Asciidoctor can't match it. - **Background Jobs:** `xref:upgrading.adoc#upgrading33x[...]` links to the Grails 3.3 upgrade notes, which the guide no longer contains. ## Affected versions The cross-chapter problem is mostly 8.0.x: on 7.0.x, only `<<multipleDatasources>>` in `services.html` is affected. The links that resolve on no page are on 7.0.x as well, apart from the What's New and Plugins ones, so they are broken in the published 7.x guide. 7.0.x also has four that 8.0.x has already fixed: - `<<profile>>` (twice) in the Command Line chapter, where `<profile>` is meant as a placeholder - `<<shiro,Shiro>>` in Authentication - `link:#mime[...]` in the HAL section - `books<<0>>.title` in Customizing Field Rendering, which renders the index as a link ## Steps to reproduce 1. `./gradlew :grails-doc:publishGuide -x aggregateGroovydoc` 2. Open `grails-doc/build/original-guide/guide/upgrading.html` and follow "Unit Testing" at the end of upgrade note 33, "Plugin Beans Now Register Before Spring Boot Auto-Configuration". The page doesn't move. 3. Open `guide/security.html` and follow "Spring Security Core plugin" in the ACL plugin introduction. The browser reports that `springSecurityCore.html` doesn't exist. ## Expected behaviour A cross reference leads to its target in both the chapter pages and `single.html`, and a plain `<<id>>` works for a target in any chapter. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
