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

[Jeff King <peff@peff.net>]

On Tue, Sep 22, 2026 at 04:54:17PM -0400, Julia Evans wrote:

> >> +See the <<PRUNING,PRUNING>> section below for more details.
> >
> > OK, we already see an example of the <<double,double>> reference
> > notation.  This needs to be in this form, intead of <<pruning>>,
> > because it refers to the named section of a different file, namely
> > git-fetch.adoc (I am just trying to make sure I understood your
> > explanation correctly).
> 
> The reason I explained this in a bit of a confusing way is that I'm not
> 100% sure in which exact cases we need to use <<double,double>
> instead of <<single>.
> 
> I double checked just now that if in `git-push.adoc`, I change:
> 
> 	of a remote (see the section <<REMOTES,REMOTES>> below),
> 
> to:
> 
> 	of a remote (see the section <<REMOTES>> below),
> 
> Then there's a problem where in the HTML version it displays as
> "[REMOTES]" instead of just "REMOTES".

Reading the asciidoc docs, I'm not sure how this is affected by the
location of the reference at all. AFAICT the syntax <<FOO,BAR>> just
means "link to FOO, using the text BAR".

The single-item <<FOO>> more or less means the same as "<<FOO,FOO>>",
but as you noticed, vanilla asciidoc seems to pick the text "[FOO]"
here, whereas asciidoctor uses "FOO". I'm using asciidoc 10.2.1 and
asciidoctor 2.0.26 to test, and I see it even with the PRUNING examples,
too.

Even weirder, in the manpage output both implementations actually expand
this to: the section called "FOO". So changing your patch like this:

  -See the <<PRUNING,PRUNING>> section below for more details.
  +See the <<PRUNING>> section below for more details.

gives doc-diff output like this:

  -         See the PRUNING section below for more details.
  +         See the the section called “PRUNING” section below for more details.

which is obviously nonsense.

I could very well believe that some older versions did other weird
things in the presence of includes. ;) But AFAICT the real need for the
doubled text is to control what is in the expanded text (both because of
differences between the versions, but also differences in output
backends).

Which is kind of a shame, because writing just <<PRUNING>> makes the
source a lot more readable. I wonder if we can configure these text
fallbacks, which would let us use the single-item form reliably.

Alternatively, I think this is all syntactic sugar over "xref:FOO[BAR]".
We already have our own linkgit: macro for linking to whole pages
(which, btw, is something xref could do for us, too, though maybe not
without the magic man section number). I wonder if it would be useful to
have a section-link macro that would give us more control, but again,
the syntax of <<PRUNING>> sure is nice.

> But in the <<PRUNING,PRUNING>> example, just using <<PRUNING>>
> seems to work. I started working on this way back in December 2025 
> so I assume that something in this patch was affected by this issue
> and that's how I came across this problem but I'm not sure exactly
> what it was.

So I think using <<PRUNING,PRUNING>> is probably OK for a first pass
here, rather than getting bogged down in trying to configure both
asciidoc implementations. We can shrink them later if we come up with a
good solution.

I do think the explanation in the commit message might be misleading,
though (at least from what I can gather from the asciidoc reference and
from a few experiments).

-Peff