I'm generally very satisfied with the documentation but how to cross-reference sections is a bit all over the place between anchors, ID generation, cross-reference, etc and difficult to grasp as a whole. As a colleague exactly asked me the same question, I create the following example:
= Test cross-references
[#explicit_section]
== Explicit section
Explicit section with an explicit anchor
== Implicit section
No explicit anchor means autogenerated ID used as anchor
== Internal References
All these internal references are working:
* <<Explicit section>> (works only because title doesn't look like an anchor, thanks to the blank)
* <<explicit_section>>
* <<explicit_section, Alternate 1st Name>>
* xref:#explicit_section[Another Alternate 1st Name]
* <<_implicit_section>>
* <<_implicit_section, Alternate 2nd Name>>
* xref:#_implicit_section[Another Alternate 2nd Name]
Perhaps a similar documentation could be added to the documentation and the different pieces of the puzzle be put together for newcomers?
I'm generally very satisfied with the documentation but how to cross-reference sections is a bit all over the place between anchors, ID generation, cross-reference, etc and difficult to grasp as a whole. As a colleague exactly asked me the same question, I create the following example:
Perhaps a similar documentation could be added to the documentation and the different pieces of the puzzle be put together for newcomers?