Re: Outdated and broken online versions of user-manual.html

From: Thomas Ackermann <th.acker@arcor.de>
Date: May 11, 2013, 07:48 UTC
Message-ID: <loom.20130511T092853-808@post.gmane.org>
In-Reply-To: <20130510190229.GA31708@odin.tremily.us>

W. Trevor King <wking <at> tremily.us> writes:

Show 12 quoted lines

> 
> 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