Re: Outdated and broken online versions of user-manual.html
Philip Oakley wrote: From: Thomas Ackermann th.ac...@arcor.de (5) Large overlapping with the tutorials. IMHO all of the tutorials should be blended into user-manual [...] 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 ;-) Yes. Once there was a lovely file at Documentation/howto/isolate-bugs-with-bisect.txt explaining how to use git bisect to find which commit caused a kernel regression. That it was a small independent file that didn't assume the reader had read much before was very helpful, since it meant people could easily point novices to that page and say It's easy! when asking them to track down a bug. Nowadays that content is gracefully included in the user-manual under the heading [[using-bisect]]. But I never point people to it any more; I just write out the steps by hand, to avoid intimidating them. Ideally this content would be in an EXAMPLE or TUTORIAL section of the git-bisect(1) manpage for easier reference. Thanks, Jonathan -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Outdated and broken online versions of user-manual.html
W. Trevor King wking at 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 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Outdated and broken online versions of user-manual.html
From: Thomas Ackermann th.ac...@arcor.de Sent: Saturday, May 11, 2013 8:48 AM W. Trevor King wking at 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 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Aw: Re: Outdated and broken online versions of user-manual.html
(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 -- To unsubscribe from this list: send the line unsubscribe git in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Outdated and broken online versions of user-manual.html
I went to reference some `rebase -i` discussion that landed in 3ca26e8 (Merge branch 'wk/user-manual', 2013-02-25), and I couldn't find a version of the manual online that contained the new content. There's a version on kernel.org [1], but that doesn't seem to have been updated since February. There's also a version on git-scm.com [2], but this cuts out after the first section (before “Exploring Git history”). I'm not sure who's in charge of maintaining either location, or which (if either) is considered “canonical”. 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. Cheers, Trevor [1]: https://www.kernel.org/pub/software/scm/git/docs/user-manual.html [2]: http://git-scm.com/docs/user-manual.html [3]: http://git-scm.com/docs/gittutorial -- This email may be signed or encrypted with GnuPG (http://www.gnupg.org). For more information, see http://en.wikipedia.org/wiki/Pretty_Good_Privacy signature.asc Description: OpenPGP digital signature
