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

From: Thomas Ackermann <th.acker@arcor.de>
Date: May 11, 2013, 15:00 UTC
Message-ID: <407109112.1476124.1368284455898.JavaMail.ngmail@webmail17.arcor-online.net>

Show 10 quoted lines

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

Show 7 quoted lines

> 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