{"thread":{"id":"14739","subject":"Git Community Book","startedAt":"2008-07-29T16:20:20Z","lastAt":"2008-08-01T11:06:34Z","messageCount":39,"participants":["Scott Chacon","Miklos Vajna","Petr Baudis","Junio C Hamano","Julian Phillips","Daniel Barkalow","Bart Trojanowski","Johannes Schindelin","J. Bruce Fields","Wincent Colaiuta","Abdelrazak Younes","Stephan Beyer","Jan Krüger","Thomas Rast","Dmitry Potapov"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"85486","messageId":"d411cc4a0807290920p62f5d7e1r727a62ef2b4611fc@mail.gmail.com","threadId":"14739","inReplyTo":null,"subject":"Git Community Book","fromName":"Scott Chacon","fromEmail":"schacon@gmail.com","sentAt":"2008-07-29T16:20:20Z","receivedAt":"2008-07-29T16:20:20Z","isPatch":false,"sender":{"key":"schacon@gmail.com","avatar":"https://gravatar.com/avatar/9b13a8a078e1dcf8588c4eea9554445d51ebed6c41b51f56f4d96738130b05c6?d=mp&s=160"},"body":"So I wanted to develop a really nice, easy to follow book for Git\nnewcomers to learn git quickly and easily. One of the issues I\nremember having when learning Git is that there is a lot of great\nmaterial in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -\nbut they're all huge long documents that are sometimes difficult to\ncome back to and remember where you were, and I didn't know which one\nto start with or where to find what I was looking for, etc.\n\nSo, what I've started to do is pull material from all of them into a\nsingle book which will be available in online HTML (one page per\nchapter) and downloadable PDF form. I'm trying to give it a very\norganized flow that will hopefully be a bit easier to follow and\ndigest than the current formats, and including a number of diagrams,\nillustrations and screencasts to supplement the text. Where possible,\nI am also trying to simplify the explanations a bit to be a tad more\ndigestible for beginning users, at least in the first couple dozen\nchapters. I have put the current html output of this book here:\n\nhttp://book.git-scm.com\n\nIt is not complete - the grey links are chapters that are very short\nor completely empty - but it is a start. Please let me know what you\nthink, and if anyone is interested in helping with the project, give\nme a shout.\n\nAlso, for credit, I have generated an Authors page I will be linking\nto the site soon that lists everyone that contributed a patch to any\nof the Git User Guide, Git Tutorials, etc. It is in the PDF right\nnow, but not in the HTML version yet (and the PDF is not yet linked to\nthe site).\n\nThanks,\nScott\n"},{"id":"85487","messageId":"20080729162859.GZ32057@genesis.frugalware.org","threadId":"14739","inReplyTo":"d411cc4a0807290920p62f5d7e1r727a62ef2b4611fc@mail.gmail.com","subject":"Re: Git Community Book","fromName":"Miklos Vajna","fromEmail":"vmiklos@frugalware.org","sentAt":"2008-07-29T16:28:59Z","receivedAt":"2008-07-29T16:28:59Z","isPatch":false,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Tue, Jul 29, 2008 at 09:20:20AM -0700, Scott Chacon wrote:\n> It is not complete - the grey links are chapters that are very short\n> or completely empty - but it is a start. Please let me know what you\n> think, and if anyone is interested in helping with the project, give\n> me a shout.\n\nAt http://github.com/schacon/learn-github/wikis/how-to-contribute, there\nis a typo: you want 'git checkout origin/book'. ;-)\n"},{"id":"85491","messageId":"20080729170955.GK32184@machine.or.cz","threadId":"14739","inReplyTo":"d411cc4a0807290920p62f5d7e1r727a62ef2b4611fc@mail.gmail.com","subject":"Re: Git Community Book","fromName":"Petr Baudis","fromEmail":"pasky@suse.cz","sentAt":"2008-07-29T17:09:55Z","receivedAt":"2008-07-29T17:09:55Z","isPatch":false,"sender":{"key":"pasky@ucw.cz","avatar":"https://avatars.githubusercontent.com/u/18439?v=4"},"body":"On Tue, Jul 29, 2008 at 09:20:20AM -0700, Scott Chacon wrote:\n> So, what I've started to do is pull material from all of them into a\n> single book which will be available in online HTML (one page per\n> chapter) and downloadable PDF form. I'm trying to give it a very\n> organized flow that will hopefully be a bit easier to follow and\n> digest than the current formats, and including a number of diagrams,\n> illustrations and screencasts to supplement the text. Where possible,\n> I am also trying to simplify the explanations a bit to be a tad more\n> digestible for beginning users, at least in the first couple dozen\n> chapters. I have put the current html output of this book here:\n> \n> http://book.git-scm.com\n\nI think what most of the people here would be also interested in is\n\n\thttp://github.com/schacon/learn-github/wikis/how-to-contribute\n\nThere is no license in the source code - what are the copying terms?\n\nIt is maybe somewhat unfortunate that this is in a different format that\nthe standard git choice asciidoc, but the formats do look rather similar\nso I assume it should not be hard to even convert from one to another if\nneeded.\n\nUnfortunately, I probably won't have enough time to review the content\nin details anytime soon, so I can only say that that the site looks\npretty. :-) I have skimmed through the Introduction part only, but\nfrankly, my feelings are somewhat mixed; I think the \"direct dive-in\"\nyou take in the Database and Index section is controversial at best, and\nI personally much prefer the gentle approach of user manual, which does\nnot hurl details on git's objects model on the user right away. To me,\nit would make sense to move this all somewhere between chapter four and\nfive. (Incidentally, only after writing this, I have looked at the\nactual structure of the User Manual and I think it makes more sense than\nyour approach.)\n\nSo my confusion still is - where does this stand wrt. the user manual?\nWhy didn't you just start with the manual and work on that? I thought\nyou were planning to do that, but apparently we misunderstood each other\nin the last mails.\n\nWhich goals are different between the Git Community Book and the User\nManual? It seems to me that the intent is the same in both cases, and if\nthe User Manual is not sufficiently digestible and easy to understand\nfor a newcomer, wouldn't it make more sense to make it so?\n\nThe thought of yet another Git resource _in addition_ to the existing\nones just makes me nervous. This isn't only about your time that I feel\nis being spent unnecessarily ineffectively by not building upon the\nexisting text, but also about the _community_ resources - the user\nmanual has a great benefit that it was actually reviewed by the mailing\nlist so it will probably have quite smaller error rate than anything\nyou or me would write on our own, no matter how big Git expert you are.\n\nI'm not saying you don't have good reasons to make the choice you did,\nI just don't understand them yet - please help me here.\n\n> So I wanted to develop a really nice, easy to follow book for Git\n> newcomers to learn git quickly and easily. One of the issues I\n> remember having when learning Git is that there is a lot of great\n> material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -\n> but they're all huge long documents that are sometimes difficult to\n> come back to and remember where you were, and I didn't know which one\n> to start with or where to find what I was looking for, etc.\n\nSo, one of your arguments is that the current material are huge long\ndocuments that are difficult to come back to and remember where you\nwere. But if I'd split the User Manaul TOC to the same layout you use\nfor the Community Book, what is the difference here? It seems to me that\nboth would appear pretty much the same. Should I do a proof of concept?\n;-)\n\n> Also, for credit, I have generated an Authors page I will be linking\n> to the site soon that lists everyone that contributed a patch to any\n> of the Git User Guide, Git Tutorials, etc. It is in the PDF right\n> now, but not in the HTML version yet (and the PDF is not yet linked to\n> the site).\n\nSo, right now you are basically taking existing material and rearranging\nit? By what rules? What is the underlying idea of your approach, and why\nis it better than the current structure of the user manual? Have you\nconsidered how to perform this all so that you can easily get further\nupdates and corrections to the user manual?\n\n-- \n\t\t\t\tPetr \"Pasky\" Baudis\nAs in certain cults it is possible to kill a process if you know\nits true name. -- Ken Thompson and Dennis M. Ritchie\n"},{"id":"85494","messageId":"7vmyk0fux8.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"d411cc4a0807290920p62f5d7e1r727a62ef2b4611fc@mail.gmail.com","subject":"Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-29T17:43:15Z","receivedAt":"2008-07-29T17:43:15Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Scott Chacon\" writes:\n\n> So I wanted to develop a really nice, easy to follow book for Git\n> newcomers to learn git quickly and easily. One of the issues I\n> remember having when learning Git is that there is a lot of great\n> material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -\n> but they're all huge long documents that are sometimes difficult to\n> come back to and remember where you were, and I didn't know which one\n> to start with or where to find what I was looking for, etc.\n\nInteresting. A few comments, before I get dragged into my day job fully.\n\n[overall]\n\n - Some people mentioned that the necessity of reading through large\n volume of documentation can be reduced if they were divided by\n developer roles (similar to how Everyday does), e.g. people in\n individual contributor role does not have to learn integrator tools\n such as \"am\" in their first pass on the documentation. Has the\n approach considered while developing this book?\n\n - The order of sections in \"Working with Git\" chapter somehow does not\n feel quite right, except that I'd agree that \"Git on Windows\" at the\n beginning is a very good idea (disclaimer. I do not use Windows\n myself). \"StGIT\" coming next was very understandable, but then\n \"Capistrano\"???? And no CVS section next to Subversion section? Ruby\n before Perl or Python (I would have listed Perl, Python and then Ruby\n to avoid language wars. That's the language age order, and it is even\n alphabetical)???\n\n Above \"Capistrano\" and \"Ruby\" comment shows the bias this TOC has (and\n my bias being different from the TOC's bias). I'd imagine that\n Ruby-minded folks won't share the same reaction as I had. What's the\n target audience of this book? Git users in general, or primarily\n Ruby-minded subset? If the latter, labeling this as \"Community Book\"\n may be misleading.\n\n[http://book.git-scm.com/1_the_git_object_database.html]\n\n - The color of \"blob\" does not match the blob that is committed to eat\n trees at the top of your site ;-)\n\n - In a recent thread on the list, quite a lot of people seem to have\n found that teaching the low level details and plumbing first to the new\n people is detrimental. Do you have response to that thread?\n"},{"id":"85497","messageId":"7v3alsfsy8.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"7vmyk0fux8.fsf@gitster.siamese.dyndns.org","subject":"Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-29T18:25:51Z","receivedAt":"2008-07-29T18:25:51Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Junio C Hamano writes:\n\n> \"Scott Chacon\" writes:\n>\n>> So I wanted to develop a really nice, easy to follow book for Git\n>> newcomers to learn git quickly and easily. One of the issues I\n>> remember having when learning Git is that there is a lot of great\n>> material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -\n>> but they're all huge long documents that are sometimes difficult to\n>> come back to and remember where you were, and I didn't know which one\n>> to start with or where to find what I was looking for, etc.\n>\n> Interesting. A few comments, before I get dragged into my day job fully.\n\n(cont'd)\n\nI was planning to comment on the contents (i.e. text) but it appears that\nmost of the stuff was borrowed from the User Manual, so I won't.\n\n\tSide note: I wonder if this makes the whole \"Community Book\"\n\tGPLv2. What would happen to the part that includes your own\n\tscreencast? You do not mind it be contaminated by our licence?\n\nBut there seems to be some stuff User Manual does not talk about.\n\n[3_basic_branching_and_merging.html]\n\n - You've talked about low-level individual objects in an earlier section\n but you stopped at showing a single commit pointing at a tree. People\n would find branching and merging very hard to get, without\n understanding the commit DAG. On the other hand, you can explain\n commit DAG without going into details down to trees and blobs in the\n earlier section. The user manual has \"understanding reachability\"\n section early on for this exact reason.\n\n[5_creating_new_empty_branches.html]\n\n - As I repeatedly said on the list, I do not think teaching this is\n useful. Multiple roots may happen as a result of pushing (or pulling)\n from a repository with unrelated root, but it is not something you\n would want to actively aim for. At least there needs an explanation\n for the reason why making disjoint roots in the same repository is\n (sometimes) a good thing to do, and what its downsides are.\n"},{"id":"85498","messageId":"d411cc4a0807291130p228f77d5r1f390090ec29aef4@mail.gmail.com","threadId":"14739","inReplyTo":"20080729170955.GK32184@machine.or.cz","subject":"Re: Git Community Book","fromName":"Scott Chacon","fromEmail":"schacon@gmail.com","sentAt":"2008-07-29T18:30:55Z","receivedAt":"2008-07-29T18:30:55Z","isPatch":false,"sender":{"key":"schacon@gmail.com","avatar":"https://gravatar.com/avatar/9b13a8a078e1dcf8588c4eea9554445d51ebed6c41b51f56f4d96738130b05c6?d=mp&s=160"},"body":">\n> There is no license in the source code - what are the copying terms?\n>\n\nI copied in the COPYING file from Git - GPL2.\n\n> It is maybe somewhat unfortunate that this is in a different format that\n> the standard git choice asciidoc, but the formats do look rather similar\n> so I assume it should not be hard to even convert from one to another if\n> needed.\n\nI simply didn't want to get asciidoc working locally - it's always\nbeen a bit of a pain to compile (I've heard it referred to more than\nonce as the only 'nightmare dependancy' in git), and I don't need to\nmake man pages or anything, so it seemed Markdown would be a better\nchoice for my output targets. There are a number of good Markdown\ninterpreters and they're easy to get running.\n\n>\n> Unfortunately, I probably won't have enough time to review the content\n> in details anytime soon, so I can only say that that the site looks\n> pretty. :-) I have skimmed through the Introduction part only, but\n> frankly, my feelings are somewhat mixed; I think the \"direct dive-in\"\n> you take in the Database and Index section is controversial at best, and\n> I personally much prefer the gentle approach of user manual, which does\n> not hurl details on git's objects model on the user right away. To me,\n> it would make sense to move this all somewhere between chapter four and\n> five. (Incidentally, only after writing this, I have looked at the\n> actual structure of the User Manual and I think it makes more sense than\n> your approach.)\n>\n> So my confusion still is - where does this stand wrt. the user manual?\n> Why didn't you just start with the manual and work on that? I thought\n> you were planning to do that, but apparently we misunderstood each other\n> in the last mails.\n>\n\nI was originally planning on doing that, but the problem is the\ngraphics, diagrams and screencasts. Unless I am mistaken, there is\nnot a single outside media reference in any of these guides - the\ndiagrams that are there are all ascii drawings. I'm assuming there is\na reason for that. If I wanted to add images and screencast embeds\ninto the guide, how would that work?\n\nAlso, the user guide seems much more technical than I wanted - I\nwanted to simplify a lot of the explanations, especially at the\nbeginning, and I don't want to screw up all the existing text. I\nthought that the best solution would be to have the Community Book as\nmore of a book format, and the User Guide as more of an advanced\ntechnical guide. We don't want to put 'Git and Capistrano' or 'Using\nGit in Perl' in the User Guide, do we? I just wanted to copy the\nsections that were already well written that need to be in both, so\nthat I don't have to re-write them.\n\n> Which goals are different between the Git Community Book and the User\n> Manual? It seems to me that the intent is the same in both cases, and if\n> the User Manual is not sufficiently digestible and easy to understand\n> for a newcomer, wouldn't it make more sense to make it so?\n\nI think the goals are a bit different. I think the User Manual is\nhelpful for people coming from the Linux/Perl hacker communities that\nare more used to guides like that - who like things explained more\ntechnically and possibly even think screencasts are stupid and an\nascii graph is just as understandable as a pretty one with rounded\ncorners and pastel colors.\n\nI think my goal with the book is to create a book. The length of a\nbook, readable one chapter at a time over several days, etc. Also,\neventually, I want to make it bookmarkable, maybe add some interactive\nquizzes at the end of each chapter, maybe add a comments section to\nthe end of each chapter, add a live search box, etc. That just seems\nso much different than the User Guide and Tutorials that it warrants a\ndifferent project, but so much of the content in the Guide is quality\nthat I didn't want to reinvent the wheel yet again.\n\n> The thought of yet another Git resource _in addition_ to the existing\n> ones just makes me nervous. This isn't only about your time that I feel\n> is being spent unnecessarily ineffectively by not building upon the\n> existing text, but also about the _community_ resources - the user\n> manual has a great benefit that it was actually reviewed by the mailing\n> list so it will probably have quite smaller error rate than anything\n> you or me would write on our own, no matter how big Git expert you are.\n\nWell, that's what the point of this is - to ask everyone to help me\nreview it, and possibly help me add to it. The user manual is great,\nbut even I don't reference it very often because I find it difficult\nto find content in it I need quickly. As Git becomes more and more\npopular, more and more resources will continue to come out - I did the\nPeepcode mini-book, which sold over a thousand copies already, and\nPragmatic Programmers and O'Reilly both have Git books in the works,\ntoo. I was planning on a second book with Peepcode, but I thought it\nwould be better to do this instead.\n\nI would love to develop a book that is totally open and rivals all of\nthose and is consistently up to date and allows the community to\ninteract. I don't think it's really possible to get the User Guide\nthere very easily except in this way.\n\n\n> So, one of your arguments is that the current material are huge long\n> documents that are difficult to come back to and remember where you\n> were. But if I'd split the User Manaul TOC to the same layout you use\n> for the Community Book, what is the difference here? It seems to me that\n> both would appear pretty much the same. Should I do a proof of concept?\n> ;-)\n\nAgain, I started to do this, but the image references, screencast\nembeds, and general different goal of the book, both in length and\nscope, makes me think that is not the best way to go.\n\n> So, right now you are basically taking existing material and rearranging\n> it? By what rules? What is the underlying idea of your approach, and why\n> is it better than the current structure of the user manual? Have you\n> considered how to perform this all so that you can easily get further\n> updates and corrections to the user manual?\n\nI have thought about this a lot, and it comes from the talks and\ntraining I've done with Git and the feedback I've gotten from that.\nFor one, I think it's very helpful to split up the chapters into\nsections ('First Time', 'Basic Usage', 'Advanced Usage', etc) so users\nof different skill levels can easily see which chapters may have\nsomething for them at a glance.\n\nThe specific order I choose is very different from the User Guide and\nis likely to bother a number of people, which you mentioned (and I'm\nsure Dscho will _hate_) because I introduce the object model at the\nbeginning. (I'm still working on that section, trying to simplify it\nand add in some other diagrams and a short screencast I have that I\nthink will be helpful) This is because I have had a lot of positive\nfeedback that primary frustration from people comes from them thinking\nof Git as a super-better Subversion. I would venture to say that\n_most_ of the users coming to Git now are currently fluent in\nSubversion. Even if they are from Perforce or CVS (the other two ones\nI will occasionally run into), their mental model of what an SCM does\nis the same - delta storage. I've found that by ridding them of that\nnotion off the bat, they have _far_ fewer problems and frustrations\nwith Git than when I just try to show them the first 10 commands in\nsort of a cookbook style. It's not a complicated model, it doesn't\ntake long to teach, and in _my personal_ experience (which is not to\nsay it's necessarily correct), it helps people the most in picking it\nup and really loving the tool.\n\nThe book is built so that it is just as easy to start in the 'Basic\nUsage' section and go back later, but if you're going to sit down and\njust start reading, I think it would be better to explain why Git is\ndifferent at a fundamental level right off the bat.\n\nScott\n"},{"id":"85499","messageId":"7vwsj4edm1.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"d411cc4a0807291130p228f77d5r1f390090ec29aef4@mail.gmail.com","subject":"Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-29T18:42:30Z","receivedAt":"2008-07-29T18:42:30Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Scott Chacon\" writes:\n\n>>\n>> There is no license in the source code - what are the copying terms?\n>>\n>\n> I copied in the COPYING file from Git - GPL2.\n>\n>> It is maybe somewhat unfortunate that this is in a different format that\n>> the standard git choice asciidoc, but the formats do look rather similar\n>> so I assume it should not be hard to even convert from one to another if\n>> needed.\n>\n> I simply didn't want to get asciidoc working locally - it's always\n> been a bit of a pain to compile (I've heard it referred to more than\n> once as the only 'nightmare dependancy' in git), and I don't need to\n> make man pages or anything, so it seemed Markdown would be a better\n> choice for my output targets. There are a number of good Markdown\n> interpreters and they're easy to get running.\n\nI personally like markdown, but doesn't your refusal to work with existing\npractices pose a significant problem, unless:\n\n (0) you do not consider it a goal to keep the documentation shipped with\n git and your book in sync; or\n\n (1) you have either markdown to asciidoc (or the other way around)\n converter; the book is written in markdown, and its conversion back\n to asciidoc is fed to Documentation as patches (or the other way\n around); or\n\n (2) somebody tries to find markdown to manpage, and we convert\n Documentation/ to markdown.\n\nOr is this, \"fork once and borrow reviewer's time, but never be able to\ncontribute back to the original text because the result is so different\"\napproach?\n"},{"id":"85500","messageId":"Pine.LNX.4.64.0807291957410.1779@reaper.quantumfyre.co.uk","threadId":"14739","inReplyTo":"7vwsj4edm1.fsf@gitster.siamese.dyndns.org","subject":"Re: Git Community Book","fromName":"Julian Phillips","fromEmail":"julian@quantumfyre.co.uk","sentAt":"2008-07-29T19:00:55Z","receivedAt":"2008-07-29T19:00:55Z","isPatch":false,"sender":{"key":"julian@quantumfyre.co.uk","avatar":"https://avatars.githubusercontent.com/u/948888?v=4"},"body":"On Tue, 29 Jul 2008, Junio C Hamano wrote:\n\n> \"Scott Chacon\" writes:\n>\n>>>\n>>> There is no license in the source code - what are the copying terms?\n>>>\n>>\n>> I copied in the COPYING file from Git - GPL2.\n>>\n>>> It is maybe somewhat unfortunate that this is in a different format that\n>>> the standard git choice asciidoc, but the formats do look rather similar\n>>> so I assume it should not be hard to even convert from one to another if\n>>> needed.\n>>\n>> I simply didn't want to get asciidoc working locally - it's always\n>> been a bit of a pain to compile (I've heard it referred to more than\n>> once as the only 'nightmare dependancy' in git), and I don't need to\n>> make man pages or anything, so it seemed Markdown would be a better\n>> choice for my output targets. There are a number of good Markdown\n>> interpreters and they're easy to get running.\n>\n> I personally like markdown, but doesn't your refusal to work with existing\n> practices pose a significant problem, unless:\n>\n> (0) you do not consider it a goal to keep the documentation shipped with\n> git and your book in sync; or\n>\n> (1) you have either markdown to asciidoc (or the other way around)\n> converter; the book is written in markdown, and its conversion back\n> to asciidoc is fed to Documentation as patches (or the other way\n> around); or\n>\n> (2) somebody tries to find markdown to manpage, and we convert\n> Documentation/ to markdown.\n\nHaven't used it personally, and without commenting on the \"political\" side \nof such an approach - there does exist at least one tool that claims to be \nable to convert from markdown to man: http://johnmacfarlane.net/pandoc/\n\n> Or is this, \"fork once and borrow reviewer's time, but never be able to\n> contribute back to the original text because the result is so different\"\n> approach?\n>\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n>\n\n-- \nJulian\n\n ---\n[The French Riviera is] a sunny place for shady people.\n \t\t-- Somerset Maugham\n"},{"id":"85501","messageId":"7vod4gecd5.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"Pine.LNX.4.64.0807291957410.1779@reaper.quantumfyre.co.uk","subject":"Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-29T19:09:26Z","receivedAt":"2008-07-29T19:09:26Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Julian Phillips writes:\n\n> On Tue, 29 Jul 2008, Junio C Hamano wrote:\n>\n>> \"Scott Chacon\" writes:\n>>\n>>> I simply didn't want to get asciidoc working locally - it's always\n>>> been a bit of a pain to compile (I've heard it referred to more than\n>>> once as the only 'nightmare dependancy' in git), and I don't need to\n>>> make man pages or anything, so it seemed Markdown would be a better\n>>> choice for my output targets. There are a number of good Markdown\n>>> interpreters and they're easy to get running.\n>>\n>> I personally like markdown, but doesn't your refusal to work with existing\n>> practices pose a significant problem, unless:\n>> ...\n>> (2) somebody tries to find markdown to manpage, and we convert\n>> Documentation/ to markdown.\n> \n> Haven't used it personally, and without commenting on the \"political\"\n> side of such an approach - there does exist at least one tool that\n> claims to be able to convert from markdown to man:\n> http://johnmacfarlane.net/pandoc/\n\nOh, there is nothing political about this. It is not like some of us is\nemployed by AsciiDoc company and defecting to markdown would cost\nsomebody's job or life ;-)\n\nIt is good to know that an option is availble to make it easier to go\nback-and-forth, when/if it becomes necessary.\n"},{"id":"85503","messageId":"d411cc4a0807291224h65e4746cgda94ee66a4ab5da0@mail.gmail.com","threadId":"14739","inReplyTo":"7vmyk0fux8.fsf@gitster.siamese.dyndns.org","subject":"Re: Git Community Book","fromName":"Scott Chacon","fromEmail":"schacon@gmail.com","sentAt":"2008-07-29T19:24:57Z","receivedAt":"2008-07-29T19:24:57Z","isPatch":false,"sender":{"key":"schacon@gmail.com","avatar":"https://gravatar.com/avatar/9b13a8a078e1dcf8588c4eea9554445d51ebed6c41b51f56f4d96738130b05c6?d=mp&s=160"},"body":"On Tue, Jul 29, 2008 at 10:43 AM, Junio C Hamano wrote:\n> \"Scott Chacon\" writes:\n>\n>> So I wanted to develop a really nice, easy to follow book for Git\n>> newcomers to learn git quickly and easily. One of the issues I\n>> remember having when learning Git is that there is a lot of great\n>> material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -\n>> but they're all huge long documents that are sometimes difficult to\n>> come back to and remember where you were, and I didn't know which one\n>> to start with or where to find what I was looking for, etc.\n>\n> Interesting. A few comments, before I get dragged into my day job fully.\n>\n> [overall]\n>\n> - Some people mentioned that the necessity of reading through large\n> volume of documentation can be reduced if they were divided by\n> developer roles (similar to how Everyday does), e.g. people in\n> individual contributor role does not have to learn integrator tools\n> such as \"am\" in their first pass on the documentation. Has the\n> approach considered while developing this book?\n>\n\nNot really - I'm assuming that everyone will have to be one of those\nroles at some point - I'm mostly aiming at the smaller developers like\nmyself, and probably 90% of the Git users, who have 20 git projects\nthat they work on with 1-5 other people. I am not aiming at the Linux\nor Git developers that have to deal with a project with hundreds of\nusers - everyone is going to have to be a developer, participant,\nintegrator and administrator to some degree, so I wanted to introduce\nthose commands when you need them. IE, 'gc' and 'fsck' are rarely\n_needed_ by most users - you can work just fine for a really long time\nwithout ever needing to run them, but they are first in the Everyday\nlist. I'm ordering it roughly in the order that I've seen people need\ncertain commands. I could be convinced otherwise on any of them,\nthough.\n\n> - The order of sections in \"Working with Git\" chapter somehow does not\n> feel quite right, except that I'd agree that \"Git on Windows\" at the\n> beginning is a very good idea (disclaimer. I do not use Windows\n> myself). \"StGIT\" coming next was very understandable, but then\n> \"Capistrano\"???? And no CVS section next to Subversion section? Ruby\n> before Perl or Python (I would have listed Perl, Python and then Ruby\n> to avoid language wars. That's the language age order, and it is even\n> alphabetical)???\n>\n\nThis is basically just notes at this point. I will likely re-arrange\nthem as they are written. However, I would argue that there are\nlikely more Git people using Ruby than there are using Python, though\nPerl might rival it. Nearly every major Ruby project out there is now\nusing Git, whereas very few Python ones seem to be (possibly because\nMercurial is written in python) - however, in all honesty, I don't\nreally care what order they are in.\n\nAs for the Capistrano section - again it is demand. I have had tons\nand tons of questions about Capistrano and Git, and many thousands of\npeople use that combination or are beginning to. Again though, I\ndon't care where it is - I would be happy to put it at the bottom of\nthe section.\n\n> Above \"Capistrano\" and \"Ruby\" comment shows the bias this TOC has (and\n> my bias being different from the TOC's bias). I'd imagine that\n> Ruby-minded folks won't share the same reaction as I had. What's the\n> target audience of this book? Git users in general, or primarily\n> Ruby-minded subset? If the latter, labeling this as \"Community Book\"\n> may be misleading.\n\nThe target audience are users being convinced by their friends to use\nGit and I want to impress them with a well thought out and laid out,\ncomprehensive, easy to use website and book as their first experience,\nand show them an easy and smooth path to switch their mind from\nthinking in SVN/Perforce to thinking in Git. The Ruby community is a\nvery large part of the current surge to Git right now, but I want the\nbook to be easily accessible and acceptable to all communities that\nare doing that.\n\n> [http://book.git-scm.com/1_the_git_object_database.html]\n>\n> - The color of \"blob\" does not match the blob that is committed to eat\n> trees at the top of your site ;-)\n>\n> - In a recent thread on the list, quite a lot of people seem to have\n> found that teaching the low level details and plumbing first to the new\n> people is detrimental. Do you have response to that thread?\n>\n\nI think I addressed this in a previous response. As for the blob\ncolor, a number of diagrams I am planning to introduce initially are\nfrom a talk I gave at RailsConf on Git, and I will likely go back over\nthem a bit later.\n\nThanks,\nScott\n"},{"id":"85504","messageId":"d411cc4a0807291229w3961f9auf26d40544138c9be@mail.gmail.com","threadId":"14739","inReplyTo":"7v3alsfsy8.fsf@gitster.siamese.dyndns.org","subject":"Re: Git Community Book","fromName":"Scott Chacon","fromEmail":"schacon@gmail.com","sentAt":"2008-07-29T19:29:02Z","receivedAt":"2008-07-29T19:29:02Z","isPatch":false,"sender":{"key":"schacon@gmail.com","avatar":"https://gravatar.com/avatar/9b13a8a078e1dcf8588c4eea9554445d51ebed6c41b51f56f4d96738130b05c6?d=mp&s=160"},"body":"On Tue, Jul 29, 2008 at 11:25 AM, Junio C Hamano wrote:\n>\n> (cont'd)\n>\n> I was planning to comment on the contents (i.e. text) but it appears that\n> most of the stuff was borrowed from the User Manual, so I won't.\n>\n> Side note: I wonder if this makes the whole \"Community Book\"\n> GPLv2. What would happen to the part that includes your own\n> screencast? You do not mind it be contaminated by our licence?\n>\n> But there seems to be some stuff User Manual does not talk about.\n\nYes, I'm using text from the User Manual and beginning to convert a\nbunch of the text to make more sense in the new context, but it is\nstill under GPL2 and the screencasts are being linked to, not included\nand distributed, so they shouldn't be affected. However, they are\nMIT, so you can pretty much do whatever you want with them.\n\n> [3_basic_branching_and_merging.html]\n>\n> - You've talked about low-level individual objects in an earlier section\n> but you stopped at showing a single commit pointing at a tree. People\n> would find branching and merging very hard to get, without\n> understanding the commit DAG. On the other hand, you can explain\n> commit DAG without going into details down to trees and blobs in the\n> earlier section. The user manual has \"understanding reachability\"\n> section early on for this exact reason.\n>\n> [5_creating_new_empty_branches.html]\n>\n> - As I repeatedly said on the list, I do not think teaching this is\n> useful. Multiple roots may happen as a result of pushing (or pulling)\n> from a repository with unrelated root, but it is not something you\n> would want to actively aim for. At least there needs an explanation\n> for the reason why making disjoint roots in the same repository is\n> (sometimes) a good thing to do, and what its downsides are.\n>\n\nThank you for your feedback, I'll try to address both of these points\nas I revise the book.\n\nScott\n"},{"id":"85506","messageId":"d411cc4a0807291234q794344e0oee09f6164286ffd1@mail.gmail.com","threadId":"14739","inReplyTo":"7vwsj4edm1.fsf@gitster.siamese.dyndns.org","subject":"Re: Git Community Book","fromName":"Scott Chacon","fromEmail":"schacon@gmail.com","sentAt":"2008-07-29T19:34:43Z","receivedAt":"2008-07-29T19:34:43Z","isPatch":false,"sender":{"key":"schacon@gmail.com","avatar":"https://gravatar.com/avatar/9b13a8a078e1dcf8588c4eea9554445d51ebed6c41b51f56f4d96738130b05c6?d=mp&s=160"},"body":"On Tue, Jul 29, 2008 at 11:42 AM, Junio C Hamano wrote:\n> \"Scott Chacon\" writes:\n>\n>>>\n>>> There is no license in the source code - what are the copying terms?\n>>>\n>>\n>> I copied in the COPYING file from Git - GPL2.\n>>\n>>> It is maybe somewhat unfortunate that this is in a different format that\n>>> the standard git choice asciidoc, but the formats do look rather similar\n>>> so I assume it should not be hard to even convert from one to another if\n>>> needed.\n>>\n>> I simply didn't want to get asciidoc working locally - it's always\n>> been a bit of a pain to compile (I've heard it referred to more than\n>> once as the only 'nightmare dependancy' in git), and I don't need to\n>> make man pages or anything, so it seemed Markdown would be a better\n>> choice for my output targets. There are a number of good Markdown\n>> interpreters and they're easy to get running.\n>\n> I personally like markdown, but doesn't your refusal to work with existing\n> practices pose a significant problem, unless:\n>\n> (0) you do not consider it a goal to keep the documentation shipped with\n> git and your book in sync; or\n>\n> (1) you have either markdown to asciidoc (or the other way around)\n> converter; the book is written in markdown, and its conversion back\n> to asciidoc is fed to Documentation as patches (or the other way\n> around); or\n>\n> (2) somebody tries to find markdown to manpage, and we convert\n> Documentation/ to markdown.\n>\n> Or is this, \"fork once and borrow reviewer's time, but never be able to\n> contribute back to the original text because the result is so different\"\n> approach?\n>\n\nThe book is basically a fork of all three of the guides I mentioned\n(User Manual and both Tutorials), and with the scope and goals I\ncurrently have in mind, will not be kept in sync - it's just not going\nto be possible. I think in the end, the goals of the texts are so\nvery different that sections it will simply not make sense to try to\nkeep them in sync in some sort of automated fashion. That's one of\nthe reasons why I choose Markdown - I saw no need to use asciidoc, as\nthe book will not be shipped around with Git or built using the same\nprocesses, and I had no need for the advantages of asciidoc in my\nproject. I don't think it makes much sense to have the book be a man\npage at all.\n\nHowever, I will watch the manual and guides and try to incorporate\nchanges to them as appropriate, and I will likely have some updates to\nthem myself as I've been more closely scrutinizing them.\n\nScott\n"},{"id":"85511","messageId":"7vzlo0cvl2.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"d411cc4a0807291234q794344e0oee09f6164286ffd1@mail.gmail.com","subject":"Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-29T19:57:13Z","receivedAt":"2008-07-29T19:57:13Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"Scott Chacon\" writes:\n\n> The book is basically a fork of all three of the guides I mentioned\n> (User Manual and both Tutorials), and with the scope and goals I\n> currently have in mind, will not be kept in sync - it's just not going\n> to be possible. I think in the end, the goals of the texts are so\n> very different that sections it will simply not make sense to try to\n> keep them in sync in some sort of automated fashion. That's one of\n> the reasons why I choose Markdown - I saw no need to use asciidoc, as\n> the book will not be shipped around with Git or built using the same\n> processes, and I had no need for the advantages of asciidoc in my\n> project. I don't think it makes much sense to have the book be a man\n> page at all.\n>\n> However, I will watch the manual and guides and try to incorporate\n> changes to them as appropriate, and I will likely have some updates to\n> them myself as I've been more closely scrutinizing them.\n\nIf that is the approach you decided for your book, I am Ok with that.\n\nNot that you need my blessing to do your own book. It was unclear what\nyour goals were, and if one of the goals were to keep the hassle of\nmaintaining shared materials in both manuals up-to-date, choice of\nmarkdown seemed suboptimal to me, hence my comments.\n\nThanks.\n\n... /me goes back to work after lunch break ...\n"},{"id":"85529","messageId":"alpine.LNX.1.00.0807291716460.19665@iabervon.org","threadId":"14739","inReplyTo":"d411cc4a0807290920p62f5d7e1r727a62ef2b4611fc@mail.gmail.com","subject":"Re: Git Community Book","fromName":"Daniel Barkalow","fromEmail":"barkalow@iabervon.org","sentAt":"2008-07-29T22:34:31Z","receivedAt":"2008-07-29T22:34:31Z","isPatch":false,"sender":{"key":"barkalow@iabervon.org","avatar":"https://avatars.githubusercontent.com/u/55364219?v=4"},"body":"On Tue, 29 Jul 2008, Scott Chacon wrote:\n\n> So I wanted to develop a really nice, easy to follow book for Git\n> newcomers to learn git quickly and easily. One of the issues I\n> remember having when learning Git is that there is a lot of great\n> material in the User Guide, Tutorial, Tutorial 2, Everyday Git, etc -\n> but they're all huge long documents that are sometimes difficult to\n> come back to and remember where you were, and I didn't know which one\n> to start with or where to find what I was looking for, etc.\n\nIt would be good to include stuff from \nhttp://eagain.net/articles/git-for-computer-scientists/\n\nMaybe only in inspiration, since it doesn't have an obvious license and \nit's stylisticly more technical. But it would be nice to have diagrams of \n\"this is what git thinks of as history\", possibly even arranging them like \ngitk shows things (older downward, refs pointing in from the side).\n\nIn particular, I think it's really useful to show a commit graph with \nbranching and merging, and introduce refs as movable pointers to commits \nin the graph, and local branches as refs that you move and tracking refs \nas refs that copy values in other repositories.\n\nI think you can even gloss of details of blobs and trees because they \npretty much work just like files and directories in a filesystem (except \nthat they take up much less storage in large quantities than you'd think). \nThe only potentially interesting things are (1) a blob names the inode, \nnot the dentry, so it's the file contents, not the name, mode, etc; and \n(2) the permission bits are just 'x', we've got symlinks, there are no \nowner/group or other attributes and \"see also Submodules\".\n\nBut I think that the section:\n http://eagain.net/articles/git-for-computer-scientists/#history\nshould have an equivalent in any git documentation that can have diagrams, \nand introducing a history diagram style early means that you can do a \nbunch of simple pictures to explain operations like \"git checkout -b foo\" \nor \"git reset --hard HEAD^^\" or \"git checkout origin/master\".\n\n\t-Daniel\n*This .sig left intentionally blank*\n"},{"id":"85532","messageId":"7v1w1cb940.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"alpine.LNX.1.00.0807291716460.19665@iabervon.org","subject":"Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-29T22:47:59Z","receivedAt":"2008-07-29T22:47:59Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Daniel Barkalow writes:\n\n> In particular, I think it's really useful to show a commit graph with \n> branching and merging, and introduce refs as movable pointers to commits \n> in the graph, and local branches as refs that you move and tracking refs \n> as refs that copy values in other repositories.\n\nI'd very strongly second this. If somebody is really into screencasts\n(and especially from the Ruby circle, I would guess), this may be worth\na look:\n\n http://excess.org/article/2008/07/ogre-git-tutorial/\n\nI saw a couple of technical inaccuracies in the presentation (I do not\nexpect any presentation or screencast to be perfect; I've never seen one\nwithout any technical error anyway, perhaps other than my own at OLS a few\nyears ago), but otherwise it was very well done. Espcially the part that\nbuilds the commit ancestry chains I was very happy to see it taught like\nso.\n"},{"id":"85613","messageId":"20080730132044.GF17649@jukie.net","threadId":"14739","inReplyTo":"7v1w1cb940.fsf@gitster.siamese.dyndns.org","subject":"Re: Git Community Book","fromName":"Bart Trojanowski","fromEmail":"bart@jukie.net","sentAt":"2008-07-30T13:20:45Z","receivedAt":"2008-07-30T13:20:45Z","isPatch":false,"sender":{"key":"bart@jukie.net","avatar":"https://avatars.githubusercontent.com/u/6721?v=4"},"body":"* Junio C Hamano [080729 18:48]:\n> I'd very strongly second this. If somebody is really into screencasts\n> (and especially from the Ruby circle, I would guess), this may be worth\n> a look:\n> \n> http://excess.org/article/2008/07/ogre-git-tutorial/\n\nThank you very much for the plug, Junio.\n\n> I saw a couple of technical inaccuracies in the presentation (I do not\n> expect any presentation or screencast to be perfect; I've never seen one\n> without any technical error anyway, perhaps other than my own at OLS a few\n> years ago)\n\nCould you let me know what the biggest inaccuracies were? I would like\nto correct my mistakes and update the slides.\n\nCheers,\n-Bart\n\n-- \n\t\t\t\tWebSig: http://www.jukie.net/~bart/sig/\n"},{"id":"85614","messageId":"alpine.LSU.1.00.0807301514280.3486@wbgn129.biozentrum.uni-wuerzburg.de","threadId":"14739","inReplyTo":"Pine.LNX.4.64.0807291957410.1779@reaper.quantumfyre.co.uk","subject":"markdown 2 man, was Re: Git Community Book","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2008-07-30T13:27:38Z","receivedAt":"2008-07-30T13:27:38Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi,\n\nOn Tue, 29 Jul 2008, Julian Phillips wrote:\n\n> there does exist at least one tool that claims to be able\n> to convert from markdown to man: http://johnmacfarlane.net/pandoc/\n\nJust want to mention that it is written in Haskell, so chances are that it \nis even harder to install than asciidoc (I am thinking about non-Linux, \nof course).\n\nNote also that Markdown cannot create TOCs automatically, AFAICT. So \nprobably it would be not all that easy to convert the User Manual to that \nformat.\n\nIf at all, I would have preferred a format switch to Wiki syntax so that \nwe can use the same source on the Git wiki as in our Documentation/ \ndirectory. But such a switch could only come after a consensus of the \nCommunity anyway.\n\nCiao,\nDscho\n"},{"id":"85616","messageId":"20080730133138.GG17649@jukie.net","threadId":"14739","inReplyTo":"7v1w1cb940.fsf@gitster.siamese.dyndns.org","subject":"Re: Git Community Book","fromName":"Bart Trojanowski","fromEmail":"bart@jukie.net","sentAt":"2008-07-30T13:31:38Z","receivedAt":"2008-07-30T13:31:38Z","isPatch":false,"sender":{"key":"bart@jukie.net","avatar":"https://avatars.githubusercontent.com/u/6721?v=4"},"body":"* Junio C Hamano [080729 18:48]:\n> I'd very strongly second this. If somebody is really into screencasts\n> (and especially from the Ruby circle, I would guess), this may be worth\n> a look:\n> \n> http://excess.org/article/2008/07/ogre-git-tutorial/\n\nBTW, if anyone is interested in the SVGs used for the slides...\n\n git clone git://tachyon.jukie.net/intro-to-git.git/\n\nYou will need inkscape and latex-beamer to build the PDF.\n\nFeel free to use them as you wish with attribution. Although my may\nwant to wait till I fix the mistakes that Junio mentioned.\n\n-Bart\n\n-- \n\t\t\t\tWebSig: http://www.jukie.net/~bart/sig/\n"},{"id":"85659","messageId":"7v3alr6xe2.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"20080730132044.GF17649@jukie.net","subject":"Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-30T18:27:01Z","receivedAt":"2008-07-30T18:27:01Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bart Trojanowski writes:\n\n> Could you let me know what the biggest inaccuracies were? I would like\n> to correct my mistakes and update the slides.\n\nThe one I offhand can recall was in your spoken part not on slides (\"git\nadd -u\" does not notice new files but does notice removed ones). Nothing\nmajor, really.\n"},{"id":"85673","messageId":"7vy73j418t.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"alpine.LSU.1.00.0807301514280.3486@wbgn129.biozentrum.uni-wuerzburg.de","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-30T19:32:02Z","receivedAt":"2008-07-30T19:32:02Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin writes:\n\n> Note also that Markdown cannot create TOCs automatically, AFAICT. So \n> probably it would be not all that easy to convert the User Manual to that \n> format.\n\nThe use of markdown may mean updates to the User Manual won't be merged\nback to his book without effort and manual porting on his side, and the\nside porting in the other direction has the same issue as well, but the\ncontents and the way materials are presented will be vastly different in\nfuture versions anyway; not being able to side-port new material verbatim\nmay not be an issue. Discussion with Scott seems to suggest that the\noverall philosophy of his book is \"this is a different book targetted for\ndifferent audiences; its initial text happens to heavily borrow from the\nexisting documents but expected to become vastly improved\", in other\nwords, fork-and-never-return.\n\nThat's one valid approach. I or you might have taken a different avenue,\nbut after all, it's his book, not mine, not yours, nor git list's book.\n\nAs I am not in \"graphics and screencast\" camp, I may probably not be able\nto offer much help improving his book, and I suspect some people on this\nlist might feel the same way. But that's is Ok --- we are not dumping the\nUser Manual.\n\nWe originally hoped (well, at least I did) that Scott's effort on his book\nmight help us in improving the User Manual as well, but the approach seems\nto make it unlikely. But that is nothing to hold against him --- he is\ndoing his own thing in a way he feels is the best, and that's perfectly\nfine. We lost nothing, perhaps except for a chance to cooperate a bit\nbetter and to widen the community.\n\n> If at all, I would have preferred a format switch to Wiki syntax so that \n> we can use the same source on the Git wiki as in our Documentation/ \n> directory.\n\nYeah, that's also true. I seem to recall markdown was used in ikiwiki?\n"},{"id":"85693","messageId":"20080730213918.GD19117@fieldses.org","threadId":"14739","inReplyTo":"d411cc4a0807291130p228f77d5r1f390090ec29aef4@mail.gmail.com","subject":"Re: Git Community Book","fromName":"J. Bruce Fields","fromEmail":"bfields@fieldses.org","sentAt":"2008-07-30T21:39:18Z","receivedAt":"2008-07-30T21:39:18Z","isPatch":false,"sender":{"key":"bfields@citi.umich.edu","avatar":null},"body":"> > So my confusion still is - where does this stand wrt. the user manual?\n> > Why didn't you just start with the manual and work on that? I thought\n> > you were planning to do that, but apparently we misunderstood each other\n> > in the last mails.\n> >\nOn Tue, Jul 29, 2008 at 11:30:55AM -0700, Scott Chacon wrote:\n> \n> I was originally planning on doing that, but the problem is the\n> graphics, diagrams and screencasts. Unless I am mistaken, there is\n> not a single outside media reference in any of these guides - the\n> diagrams that are there are all ascii drawings. I'm assuming there is\n> a reason for that. If I wanted to add images and screencast embeds\n> into the guide, how would that work?\n> \n\nYeah, some possible obstacles:\n\n\t- Size: People probably won't want large binary blobs added to\n\t the git repository.\n\t- Editability: We want to be able to keep the materials up to\n\t date and accurate.\n\t- Source readability: the current documentation can all be read\n\t in place without doing a build.\n\t- Build requirements: I seem to recall complaints about the\n\t toolchain required to build the existing documentation.\n\nAt least for simple diagrams it might be possible to solve most of those\nproblems with an appropriate diagram-description-language that could be\ncompiled into image files. Screencasts are probably totally out,\nthough.\n\nIn cases where you do find you're working with the same material, any\nimprovements you could contribute back to the in-tree documentation\nwould of course be appreciated.\n\n> Well, that's what the point of this is - to ask everyone to help me\n> review it, and possibly help me add to it. The user manual is great,\n> but even I don't reference it very often because I find it difficult\n> to find content in it I need quickly.\n\nIf you had notes on any particular examples (I looked for X in place Y,\nthen place Z, and finally found it where I least expected it in place\nQ...), they'd be appreciated.\n\n> The specific order I choose is very different from the User Guide and\n> is likely to bother a number of people, which you mentioned (and I'm\n> sure Dscho will _hate_) because I introduce the object model at the\n> beginning. (I'm still working on that section, trying to simplify it\n> and add in some other diagrams and a short screencast I have that I\n> think will be helpful) This is because I have had a lot of positive\n> feedback that primary frustration from people comes from them thinking\n> of Git as a super-better Subversion.\n>\n> I would venture to say that\n> _most_ of the users coming to Git now are currently fluent in\n> Subversion. Even if they are from Perforce or CVS (the other two ones\n> I will occasionally run into), their mental model of what an SCM does\n> is the same - delta storage. I've found that by ridding them of that\n> notion off the bat, they have _far_ fewer problems and frustrations\n> with Git than when I just try to show them the first 10 commands in\n> sort of a cookbook style. It's not a complicated model, it doesn't\n> take long to teach, and in _my personal_ experience (which is not to\n> say it's necessarily correct), it helps people the most in picking it\n> up and really loving the tool.\n\nI've considered doing the same for the user manual, actually, for some\nof the same reasons--my main concern would be that it be done very\nquickly, so as not to make people feel like it was a big obstacle on\ntheir way to actually doing what they need to do.\n\nSo, anyway, that's to say that suggestions for reorganization of the\nin-tree documentation (as opposed to just smaller-scale fixes) would\nalso be welcomed....\n\n--b.\n\n> \n> The book is built so that it is just as easy to start in the 'Basic\n> Usage' section and go back later, but if you're going to sit down and\n> just start reading, I think it would be better to explain why Git is\n> different at a fundamental level right off the bat.\n> \n> Scott\n> --\n> To unsubscribe from this list: send the line \"unsubscribe git\" in\n> the body of a message to majordomo@vger.kernel.org\n> More majordomo info at http://vger.kernel.org/majordomo-info.html\n"},{"id":"85711","messageId":"B7697630-DF9C-4EF0-9D63-9E362CEE125B@wincent.com","threadId":"14739","inReplyTo":"7vy73j418t.fsf@gitster.siamese.dyndns.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Wincent Colaiuta","fromEmail":"win@wincent.com","sentAt":"2008-07-30T23:48:02Z","receivedAt":"2008-07-30T23:48:02Z","isPatch":false,"sender":{"key":"greg@hurrell.net","avatar":"https://avatars.githubusercontent.com/u/7074?v=4"},"body":"El 30/7/2008, a las 21:32, Junio C Hamano escribió:\n\n> That's one valid approach. I or you might have taken a different \n> avenue,\n> but after all, it's his book, not mine, not yours, nor git list's \n> book.\n\nFunnily enough, he chose to title it the \"Git Community Book\". Hard to \nmatch Scott's enthusiasm; this is the second major initiative we've \nseen from him in the last few days (the other being git-scm.com \nitself) which to the casual onlooker might look like the \"official\" \nGit homepage and documentation, but in both cases development occurred \nbehind the scenes and the list was only notified after the fact. \nBetter late than never I suppose.\n\n> We originally hoped (well, at least I did) that Scott's effort on \n> his book\n> might help us in improving the User Manual as well, but the approach \n> seems\n> to make it unlikely. But that is nothing to hold against him --- he \n> is\n> doing his own thing in a way he feels is the best, and that's \n> perfectly\n> fine. We lost nothing, perhaps except for a chance to cooperate a bit\n> better and to widen the community.\n\nEven though there might not be an automated way to get changes back \nfrom the fork, if there are clear improvements made then there is at \nleast no legal obstacle to incorporating them back in, the only \nobstacle would be time and willingness to do so manually.\n\n>\nCheers,\nWincent\n"},{"id":"85716","messageId":"d411cc4a0807301713o6b1fd2e8lde0636352f8f1c5b@mail.gmail.com","threadId":"14739","inReplyTo":"B7697630-DF9C-4EF0-9D63-9E362CEE125B@wincent.com","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Scott Chacon","fromEmail":"schacon@gmail.com","sentAt":"2008-07-31T00:13:43Z","receivedAt":"2008-07-31T00:13:43Z","isPatch":false,"sender":{"key":"schacon@gmail.com","avatar":"https://gravatar.com/avatar/9b13a8a078e1dcf8588c4eea9554445d51ebed6c41b51f56f4d96738130b05c6?d=mp&s=160"},"body":"On Wed, Jul 30, 2008 at 4:48 PM, Wincent Colaiuta wrote:\n> El 30/7/2008, a las 21:32, Junio C Hamano escribió:\n>\n>> That's one valid approach. I or you might have taken a different avenue,\n>> but after all, it's his book, not mine, not yours, nor git list's book.\n>\n> Funnily enough, he chose to title it the \"Git Community Book\". Hard to match\n> Scott's enthusiasm; this is the second major initiative we've seen from him\n> in the last few days (the other being git-scm.com itself) which to the\n> casual onlooker might look like the \"official\" Git homepage and\n> documentation, but in both cases development occurred behind the scenes and\n> the list was only notified after the fact. Better late than never I suppose.\n\nNot sure what else I could have done - I announced that I was starting\na documentation project like this about a week ago on this list, then\nI started the book 3 days ago\n(http://github.com/schacon/gitscm/commits/book) and announced it here\nfor initial review yesterday. I haven't told very many people about\nit yet and I haven't linked to it from git-scm.com yet either. It's\nbeen open source from the first minute on GitHub, and the link to the\nsource was on the website I posted here.\n\nSame for the git-scm site - I started it on the 23rd and emailed Pasky\nabout it the next day, and the day after that he began submitting\npatches to me for it and I announced it on this list. Am I missing\nsomething here? Do you think I've been working on these secretly for\nmonths, or something? If there is a better communication workflow, I\nwould be happy to do so.\n\nI appreciate that you notice my enthusiasm, though. :)\n\nScott\n\n\n\n>> We originally hoped (well, at least I did) that Scott's effort on his book\n>> might help us in improving the User Manual as well, but the approach seems\n>> to make it unlikely. But that is nothing to hold against him --- he is\n>> doing his own thing in a way he feels is the best, and that's perfectly\n>> fine. We lost nothing, perhaps except for a chance to cooperate a bit\n>> better and to widen the community.\n>\n> Even though there might not be an automated way to get changes back from the\n> fork, if there are clear improvements made then there is at least no legal\n> obstacle to incorporating them back in, the only obstacle would be time and\n> willingness to do so manually.\n>\n>>\n> Cheers,\n> Wincent\n>\n>\n"},{"id":"85718","messageId":"7v3alq520e.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"B7697630-DF9C-4EF0-9D63-9E362CEE125B@wincent.com","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-07-31T00:30:09Z","receivedAt":"2008-07-31T00:30:09Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Wincent Colaiuta writes:\n\n> Funnily enough, he chose to title it the \"Git Community Book\". Hard to \n> match Scott's enthusiasm; this is the second major initiative we've \n> seen from him in the last few days (the other being git-scm.com \n> itself) which to the casual onlooker might look like the \"official\" \n> Git homepage and documentation, but in both cases development occurred \n> behind the scenes and the list was only notified after the fact. \n\nI think your \"Behind the scenes, after the fact\" is being unnecessarily\nharsh.\n\nWhat counts is what happens now after the launch, when there are issues\nidentified that he could address on his side if he wanted to work with the\ncommunity. \"Ignore and fork forever\" may be to further fracture the\ncommunity, but for a book like his that has quite different aim than the\nofficial manual set, it might be a sensible approach. You have to weigh\nthe pros and cons.\n\nWe've seen other comments raised to both the book and the git-scm.com site\non this list after they were announced. We'll see how they are addressed\nin coming weeks. I think it is not too late to voice your negative\njudgements only after seeing what happens.\n"},{"id":"85766","messageId":"4891A0D0.6060503@lyx.org","threadId":"14739","inReplyTo":"7vy73j418t.fsf@gitster.siamese.dyndns.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Abdelrazak Younes","fromEmail":"younes@lyx.org","sentAt":"2008-07-31T11:24:00Z","receivedAt":"2008-07-31T11:24:00Z","isPatch":false,"sender":{"key":"younes@lyx.org","avatar":null},"body":"Hello,\n\nSorry for this irruption on this list. I am just a git user and casual \nreader of this list. I thought I could share my thoughts about this as I \nknow a bit about document creation. Please ignore if this is not \nappropriate.\n\nDisclaimer: I am involved in LyX development, so anything I said will be \nbiased :-)\n\nJunio C Hamano wrote:\n> As I am not in \"graphics and screencast\" camp, I may probably not be able\n> to offer much help improving his book, and I suspect some people on this\n> list might feel the same way. But that's is Ok --- we are not dumping the\n> User Manual.\n\nIMHO, documentation is best written by users, not developer. So, again \nIMHO, anything that could accommodate the _user_ for document writing \nshould be done. An enthusiastic user is more likely to spend time \nwriting documentation than a developer. For example, within the LyX \nproject, most writers and translator are not developer.\n\nAsciidoc or Markdown are tools that accommodate the _developer_, not the \nuser. I understand that these markup language are ideally suited for in \nsource documentation (thought I personally much prefer Doxygen). I also \nunderstand that launching a different application just to modify a line \nor two in the user manual seems cumbersome for the developer but IMHO, \nif you're serious about working on the documentation, you are not going \nto change a line or two and launching an external application is no big \ndeal.\n\nNow, about my shameless plug: LyX is ideally suited for structured \ndocumentation writing :-)\n\nAbdel.\n"},{"id":"85776","messageId":"20080731130101.GC18106@leksak.fem-net","threadId":"14739","inReplyTo":"4891A0D0.6060503@lyx.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Stephan Beyer","fromEmail":"s-beyer@gmx.net","sentAt":"2008-07-31T13:01:01Z","receivedAt":"2008-07-31T13:01:01Z","isPatch":false,"sender":{"key":"s-beyer@gmx.net","avatar":"https://avatars.githubusercontent.com/u/143889?v=4"},"body":"Hi,\n\nAbdelrazak Younes wrote:\n> Please ignore if this is not appropriate.\n\nWell, so I should've ignored, but I think this is worth some correction.\n\n> Asciidoc or Markdown are tools that accommodate the _developer_, not the \n> user. I understand that these markup language are ideally suited for in \n> source documentation (thought I personally much prefer Doxygen).\n\nhttp://www.methods.co.nz/asciidoc/ says\n ``AsciiDoc is a text document format for writing short documents,\n articles, books and UNIX man pages. AsciiDoc files can be translated to\n HTML and DocBook markups using the asciidoc(1) command.''\n\nhttp://daringfireball.net/projects/markdown/ says\n ``Markdown is a text-to-HTML conversion tool for web writers. Markdown\n allows you to write using an easy-to-read, easy-to-write plain text\n format, then convert it to structurally valid XHTML (or HTML).''\n\nSo those are not suited for in-source documentation.\n\nThey're \"lightweight\" markup for documentation, very easy to read and somehow\neasy to write for non-developers.\nThe user manual can give you an impression:\n\thttp://repo.or.cz/w/git.git?a=blob;f=Documentation/user-manual.txt\n\nI think, this is easier than LyX for users and developers..\n\nRegards,\n Stephan\n\n-- \nStephan Beyer , PGP 0x6EDDD207FCC5040F\n"},{"id":"85781","messageId":"4891C8A1.7040203@lyx.org","threadId":"14739","inReplyTo":"20080731130101.GC18106@leksak.fem-net","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Abdelrazak Younes","fromEmail":"younes@lyx.org","sentAt":"2008-07-31T14:13:53Z","receivedAt":"2008-07-31T14:13:53Z","isPatch":false,"sender":{"key":"younes@lyx.org","avatar":null},"body":"Stephan Beyer wrote:\n> Hi,\n>\n> Abdelrazak Younes wrote:\n> \n>> Please ignore if this is not appropriate.\n>> \n>\n> Well, so I should've ignored, but I think this is worth some correction.\n> \nThanks for the corrections :-)\n\n> They're \"lightweight\" markup for documentation, very easy to read and somehow\n> easy to write for non-developers.\n> The user manual can give you an impression:\n> \thttp://repo.or.cz/w/git.git?a=blob;f=Documentation/user-manual.txt\n>\n> I think, this is easier than LyX for users and developers..\n> \n\nWell, easier for short document writing maybe, better suited I don't \nthink so, at least if you want to keep track of contents, structure, \nlinks, references, citations, etc. Bug again this is IMHO.\n\nAbdel.\n"},{"id":"85782","messageId":"4891CD34.1070308@lyx.org","threadId":"14739","inReplyTo":"20080731130101.GC18106@leksak.fem-net","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Abdelrazak Younes","fromEmail":"younes@lyx.org","sentAt":"2008-07-31T14:33:24Z","receivedAt":"2008-07-31T14:33:24Z","isPatch":false,"sender":{"key":"younes@lyx.org","avatar":null},"body":"Stephan Beyer wrote:\n> They're \"lightweight\" markup for documentation, very easy to read and somehow\n> easy to write for non-developers.\n> The user manual can give you an impression:\n> \thttp://repo.or.cz/w/git.git?a=blob;f=Documentation/user-manual.txt\n>\n> I think, this is easier than LyX for users and developers..\n\nI just had a look at the user manual and, well unless you have a special \nemacs mode or whatever that can automate the markup tag insertion, I \nwonder how can anybody think that writing with this markup language is \neasier than within LyX, really (genuine question, not sarcasm).\n\nAbdel.\n"},{"id":"85785","messageId":"20080731150958.GO32057@genesis.frugalware.org","threadId":"14739","inReplyTo":"4891CD34.1070308@lyx.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Miklos Vajna","fromEmail":"vmiklos@frugalware.org","sentAt":"2008-07-31T15:09:58Z","receivedAt":"2008-07-31T15:09:58Z","isPatch":false,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Thu, Jul 31, 2008 at 04:33:24PM +0200, Abdelrazak Younes wrote:\n> I just had a look at the user manual and, well unless you have a special \n> emacs mode or whatever that can automate the markup tag insertion, I wonder \n> how can anybody think that writing with this markup language is easier than \n> within LyX, really (genuine question, not sarcasm).\n\nPeople usually find it easy to contribute to a wiki, due to its easy\nmarkup language.\n\nasciidoc's markup is configurable, but the default one is really similar\nto a wiki syntax, so at the end, people find it easy, including myself.\n"},{"id":"85787","messageId":"4891DA49.2070407@lyx.org","threadId":"14739","inReplyTo":"20080731150958.GO32057@genesis.frugalware.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Abdelrazak Younes","fromEmail":"younes@lyx.org","sentAt":"2008-07-31T15:29:13Z","receivedAt":"2008-07-31T15:29:13Z","isPatch":false,"sender":{"key":"younes@lyx.org","avatar":null},"body":"Hi Miklos,\n\nMiklos Vajna wrote:\n> On Thu, Jul 31, 2008 at 04:33:24PM +0200, Abdelrazak Younes wrote:\n> \n>> I just had a look at the user manual and, well unless you have a special\n>> emacs mode or whatever that can automate the markup tag insertion, I wonder\n>> how can anybody think that writing with this markup language is easier than\n>> within LyX, really (genuine question, not sarcasm).\n>> \n>\n> People usually find it easy to contribute to a wiki, due to its easy\n> markup language.\n> \n\nI understand that but my point is that writing a book or a manual is too \nbig a task for a wiki.\n\nAnyway, if there is an interest to switch to LyX for the user manual, \njust let me know. Ascii has a LateX backend* and LyX can import LateX so \nthe task should be easy.\n\n* http://www.methods.co.nz/asciidoc/latex-backend.html\n\nThanks for answering :-)\nAbdel.\n"},{"id":"85797","messageId":"20080731190034.GP32057@genesis.frugalware.org","threadId":"14739","inReplyTo":"4891DA49.2070407@lyx.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Miklos Vajna","fromEmail":"vmiklos@frugalware.org","sentAt":"2008-07-31T19:00:34Z","receivedAt":"2008-07-31T19:00:34Z","isPatch":false,"sender":{"key":"vmiklos@frugalware.org","avatar":"https://gravatar.com/avatar/401c1cbbb3a5d13e650c691a2c71d6fd0b80df1a01bc74d9f1972675dd58f2bd?d=mp&s=160"},"body":"On Thu, Jul 31, 2008 at 05:29:13PM +0200, Abdelrazak Younes wrote:\n> I understand that but my point is that writing a book or a manual is too \n> big a task for a wiki.\n\nThat's probably subjective. There is http://wikibooks.org/, after all.\n;-)\n\n> Anyway, if there is an interest to switch to LyX for the user manual, just \n> let me know. Ascii has a LateX backend* and LyX can import LateX so the \n> task should be easy.\n> \n> * http://www.methods.co.nz/asciidoc/latex-backend.html\n\nLast time I checked it was actually broken, but dblatex can transform\nasciidoc's docbook output to latex, if that's really wished.\n"},{"id":"85823","messageId":"20080731225703.7be6f76e@neuron","threadId":"14739","inReplyTo":"4891A0D0.6060503@lyx.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Jan Krüger","fromEmail":"jk@jk.gs","sentAt":"2008-07-31T20:57:03Z","receivedAt":"2008-07-31T20:57:03Z","isPatch":false,"sender":{"key":"jk@jk.gs","avatar":"https://avatars.githubusercontent.com/u/1774?v=4"},"body":"Hi,\n\n> Disclaimer: I am involved in LyX development, so anything I said will\n> be biased :-)\n\nI think that's fine since I consider LaTeX (and therefore LyX as the\nbest graphical editor for it that I know) a choice always worth\nconsidering when it comes to projects that have the size of a book.\n\n> Now, about my shameless plug: LyX is ideally suited for structured \n> documentation writing :-)\n\nThat may well be, but it gets really complicated once you want to\nget your document into other markup-based formats while preserving all\nthe important aspects of formatting. I know this because I started\nusing LaTeX for a project that was supposed to be available in HTML\nform along with, say, PDF. I've found that the only converter that\ncomes close to being useful for somewhat more ambitious sources\n(including, perhaps, custom environments and stuff like that) without\nspending a ridiculous amount of time trying to understand it is hevea.\nOf course, hevea only translates to HTML, so, for example, generating\nmanpages or plain text is an entirely different matter of considerable\ndifficulty.\n\nIn addition to that, I suspect that LyX files might be difficult to\ndeal with in forky Git situations. For example, what if two\nseparately contributed patches need merging into a LyX source file?\nThis will only work automatically if the LyX source, treated as plain\ntext, has a really low chance of randomly changing in other places than\nwhat the patch is supposed to touch. Also, if a merge does cause a\nconflict, I imagine it would be difficult to resolve that.\n\nFinally, it's pretty much a given that Git's manpages continue to use\nAsciiDoc because there are few other things that can generate actual\nmanpages. I'm not sure it would be a good idea to keep half of Git's\ndocumentation in one format and the rest in another. And AsciiDoc is --\nby far! -- not the worst choice. I'm tempted to say it's the best that\nI know.\n\n-Jan\n"},{"id":"85846","messageId":"7vvdylv9zq.fsf@gitster.siamese.dyndns.org","threadId":"14739","inReplyTo":"4891CD34.1070308@lyx.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2008-08-01T00:45:29Z","receivedAt":"2008-08-01T00:45:29Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Abdelrazak Younes writes:\n\n> I just had a look at the user manual and, well unless you have a\n> special emacs mode or whatever that can automate the markup tag\n> insertion, I wonder how can anybody think that writing with this\n> markup language is easier than within LyX, really (genuine question,\n> not sarcasm).\n\nHow greppable and \"log -p\"-able is the documentation written in LyX?\n\n * Where in the documentation do I have to change the description of\n \"--parents\" option?\n\n * When did the description of \"--cc\" for diff families last changed, by\n whom and why?\n\nEas of doing these is mostly why we chose AsciiDoc to begin with. Any\nalternative you are going to suggest should not make these two things\nimpossible or very harder to do.\n"},{"id":"85866","messageId":"4892B714.8010401@lyx.org","threadId":"14739","inReplyTo":"7vvdylv9zq.fsf@gitster.siamese.dyndns.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Abdelrazak Younes","fromEmail":"younes@lyx.org","sentAt":"2008-08-01T07:11:16Z","receivedAt":"2008-08-01T07:11:16Z","isPatch":false,"sender":{"key":"younes@lyx.org","avatar":null},"body":"Junio C Hamano wrote:\n> Abdelrazak Younes writes:\n>\n> \n>> I just had a look at the user manual and, well unless you have a\n>> special emacs mode or whatever that can automate the markup tag\n>> insertion, I wonder how can anybody think that writing with this\n>> markup language is easier than within LyX, really (genuine question,\n>> not sarcasm).\n>> \n>\n> How greppable and \"log -p\"-able is the documentation written in LyX?\n> \n\nLyX format is plain text, loosely based on LateX. Here's attached a \nsample .lyx file FYI. We have one tag per line and a maximum of 80 char \nper line so that the format is easily parsable. Advanced users often use \nunix tools (grep, sed, etc) to modify the .lyx file manually.\n\n> * Where in the documentation do I have to change the description of\n> \"--parents\" option?\n> \n\nYou mean in a text editor, not within LyX? Just look for the string :-)\n\n> * When did the description of \"--cc\" for diff families last changed, by\n> whom and why?\n> \n\nDitto.\n\n> Eas of doing these is mostly why we chose AsciiDoc to begin with. Any\n> alternative you are going to suggest should not make these two things\n> impossible or very harder to do.\n> \n\nIf you ignore the LyX tags, you can just do what you are used to do \nwithout problem using a plain text editor. If you want to do something \nmore complicated stuff like choosing a different environment or creating \na nested enumerate list, it is easier to do that within LyX.\n\nAbdel.\n\n"},{"id":"85872","messageId":"4892C042.20302@lyx.org","threadId":"14739","inReplyTo":"20080731225703.7be6f76e@neuron","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Abdelrazak Younes","fromEmail":"younes@lyx.org","sentAt":"2008-08-01T07:50:26Z","receivedAt":"2008-08-01T07:50:26Z","isPatch":false,"sender":{"key":"younes@lyx.org","avatar":null},"body":"Hi Jan,\n\nJan Krüger wrote:\n>> Now, about my shameless plug: LyX is ideally suited for structured\n>> documentation writing :-)\n>\n> That may well be, but it gets really complicated once you want to\n> get your document into other markup-based formats while preserving all\n> the important aspects of formatting. I know this because I started\n> using LaTeX for a project that was supposed to be available in HTML\n> form along with, say, PDF. I've found that the only converter that\n> comes close to being useful for somewhat more ambitious sources\n> (including, perhaps, custom environments and stuff like that) without\n> spending a ridiculous amount of time trying to understand it is hevea.\n\nI had good success with htlatex (the default converter within LyX). I \njust modified the css and was done with it. All cross-references etc \nwere correctly handled.\n\n> Of course, hevea only translates to HTML, so, for example, generating\n> manpages or plain text is an entirely different matter of considerable\n> difficulty.\n\nLyX has an excellent plain text export. You can use the export method of \nLyX at the command line without launching it graphically by the way. You \ndon't even need an X server, just use 'lyx -e text mydocument.lyx'\n\nFor man page, LyX does not support it natively I'm afraid, but I guess \nthere are LateX to man converter, aren't there?\n\n> In addition to that, I suspect that LyX files might be difficult to\n> deal with in forky Git situations. For example, what if two\n> separately contributed patches need merging into a LyX source file?\n> This will only work automatically if the LyX source, treated as plain\n> text, has a really low chance of randomly changing in other places than\n> what the patch is supposed to touch. Also, if a merge does cause a\n> conflict, I imagine it would be difficult to resolve that.\n\nNot really. As I said to Junio, .lyx files are using a plain text utf8 \nformat. They are easily mergeable as LyX preserves the structure of the \nfile: if the two collaborators modify two different parts of the \ndocument there is basically zero chance to have a conflict. On the rare \noccasion where I had a conflict with svn, it was very easy to solve \nmanually by removing the conflict tags inserted by svn. With git, I \nnever had a single conflict ;-)\n\n> Finally, it's pretty much a given that Git's manpages continue to use\n> AsciiDoc because there are few other things that can generate actual\n> manpages. I'm not sure it would be a good idea to keep half of Git's\n> documentation in one format and the rest in another.\n\nThat's a good argument. My personal opinion is that users prefer to use \n'-help' for short help and to read the tutorial or the user guide for \nmore in-depth information. I never use man personally... OK, that's \nprobably because I use Windows :-)\n\n> And AsciiDoc is --\n> by far! -- not the worst choice. I'm tempted to say it's the best that\n> I know.\n\nAsciiDoc is indeed excellent if you want to write in a plain text \neditor. But LyX is easier to use and more porwerful :-)\n\nThanks,\nAbdel\n"},{"id":"85880","messageId":"200808011146.29883.trast@student.ethz.ch","threadId":"14739","inReplyTo":"4892B714.8010401@lyx.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Thomas Rast","fromEmail":"trast@student.ethz.ch","sentAt":"2008-08-01T09:46:26Z","receivedAt":"2008-08-01T09:46:26Z","isPatch":false,"sender":{"key":"tr@thomasrast.ch","avatar":"https://avatars.githubusercontent.com/u/153510?v=4"},"body":"You wrote:\n> Junio C Hamano wrote:\n> >\n> > How greppable and \"log -p\"-able is the documentation written in LyX?\n> \n> LyX format is plain text, loosely based on LateX. Here's attached a \n> sample .lyx file FYI. We have one tag per line and a maximum of 80 char \n> per line so that the format is easily parsable. Advanced users often use \n> unix tools (grep, sed, etc) to modify the .lyx file manually.\n\nIs it just me or is the format very hard to read? For example, line\n492ff spells a list of quoted items as\n\n \\begin_layout Standard\n Generally, you would send email to lyx-foo-subscribe@lists.lyx.org to subscribe\n to these lists or to lyx-foo-unsubscribe@lists.lyx.org to unsubscribe, where\n \n \\begin_inset Quotes eld\n \\end_inset\n\n foo\n \\begin_inset Quotes erd\n \\end_inset\n\n is one of \n \\begin_inset Quotes eld\n \\end_inset\n\n announce\n \\begin_inset Quotes erd\n \\end_inset\n\netc. Of course I can \"parse\" the language, but my untrained eye is\nunable to fluently read the text hiding behind it.\n\nAlso, if I made a commit changing the \"announce\", you would have to\nturn up diff context to at least 13 lines to get any _semantic_\ncontext of the change.\n\n- Thomas\n\n"},{"id":"85884","messageId":"4892E332.5060804@lyx.org","threadId":"14739","inReplyTo":"200808011146.29883.trast@student.ethz.ch","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Abdelrazak Younes","fromEmail":"younes@lyx.org","sentAt":"2008-08-01T10:19:30Z","receivedAt":"2008-08-01T10:19:30Z","isPatch":false,"sender":{"key":"younes@lyx.org","avatar":null},"body":"Thomas Rast wrote:\n> You wrote:\n> \n>> Junio C Hamano wrote:\n>> \n>>> How greppable and \"log -p\"-able is the documentation written in LyX?\n>>> \n>> LyX format is plain text, loosely based on LateX. Here's attached a\n>> sample .lyx file FYI. We have one tag per line and a maximum of 80 char\n>> per line so that the format is easily parsable. Advanced users often use\n>> unix tools (grep, sed, etc) to modify the .lyx file manually.\n>> \n>\n> Is it just me or is the format very hard to read? For example, line\n> 492ff spells a list of quoted items as\n> \n\nRight, quote is a special case in lyx format because we have to take \ncare of locale differences. So, as you guessed, quotes are not really \nwritten with the ascii quote character. But the format is not that hard \nin general. If needed, I could modify this special case so that it's \neasier to read though.\nDon't get me wrong, I don't pretend that LyX is easy to read for the \nuntrained eyes, it is not. But simple modifications like Junio's example \nis definitely possible. For non simple text insertion, it is better to \nlaunch LyX and to type the modification within LyX. But maybe this is a \nshowstopper for you, and so is maybe our treatment of quotes. In which \ncase I'll stop arguying :-)\n\nAbdel.\n"},{"id":"85886","messageId":"37fcd2780808010345l755b83a5gff8a5aa350016ad5@mail.gmail.com","threadId":"14739","inReplyTo":"4892C042.20302@lyx.org","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Dmitry Potapov","fromEmail":"dpotapov@gmail.com","sentAt":"2008-08-01T10:45:15Z","receivedAt":"2008-08-01T10:45:15Z","isPatch":false,"sender":{"key":"dpotapov@gmail.com","avatar":"https://avatars.githubusercontent.com/u/6568595?v=4"},"body":"On Fri, Aug 1, 2008 at 11:50 AM, Abdelrazak Younes wrote:\n>\n> AsciiDoc is indeed excellent if you want to write in a plain text editor.\n> But LyX is easier to use and more porwerful :-)\n\nWhat is really powerful is TeX. As to LyX, it is leaky abstraction over it.\nI have never been able to use without ending up saying, it is so much easier\nand much more powerful to use Latex than trying to do the same with LyX. Of\ncourse, LyX looks much better nowadays than used to be, so I decided to give\nit another try, and here is my fifteen minutes experience with it.\n\nFirst, I tried to open FAQ.lyx that you attached to your previous email, and\nhere is what I see:\n\n===\n/tmp/FAW.lix is from a different version of LyX, but the lex2lex script failed\nto covert it.\n===\n\nThis is result was received with two LyX versions that I tried:\nLyX Version 1.4.3 (21/09/2006)\nLyX 1.5.5 (Sun, May 11, 2008)\n\nNow, I see, that your FAQ was created with LyX 1.6.0svn, which is not released\nyet. So, I hope that this issue will be correctly before it will be released.\nOtherwise, anyone opening document with 1.6.0 will make it unaccessible to users\nof previous versions.\n\nThen I tried to use Formatted reference and everything looks okay until I tried\nto generate DVI file, where I was welcome but the following error:\n===\nParagraph ended before \\@prettyref was complete.\n===\n\nWhat is \\@prettyref? What is wrong with my paragraph? Actually, my paragraph is\nfine, it is just when you use Formatted reference, you should know that it is\nimplemented using prettyref TeX package, which requires three letter prefix in\nname of each label. Why did not LyX warn me about that? BTW, is really prettyref\nis the best package for this job anyway? I remember some TeX experts recommended\nsome other packages for references.\n\nFinally, I still have not figured out how to the same what AsciiDoc does:\nChapter #, $CHAPTER_NAME\nIt does not look like that LyX can produce references in this format.\n\nThe I tried to insert some verbatim text, and I cannot find the standard way\nto do that in LyX. Sure, I can press CTRL-L and type in TeX:\n\\begin{verbatim}\n # git itself (approx. 10MB download):\n$ git clone git://git.kernel.org/pub/scm/git/git.git\n # the linux kernel (approx. 150MB download):\n$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git\n\\end{verbatim}\n\nbut I don't think that having a lot TeX code is going to help us with\nhaving good formatted HTML version.\n\nBTW, it is really annoying to see TeX code displayed in proportional\nfonts and formatted with full adjustment. For instance, the last line\nwas displayed like this:\n\n$ git clone\ngit://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git\n\n\nAnother rather surprising experience for those who got used to HTML:\nLeft-click on a reference produces its properties, while the right\nclick means to go to the label, and once you jump on it, there is\nno way to jump back (at least, I was not able to find how to do that).\n\nWell, I wrote all above only because I hope that LyX will continue to\nimprove. It looks much better now than before. Yet, I will rather stay\nwith plain text editors for now. Some of them are much more powerful\nthan Notepad :)\n\n\nDmitry\n"},{"id":"85888","messageId":"4892EE3A.3040108@lyx.org","threadId":"14739","inReplyTo":"37fcd2780808010345l755b83a5gff8a5aa350016ad5@mail.gmail.com","subject":"Re: markdown 2 man, was Re: Git Community Book","fromName":"Abdelrazak Younes","fromEmail":"younes@lyx.org","sentAt":"2008-08-01T11:06:34Z","receivedAt":"2008-08-01T11:06:34Z","isPatch":false,"sender":{"key":"younes@lyx.org","avatar":null},"body":"Hi Dimitry,\n\nDmitry Potapov wrote:\n> On Fri, Aug 1, 2008 at 11:50 AM, Abdelrazak Younes \n> wrote:\n> > AsciiDoc is indeed excellent if you want to write in a plain text\n> > editor. But LyX is easier to use and more porwerful :-)\n>\n> What is really powerful is TeX. As to LyX, it is leaky abstraction\n> over it. I have never been able to use without ending up saying, it\n> is so much easier and much more powerful to use Latex than trying to\n> do the same with LyX. Of course, LyX looks much better nowadays than\n> used to be, so I decided to give it another try, and here is my\n> fifteen minutes experience with it.\n\nI was afraid this thread will turn into a pro and con of LyX versus \nplain LateX :-)\n\n\n> First, I tried to open FAQ.lyx that you attached to your previous\n> email, and here is what I see:\n...\n> Now, I see, that your FAQ was created with LyX 1.6.0svn, which is not\n> released yet. So, I hope that this issue will be correctly before it\n> will be released.\n\nOf course. Sorry, as I use the pre-release I didn't think that about \nthat. FYI, we will release one last version of 1.5.x that is able to \nread 1.6 format. 1.6 will is of course able to read all previous format.\n\n> Otherwise, anyone opening document with 1.6.0 will make it\n> unaccessible to users of previous versions.\n>\n> Then I tried to use Formatted reference and everything looks okay\n> until I tried to generate DVI file, where I was welcome but the\n> following error: === Paragraph ended before \\@prettyref was\n> complete. ===\n>\n> What is \\@prettyref? What is wrong with my paragraph? Actually, my\n> paragraph is fine, it is just when you use Formatted reference, you\n> should know that it is implemented using prettyref TeX package, which\n> requires three letter prefix in name of each label. Why did not LyX\n> warn me about that? BTW, is really prettyref is the best package for\n> this job anyway? I remember some TeX experts recommended some other\n> packages for references.\n\nAha, yes you're right. LyX will automatically insert those three letters \n(eg. 'cha' for chapter). This is the reason why I never came across this \nbug. We'll try to fix that, thanks!\n\n>\n> Finally, I still have not figured out how to the same what AsciiDoc\n> does: Chapter #, $CHAPTER_NAME It does not look like that LyX can\n> produce references in this format.\n\nYou can choose among a number of document class. If you want the \n\"Chapter\" prefixing, choose the 'Book' document class. The default, \ndocument class is 'Article', for with you don't have level 1 sections.\n\n> The I tried to insert some verbatim text, and I cannot find the\n> standard way to do that in LyX.\n\nThere are at least two:\n- The LyX-code environment\n- The listing inset\n\nThe listing inset supports a number of languages so you'll be able to \nhave syntax highlighting and cloring for your language of choice.\n\n> Sure, I can press CTRL-L and type in\n> TeX: \\begin{verbatim} # git itself (approx. 10MB download): $ git\n> clone git://git.kernel.org/pub/scm/git/git.git # the linux kernel\n> (approx. 150MB download): $ git clone\n> git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git\n> \\end{verbatim}\n>\n> but I don't think that having a lot TeX code is going to help us\n> with having good formatted HTML version.\n\nNo, either LyX-code (To choose from the Layout combo box) or preferable \nthe Listing inset (Menu Insert -> Program Listing). Of course, all these \naction have keyboard shortcuts.\n\n>\n> BTW, it is really annoying to see TeX code displayed in proportional\n> fonts and formatted with full adjustment. For instance, the last\n> line was displayed like this:\n>\n> $ git\n> clone\n> git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux-2.6.git\n\nYes I know, this will be better in 1.6 due out this month in principle.\n\n> Another rather surprising experience for those who got used to HTML:\n> Left-click on a reference produces its properties, while the right\n> click means to go to the label, and once you jump on it, there is no\n> way to jump back (at least, I was not able to find how to do that).\n\nThere is one 'Ctrl-0' but this is more or less hidden feature. 1.6 will \nhave context menu so all the above actions will be a lot more consistant \nand easier.\n\n> Well, I wrote all above only because I hope that LyX will continue\n> to improve. It looks much better now than before.\n\nThanks for the comments :-)\n\n> Yet, I will rather\n> stay with plain text editors for now. Some of them are much more\n> powerful than Notepad :)\n\nIt's a matter of choice. I have to confess that I don't use plain text \neditor anymore because I am so used to LyX keybindings.\n\nThanks,\nAbdel.\n"}]}