threads / patch / 60969

patch, 3 partsDoc placeholders

Subject: [PATCH 0/3] Doc placeholders

## tl;dr

15 messages between Feb 20, 2024 and Feb 24, 2024. Diffs are folded; open one to read it.

replies: 14people: 3as markdown or json

Jean-Noël Avila via GitGitGadget· Feb 20, 2024, 22:32 UTC · lore

Here a few commits of some typos/mistakes found while translating the manpages.

Jean-Noël Avila (3):
  doc: git-rev-parse: enforce command-line description syntax
  doc: git-clone fix missing placeholder end carret
  doc: add some missing sentence dots.
 Documentation/config/diff.txt     |  4 ++--
 Documentation/git-clone.txt       |  2 +-
 Documentation/git-fast-export.txt |  2 +-
 Documentation/git-rev-parse.txt   | 24 ++++++++++++------------
 4 files changed, 16 insertions(+), 16 deletions(-)
base-commit: 5fdd5b989cbe5096d44e89861a92b2dd47c279d9
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1670%2Fjnavila%2Fdoc_placeholders-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1670/jnavila/doc_placeholders-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1670
-- 
gitgitgadget
Jean-Noël Avila via GitGitGadget· Feb 20, 2024, 22:32 UTC · re: Jean-Noël Avila via GitGitGadget · lore

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

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>

git-rev-parse(1) manpage is completely off with respect to the command-line description syntax with badly formatted placeholders and malformed alternatives.

Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-rev-parse.txt | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)
Show changes to Documentation/git-rev-parse.txt +12 −2
diff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt
index 546faf90177..5d83dd36da1 100644
--- a/Documentation/git-rev-parse.txt
+++ b/Documentation/git-rev-parse.txt
@@ -9,7 +9,7 @@ git-rev-parse - Pick out and massage parameters
 SYNOPSIS
 --------
 [verse]
-'git rev-parse' [<options>] <args>...
+'git rev-parse' [<options>] <arg>...
 
 DESCRIPTION
 -----------
@@ -130,7 +130,7 @@ for another option.
 	'git diff-{asterisk}'). In contrast to the `--sq-quote` option,
 	the command input is still interpreted as usual.
 
---short[=length]::
+--short[=<length>]::
 	Same as `--verify` but shortens the object name to a unique
 	prefix with at least `length` characters. The minimum length
 	is 4, the default is the effective value of the `core.abbrev`
@@ -165,9 +165,9 @@ Options for Objects
 --all::
 	Show all refs found in `refs/`.
 
---branches[=pattern]::
---tags[=pattern]::
---remotes[=pattern]::
+--branches[=<pattern>]::
+--tags[=<pattern>]::
+--remotes[=<pattern>]::
 	Show all branches, tags, or remote-tracking branches,
 	respectively (i.e., refs found in `refs/heads`,
 	`refs/tags`, or `refs/remotes`, respectively).
@@ -176,7 +176,7 @@ If a `pattern` is given, only refs matching the given shell glob are
 shown.  If the pattern does not contain a globbing character (`?`,
 `*`, or `[`), it is turned into a prefix match by appending `/*`.
 
---glob=pattern::
+--glob=<pattern>::
 	Show all refs matching the shell glob pattern `pattern`. If
 	the pattern does not start with `refs/`, this is automatically
 	prepended.  If the pattern does not contain a globbing
@@ -197,7 +197,7 @@ respectively, and they must begin with `refs/` when applied to `--glob`
 or `--all`. If a trailing '/{asterisk}' is intended, it must be given
 explicitly.
 
