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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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.

Does anybody feel this is worth pursuing?

+ Nicer blob view
+ Simpler way to judge documentation changes
- Need to get our asciidoc config in there
- GitHub's parser neeeds to learn include

Michael
--
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


[Index of Archives]     [Linux Kernel Development]     [Gcc Help]     [IETF Annouce]     [DCCP]     [Netdev]     [Networking]     [Security]     [V4L]     [Bugtraq]     [Yosemite]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Linux SCSI]     [Fedora Users]