Fwd: RFD: leveraging GitHub's asciidoc rendering for our Documentation/

From: Sitaram Chamarty <sitaramc@gmail.com>
Date: Sep 9, 2011, 15:55 UTC
Message-ID: <CAMK1S_iSOY6DuP8-u1txUOyA393XjF4GF3m6VQfPgG5bx2QcPA@mail.gmail.com>
In-Reply-To: <CAMK1S_hOY-riZnHAZhC32UAA0BYF1YyXUPujj_jFUEjcYC_4ZA@mail.gmail.com>

forgot to copy the list; sorry...

---------- Forwarded message ----------
From: Sitaram Chamarty <sitaramc@gmail.com>
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@drmicha.warpmail.net>

On Fri, Sep 9, 2011 at 8:04 PM, Michael J Gruber <git@drmicha.warpmail.net> wrote:

Show 28 quoted lines

> 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