---exclude-hidden=[fetch|receive|uploadpack]::
+--exclude-hidden=(fetch|receive|uploadpack)::
 	Do not include refs that would be hidden by `git-fetch`,
 	`git-receive-pack` or `git-upload-pack` by consulting the appropriate
 	`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
@@ -314,17 +314,17 @@ The following options are unaffected by `--path-format`:
 Other Options
 ~~~~~~~~~~~~~
 
---since=datestring::
---after=datestring::
+--since=<datestring>::
+--after=<datestring>::
 	Parse the date string, and output the corresponding
 	--max-age= parameter for 'git rev-list'.
 
---until=datestring::
---before=datestring::
+--until=<datestring>::
+--before=<datestring>::
 	Parse the date string, and output the corresponding
 	--min-age= parameter for 'git rev-list'.
 
-<args>...::
+<arg>...::
 	Flags and parameters to be parsed.
 
 

-- 
gitgitgadget
Junio C Hamano· Feb 20, 2024, 22:57 UTC · re: Jean-Noël Avila via GitGitGadget · lore

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

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
>  [verse]
> -'git rev-parse' [<options>] <args>...
> +'git rev-parse' [<options>] <arg>...

Good. The "or more" is signalled by the ellipsis, not "args" being plural.

> ---short[=length]::
> +--short[=<length>]::
>  	Same as `--verify` but shortens the object name to a unique
>  	prefix with at least `length` characters. The minimum length

This same comment applies throughout this patch, but in other places when we use <placeholder> in the option argument description, don't we use the same <placeholder> in text as well? I am wondering if the `length` (typeset in fixed-width) should become <length>. What do other recent[*] documentation pages commonly do?

	Side note: I say "recent" because rev-parse doc is one of
	the oldest ones that did not get typesetting attention they
	deserve, compared to more recent ones that got nitpicked
	while they were written and updated.
Show 9 quoted lines
> ---branches[=pattern]::
> ---tags[=pattern]::
> ---remotes[=pattern]::
> +--branches[=<pattern>]::
> +--tags[=<pattern>]::
> +--remotes[=<pattern>]::
>  	Show all branches, tags, or remote-tracking branches,
>  	respectively (i.e., refs found in `refs/heads`,
>  	`refs/tags`, or `refs/remotes`, respectively).

Ditto. We see `pattern` that may want to become <pattern> in the description (after the post context of this hunk).

Show 5 quoted lines
> ---glob=pattern::
> +--glob=<pattern>::
>  	Show all refs matching the shell glob pattern `pattern`. If
>  	the pattern does not start with `refs/`, this is automatically
>  	prepended.  If the pattern does not contain a globbing
Ditto.
Show 5 quoted lines
> ---exclude-hidden=[fetch|receive|uploadpack]::
> +--exclude-hidden=(fetch|receive|uploadpack)::
>  	Do not include refs that would be hidden by `git-fetch`,
>  	`git-receive-pack` or `git-upload-pack` by consulting the appropriate
>  	`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
Good.
Show 6 quoted lines
> ---since=datestring::
> ---after=datestring::
> +--since=<datestring>::
> +--after=<datestring>::
>  	Parse the date string, and output the corresponding
>  	--max-age= parameter for 'git rev-list'.
Good, modulo possibly "date string" -> "<datestring>".
Show 6 quoted lines
> ---until=datestring::
> ---before=datestring::
> +--until=<datestring>::
> +--before=<datestring>::
>  	Parse the date string, and output the corresponding
>  	--min-age= parameter for 'git rev-list'.
Ditto.
> -<args>...::
> +<arg>...::
>  	Flags and parameters to be parsed.
Good.
Jean-Noël Avila· Feb 21, 2024, 07:41 UTC · re: Junio C Hamano · lore

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

Le 20/02/2024 à 23:57, Junio C Hamano a écrit :
Show 19 quoted lines
> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
>>   [verse]
>> -'git rev-parse' [<options>] <args>...
>> +'git rev-parse' [<options>] <arg>...
> 
> Good.  The "or more" is signalled by the ellipsis, not "args" being
> plural.
> 
>> ---short[=length]::
>> +--short[=<length>]::
>>   	Same as `--verify` but shortens the object name to a unique
>>   	prefix with at least `length` characters. The minimum length
> 
> This same comment applies throughout this patch, but in other places
> when we use <placeholder> in the option argument description, don't
> we use the same <placeholder> in text as well?  I am wondering if
> the `length` (typeset in fixed-width) should become <length>.  What
> do other recent[*] documentation pages commonly do?

This is another part of the inconsistences in documentation that I'd like to tackle (hopefully, not in another life).

Using angle brackets for placeholders everywhere they appear is a visual link to the preceding syntax description, but may feel a bit heavy on some cases. Anyway, I'm all for applying the rule everywhere, for the sake of consistency.

Backticks and single quotes are used indistinctively (by the way, asciidoctor does not process single quotes as markup) and are not used everywhere they should. Using backticks is also a good hint for translators to mean "verbatim, do not translate". Obviously, the placeholders ask for translation, so the backtick rule should not apply to them, even if another formating would be welcome : _<placeholder>_ for instance?

