git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: "Jean-Noël Avila" <avila.jn@gmail.com>
To: "Junio C Hamano" <gitster@pobox.com>,
	"Jean-Noël AVILA" <jn.avila@free.fr>
Cc: "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>,
	git@vger.kernel.org, "Eli Schwartz" <eschwartz@archlinux.org>,
	"Martin Ågren" <martin.agren@gmail.com>,
	"Eric Sunshine" <sunshine@sunshineco.com>
Subject: Re: [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders
Date: Wed, 3 Nov 2021 13:46:39 +0100	[thread overview]
Message-ID: <0b404448-cd4b-8614-2c49-c4683b56879f@gmail.com> (raw)
In-Reply-To: <xmqqmtmocqz4.fsf@gitster.g>

Junio C Hamano wrote:
> Jean-Noël AVILA <jn.avila@free.fr> writes:
>
>> The choices here may be awkward; no problem to propose even more descriptive 
>> names.
>>
>>>   Similarly "the 'format:<format-string>' format" feels highly
>>>   redundant, I expect the reader knows that <string> contains a format
>>>   inside it as it's mentioned immediately before *and* after.
>>>
>> The fact that it is a string doesn't tell you much about what you can do with 
>> it. For me, this isn't a problem that the explanation is redundant.
> I agree that --format:<string> is quite poor, as type alone does not
> give readers any information on what it means and how it is supposed
> to look like.  Calling it <format-string> does make quite a lot of
> sense.
>
> It is a bit less obvious how much value we get out of <bool-value>,
> though.  In --opt=<arg> scheme of things, what comes after '=' are
> all <value>s, so <bool-value> does not clarify over <bool> like the
> way <format-string> clarifies over <string>.
>
Agreed. Should reroll the patch series?


  reply	other threads:[~2021-11-03 12:46 UTC|newest]

Thread overview: 49+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-10-26 15:11 [PATCH] doc: fix grammar rules in commands'syntax Jean-Noël Avila via GitGitGadget
2021-10-26 18:21 ` Eric Sunshine
2021-10-27 13:01   ` Jean-Noël Avila
2021-10-27 18:56 ` Martin Ågren
2021-10-27 20:08   ` Eric Sunshine
2021-10-28  9:31   ` Jean-Noël Avila
2021-10-28 18:47     ` Martin Ågren
2021-10-28 16:21 ` [PATCH v2 0/9] doc: fix grammar rules in commands' syntax Jean-Noël Avila via GitGitGadget
2021-10-28 16:21   ` [PATCH v2 1/9] doc: fix git credential synopsis Jean-Noël Avila via GitGitGadget
2021-10-28 16:21   ` [PATCH v2 2/9] doc: split placeholders as individual tokens Jean-Noël Avila via GitGitGadget
2021-10-28 18:45     ` Martin Ågren
2021-10-28 16:21   ` [PATCH v2 3/9] doc: express grammar placeholders between angle brackets Jean-Noël Avila via GitGitGadget
2021-10-28 17:46     ` Eric Sunshine
2021-10-28 19:36       ` Junio C Hamano
2021-10-28 16:21   ` [PATCH v2 4/9] doc: use only hyphens as word separators in placeholders Jean-Noël Avila via GitGitGadget
2021-10-28 18:47     ` Martin Ågren
2021-10-28 19:35       ` Junio C Hamano
2021-10-31 18:58     ` Eli Schwartz
2021-10-31 20:23       ` Jean-Noël AVILA
2021-11-01  6:47         ` Junio C Hamano
2021-11-03 12:46           ` Jean-Noël Avila [this message]
2021-11-03 16:28             ` Junio C Hamano
2021-11-04  0:38               ` Johannes Schindelin
2021-11-04 17:36                 ` Junio C Hamano
2021-11-07 12:40                 ` Eli Schwartz
2021-10-28 16:22   ` [PATCH v2 5/9] doc: git-ls-files: express options as optional alternatives Jean-Noël Avila via GitGitGadget
2021-10-28 16:22   ` [PATCH v2 6/9] doc: use three dots for indicating repetition instead of star Jean-Noël Avila via GitGitGadget
2021-10-28 16:22   ` [PATCH v2 7/9] doc: uniformize <URL> placeholders' case Jean-Noël Avila via GitGitGadget
2021-10-28 17:53     ` Junio C Hamano
2021-10-28 16:22   ` [PATCH v2 8/9] doc: git-http-push: describe the refs as pattern pairs Jean-Noël Avila via GitGitGadget
2021-10-28 17:55     ` Junio C Hamano
2021-10-28 16:22   ` [PATCH v2 9/9] doc: git-init: clarify file modes in octal Jean-Noël Avila via GitGitGadget
2021-10-28 17:17     ` Junio C Hamano
2021-10-28 17:25       ` Junio C Hamano
2021-10-28 19:22   ` [PATCH v2 0/9] doc: fix grammar rules in commands' syntax Junio C Hamano
2021-11-06 18:48 ` [PATCH v3 00/10] " Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 01/10] doc: fix git credential synopsis Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 02/10] doc: split placeholders as individual tokens Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 03/10] doc: express grammar placeholders between angle brackets Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 04/10] doc: use only hyphens as word separators in placeholders Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 05/10] doc: git-ls-files: express options as optional alternatives Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 06/10] doc: use three dots for indicating repetition instead of star Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 07/10] doc: uniformize <URL> placeholders' case Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 08/10] doc: git-http-push: describe the refs as pattern pairs Jean-Noël Avila
2021-11-06 18:48   ` [PATCH v3 09/10] doc: git-init: clarify file modes in octal Jean-Noël Avila
2021-11-07 13:20     ` Johannes Altmanninger
2021-11-06 18:48   ` [PATCH v3 10/10] init doc: --shared=0xxx does not give umask but perm bits Jean-Noël Avila
2021-11-07 13:22     ` Johannes Altmanninger
2021-11-09 17:32       ` Junio C Hamano

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=0b404448-cd4b-8614-2c49-c4683b56879f@gmail.com \
    --to=avila.jn@gmail.com \
    --cc=eschwartz@archlinux.org \
    --cc=git@vger.kernel.org \
    --cc=gitgitgadget@gmail.com \
    --cc=gitster@pobox.com \
    --cc=jn.avila@free.fr \
    --cc=martin.agren@gmail.com \
    --cc=sunshine@sunshineco.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).