git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH v10 5/5] help: respect new common command grouping

From
Eric Sunshine <sunshine@sunshineco.com>
Date
May 21, 2015, 16:46 UTC
Message-ID
<CAPig+cT65MpPYaE4BxajMNU2N=rf6QQzsxDsc7fV-_GMPVcdhw@mail.gmail.com>
In-Reply-To
<xmqqiobllxdk.fsf@gitster.dls.corp.google.com>
On Thu, May 21, 2015 at 12:16 PM, Junio C Hamano <gitster@pobox.com> wrote:
Show 9 quoted lines
> Eric Sunshine <sunshine@sunshineco.com> writes:
>>> +       puts(_("These are common Git commands used in various situations:"));
>>
>> The clause "in various situations" is quite nebulous and thus adds no
>> substance.
>
> FWIW I view the latter half of that sentence as explaining the group
> labels which we did not have (so we did not have to mention in the
> original).

Hmm, but is it necessary to explain the group labels in the first place? The help output (group labels and all) seems self-explanatory already, and one would expect (hope) that readers are intelligent enough to understand implicitly that the group labels are a simple organizational aid. If that understanding is indeed implicit, then there should be no need to declare it explicitly and "in various situations" becomes mere noise.

> Perhaps swapping the order may clarify, as the list
> itself is a two-level, i.e. list of workflow elements, each of which
> has list of commands?

Perhaps, but I may not be the best judge of that since, to me, that level of hand-holding seems unnecessary.

Anyhow, it's just a minor observation, and it's something people can argue later if they feel strongly about it, so I don't think it should hold up this patch series.

Previous: Junio C HamanoNext: Junio C Hamano
Message 12 of 13 in “group common commands by theme”
  1. 0/5 group common commands by themeSébastien Guimmara, May 21, 2015
  2. 1/5 command-list: prepare machinery for upcoming "common groups" sectionSébastien Guimmara, May 21, 2015
  3. Eric SunshineMay 21, 2015
  4. Sébastien GuimmaraMay 21, 2015
  5. Eric SunshineMay 21, 2015
  6. 2/5 command-list.txt: add the common groups blockSébastien Guimmara, May 21, 2015
  7. 3/5 generate-cmdlist: parse common group commandsSébastien Guimmara, May 21, 2015
  8. 4/5 command-list.txt: drop the "common" tagSébastien Guimmara, May 21, 2015
  9. 5/5 help: respect new common command groupingSébastien Guimmara, May 21, 2015
  10. Eric SunshineMay 21, 2015
  11. Junio C HamanoMay 21, 2015
  12. Eric SunshineMay 21, 2015
  13. Junio C HamanoMay 21, 2015

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.