search

asciidoctor / asciidoctor.org

:globe_with_meridians: Asciidoctor project site. Composed in AsciiDoc. Baked with Awestruct.
https://asciidoctor.org
Other
322 stars 807 forks source link

Document the xref: syntax #973

Closed agoncal closed 2 years ago

agoncal commented 3 years ago

For many years I've been using the following syntax when it comes to have chapter cross references:

:xrefstyle: short

<<my.adoc#myref>>

But sometimes I need to use both short and basic style. Thanks to Dan[1] I discovered the xref: syntax[2]:

:xrefstyle: short

xref:my.adoc#myref

xref:my.adoc#myref[xrefstyle=basic]

This syntax is not documented. Neither on the manual[3] nor the guide[4]. Maybe this should be documented in the "Customizing the Cross Reference Text" section[5] of the manual ? Something like:

You can also customize the label (short, basic or full) on each cross-reference using the xref: syntax. This syntax can be used for internal as well as external references:

Refer to xref:interalref[xrefstyle=basic]

Refer to xref:interalref[xrefstyle=full]

Refer to xref:external.adoc#externalref[xrefstyle=basic]

Refer to xref:external.adoc#externalref[xrefstyle=short]

WDYT?

[1] https://twitter.com/mojavelinux/status/1311398097226883072 [2] https://github.com/asciidoctor/asciidoctor/blob/master/features/xref.feature#L1049 [3] https://asciidoctor.org/docs/user-manual/ [4] https://asciidoctor.org/docs/asciidoc-writers-guide/ [5] https://asciidoctor.org/docs/user-manual/#customizing-the-cross-reference-text

mojavelinux commented 2 years ago

This syntax is not documented.

In fact, this syntax is documented on the following page: https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/

The problem is that the documentation is very sparse. It also doesn't address why the xref macro is preferred over the shorthand for this particular case. So it can stand to be elaborated.

mojavelinux commented 2 years ago

Moved to https://github.com/asciidoctor/asciidoc-docs/issues/79