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 24, 2026, 15:55 UTC
Message-ID
<20260924155517.GB736248@coredump.intra.peff.net>
In-Reply-To
<63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com>
On Thu, Sep 24, 2026 at 08:30:31AM -0400, Julia Evans wrote:
Show 5 quoted lines
> 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.

Show 9 quoted lines
> 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.

Show 14 quoted lines
> 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
Previous: Julia EvansNext: Junio C Hamano
Message 6 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.