Re: [PATCH v8 4/5] doc: git-rebase: move --onto explanation down

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

> From: Julia Evans <julia@jvns.ca>
>
> There's a very clear explanation with examples of using --onto which is
> currently buried in the very long DESCRIPTION section. This moves it to
> its own section, so that we can reference the explanation from the
> `--onto` option by name.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-rebase.adoc | 168 ++++++++++++++++++----------------
>  1 file changed, 87 insertions(+), 81 deletions(-)

Deduplicating is very good idea.

I gave a read-through over the result of the entire series,
including the parts that did not change, to see if the new
organization is easy to read and coherently tells the story
we want to tell, and what I saw was mostly very pleasing, except for
one thing.

The new location of this section on "--onto" felt a bit off.
Perhaps it is just me, but in case others have different opinions,
I'd raise it here.

The overall structure of the document with these patches becomes:

 - description that gives a simplified "what is achieved".

 - "mode options" that control what to do during a rebase once the
   user is given control back

 - "options" that is given upfront

 - notes about incompatible options

 - discussions about apply/merge backends and how they differ

 - overall notes on advanced topics

   - interactive mode basics

   - splitting commits

   - use of --onto

   - dealing with rebased upstream

   - rebasing merges

Is it so exotic to use "--onto" to replay a topic to somewhere other
than the direct descendant of the fork point, to make it a part of
advanced topics?  I somehow doubt it.  It is a very basic and common
thing to do while correcting a mistake of choosing a wrong base
commit.  You often realize that your topic is basically good but has
to work well with a different base commit.

I wonder if it gives the same understanding with a much shorter text
and illustration if we get rid of that section, and mention --onto
as a part of the early examples in the description section.  That
way, we can reuse the "set up" of user's brain and context we
already made with the existing example.

For example, after showing the rebase of A..C on top of G, we can
mention that the range can be transplanted on top of commit other
than G, say D.  Perhaps we can say that 'D' is still part of the
maintenance track, and the topic being a fix for a bug that happened
before D, it should not have forked from E that is a feature
enhancement commit that is not eligible for being on the maintenance
track.  That would be a good reason why the user may want to move
A..C on top of D instead of E.