Re: [PATCH] doc: add more AsciiDoc cross-references
- From
Jeff King <peff@peff.net>
- Date
- Sep 24, 2026, 18:42 UTC
- Message-ID
- <20260924184220.GA747880@coredump.intra.peff.net>
- In-Reply-To
- <31577b6f-79b6-456f-9ecd-d1a3df6209e2@app.fastmail.com>
On Thu, Sep 24, 2026 at 01:22:49PM -0400, Julia Evans wrote:
Show 10 quoted lines
> I meant something different, let me try again (with Peff's corrections as well):
>
> The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
> (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is
> rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`.
> <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us
> more control over the output.
>
> ("in some cases" is code for "I still don't fully understand
> exactly when each one happens and why")I think it's just "depending on the implementation and output backends". The complete table I saw is:
| HTML | manpage ---------------------------------------------- asciidoc | [FOO] | the section called "FOO" asciidoctor | FOO | the section called "FOO"
I'm not sure if the manpage expansion is asciidoc itself, though, or docbook. I guess that should be easy to test...
Ah, yeah, it's docbook. Using <<PRUNING>>, the xml generated by asciidoc looks like this:
and the <xref linkend="PRUNING"/> section of
and then the roff output from docbook becomes:
and the the section called \(lqPRUNING\(rq section of
So if we wanted to override that, we'd do it at the docbook layer. If you use <<PRUNING,PRUNING>> instead, then the xml looks like:
and the <link linkend="PRUNING">PRUNING</link> section of
which takes the decision away from docbook and uses the text we provide.
I don't think your commit message needs to go into that detail, but I thought it worth documenting in case we revisit this later.
-Peff