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

> 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?
> 

> 
> 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 

>  	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
> 
>