[PATCH 0/3] Doc placeholders

[PATCH 0/3] Doc placeholders

[Jean-Noël Avila via GitGitGadget]

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

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

[Jean-Noël Avila via GitGitGadget]

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

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

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

[Jean-Noël Avila via GitGitGadget]

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

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

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

[Jean-Noël Avila via GitGitGadget]

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

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

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

[Eric Sunshine]

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.

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

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

[Junio C Hamano]

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

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

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

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

[Junio C Hamano]

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

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

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

[Junio C Hamano]

Eric Sunshine <sunshine@sunshineco.com> writes:

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

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

[Jean-Noël Avila]

Le 20/02/2024 à 23:57, Junio C Hamano a écrit :
> "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?

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

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

[Junio C Hamano]

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.

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

[Jean-Noël AVILA]

On Wednesday, 21 February 2024 18:31:30 CET Junio C Hamano wrote:
> 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

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

[Junio C Hamano]

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

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

[Jean-Noël AVILA]

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. 

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

[Junio C Hamano]

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.

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

[Jean-Noël AVILA]

On Thursday, 22 February 2024 17:38:36 CET Junio C Hamano wrote:
> 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?

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