From: Thomas Ackermann Date: Sat, 11 May 2013 15:00:55 GMT Subject: Aw: Re: Outdated and broken online versions of user-manual.html Message-ID: <407109112.1476124.1368284455898.JavaMail.ngmail@webmail17.arcor-online.net> > > (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'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? > This is another topic on my to-do list ... > 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 did not have a closer look on this but just from reading the documents I got the impression that the tutorials are already more or less contained in the user-manual and by a little restructuring the melon will fall into handy pieces ;-) > 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). > Thanks :-) My patches were rejected but (4) shows that now I know why ;-) Nevertheless I maintain this in https://github.com/tacker66/git.git and provide the documents for every major version of Git in https://github.com/tacker66/git-docpdf.git. (4) is also the reason why I stopped using the pdf target and instead create user-manual.pdf with wkhtmltopdf from user-manual.html. Additionally I use Amazons kindlegen to create mobi version from the html documents which look quite good on a Kindle. --- Thomas