From: "Thomas Ackermann" <th.acker@xxxxxxxx>
Sent: Saturday, May 11, 2013 8:48 AM
W. Trevor King <wking <at> tremily.us> writes:
I'm also surprised that I couldn't find a more obvious link to the
manual from git-scm.com (I ended up taking a “See Also” link from
gittutorial(7) [3]). I'm not sure if this is intentional or not,
since git-scm.com does prominently link Pro Git, and that overlaps
fairly significantly with the manual.
Folks with Git installed will generally have man pages, so it's not a
big deal, but having current docs somewhere online to link against
would be nice. I'm also curious if I should be linking against a
particular location.
IMHO user-manual is a natural step for a Git beginner after reading
one
of the books like "Pro Git" and before he is ready to digest the man
pages.
But up to now there are several problems with user-manual besides the
problems described by Trevor:
(1) Very poor html formatting (document type "book" causes
ugly TOCs per section and there's a "Part I" without a "Part II")
(2) Partly outdated content
(3) Sub-optimal structuring (to-do list as part of the document,
glossary not at the end of the document)
(4) User-manual.PDF uses an independent tool chain which makes it
harder to do improvements for user-manual.html and also is the only
pdf doc we are creating. IMHO we should remove this altogether.
(5) Large overlapping with the tutorials. IMHO all of the
tutorials should be blended into user-manual
I am currently working on (1)-(4) and then aiming for (5).
Comments are welcome ...
---
Thomas
I too had noticed that both the User-Manual and git Everyday are not
formatted in a manner that allows them to be accessed via 'git help'.
I recently added a '--guides' option to 'git help' (v1.8.2-377-g73903d0)
which will show the common guides but was frustrated that I couldn't
include either the user-manual or everday in the list.
I'd welcome the provision of a 'man'/'html' formatted version of the two
guides. Are you expecting to make then compatible with the man format?
I would be a little cautious of your point 5 if it squoze everything
into one overlong document at the expense of losing the shorter
documents - one can't eat a whole melon in one bite ;-) That said there
is a significant opportunity for rationalisation and clarity
improvement, even if it is only a proper realisation of where we
deliberately duplicate information for ease of user learning.
I also liked the idea of all the documenation being collated into one
Humongous pdf as a reference (there was a patch a while back - don't
have a reference right now).
Philip
--
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