{"thread":{"id":"33793","subject":"Aw: Re: Outdated and broken online versions of user-manual.html","startedAt":"2013-05-11T15:00:55Z","lastAt":"2013-05-11T15:00:55Z","messageCount":1,"participants":["Thomas Ackermann"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"217005","messageId":"407109112.1476124.1368284455898.JavaMail.ngmail@webmail17.arcor-online.net","threadId":"33793","inReplyTo":null,"subject":"Aw: Re: Outdated and broken online versions of user-manual.html","fromName":"Thomas Ackermann","fromEmail":"th.acker@arcor.de","sentAt":"2013-05-11T15:00:55Z","receivedAt":"2013-05-11T15:00:55Z","isPatch":false,"sender":{"key":"th.acker@arcor.de","avatar":"https://avatars.githubusercontent.com/u/1358536?v=4"},"body":" \n> > (1) Very poor html formatting (document type \"book\" causes\n> > ugly TOCs per section and there's a \"Part I\" without a \"Part II\")\n> > (2) Partly outdated content\n> > (3) Sub-optimal structuring (to-do list as part of the document,\n> > glossary not at the end of the document)\n> > (4) User-manual.PDF uses an independent tool chain which makes it\n> > harder to do improvements for user-manual.html and also is the only\n> > pdf doc we are creating. IMHO we should remove this altogether.\n> > (5) Large overlapping with the tutorials. IMHO all of the\n> > tutorials should be blended into user-manual\n\n> I'd welcome the provision of a 'man'/'html' formatted version of the two \n> guides. Are you expecting to make then compatible with the man format?\n>\nThis is another topic on my to-do list ...\n \n> I would be a little cautious of your point 5 if it squoze everything \n> into one overlong document at the expense of losing the shorter \n> documents - one can't eat a whole melon in one bite ;-) That said there \n> is a significant opportunity for rationalisation and clarity \n> improvement, even if it is only a proper realisation of where we \n> deliberately duplicate information for ease of user learning.\n> \nI did not have a closer look on this but just from reading the documents\nI got the impression that the tutorials are already more or less contained\nin the user-manual and by a little restructuring the melon will fall into handy pieces ;-)\n\n> I also liked the idea of all the documenation being collated into one \n> Humongous pdf as a reference (there was a patch a while back - don't \n> have a reference right now).\n>\nThanks :-) My patches were rejected but (4) shows that now I know why ;-)\nNevertheless I maintain this in https://github.com/tacker66/git.git and provide\nthe documents for every major version of Git in https://github.com/tacker66/git-docpdf.git.\n(4) is also the reason why I stopped using the pdf target and instead create user-manual.pdf\nwith wkhtmltopdf from user-manual.html.\nAdditionally I use Amazons kindlegen to create mobi version from the html documents\nwhich look quite good on a Kindle.\n\n\n---\nThomas\n"}]}