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

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

[Thomas Ackermann]

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