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

From: Junio C Hamano <gitster@pobox.com>
Date: Feb 21, 2024, 22:36 UTC
Message-ID: <xmqqbk89molz.fsf@gitster.g>
In-Reply-To: <xmqqfrxlpvv1.fsf@gitster.g>

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?

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