Matthew Brett <matthew.brett@xxxxxxxxx> writes:
> Obviously my page as it is now is very different in tone from the
> git-rebase page, but I think there are some aspects that could be
> fruitfully merged. Would you be interested in patches of this sort,
> or does the page seem too far from the intention of the man page?
I think it is deliberate that manpages are not written as tutorial, but
as more advanced technical documentation. Just like learning Unix can
hardly be done by reading "man ls", "man cd", ... the best entry point
to learn Git is not the manpages. OTOH, I usually like Git's manpages
when I know what I'm looking for.
All that being said, there's a lot of room for improvement in our
manpages, event remaining in a technical-style. I'm not a good juge
because I already learnt how rebase works long ago, but the git rebase
man page does seem terrible for bare mortals:
NAME
git-rebase - Forward-port local commits to the updated upstream head
=> Quite technical already.
DESCRIPTION
If <branch> is specified, git rebase will perform an automatic
git checkout <branch> before doing anything else. Otherwise it
remains on the current branch.
=> Ouch, do we really want to start a documentation like this?
So, the DESCRIPTION part can definitely be improved IMHO. Your notation
<graft-point>, <exclude-from> and <include-from> may be an improvement
already.
Some concrete examples may help too, like "I started developing against
origin/foo, on local branch bar, and now want to rebase my work on top
of origin/boz".
My 2 cents,
--
Matthieu Moy
http://www-verimag.imag.fr/~moy/
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html