Re: [PATCH v2] doc: git-diff: rewrite EXAMPLES section

[Junio C Hamano <gitster@pobox.com>]

Jeff King <peff@peff.net> writes:

> On Thu, Nov 05, 2026 at 03:40:17PM +0000, Julia Evans via GitGitGadget wrote:
>
>> +[[name_only]]
>>  `--name-only`::
>>  	Show only the name of each changed file in the post-image tree.
>>  	The file names are often encoded in UTF-8.
>>  	For more information see the discussion about encoding in the linkgit:git-log[1]
>>  	manual page.
>
> Sadly this syntax seems to work with Asciidoctor, but not Asciidoc. The
> latter doesn't create the anchors, and then xmlto complaints that the
> result doesn't validate.
>
> Doing it like this works in both:
>
>   `--name-only`[[name_only]]::
> 	...
>
> but...yikes. It's pretty ugly. This of course tempts me in the direction
> of ditching python asciidoc support, but I'm not sure if you want to
> hold up your series for that.

In any case, I'll queue another SQUASH??? commit on top of the topic
until v3 materiazlies to fix these issues we have accumulated so
far.



diff --git c/Documentation/diff-options.adoc w/Documentation/diff-options.adoc
index 2dc54fa00e..bb46fd065b 100644
--- c/Documentation/diff-options.adoc
+++ w/Documentation/diff-options.adoc
@@ -201,8 +201,7 @@ diff" algorithm internally.
 
 include::diff-algorithm-option.adoc[]
 
-[[stat]]
-`--stat[=<width>[,<name-width>[,<count>]]]`::
+`--stat[=<width>[,<name-width>[,<count>]]]`[[stat]]::
 	Generate a diffstat. By default, as much space as necessary
 	will be used for the filename part, and the rest for the graph
 	part. Maximum width defaults to terminal width, or 80 columns
@@ -319,15 +318,13 @@ Without this option, pathnames with "unusual" characters are quoted as
 explained for the configuration variable `core.quotePath` (see
 linkgit:git-config[1]).
 
-[[name_only]]
-`--name-only`::
+`--name-only`[[name_only]]::
 	Show only the name of each changed file in the post-image tree.
 	The file names are often encoded in UTF-8.
 	For more information see the discussion about encoding in the linkgit:git-log[1]
 	manual page.
 
-[[name_status]]
-`--name-status`::
+`--name-status`[[name_status]]::
 	Show only the name(s) and status of each changed file. See the description
 	of the `--diff-filter` option on what the status letters mean.
 	Just like `--name-only` the file names are often encoded in UTF-8.
@@ -420,8 +417,7 @@ endif::git-diff[]
 	Ignore changes in amount of whitespace.  This ignores whitespace
 	at line end, and considers all other sequences of one or
 	more whitespace characters to be equivalent.
-[[ignore_all_space]]
-`ignore-all-space`::
+`ignore-all-space`[[ignore_all_space]]::
 	Ignore whitespace when comparing lines. This ignores differences
 	even if one line has whitespace where the other line has none.
 `allow-indentation-change`::
@@ -436,8 +432,7 @@ endif::git-diff[]
 	used to override configuration settings. It is the same as
 	`--color-moved-ws=no`.
 
-[[word_diff]]
-`--word-diff[=<mode>]`::
+`--word-diff[=<mode>]`[[word_diff]]::
 	By default, words are delimited by whitespace; see
 	`--word-diff-regex` below.  The _<mode>_ defaults to `plain`, and
 	must be one of: