Doc placeholders

doc: git-clone fix missing placeholder end carret

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

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

[verse]
-'git rev-parse' [<options>] <args>...
+'git rev-parse' [<options>] <arg>...

-<args>...::
+<arg>...::
Flags and parameters to be parsed.

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

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

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

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, or refs/remotes, respectively).

Ditto. We see pattern that 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 pattern pattern. If the pattern does not start with refs/, this is automatically prepended. If the pattern does not contain a globbing

Ditto.

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-pack or git-upload-pack by consulting the appropriate fetch.hideRefs, receive.hideRefs or uploadpack.hideRefs

Good.

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.

Quoted 9 lines

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

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 10 lines · Jean-Noël Avila

Quoted 9 lines

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

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.

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.

Quoted 2 lines

Backticks and single quotes are used indistinctively (by the way, asciidoctor does not process single quotes as markup) ...

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

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.

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

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,

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?

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

Quoted 1 line

modifying a title and are a pain for translators in languages with

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?

Thanks.