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

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

From
Julia Evans <julia@jvns.ca>
Date
Sep 24, 2026, 12:30 UTC
Message-ID
<63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com>
In-Reply-To
<20260923214038.GA49087@coredump.intra.peff.net>
Show 22 quoted lines
> 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.

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.

Re your other message about breaking links because we're changing the HTML IDs: the options I see right now are

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.

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.
Previous: Jeff KingNext: Jeff King
Message 5 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.