forgot to copy the list; sorry... ---------- Forwarded message ---------- From: Sitaram Chamarty <sitaramc@xxxxxxxxx> Date: Fri, Sep 9, 2011 at 9:24 PM Subject: Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/ To: Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> On Fri, Sep 9, 2011 at 8:04 PM, Michael J Gruber <git@xxxxxxxxxxxxxxxxxxxx> wrote: > Hi there, > > I've been looking more to GitHub lately and was wondering whether it is > worth to leverage their automatic asciidoc rendering for our asciidoc > files. I have put up a test tree at > > https://github.com/gitigit/git/tree/githubtest > > which has all the renaming (*.txt -> *.asciidoc) and Makefile and script > changes, but is missing some include changes (because include breaks > anyway, see below). > > The simple renaming already gives a rendered display of blobs for > simpler asciidoc files like release notes > > https://github.com/gitigit/git/blob/githubtest/Documentation/RelNotes/1.7.7.asciidoc > > and api documentation > > https://github.com/gitigit/git/blob/githubtest/Documentation/technical/api-credentials.asciidoc > > For the man pages, there are several problems as can be seen here: > > https://github.com/gitigit/git/blob/githubtest/Documentation/git-blame.asciidoc > > Our own customisation is not loaded (of course) so that, e.g., the > linkgit macro does not work; and the include statement makes GitHub's > parser unhappy and choke. maybe github will consider supporting linkgit? 3 letters are common anyway :) > Does anybody feel this is worth pursuing? For a long time, I relied on github's rendering for all of my (gitolite) documentation. Eventually I realised it is too slow to render. More importantly, the whole github "presence" was extraneous to the manpage, and often distracted my readers. Eventually I started pre-rendering my documentation to HTML myself and pushing it to a branch called "gh-pages". Contrast the visual appeal of the github-rendered page [1] versus the pre-rendered page [2]. (I admit I do have some very minimal CSS in my version but that's another plus point for pre-rendering) [1]: https://github.com/sitaramc/gitolite/blob/pu/README.mkd [2]: http://sitaramc.github.com/gitolite/README.html -- Sitaram -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html