Show 58 quoted lines
> 
> 	Side note: I say "recent" because rev-parse doc is one of
> 	the oldest ones that did not get typesetting attention they
> 	deserve, compared to more recent ones that got nitpicked
> 	while they were written and updated.
> 
>> ---branches[=pattern]::
>> ---tags[=pattern]::
>> ---remotes[=pattern]::
>> +--branches[=<pattern>]::
>> +--tags[=<pattern>]::
>> +--remotes[=<pattern>]::
>>   	Show all branches, tags, or remote-tracking branches,
>>   	respectively (i.e., refs found in `refs/heads`,
>>   	`refs/tags`, or `refs/remotes`, respectively).
> 
> Ditto.  We see `pattern` that may want to become <pattern> in the
> description (after the post context of this hunk).
> 
>> ---glob=pattern::
>> +--glob=<pattern>::
>>   	Show all refs matching the shell glob pattern `pattern`. If
>>   	the pattern does not start with `refs/`, this is automatically
>>   	prepended.  If the pattern does not contain a globbing
> 
> Ditto.
> 
>> ---exclude-hidden=[fetch|receive|uploadpack]::
>> +--exclude-hidden=(fetch|receive|uploadpack)::
>>   	Do not include refs that would be hidden by `git-fetch`,
>>   	`git-receive-pack` or `git-upload-pack` by consulting the appropriate
>>   	`fetch.hideRefs`, `receive.hideRefs` or `uploadpack.hideRefs`
> 
> Good.
> 
>> ---since=datestring::
>> ---after=datestring::
>> +--since=<datestring>::
>> +--after=<datestring>::
>>   	Parse the date string, and output the corresponding
>>   	--max-age= parameter for 'git rev-list'.
> 
> Good, modulo possibly "date string" -> "<datestring>".
> 
>> ---until=datestring::
>> ---before=datestring::
>> +--until=<datestring>::
>> +--before=<datestring>::
>>   	Parse the date string, and output the corresponding
>>   	--min-age= parameter for 'git rev-list'.
> 
> Ditto.
> 
>> -<args>...::
>> +<arg>...::
>>   	Flags and parameters to be parsed.
> 
> Good.
Junio C Hamano· Feb 21, 2024, 17:31 UTC · re: Jean-Noël Avila · lore

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

Jean-Noël Avila <jn.avila@free.fr> writes:
Show 17 quoted lines
>>> ---short[=length]::
>>> +--short[=<length>]::
>>>   	Same as `--verify` but shortens the object name to a unique
>>>   	prefix with at least `length` characters. The minimum length
>> This same comment applies throughout this patch, but in other places
>> when we use <placeholder> in the option argument description, don't
>> we use the same <placeholder> in text as well?  I am wondering if
>> the `length` (typeset in fixed-width) should become <length>.  What
>> do other recent[*] documentation pages commonly do?
>
> This is another part of the inconsistences in documentation that I'd
> like to tackle (hopefully, not in another life).
>
> Using angle brackets for placeholders everywhere they appear is a
> visual link to the preceding syntax description, but may feel a bit
> heavy on some cases. Anyway, I'm all for applying the rule everywhere,
> for the sake of consistency.

I agree that if <placeholder> is not an appropriate way to spell them in the explanation text, we would want to change them consistently everywhere, and until then, using the angle-bracketted <placeholder> that is common would be better. The text will be modified again when we decide to switch from <placeholder> to something else, so updating them now may be a wasted effort, but (1) we may decide that <placeholder> is good enough after all, or (2) it may make it easier to mechanically identify words whose mark-up should be converted if we consistently use <placeholder> now, even if we know it won't be the final mark-up.

So I am inclined to say that we should first do `length` -> <length> in the body text in the short term. But I also think we should *not* do so as part of this patch, whose focus is how the option enumeration header should mark up the option arguments.

Show 7 quoted lines
> Backticks and single quotes are used indistinctively (by the way,
> asciidoctor does not process single quotes as markup) and are not used
> everywhere they should. Using backticks is also a good hint for
> translators to mean "verbatim, do not translate". Obviously, the
> placeholders ask for translation, so the backtick rule should not
> apply to them, even if another formating would be welcome :
> _<placeholder>_ for instance?

Yes. The way AsciiDoc renders (at least HTML) an unadorned <placeholder> is not so great.

