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, 18:17 UTC
Message-ID
<xmqq4ife344q.fsf@gitster.g>
In-Reply-To
<31577b6f-79b6-456f-9ecd-d1a3df6209e2@app.fastmail.com>
"Julia Evans" <julia@jvns.ca> writes:
Show 27 quoted lines
>> 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 meant something different, let me try again (with Peff's corrections as well):
>
>     The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
>     (instead of <<EXAMPLES>>) is that in some cases, <<EXAMPLES>> is
>     rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`.
>     <<EXAMPLES,EXAMPLES>> is rendered as just `EXAMPLES`, which gives us
>     more control over the output.
>
> ("in some cases" is code for "I still don't fully understand
> exactly when each one happens and why")
I see.  I think I understand now.

In your example, "leaving it vanilla without any extra adornment" is the control you want to gain by using the two-argument form, while in the version that shows my (mis)understanding, it is "you can mark up the string that is shown in any way you want".

Either way, the shorthand form forces you to leave the rendering to the toolchain, but the two-argument form gives you more control over how the text is rendered.

Thanks.
Previous: Julia EvansNext: Jeff King
Message 9 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.