Clarify and expand xref macro end user documentation
Original issue: https://github.com/asciidoctor/asciidoc-docs/issues/79
Some users are having difficulty finding the documentation about how to use the xref macro (both the shorthand and named version), determining when they should use which form, and what options and attributes are associated with the xref macro.
This issue should:
- identify what areas of the xref end user documentation needs to be clarified (restructured, reworked, more search-friendly, direct headings, etc.)
- restructure and edit the xref content that is problematic
- add new content and/or new examples for any undocumented xref options, attributes, or common use cases
The existing xref documentation pages are:
- Cross References: https://docs.asciidoctor.org/asciidoc/latest/macros/xref/
- Document to Document Cross References: https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/
- Cross Reference Text and Styles: https://docs.asciidoctor.org/asciidoc/latest/macros/xref-text-and-style/
- Validate Cross References: https://docs.asciidoctor.org/asciidoc/latest/macros/xref-validate/