In "git-add.html" manual page, we see these examples. The first one (unadorned) does not make the placeholder word stand out enough; the second one that does `<file>` makes it stand out better, but as you said, the `verbatim` mark-up is semantically wrong.

https://git.github.io/htmldocs/git-add.html#:~:text=For%20more%20details%20about%20the%20%3Cpathspec%3E%20syntax
https://git.github.io/htmldocs/git-add.html#:~:text=Pathspec%20is%20passed%20in%20%3Cfile%3E%20instead%20of%20commandline%20args.%20If%20%3Cfile%3E%20is%20exactly%20%2D%20then%20standard%20input%20is%20used.%20Pathspec

The last part of the Documentation/CodingGuidelines document talks about how to mark up placeholders but it does not go beyond saying that they are written as <hyphen-in-between-words-in-angle-braket>. Whatever mark-up rule we decide to use, we should document it there.

Thanks.
Jean-Noël AVILA· Feb 21, 2024, 21:52 UTC · re: Junio C Hamano · lore

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

On Wednesday, 21 February 2024 18:31:30 CET Junio C Hamano wrote:
Show 66 quoted lines
> Jean-Noël Avila <jn.avila@free.fr> writes:
> 
> >>> ---short[=length]::
> >>> +--short[=<length>]::
> >>>   	Same as `--verify` but shortens the object name to a unique
> >>>   	prefix with at least `length` characters. The minimum length
> >> This same comment applies throughout this patch, but in other places
> >> when we use <placeholder> in the option argument description, don't
> >> we use the same <placeholder> in text as well?  I am wondering if
> >> the `length` (typeset in fixed-width) should become <length>.  What
> >> do other recent[*] documentation pages commonly do?
> >
> > This is another part of the inconsistences in documentation that I'd
> > like to tackle (hopefully, not in another life).
> >
> > Using angle brackets for placeholders everywhere they appear is a
> > visual link to the preceding syntax description, but may feel a bit
> > heavy on some cases. Anyway, I'm all for applying the rule everywhere,
> > for the sake of consistency.
> 
> I agree that if <placeholder> is not an appropriate way to spell
> them in the explanation text, we would want to change them
> consistently everywhere, and until then, using the angle-bracketted
> <placeholder> that is common would be better.  The text will be
> modified again when we decide to switch from <placeholder> to
> something else, so updating them now may be a wasted effort, but (1)
> we may decide that <placeholder> is good enough after all, or (2) it
> may make it easier to mechanically identify words whose mark-up
> should be converted if we consistently use <placeholder> now, even
> if we know it won't be the final mark-up.
> 
> So I am inclined to say that we should first do `length` -> <length>
> in the body text in the short term.  But I also think we should
> *not* do so as part of this patch, whose focus is how the option
> enumeration header should mark up the option arguments.
> 
> > Backticks and single quotes are used indistinctively (by the way,
> > asciidoctor does not process single quotes as markup) and are not used
> > everywhere they should. Using backticks is also a good hint for
> > translators to mean "verbatim, do not translate". Obviously, the
> > placeholders ask for translation, so the backtick rule should not
> > apply to them, even if another formating would be welcome :
> > _<placeholder>_ for instance?
> 
> Yes.  The way AsciiDoc renders (at least HTML) an unadorned <placeholder>
> is not so great.
> 
> In "git-add.html" manual page, we see these examples.  The first one
> (unadorned) does not make the placeholder word stand out enough; the
> second one that does `<file>` makes it stand out better, but as you
> said, the `verbatim` mark-up is semantically wrong.
> 
> https://git.github.io/htmldocs/git-add.html#:~:text=For%20more%20details%20about%20the%20%3Cpathspec%3E%20syntax
> 
> https://git.github.io/htmldocs/git-add.html#:~:text=Pathspec%20is%20passed%20in%20%3Cfile%3E%20instead%20of%20commandline%20args.%20If%20%3Cfile%3E%20is%20exactly%20%2D%20then%20standard%20input%20is%20used.%20Pathspec
> 
> The last part of the Documentation/CodingGuidelines document talks
> about how to mark up placeholders but it does not go beyond saying
> that they are written as <hyphen-in-between-words-in-angle-braket>.
> Whatever mark-up rule we decide to use, we should document it there.
> 
> Thanks.
> 
> 
> 
> 
Hi,
I just saw that you pushed this series to 'next'. That's embarrassing because I missed other spots in the file were the formating was not correct. I was also preparing the changes of placeholders in paragraphs as suggested.
Should I prepare another PR?
Thanks
Junio C Hamano· Feb 21, 2024, 22:36 UTC · re: Junio C Hamano · lore

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?

