From: Philip Oakley Date: Sat, 11 May 2013 11:36:21 GMT Subject: Re: Outdated and broken online versions of user-manual.html Message-ID: In-Reply-To: From: "Thomas Ackermann" Sent: Saturday, May 11, 2013 8:48 AM > W. Trevor King 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