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

[Jeff King <peff@peff.net>]

On Tue, Sep 22, 2026 at 07:29:02PM +0000, Julia Evans via GitGitGadget wrote:

> 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