----- >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>
Show changes to Documentation/git-add.txt +10 −10
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
Jean-Noël AVILA· Feb 22, 2024, 09:07 UTC · re: Junio C Hamano · lore

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

On Wednesday, 21 February 2024 23:36:24 CET Junio C Hamano wrote:
Show 40 quoted lines
> 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
Show 59 quoted lines
> 
> 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.
Show 12 quoted lines
>  	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.
Junio C Hamano· Feb 22, 2024, 16:38 UTC · re: Jean-Noël AVILA · lore

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

Jean-Noël AVILA <jn.avila@free.fr> writes:
>> So, perhaps we do not have to do a lot of 'word' -> _word_
>> replacements, hopefully?
> ... At least, we 
> should try to stick as much as possible to the common markup _ for emphasis.
OK, that clears up my confusion.  Thanks.

We do not want to rely on an external party indefinitely maintaining what they consider backward compatibility wart, so the mark-up migration would need to happen before it becomes too late.

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

Given enough time, yes. Or we can actively disable AsciiDoctor's compatibility mode and/or tweak asciidoc.conf to do the equivalent for AsciiDoc, to start early. Until then, we cannot really use "a real single quote", right?

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

I personally strongly prefer the underline format because I care about readability of sources, but that is just me. Is that also getting deprecated?

Thanks.
Jean-Noël AVILA· Feb 24, 2024, 18:28 UTC · re: Junio C Hamano · lore

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

On Thursday, 22 February 2024 17:38:36 CET Junio C Hamano wrote:
Show 7 quoted lines
> Jean-Noël AVILA <jn.avila@free.fr> writes:
> 
> >> So, perhaps we do not have to do a lot of 'word' -> _word_
> >> replacements, hopefully?
> 
> > ... At least, we 
> > should try to stick as much as possible to the common markup _ for 
emphasis.
Show 9 quoted lines
> 
> OK, that clears up my confusion.  Thanks.
> 
> We do not want to rely on an external party indefinitely maintaining
> what they consider backward compatibility wart, so the mark-up migration
> would need to happen before it becomes too late.
> 
> > This would have the added benefit of differentiating single quotes from 
> > backticks, because single quotes would completely disappear in the end, 
except
Show 6 quoted lines
> > when a real single quote is needed.
> 
> Given enough time, yes.  Or we can actively disable AsciiDoctor's
> compatibility mode and/or tweak asciidoc.conf to do the equivalent
> for AsciiDoc, to start early.  Until then, we cannot really use "a
> real single quote", right?

The logic for managing single quotes as markup is that there should be a word boundary at the quote <SPC>'<letter> for opening and <letter>'<SPC> for closing, whereas for "real single quote" there's no space. This rule is "natural" when writing in English and writers don't pay attention.

> 
> > 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
Show 6 quoted lines
> > width characters.
> 
> I personally strongly prefer the underline format because I care
> about readability of sources, but that is just me.  Is that also
> getting deprecated?
>

The underline format is bound to be deprecated. Right now, Asciidoctor detects this formatting to infer a switch to compat-mode. That's why markup-quote works as expected with Asciidoctor in current documents.

> Thanks.
> 
>
Jean-Noël Avila via GitGitGadget· Feb 20, 2024, 22:32 UTC · re: Jean-Noël Avila via GitGitGadget · lore

[PATCH 2/3] doc: git-clone fix missing placeholder end carret

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/git-clone.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Show changes to Documentation/git-clone.txt +1 −0
diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index 6e43eb9c205..0c07720c6f4 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -311,7 +311,7 @@ or `--mirror` is given)
 	The result is Git repository can be separated from working
 	tree.
 
---ref-format=<ref-format::
+--ref-format=<ref-format>::
 
 Specify the given ref storage format for the repository. The valid values are:
 +

-- 
gitgitgadget
Eric Sunshine· Feb 20, 2024, 22:39 UTC · re: Jean-Noël Avila via GitGitGadget · lore

Re: [PATCH 2/3] doc: git-clone fix missing placeholder end carret

On Tue, Feb 20, 2024 at 5:33 PM Jean-Noël Avila via GitGitGadget <gitgitgadget@gmail.com> wrote:

