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 22, 2026, 20:20 UTC
Message-ID
<xmqq4ifhdon2.fsf@gitster.g>
In-Reply-To
<pull.2416.git.git.1790105342890.gitgitgadget@gmail.com>
"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
Show 14 quoted lines
> From: Julia Evans <julia@jvns.ca>
>
> Instead of saying "see EXAMPLES below", say "see <<EXAMPLES,EXAMPLES>>
> below" to make the man pages easier to navigate on the web.
>
> The reason for using the more verbose <<EXAMPLES,EXAMPLES>>
> (instead of <<EXAMPLES>>) is that if the header that `<<EXAMPLES>>`
> is referring to is in an included page (for example `REMOTES` in the
> `git-push` man page), then AsciiDoc will think it's a broken link even
> though it isn't. So it's easier to just make all of the links use the
> form with two parts.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---

Oh, I love a change that is so sharply focused on a single issue and describes what the problem being solved is.

Show 9 quoted lines
>      * 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
>        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.
Show 10 quoted lines
> diff --git a/Documentation/fetch-options.adoc b/Documentation/fetch-options.adoc
> 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).

Show 6 quoted lines
> @@ -210,7 +210,7 @@ See the PRUNING section below for more details.
>  	a shorthand for providing the explicit tag refspec along with
>  	`--prune`, see the discussion about that in its documentation.
>  +
> -See the PRUNING section below for more details.
> +See the <<PRUNING,PRUNING>> section below for more details.
Ditto.
Show 14 quoted lines
> diff --git a/Documentation/git-bundle.adoc b/Documentation/git-bundle.adoc
> index 03cd36fe8d..cd722bd674 100644
> --- a/Documentation/git-bundle.adoc
> +++ b/Documentation/git-bundle.adoc
> @@ -94,7 +94,8 @@ unbundle <file>::
>  
>  <git-rev-list-args>::
>  	A list of arguments, acceptable to 'git rev-parse' and
> -	'git rev-list' (and containing a named ref, see SPECIFYING REFERENCES
> +	'git rev-list' (and containing a named ref, see
> +	<<SPECIFYING_REFERENCES,SPECIFYING REFERENCES>>
>  	below), that specifies the specific objects and references
>  	to transport.  For example, `master~10..master` causes the
>  	current master reference to be packaged along with all objects

This doubled reference is more for consistency (in other words, "it is easier to just make all of the links use the form") than the "cross references from/to included page" we saw earlier, since ...

Show 7 quoted lines
> @@ -127,6 +128,7 @@ unbundle <file>::
>  	This flag makes the command not to report its progress
>  	on the standard error stream.
>  
> +[[SPECIFYING_REFERENCES]]
>  SPECIFYING REFERENCES
>  ---------------------

... the target happens to live in the same file. It of course future-proofs the reference in case the section gets split out of the file into another included one.

Thanks, will queue.
Previous: Julia Evans via GitGitGadgetNext: Julia Evans
Message 2 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.