git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Jeff King <peff@peff.net>
Date
Sep 23, 2026, 21:40 UTC
Message-ID
<20260923214038.GA49087@coredump.intra.peff.net>
In-Reply-To
<665e8f8d-7bde-449b-a390-10875135cba2@app.fastmail.com>
On Tue, Sep 22, 2026 at 04:54:17PM -0400, Julia Evans wrote:
Show 22 quoted lines
> >> +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.

Show 5 quoted lines
> 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
Previous: Julia EvansNext: Julia Evans
Message 4 of 23 in “doc: add more AsciiDoc cross-references”
  1. doc: add more AsciiDoc cross-referencesJulia Evans via GitGitGadget, Sep 22, 2026
  2. Junio C HamanoSep 22, 2026
  3. Julia EvansSep 22, 2026
  4. Jeff KingSep 23, 2026
  5. Julia EvansSep 24, 2026
  6. Jeff KingSep 24, 2026
  7. Junio C HamanoSep 24, 2026
  8. Julia EvansSep 24, 2026
  9. Junio C HamanoSep 24, 2026
  10. Jeff KingSep 24, 2026
  11. Jean-Noël AVILAOct 18, 2026
  12. Kristoffer HaugsbakkSep 23, 2026
  13. Jeff KingSep 23, 2026
  14. doc: add more AsciiDoc cross-referencesJulia Evans via GitGitGadget, Sep 25, 2026
  15. Jeff KingSep 25, 2026
  16. Rewriting the Git tutorial to cover less contentJulia Evans, Sep 25, 2026
  17. Junio C HamanoSep 25, 2026
  18. Julia EvansSep 25, 2026
  19. Junio C HamanoSep 25, 2026
  20. Julia EvansSep 25, 2026
  21. Junio C HamanoSep 25, 2026
  22. Julia EvansSep 28, 2026
  23. Junio C HamanoSep 28, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.