From: "Junio C Hamano" <gitster@xxxxxxxxx>
Matthieu Moy <Matthieu.Moy@xxxxxxxxxxxxxxx> writes:
Junio C Hamano <gitster@xxxxxxxxx> writes:
"Philip Oakley" <philipoakley@xxxxxxx> writes:
Having said that, it would therefore be better to point folk at
gitcli
in a few more places, not just the 'see also' line at the very end
of
the general 'git' page, and buried within rev-parse.
Didn't we update the very early part of git(1) for exactly for that
reason recently?
Oops I'd forgotten that specific change.
I don't think many people read git(1) directly, as there are many
other
starting points to learn Git (official tutorial, user-manual, and
tens
of very good tutorial on the web).
Many of which is outside what patches made against to my tree would
be able to fix. I wonder if we can have some mechanism to easily
notify and help the owners of these material to keep them up to
date.
On the other hand, reading git-<command> is probably much more
common, as it is the only place to find exhaustive documentation
about a particular command.
That "people diving into 'git --help <subcmd>', assuming everything
can be learned there" is a problem within the scope of what we could
control. For obvious reasons, including "glossary-contents" and
"gitcli" at the beginning of documentation for each and every
subcommand is not a useful solution, and referring the prerequisite
reading for them in git(1) was done as the first step to solve that
issue, and you are essentially saying that it is not enough.
So what is the right second step?
a simple link to the gitcli page? or, add the <pathspec> into the
checkout options list and a link to a suitable place for that, which can
then point to the gitcli.
From my perspective the majority of the top twenty git commands should,
within each of their help pages, have an in-text link into one or other
of the various 'guide' style articles, which can then be interconnected
to each other. This should give the beginner help by directing them away
from the details of a man page for the general issues. That is,
distinguish which parts are help for those who aren't sure what they
need to know, from the those parts that provide the specfic details for
those do know.
I hope to have some documentation patches in the next few days on other
small misunderstandings I've seen/made. Just battling my windows /
msysgit / pu set-up at the moment.
--
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