Re: [PATCH 0/3] git help: group common commands by theme

On Wed, May 6, 2015 at 4:26 PM, Sébastien Guimmara
[off-list ref] wrote:

On 05/06/2015 05:08 AM, Eric Sunshine wrote:

quoted

On Mon, May 4, 2015 at 4:28 PM, Sébastien Guimmara
[off-list ref] wrote:

quoted

- Add a [groups] block containing names and description for groups:

    [groups]
    init                   starting a working area

- Add a [commands] header on top of the known command list, and
   group names as a third column.

    [commands]
    git-add            mainporcelain                common-worktree

Thanks, this version is looking better. I, personally, still find the
redundant "command-" prefix ugly and would just as soon see it go
away. I'll make some suggestions about that when reviewing patch 2/3.

Indeed, I'm a bit annoyed by this prefix. We could do two things:
- either drop the [deprecated] options, since it's never used.
- or keep it, but make it exclusive with [common]. It makes sense after
  all that if a command is deprecated, we don't want to consider it
  common anymore.

In both cases, we end up with only three columns, the third being
optional.

The common- prefix can then be removed in favor of the group ID alone.

Sorry for not yet reviewing patch 2/3. I'm trying to find time to
review it and make the promised suggestions, however, Real Life keeps
getting in the way. If 'deprecated' has never been used and if it is
not likely to be used in the future, then dropping that column may
indeed be an easy way forward toward the goal of eliminating the
"common-" prefix. A possible shortcoming of this columnar approach,
however, is that if someone someday comes up with some new type of
attribute to assign in a new column, then you still end up in the same
boat where not all entries use all columns, and you have difficulty
figuring out to which column an attribute belongs.

Instead, as mentioned originally, I had envisioned a solution in which
any command tagged with an attribute mentioned in [groups] would be
considered common, without having to resort to a prefix or fixed
columns. This should be more flexible in the long run, but may be
overkill for present day. I think that awk should be able to handle
this easily, but haven't had the time to actually sit down and flesh
it out (which I wanted to do while reviewing 2/3).

And, any solution is likely going to have to take into account the two
Makefiles Junio mentioned.