Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Wednesday, 21 February 2024 23:36:24 CET Junio C Hamano wrote:
> Junio C Hamano <gitster@pobox.com> writes:
> 
> >> Backticks and single quotes are used indistinctively (by the way,
> >> asciidoctor does not process single quotes as markup) ...
> 
> Hmph, it sounds like a bug of asciidoctor we'd need to work around?
> 
> In any case, I practiced your "_<placeholder>_" rule on git-add.txt
> and here is how my local HTML rendition of the updated line in the
> first hunk in the attached patch looks like with "AsciiDoc 10.2.0".
> 
>     https://pasteboard.co/6koO0h0KJAjW.png
> 
> The actual HTML for the above part looks like this:
> 
>     <div class="paragraph"><p>For more details about the
>     <em>&lt;pathspec&gt;</em> syntax, see the <em>pathspec</em> entry
>     in <a href="gitglossary.html">gitglossary(7)</a>.</p></div>
> 
> In the first hunk, the updated "_<pathspec>_" is enclosed inside an
> <em>..</em> pair, which is made into "font-style: italic" via css,
> while 'pathspec' that remains is already inside <em>..</em>.
> 
> By the way, I am getting some typesetting effect from the pair of
> single quotes with AsciiDoctor.  Here is the rendition of the same
> part:
> 
>     https://pasteboard.co/LbDi95G8BNGv.png
> 
> The <meta name="generator"> element in the generated HTML claims it
> is "Asciidoctor 2.0.20".  The actual HTML for that piece looks like
> this:
> 
>     <p>For more details about the <em>&lt;pathspec&gt;</em> syntax,
>     see the <em>pathspec</em> entry
>     in <a href="gitglossary.html">gitglossary(7)</a>.</p>
> 
> So, perhaps we do not have to do a lot of 'word' -> _word_
> replacements, hopefully?
> 

Asciidoctor tries to "normify" the asciidoc format (https://asciidoc-wg.eclipse.org/projects/) and pushes for deprecating the 'word' markup which 
is a  asciidoc.py legacy.

See https://docs.asciidoctor.org/asciidoctor/latest/migrate/asciidoc-py/
#updated-and-deprecated-asciidoc-syntax

In the transition period (which is lasting), they introduce a compatibility 
mode with the compat-mode flag in order to support legacy content.

For all I know, asciidoc.py has entered a maintenance stage where it will not 
support the evolutions of the standard. Should the Git documentation migrate 
to asciidoctor and drop the compat mode is an open question. At least, we 
should try to stick as much as possible to the common markup _ for emphasis. 
This would have the added benefit of differentiating single quotes from 
backticks, because single quotes would completely disappear in the end, except 
when a real single quote is needed.

 For the migration to "standard" asciidoc, I would also recommend using "=" 
prefix for titles instead of underlines which require changing two lines when 
modifying  a title and are a pain for translators in languages with variable 
width characters.


> ----- >8 --------- >8 --------- >8 --------- >8 ----
> 
> Subject: [PATCH] doc: apply the new placeholder rules to git-add 
documentation
> 
> Signed-off-by: Junio C Hamano <gitster@pobox.com>
> 
> diff --git a/Documentation/git-add.txt b/Documentation/git-add.txt
> index ed44c1cb31..b73071ba47 100644
> --- a/Documentation/git-add.txt
> +++ b/Documentation/git-add.txt
> @@ -63,7 +63,7 @@ OPTIONS
>  	to ignore removed files; use `--no-all` option if you want
>  	to add modified or new files but ignore removed ones.
>  +
> -For more details about the <pathspec> syntax, see the 'pathspec' entry
> +For more details about the _<pathspec>_ syntax, see the 'pathspec' entry
>  in linkgit:gitglossary[7].
>  
>  -n::
> @@ -119,10 +119,10 @@ apply to the index. See EDITING PATCHES below.
>  -u::
>  --update::
>  	Update the index just where it already has an entry matching
> -	<pathspec>.  This removes as well as modifies index entries to
> +	_<pathspec>_.  This removes as well as modifies index entries to
>  	match the working tree, but adds no new files.
>  +
> -If no <pathspec> is given when `-u` option is used, all
> +If no _<pathspec>_ is given when `-u` option is used, all
>  tracked files in the entire working tree are updated (old versions
>  of Git used to limit the update to the current directory and its
>  subdirectories).
> @@ -131,11 +131,11 @@ subdirectories).
>  --all::
>  --no-ignore-removal::
>  	Update the index not only where the working tree has a file
> -	matching <pathspec> but also where the index already has an
> +	matching _<pathspec>_ but also where the index already has an
>  	entry. This adds, modifies, and removes index entries to
>  	match the working tree.
>  +
> -If no <pathspec> is given when `-A` option is used, all
> +If no _<pathspec>_ is given when `-A` option is used, all
>  files in the entire working tree are updated (old versions
>  of Git used to limit the update to the current directory and its
>  subdirectories).
> @@ -145,11 +145,11 @@ subdirectories).
>  	Update the index by adding new files that are unknown to the
>  	index and files modified in the working tree, but ignore
>  	files that have been removed from the working tree.  This
> -	option is a no-op when no <pathspec> is used.
> +	option is a no-op when no _<pathspec>_ is used.
>  +
>  This option is primarily to help users who are used to older
> -versions of Git, whose "git add <pathspec>..." was a synonym
> -for "git add --no-all <pathspec>...", i.e. ignored removed files.
> +versions of Git, whose "git add _<pathspec>_..." was a synonym
> +for "git add --no-all _<pathspec>_...", i.e. ignored removed files.
>  
>  -N::
>  --intent-to-add::
> @@ -198,8 +198,8 @@ for "git add --no-all <pathspec>...", i.e. ignored 
removed files.
>  	unchanged.
>  
>  --pathspec-from-file=<file>::
> -	Pathspec is passed in `<file>` instead of commandline args. If
> -	`<file>` is exactly `-` then standard input is used. Pathspec
> +	Pathspec is passed in _<file>_ instead of commandline args. If
> +	_<file>_ is exactly `-` then standard input is used. Pathspec
>  	elements are separated by LF or CR/LF. Pathspec elements can be
>  	quoted as explained for the configuration variable `core.quotePath`
>  	(see linkgit:git-config[1]). See also `--pathspec-file-nul` and
> 
> 

This looks good to me.