Re: [PATCH] doc: add more AsciiDoc cross-references
- From
Jean-Noël AVILA <avila.jn@gmail.com>
- Date
- Oct 18, 2026, 12:32 UTC
- Message-ID
- <meK9MCd0TPmi4tPMhh-XUA@gmail.com>
- In-Reply-To
- <665e8f8d-7bde-449b-a390-10875135cba2@app.fastmail.com>
On Tuesday, 22 September 2026 22:54:17 CEST Julia Evans wrote:
Show 8 quoted lines
> > Oh, I love a change that is so sharply focused on a single issue and > > describes what the problem being solved is. > : > :) > : > >> * I tested it by running this script > >> > >> (https://gist.github.com/jvns/039c8ed0add092f2179f0dba52ebb896)
which
> >> builds the previous and current views of all the man pages. I
looked
> >> at the output to make sure there were no differences. You can see
the
Show 11 quoted lines
> >> output in that gist. > >> > >> * I believe that asciidoctor will automatically make sure that there > >> > >> are no broken links. > >> > >> * I also spot checked some of the HTML output to make sure it looked > >> > >> reasonable. > >> > >> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-
options.adoc
Show 39 quoted lines
> >> index 035f780e58..47dea1de8e 100644 > >> --- a/Documentation/fetch-options.adoc > >> +++ b/Documentation/fetch-options.adoc > >> @@ -199,7 +199,7 @@ endif::git-pull[] > >> > >> providing the tag refspec. > >> > >> ifndef::git-pull[] > >> + > >> > >> -See the PRUNING section below for more details. > >> +See the <<PRUNING,PRUNING>> section below for more details. > > > > OK, we already see an example of the <<double,double>> reference > > notation. This needs to be in this form, intead of <<pruning>>, > > because it refers to the named section of a different file, namely > > git-fetch.adoc (I am just trying to make sure I understood your > > explanation correctly). > > The reason I explained this in a bit of a confusing way is that I'm not > 100% sure in which exact cases we need to use <<double,double> > instead of <<single>. > > I double checked just now that if in `git-push.adoc`, I change: > > of a remote (see the section <<REMOTES,REMOTES>> below), > > to: > > of a remote (see the section <<REMOTES>> below), > > Then there's a problem where in the HTML version it displays as > "[REMOTES]" instead of just "REMOTES". > > But in the <<PRUNING,PRUNING>> example, just using <<PRUNING>> > seems to work. I started working on this way back in December 2025 > so I assume that something in this patch was affected by this issue > and that's how I came across this problem but I'm not sure exactly > what it was.
I have a strong argument for using <<PRUNING,PRUNING>>, it is that the manual pages are now translated and that the translated term can require changes in the target languages and not be compatible with simply inserting the title, where English is very malleable.