Re: [PATCH] doc: add more AsciiDoc cross-references

[Jeff King <peff@peff.net>]

On Thu, Sep 24, 2026 at 08:30:31AM -0400, Julia Evans wrote:

> Thanks for investigating, I was really dreading looking into the guts of
> asciidoc to figure out exactly what was happening. It would be nice to be able
> to write just <<PRUNING>>, especially because I believe asciidoctor will check
> that internal links are valid, so there's no concern about breaking links if we
> change the title of a section.

I think asciidoc(tor) doesn't do it itself, so HTML will be generated
with a broken link. But in the manpage flow, we pass through xml
docbook, which does complain loudly. So that will be enough to let us
know about the breakage.

> 1. Leave it is as is and break some links
> 2. manually enter the ID like `_editing_patches`, trying to make sure to always
> match the auto-generated ID (I'm not sure how to do that). I think this might
> also cause some confusion for editors in the future as to why the section IDs
> are formatted like that
> 3. Somehow fix it so that we can just do <<PRUNING>>
> 
> I'm not sure if #1 or #2 is better, obviously I'm biased towards #1 because
> it's less work for me. #3 seems like the ideal but I don't know how to do that.

Yeah, sorry I was a bit rambly in my other message, but I think #1 is
OK. I'm not sure if asciidoctor allows us to configure the algorithm for
converting a title into a section id. If it does, it might be nice to
have a flag day where we make all of the auto-ids look like what we'd
expect. But that is a totally separate topic, and can happen later.

I think #3 is sort-of orthogonal, as I couldn't get the "natural" xrefs
to work. So we have to either declare the ids ourselves or use the
auto-generated ones, at which point the use of single- or double-
<<FOO>> xrefs is purely a matter for the linking site, not the linked-to
section.

> Here's a revised commit message, can submit that as a v2 if it seems correct.
> 
>     doc: add more AsciiDoc cross-references
> 
>     Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
>     below" to make the man pages easier to navigate on the web.
> 
>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
>     (instead of <<EXAMPLES>>) is in some cases, the HTML output is rendered
>     as `"EXAMPLES"` or `[EXAMPLES]` instead of just `EXAMPLES`.
>     So this gives us more control over how the output looks.
> 
>     This also changes some of the HTML IDs of the headings from `_examples`
>     to `EXAMPLES`, which has the potential to break some links.

Yeah, I think this is OK. If we want to be really pedantic, the
"EXAMPLES" with quotes is only in the manpages, not the HTML (and also
includes extra text: "the section called"). But the point is the same.
We must use the doubled form to get consistent text output.

-Peff