{"thread":{"id":"28346","subject":"RFD: leveraging GitHub's asciidoc rendering for our Documentation/","startedAt":"2011-09-09T14:34:03Z","lastAt":"2011-09-10T03:02:44Z","messageCount":10,"participants":["Michael J Gruber","Scott Chacon","Sitaram Chamarty","Michael Haggerty","Junio C Hamano","Jeff King","Giuseppe Bilotta"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"175194","messageId":"4E6A23DB.1040606@drmicha.warpmail.net","threadId":"28346","inReplyTo":null,"subject":"RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2011-09-09T14:34:03Z","receivedAt":"2011-09-09T14:34:03Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Hi there,\n\nI've been looking more to GitHub lately and was wondering whether it is\nworth to leverage their automatic asciidoc rendering for our asciidoc\nfiles. I have put up a test tree at\n\nhttps://github.com/gitigit/git/tree/githubtest\n\nwhich has all the renaming (*.txt -> *.asciidoc) and Makefile and script\nchanges, but is missing some include changes (because include breaks\nanyway, see below).\n\nThe simple renaming already gives a rendered display of blobs for\nsimpler asciidoc files like release notes\n\nhttps://github.com/gitigit/git/blob/githubtest/Documentation/RelNotes/1.7.7.asciidoc\n\nand api documentation\n\nhttps://github.com/gitigit/git/blob/githubtest/Documentation/technical/api-credentials.asciidoc\n\nFor the man pages, there are several problems as can be seen here:\n\nhttps://github.com/gitigit/git/blob/githubtest/Documentation/git-blame.asciidoc\n\nOur own customisation is not loaded (of course) so that, e.g., the\nlinkgit macro does not work; and the include statement makes GitHub's\nparser unhappy and choke.\n\nDoes anybody feel this is worth pursuing?\n\n+ Nicer blob view\n+ Simpler way to judge documentation changes\n- Need to get our asciidoc config in there\n- GitHub's parser neeeds to learn include\n\nMichael\n"},{"id":"175201","messageId":"CAP2yMaJ+UBHZp0U=QWOZbnbbOuq8vNoJODWtxZPb1sKXTC_UEg@mail.gmail.com","threadId":"28346","inReplyTo":"4E6A23DB.1040606@drmicha.warpmail.net","subject":"Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Scott Chacon","fromEmail":"schacon@gmail.com","sentAt":"2011-09-09T15:45:52Z","receivedAt":"2011-09-09T15:45:52Z","isPatch":false,"sender":{"key":"schacon@gmail.com","avatar":"https://gravatar.com/avatar/9b13a8a078e1dcf8588c4eea9554445d51ebed6c41b51f56f4d96738130b05c6?d=mp&s=160"},"body":"Hey,\n\nOn Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber\n wrote:\n> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script\n> changes, but is missing some include changes (because include breaks\n> anyway, see below).\n\nI can change this so we can render .asc if that's less ugly. I've\nbeen meaning to do this for a while, but I don't think I ever\nincorporated it.\n\n>\n> Our own customisation is not loaded (of course) so that, e.g., the\n> linkgit macro does not work; and the include statement makes GitHub's\n> parser unhappy and choke.\n>\n> Does anybody feel this is worth pursuing?\n>\n> + Nicer blob view\n> + Simpler way to judge documentation changes\n> - Need to get our asciidoc config in there\n> - GitHub's parser neeeds to learn include\n\nIf this is interesting to people, I can help out. However, you can\nalso fix rendering issues, as long as they don't introduce security\nissues (which 'include' and macros can do) by fixing it here:\n\nhttps://github.com/github/markup\n\nThat is the rendering engine we use. If you make it work how you want\nand it's safe and you send us a pull request, we'll happily take fixes\nto the asciidoc renderer.\n\nScott\n"},{"id":"175203","messageId":"CAMK1S_iSOY6DuP8-u1txUOyA393XjF4GF3m6VQfPgG5bx2QcPA@mail.gmail.com","threadId":"28346","inReplyTo":"CAMK1S_hOY-riZnHAZhC32UAA0BYF1YyXUPujj_jFUEjcYC_4ZA@mail.gmail.com","subject":"Fwd: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Sitaram Chamarty","fromEmail":"sitaramc@gmail.com","sentAt":"2011-09-09T15:55:59Z","receivedAt":"2011-09-09T15:55:59Z","isPatch":false,"sender":{"key":"sitaramc@gmail.com","avatar":"https://avatars.githubusercontent.com/u/43316?v=4"},"body":"forgot to copy the list; sorry...\n\n\n---------- Forwarded message ----------\nFrom: Sitaram Chamarty \nDate: Fri, Sep 9, 2011 at 9:24 PM\nSubject: Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/\nTo: Michael J Gruber \n\n\nOn Fri, Sep 9, 2011 at 8:04 PM, Michael J Gruber\n wrote:\n> Hi there,\n>\n> I've been looking more to GitHub lately and was wondering whether it is\n> worth to leverage their automatic asciidoc rendering for our asciidoc\n> files. I have put up a test tree at\n>\n> https://github.com/gitigit/git/tree/githubtest\n>\n> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script\n> changes, but is missing some include changes (because include breaks\n> anyway, see below).\n>\n> The simple renaming already gives a rendered display of blobs for\n> simpler asciidoc files like release notes\n>\n> https://github.com/gitigit/git/blob/githubtest/Documentation/RelNotes/1.7.7.asciidoc\n>\n> and api documentation\n>\n> https://github.com/gitigit/git/blob/githubtest/Documentation/technical/api-credentials.asciidoc\n>\n> For the man pages, there are several problems as can be seen here:\n>\n> https://github.com/gitigit/git/blob/githubtest/Documentation/git-blame.asciidoc\n>\n> Our own customisation is not loaded (of course) so that, e.g., the\n> linkgit macro does not work; and the include statement makes GitHub's\n> parser unhappy and choke.\n\nmaybe github will consider supporting linkgit?  3 letters are common anyway :)\n\n> Does anybody feel this is worth pursuing?\n\nFor a long time, I relied on github's rendering for all of my\n(gitolite) documentation.  Eventually I realised it is too slow to\nrender.  More importantly, the whole github \"presence\" was extraneous\nto the manpage, and often distracted my readers.\n\nEventually I started pre-rendering my documentation to HTML myself and\npushing it to a branch called \"gh-pages\".  Contrast the visual appeal\nof the github-rendered page [1] versus the pre-rendered page [2].  (I\nadmit I do have some very minimal CSS in my version but that's another\nplus point for pre-rendering)\n\n[1]: https://github.com/sitaramc/gitolite/blob/pu/README.mkd\n[2]: http://sitaramc.github.com/gitolite/README.html\n\n-- \nSitaram\n"},{"id":"175204","messageId":"4E6A378E.6020704@alum.mit.edu","threadId":"28346","inReplyTo":"CAP2yMaJ+UBHZp0U=QWOZbnbbOuq8vNoJODWtxZPb1sKXTC_UEg@mail.gmail.com","subject":"Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Michael Haggerty","fromEmail":"mhagger@alum.mit.edu","sentAt":"2011-09-09T15:58:06Z","receivedAt":"2011-09-09T15:58:06Z","isPatch":false,"sender":{"key":"mhagger@alum.mit.edu","avatar":"https://avatars.githubusercontent.com/u/119718?v=4"},"body":"On 09/09/2011 05:45 PM, Scott Chacon wrote:\n> On Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber\n> wrote:\n>> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script\n>> changes, but is missing some include changes (because include breaks\n>> anyway, see below).\n> \n> I can change this so we can render .asc if that's less ugly. I've\n> been meaning to do this for a while, but I don't think I ever\n> incorporated it.\n\nWhat about letting the project set a gitattribute that tells github how\nto render particular files? It would not require files to be renamed,\nand it would be more flexible.\n\nOTOH it would not be possible to apply gitattributes (or file renamings)\nto old revisions, so the history would continue to be rendered naively.\n But here's an additional idea: github could provide web access to the\nequivalent of $GIT_DIR/info/attributes (a project-wide .gitattributes\nfile), which would allow the rendering of files in historical revisions\nto be customized and would also allow github rendering behavior to be\ndefined even in projects that do not want github-specific tags in the\n.gitattributes files in their project.\n\nMichael\n\n-- \nMichael Haggerty\nmhagger@alum.mit.edu\nhttp://softwareswirl.blogspot.com/\n"},{"id":"175211","messageId":"4E6A3944.8000403@drmicha.warpmail.net","threadId":"28346","inReplyTo":"4E6A378E.6020704@alum.mit.edu","subject":"Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2011-09-09T16:05:24Z","receivedAt":"2011-09-09T16:05:24Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Michael Haggerty venit, vidit, dixit 09.09.2011 17:58:\n> On 09/09/2011 05:45 PM, Scott Chacon wrote:\n>> On Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber\n>> wrote:\n>>> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script\n>>> changes, but is missing some include changes (because include breaks\n>>> anyway, see below).\n>>\n>> I can change this so we can render .asc if that's less ugly. I've\n>> been meaning to do this for a while, but I don't think I ever\n>> incorporated it.\n> \n> What about letting the project set a gitattribute that tells github how\n> to render particular files? It would not require files to be renamed,\n> and it would be more flexible.\n> \n> OTOH it would not be possible to apply gitattributes (or file renamings)\n> to old revisions, so the history would continue to be rendered naively.\n> But here's an additional idea: github could provide web access to the\n> equivalent of $GIT_DIR/info/attributes (a project-wide .gitattributes\n> file), which would allow the rendering of files in historical revisions\n> to be customized and would also allow github rendering behavior to be\n> defined even in projects that do not want github-specific tags in the\n> .gitattributes files in their project.\n> \n> Michael\n\nI don't think that the naming is a problem. In fact, we have .txt files\nwhich are asciidoc and some which are not, so renaming the former is an\nimprovement in itself.\n\nAlso, I don't mean to replace our prerendered html. Just a nicer source\nview for documentation source.\n\nSince this is about source view, we might not even want to execute an\ninclude - but we don't want the rendering to stop where there is one either.\n\nBesides linkgit and things like apostrophe, all our asciidoc marcos are\nworkarounds for docbook, and thus a non-issue for html rendering.\n\nDon't know where the parser gets stuck. Maybe cwd is not where one\nthinks it is, and safe mode spoils the party.\n\nMichael\n"},{"id":"175217","messageId":"7v4o0lvcq3.fsf@alter.siamese.dyndns.org","threadId":"28346","inReplyTo":"4E6A23DB.1040606@drmicha.warpmail.net","subject":"Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-09-09T17:37:24Z","receivedAt":"2011-09-09T17:37:24Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Michael J Gruber writes:\n\n> Our own customisation is not loaded (of course) so that, e.g., the\n> linkgit macro does not work; and the include statement makes GitHub's\n> parser unhappy and choke.\n>\n> Does anybody feel this is worth pursuing?\n>\n> + Nicer blob view\n> + Simpler way to judge documentation changes\n> - Need to get our asciidoc config in there\n> - GitHub's parser neeeds to learn include\n\nPersonally I am not very interested. Couldn't you just visit the html\nbranch instead for viewing?\n"},{"id":"175227","messageId":"4E6A6363.3060608@drmicha.warpmail.net","threadId":"28346","inReplyTo":"7v4o0lvcq3.fsf@alter.siamese.dyndns.org","subject":"Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Michael J Gruber","fromEmail":"git@drmicha.warpmail.net","sentAt":"2011-09-09T19:05:07Z","receivedAt":"2011-09-09T19:05:07Z","isPatch":false,"sender":{"key":"git@grubix.eu","avatar":"https://avatars.githubusercontent.com/u/233215?v=4"},"body":"Junio C Hamano venit, vidit, dixit 09.09.2011 19:37:\n> Michael J Gruber writes:\n> \n>> Our own customisation is not loaded (of course) so that, e.g., the\n>> linkgit macro does not work; and the include statement makes GitHub's\n>> parser unhappy and choke.\n>>\n>> Does anybody feel this is worth pursuing?\n>>\n>> + Nicer blob view\n>> + Simpler way to judge documentation changes\n>> - Need to get our asciidoc config in there\n>> - GitHub's parser neeeds to learn include\n> \n> Personally I am not very interested. Couldn't you just visit the html\n> branch instead for viewing?\n\nFor viewing what you generated yes, of course. Though there's some\nfiddling if you want to view a specific version. And even for the latest\nversion it is more direct to click on the file in the tree and see it\nrendered.\n\nBut what I had in mind was being able to view anyone's branches like\nthat, to aid review of a patch which is on list and in a branch on\nGitHub, say for restructuring layout or presentation of some man pages.\nThe linkgit and include issues are a bit of a showstopper (looks like\nlots of digging in foreign code).\n\nMichael\n"},{"id":"175228","messageId":"20110909190547.GF28480@sigill.intra.peff.net","threadId":"28346","inReplyTo":"7v4o0lvcq3.fsf@alter.siamese.dyndns.org","subject":"Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2011-09-09T19:05:47Z","receivedAt":"2011-09-09T19:05:47Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Fri, Sep 09, 2011 at 10:37:24AM -0700, Junio C Hamano wrote:\n\n> Michael J Gruber writes:\n> \n> > Our own customisation is not loaded (of course) so that, e.g., the\n> > linkgit macro does not work; and the include statement makes GitHub's\n> > parser unhappy and choke.\n> >\n> > Does anybody feel this is worth pursuing?\n> >\n> > + Nicer blob view\n> > + Simpler way to judge documentation changes\n> > - Need to get our asciidoc config in there\n> > - GitHub's parser neeeds to learn include\n> \n> Personally I am not very interested. Couldn't you just visit the html\n> branch instead for viewing?\n\nI agree that it's not very nice for release-quality documentation. But\nif I understand correctly, Michael means that you can go straight to any\nblob at any commit of any fork on github, and get the rendered (or raw)\nversion. Which is neat.\n\nHow frequently do you build the html branch? I always assumed it was\nonce in a while (every push?), not for every commit.\n\nWe could help that along by giving our documentation a more descriptive\nfilename. But it would be cool if GitHub respected gitattributes for\nthis, too.\n\n-Peff\n"},{"id":"175245","messageId":"7vehzptp88.fsf@alter.siamese.dyndns.org","threadId":"28346","inReplyTo":"20110909190547.GF28480@sigill.intra.peff.net","subject":"Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2011-09-09T20:50:15Z","receivedAt":"2011-09-09T20:50:15Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> How frequently do you build the html branch? I always assumed it was\n> once in a while (every push?), not for every commit.\n\nI don't ;-)\n\nEvery time \"master\" is updated to the official distribution point, i.e.,\nkernel.org (which currently is down). A post-update hook runs there,\nfetches the \"master\" branch commit into a separate repository, rebuilds\nthe documentation, updates \"html\" and \"man\" branches and pushes the\nresults back to that distribution point repository.\n\nThe mirrors will pick the result up after all that happens (or they may\nlag but they will eventually catch up).\n"},{"id":"175256","messageId":"j4ek0n$fsi$1@dough.gmane.org","threadId":"28346","inReplyTo":"CAP2yMaJ+UBHZp0U=QWOZbnbbOuq8vNoJODWtxZPb1sKXTC_UEg@mail.gmail.com","subject":"Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/","fromName":"Giuseppe Bilotta","fromEmail":"giuseppe.bilotta@gmail.com","sentAt":"2011-09-10T03:02:44Z","receivedAt":"2011-09-10T03:02:44Z","isPatch":false,"sender":{"key":"giuseppe.bilotta@gmail.com","avatar":"https://avatars.githubusercontent.com/u/1464?v=4"},"body":"Scott Chacon wrote:\n\n> Hey,\n> \n> On Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber\n> wrote:\n>> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script\n>> changes, but is missing some include changes (because include breaks\n>> anyway, see below).\n> \n> I can change this so we can render .asc if that's less ugly. I've\n> been meaning to do this for a while, but I don't think I ever\n> incorporated it.\n\nRather than forcing a rename on the repository, do you think it would be\npossible to implement some form of gitattribute support in GitHub?\nThe user could then specify something like render=asciidoc (as opposed to,\nsay, render=markdown or render=rdoc or whatever else you support): a few\nsimple additions to .gitattributes and the user would be able to customize\nthe cooked file view without needing to use GitHub's expected extension.\n\n-- \nGiuseppe Bilotta\n"}]}