Jonathan Nieder [off-list ref] writes:
Philip Oakley wrote:
quoted
Describe rebase in the description section.
It already does that. :) I think you mean "start with a summary",
which is a valuable improvement.
It indeed is a good idea to give the "high-level introduction" at
the very beginning, but I do not think it should describe only one
of the three major modes of "git rebase" (i.e. no -m, no -i), like
the proposed patch text does. We should instead say what it is used
for and why the user would want to use it that is common across
these modes at a very high level.
DESCRIPTION
-----------
<brief description of the purpose of the command, including some token
mention of *why* a user would want to use it (e.g., "so that the patches
apply cleanly to their new base").>
Exactly.
From: "Junio C Hamano" <redacted>
Sent: Monday, May 20, 2013 5:43 AM
Jonathan Nieder [off-list ref] writes:
quoted
Philip Oakley wrote:
quoted
Describe rebase in the description section.
It already does that. :) I think you mean "start with a summary",
which is a valuable improvement.
It indeed is a good idea to give the "high-level introduction" at
the very beginning, but I do not think it should describe only one
of the three major modes of "git rebase" (i.e. no -m, no -i), like
the proposed patch text does. We should instead say what it is used
for and why the user would want to use it that is common across
these modes at a very high level.
That would repeat the NAME issue (of trying too hard to be exact &
precise). This introductory text is that "summary". The patch 2/2 should
be the one for the extra detail of the various whys and wherefores - at
least that was my intent.
quoted
DESCRIPTION
-----------
<brief description of the purpose of the command, including some
token
mention of *why* a user would want to use it (e.g., "so that the
patches
apply cleanly to their new base").>
Exactly.
--