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

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

From
Junio C Hamano <gitster@pobox.com>
Date
Sep 24, 2026, 17:15 UTC
Message-ID
<xmqqse2y371a.fsf@gitster.g>
In-Reply-To
<63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com>
"Julia Evans" <julia@jvns.ca> writes:
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.

To see if I understand correctly, let me rephrase the second paragraph a bit (not as an attempt to offer an improvement; by restating the above differently while expressing what I take to be the same thing, we will see whether I misunderstood what you wrote if my version ends up saying what you did not intend), as I found it somewhat puzzling.

    The short form <<EXAMPLES>> uses EXAMPLES as both the link
    target (which is not shown to the end user except in the
    browser's location bar when the link is visited) and the
    clickable text.  In different parts of the document, however,
    the text in HTML may need to be rendered as "EXAMPLES" or
    [EXAMPLES], which can be achieved by using the
    <<EXAMPLES,"EXAMPLES">> or <<EXAMPLES,[EXAMPLES]>> form.  For
    consistency, always use the longer form, even when there are no
    such typesetting constraints.

I'll mark the topic as Expecting a reroll in my working copy of the "What's cooking" report of the next issue.

Thanks.
Previous: Jeff KingNext: Julia Evans
Message 7 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.