The cross-reference information is documented all over the place

[ericzolf]

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?

[mojavelinux]

The documentation no longer lives in this repository, so this is not the proper place to file an issue. If the documentation pertains to the AsciiDoc Language guide, then you can file the issue in the following repository: https://github.com/asciidoctor/asciidoc-docs You may notice there is already an open issue related to this subject. See asciidoctor/asciidoc-docs#79