Doc placeholders
cover Doc placeholders
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
Signature · 1 line
gitgitgadget
PATCH 1/3 doc: git-rev-parse: enforce command-line description syntax
From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
git-rev-parse(1) manpage is completely off with respect to the command-line description syntax with badly formatted placeholders and malformed alternatives.
--- Documentation/git-rev-parse.txt | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-)
Documentation/git-rev-parse.txt +12 -12
@@ -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.
Signature · 1 line
gitgitgadget
Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax
Quoted 3 lines · Jean-Noël Avila via GitGitGadget
[verse]
-'git rev-parse' [<options>] <args>...
+'git rev-parse' [<options>] <arg>...
Good. The "or more" is signalled by the ellipsis, not "args" being plural.
Documentation/git-rev-parse.txt for another option. · line 135
Quoted 4 lines
---short[=length]::
+--short[=<length>]::Documentation/git-rev-parse.txt +0
-0Same 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.
Documentation/git-rev-parse.txt Options for Objects · line 173
Quoted 9 lines
---branches[=pattern]::
---tags[=pattern]::
---remotes[=pattern]::+--branches[=<pattern>]:: +--tags[=<pattern>]:: +--remotes[=<pattern>]::Documentation/git-rev-parse.txt +0
-0Show 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).
Documentation/git-rev-parse.txt If a `pattern` is given, only refs matching the given shell glob are · line 182
Quoted 5 lines
---glob=pattern::
+--glob=<pattern>::Documentation/git-rev-parse.txt +0
-0Show 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.
Documentation/git-rev-parse.txt respectively, and they must begin with `refs/` when applied to `--glob` · line 203
Quoted 5 lines
---exclude-hidden=[fetch|receive|uploadpack]:: +--exclude-hidden=(fetch|receive|uploadpack)::Documentation/git-rev-parse.txt +0
-0Do 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.
Documentation/git-rev-parse.txt The following options are unaffected by `--path-format`: · line 320
Quoted 6 lines
---since=datestring::
---after=datestring::+--since=<datestring>:: +--after=<datestring>::Documentation/git-rev-parse.txt +0
-0Parse the date string, and output the corresponding --max-age= parameter for 'git rev-list'.
Good, modulo possibly "date string" -> "<datestring>".
Review
Quoted 6 lines
---until=datestring::
---before=datestring::+--until=<datestring>:: +--before=<datestring>::(quoted diff) +0
-0Parse the date string, and output the corresponding --min-age= parameter for 'git rev-list'.
Ditto.
Quoted 3 lines
-<args>...::
+<arg>...::
Flags and parameters to be parsed.
Good.
Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax
Le 20/02/2024 à 23:57, Junio C Hamano a écrit :
Quoted 14 lines
Quoted 3 lines · Jean-Noël Avila via GitGitGadget
[verse]
-'git rev-parse' [<options>] <args>...
+'git rev-parse' [<options>] <arg>...Good. The "or more" is signalled by the ellipsis, not "args" being plural.
Quoted 4 lines
---short[=length]::
+--short[=<length>]::
Same as--verifybut shortens the object name to a unique prefix with at leastlengthcharacters. The minimum length
Quoted 5 lines
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?
Quoted 58 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.
Quoted 9 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, orrefs/remotes, respectively).Ditto. We see
patternthat may want to become <pattern> in the description (after the post context of this hunk).Quoted 5 lines
---glob=pattern::
+--glob=<pattern>::
Show all refs matching the shell glob patternpattern. If the pattern does not start withrefs/, this is automatically prepended. If the pattern does not contain a globbingDitto.
Quoted 5 lines
---exclude-hidden=[fetch|receive|uploadpack]:: +--exclude-hidden=(fetch|receive|uploadpack)::Do not include refs that would be hidden by
git-fetch,git-receive-packorgit-upload-packby consulting the appropriatefetch.hideRefs,receive.hideRefsoruploadpack.hideRefsGood.
Quoted 6 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>".
Quoted 6 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.
Quoted 3 lines
-<args>...::
+<arg>...::
Flags and parameters to be parsed.Good.
Re: [PATCH 1/3] doc: git-rev-parse: enforce command-line description syntax
Quoted 10 lines · Jean-Noël Avila
Quoted 9 lines
Quoted 4 lines
---short[=length]::
+--short[=<length>]::
Same as--verifybut shortens the object name to a unique prefix with at leastlengthcharacters. The minimum lengthThis 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?
Quoted 7 lines
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.
Quoted 7 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.
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
Quoted 54 lines · On Wednesday, 21 February 2024 18:31:30 CET Junio C Hamano wrote:
Quoted 10 lines · Jean-Noël Avila
Quoted 9 lines
Quoted 4 lines
---short[=length]::
+--short[=<length>]::
Same as--verifybut shortens the object name to a unique prefix with at leastlengthcharacters. The minimum lengthThis 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?Quoted 7 lines
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.Quoted 7 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, theverbatimmark-up is semantically wrong.
Quoted 12 lines
The last part of the
Documentation/CodingGuidelinesdocument 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
In reply to Junio C HamanoQuoted 2 lines · Junio C Hamano
Quoted 2 lines
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><pathspec></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><pathspec></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
Documentation/git-add.txt +10 -10
@@ -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
Quoted 33 lines · On Wednesday, 21 February 2024 23:36:24 CET Junio C Hamano wrote:
Quoted 2 lines · Junio C Hamano
Quoted 2 lines
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><pathspec></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:
Quoted 7 lines
<p>For more details about the <em><pathspec></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.
Quoted 3 lines
----- >8 --------- >8 --------- >8 --------- >8 ----
Subject: [PATCH] doc: apply the new placeholder rules to git-add
documentation
Documentation/git-add.txt for "git add --no-all <pathspec>...", i.e. ignored
Quoted 59 lines
Signed-off-by Junio C Hamano <[email protected]>Documentation/git-add.txt +8
-8@@ -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.
Documentation/git-add.txt for "git add --no-all <pathspec>...", i.e. ignored removed files. · line 205
Quoted 12 lines
Documentation/git-add.txt +2
-2unchanged. --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
Quoted 5 lines · Jean-Noël AVILA
Quoted 2 lines
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.
Quoted 3 lines
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?
Quoted 4 lines
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
Quoted 7 lines · On Thursday, 22 February 2024 17:38:36 CET Junio C Hamano wrote:
Quoted 5 lines · Jean-Noël AVILA
Quoted 2 lines
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.
Quoted 9 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.
Quoted 2 lines
This would have the added benefit of differentiating single quotes from backticks, because single quotes would completely disappear in the end,
except
Quoted 6 lines
Quoted 1 line
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.
Quoted 3 lines
Quoted 3 lines
For the migration to "standard" asciidoc, I would also recommend using "=" prefix for titles instead of underlines which require changing two lines
when
Quoted 1 line
Quoted 1 line
modifying a title and are a pain for translators in languages with
variable
Quoted 6 lines
Quoted 1 line
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.
Quoted 3 lines
Thanks.
PATCH 2/3 doc: git-clone fix missing placeholder end carret
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
--- Documentation/git-clone.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/git-clone.txt +1 -1
@@ -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: +
Signature · 1 line
gitgitgadget
Re: [PATCH 2/3] doc: git-clone fix missing placeholder end carret
Quoted 1 line · Jean-Noël Avila via GitGitGadget
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.
Quoted 6 lines
Signed-off-by Jean-Noël Avila <[email protected]>Documentation/git-clone.txt +1
-1@@ -311,7 +311,7 @@ or `--mirror` is given) ---ref-format=<ref-format:: +--ref-format=<ref-format>::
Re: [PATCH 2/3] doc: git-clone fix missing placeholder end carret
Quoted 7 lines · Eric Sunshine
Quoted 1 line · Jean-Noël Avila via GitGitGadget
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 "^".
Quoted 4 lines
Documentation/git-clone.txt or `--mirror` is given) · line 311
Quoted 4 lines
Documentation/git-clone.txt +1
-1@@ -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.
PATCH 3/3 doc: add some missing sentence dots.
In reply to Jean-Noël Avila via GitGitGadgetFrom: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <[email protected]>
--- Documentation/config/diff.txt | 4 ++-- Documentation/git-fast-export.txt | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-)
Documentation/config/diff.txt +2 -2
@@ -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].
Documentation/git-fast-export.txt +1 -1
@@ -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::
Signature · 1 line
gitgitgadget
Re: [PATCH 3/3] doc: add some missing sentence dots.
Quoted 1 line · Jean-Noël Avila via GitGitGadget
Subject: Re: [PATCH 3/3] doc: add some missing sentence dots.
"sentence dots." -> "full stop at the end of sentence" or something?
Documentation/config/diff.txt diff.colorMoved:: · line 227
Quoted 12 lines
Documentation/config/diff.txt +2
-2@@ -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.
Documentation/git-fast-export.txt When asking to 'abort' (which is the default), this program will die · line 51
Quoted 10 lines
Documentation/git-fast-export.txt +1
-1@@ -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.