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

forgot to copy the list; sorry...


---------- Forwarded message ----------
From: Sitaram Chamarty <redacted>
Date: Fri, Sep 9, 2011 at 9:24 PM
Subject: Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/
To: Michael J Gruber <redacted>


On Fri, Sep 9, 2011 at 8:04 PM, Michael J Gruber
[off-list ref] 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