> doc: git-clone fix missing placeholder end carret
I believe you meant: s/carret/caret/
In English, I think this symbol is typically called an "angle bracket".
Either way, probably not worth a reroll since it's just a commit-message nit.
Show 6 quoted lines
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> @@ -311,7 +311,7 @@ or `--mirror` is given)
> ---ref-format=<ref-format::
> +--ref-format=<ref-format>::
Junio C Hamano· Feb 20, 2024, 23:01 UTC · re: Eric Sunshine · lore

Re: [PATCH 2/3] doc: git-clone fix missing placeholder end carret

Eric Sunshine <sunshine@sunshineco.com> writes:
Show 7 quoted lines
> On Tue, Feb 20, 2024 at 5:33 PM Jean-Noël Avila via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>> doc: git-clone fix missing placeholder end carret
>
> I believe you meant: s/carret/caret/
>
> In English, I think this symbol is typically called an "angle bracket".
Yes, caret is "^".
>> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
>> @@ -311,7 +311,7 @@ or `--mirror` is given)
>> ---ref-format=<ref-format::
>> +--ref-format=<ref-format>::

A closing angle bracket is what is missing there. Thanks for reading carefully.

Jean-Noël Avila via GitGitGadget· Feb 20, 2024, 22:32 UTC · re: Jean-Noël Avila via GitGitGadget · lore

[PATCH 3/3] doc: add some missing sentence dots.

From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
---
 Documentation/config/diff.txt     | 4 ++--
 Documentation/git-fast-export.txt | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)
Show changes to 2 files +3 −3

Documentation/config/diff.txt, Documentation/git-fast-export.txt

diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
index bd5ae0c3378..6c7e09a1ef5 100644
--- a/Documentation/config/diff.txt
+++ b/Documentation/config/diff.txt
@@ -223,5 +223,5 @@ diff.colorMoved::
 
 diff.colorMovedWS::
 	When moved lines are colored using e.g. the `diff.colorMoved` setting,
-	this option controls the `<mode>` how spaces are treated
-	for details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].
+	this option controls the `<mode>` how spaces are treated.
+	For details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].
diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
index 4643ddbe68f..752e4b9b01d 100644
--- a/Documentation/git-fast-export.txt
+++ b/Documentation/git-fast-export.txt
@@ -48,7 +48,7 @@ When asking to 'abort' (which is the default), this program will die
 when encountering such a tag.  With 'drop' it will omit such tags from
 the output.  With 'rewrite', if the tagged object is a commit, it will
 rewrite the tag to tag an ancestor commit (via parent rewriting; see
-linkgit:git-rev-list[1])
+linkgit:git-rev-list[1]).
 
 -M::
 -C::

-- 
gitgitgadget
Junio C Hamano· Feb 20, 2024, 22:50 UTC · re: Jean-Noël Avila via GitGitGadget · lore

Re: [PATCH 3/3] doc: add some missing sentence dots.

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> Subject: Re: [PATCH 3/3] doc: add some missing sentence dots.
"sentence dots." -> "full stop at the end of sentence" or something?
Show 12 quoted lines
> diff --git a/Documentation/config/diff.txt b/Documentation/config/diff.txt
> index bd5ae0c3378..6c7e09a1ef5 100644
> --- a/Documentation/config/diff.txt
> +++ b/Documentation/config/diff.txt
> @@ -223,5 +223,5 @@ diff.colorMoved::
>  
>  diff.colorMovedWS::
>  	When moved lines are colored using e.g. the `diff.colorMoved` setting,
> -	this option controls the `<mode>` how spaces are treated
> -	for details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].
> +	this option controls the `<mode>` how spaces are treated.
> +	For details of valid modes see '--color-moved-ws' in linkgit:git-diff[1].
Very good.  Thanks for spotting this one.
Show 10 quoted lines
> diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt
> index 4643ddbe68f..752e4b9b01d 100644
> --- a/Documentation/git-fast-export.txt
> +++ b/Documentation/git-fast-export.txt
> @@ -48,7 +48,7 @@ When asking to 'abort' (which is the default), this program will die
>  when encountering such a tag.  With 'drop' it will omit such tags from
>  the output.  With 'rewrite', if the tagged object is a commit, it will
>  rewrite the tag to tag an ancestor commit (via parent rewriting; see
> -linkgit:git-rev-list[1])
> +linkgit:git-rev-list[1]).
Ditto.

← back to recent threads