From: Jeff King Date: Thu, 24 Sep 2026 18:42:20 GMT Subject: Re: [PATCH] doc: add more AsciiDoc cross-references 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: > I meant something different, let me try again (with Peff's corrections as well): > > The reason for using the more verbose <> > (instead of <>) is that in some cases, <> is > rendered as `the section called "EXAMPLES"` or `[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 <>, the xml generated by asciidoc looks like this: and the 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 <> instead, then the xml looks like: and the PRUNING 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