Re: [PATCH] doc: add more AsciiDoc cross-references
From: Jeff King <hidden>
Date: 2026-09-23 22:00:54
On Tue, Sep 22, 2026 at 07:29:02PM +0000, Julia Evans via GitGitGadget wrote:
quoted hunk ↗ jump to hunk
diff --git a/Documentation/git-add.adoc b/Documentation/git-add.adoc index 16b06e38e1..906db7ccf3 100644 --- a/Documentation/git-add.adoc +++ b/Documentation/git-add.adoc@@ -117,7 +117,7 @@ The intent of this option is to pick and choose lines of the patch to apply, or even to modify the contents of lines to be staged. This can be quicker and more flexible than using the interactive hunk selector. However, it is easy to confuse oneself and create a patch that does not -apply to the index. See EDITING PATCHES below. +apply to the index. See <<EDITING_PATCHES,EDITING PATCHES>> below. `-u`:: `--update`::@@ -375,6 +375,7 @@ diff:: `HEAD` and index). +[[EDITING_PATCHES]] EDITING PATCHES ---------------
I think we have section auto-ids enabled these days, so I don't think it's strictly necessary to make our own ids like this. But the generated ids are syntactically a little different, so you'd need: -apply to the index. See <<EDITING_PATCHES,EDITING PATCHES>> below. +apply to the index. See <<_editing_patches,EDITING PATCHES>> below. The asciidoctor reference made some mention of linking to sections directly by title (a "Natural cross reference"). But it did not seem to work for me in this case, and anyway I think it only works with the single-argument form (which has other headaches). So we could probably get away with using the auto-generated ones, but it does mean using their syntax. Though there is another related issue there: these ids are also somewhat user-visible, because they end up in the final HTML documents and people link to them. Right now this works: https://git-scm.com/docs/git-add#_editing_patches but after your patch, I think it will have to be spelled as: https://git-scm.com/docs/git-add#EDITING_PATCHES I think I prefer the all-caps one, but it is kind of gross that as we change the docs we may break fragment links across the web. IIRC there are similar problems with linking to list items, where we auto-generate ids to allow linking to specific options (this is custom code on git-scm.com, not asciidoctor and not within git.git). The resulting fragment ids are long and gross and have changed a few times over the years (I think we had to add in some disambiguation because multiple lists in the same file might generate the same id). So I dunno what all that means. Your patch "breaks" existing links into the HTML by assigning a new (but IMHO prettier) id. At some point I don't know how much we want to care about that. But I thought it was worth ignoring consciously rather than accidentally. ;)
-See the "OBJECT PREREQUISITES" section below. +See the <<OBJECT_PREREQUISITES,"OBJECT PREREQUISITES">> section below.
I noticed a few interesting typographic bits, like this one. I'd have expected: "<<OBJECT_PREREQUISITES,OBJECT PREREQUISITES>>" but I guess this is one of the inconsistencies you mentioned in the cover letter. I'm fine punting on those for now and fixing them later. Especially this one:
- `BATCH OUTPUT` below for details. + <<BATCH_OUTPUT,`BATCH OUTPUT`>> below for details.
which can't move the backticks out (because they'd suppress the xref syntax). But probably it ought to drop the backticks entirely (which again can come later). -Peff