From: Junio C Hamano Date: Thu, 24 Sep 2026 17:15:13 GMT Subject: Re: [PATCH] doc: add more AsciiDoc cross-references Message-ID: In-Reply-To: <63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com> "Julia Evans" writes: > 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 <> > below" to make the man pages easier to navigate on the web. > > The reason for using the more verbose <> > (instead of <>) 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 <> 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 <> or <> 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.