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

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

[Michael J Gruber]

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

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

[Scott Chacon]

Hey,

On Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber
<git@drmicha.warpmail.net> wrote:
> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script
> changes, but is missing some include changes (because include breaks
> anyway, see below).

I can change this so we can render .asc if that's less ugly.  I've
been meaning to do this for a while, but I don't think I ever
incorporated it.

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

If this is interesting to people, I can help out.  However, you can
also fix rendering issues, as long as they don't introduce security
issues (which 'include' and macros can do) by fixing it here:

https://github.com/github/markup

That is the rendering engine we use.  If you make it work how you want
and it's safe and you send us a pull request, we'll happily take fixes
to the asciidoc renderer.

Scott

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

[Sitaram Chamarty]

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

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

[Michael Haggerty]

On 09/09/2011 05:45 PM, Scott Chacon wrote:
> On Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber
> <git@drmicha.warpmail.net> wrote:
>> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script
>> changes, but is missing some include changes (because include breaks
>> anyway, see below).
> 
> I can change this so we can render .asc if that's less ugly.  I've
> been meaning to do this for a while, but I don't think I ever
> incorporated it.

What about letting the project set a gitattribute that tells github how
to render particular files?  It would not require files to be renamed,
and it would be more flexible.

OTOH it would not be possible to apply gitattributes (or file renamings)
to old revisions, so the history would continue to be rendered naively.
 But here's an additional idea: github could provide web access to the
equivalent of $GIT_DIR/info/attributes (a project-wide .gitattributes
file), which would allow the rendering of files in historical revisions
to be customized and would also allow github rendering behavior to be
defined even in projects that do not want github-specific tags in the
.gitattributes files in their project.

Michael

-- 
Michael Haggerty
mhagger@alum.mit.edu
http://softwareswirl.blogspot.com/

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

[Michael J Gruber]

Michael Haggerty venit, vidit, dixit 09.09.2011 17:58:
> On 09/09/2011 05:45 PM, Scott Chacon wrote:
>> On Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber
>> <git@drmicha.warpmail.net> wrote:
>>> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script
>>> changes, but is missing some include changes (because include breaks
>>> anyway, see below).
>>
>> I can change this so we can render .asc if that's less ugly.  I've
>> been meaning to do this for a while, but I don't think I ever
>> incorporated it.
> 
> What about letting the project set a gitattribute that tells github how
> to render particular files?  It would not require files to be renamed,
> and it would be more flexible.
> 
> OTOH it would not be possible to apply gitattributes (or file renamings)
> to old revisions, so the history would continue to be rendered naively.
>  But here's an additional idea: github could provide web access to the
> equivalent of $GIT_DIR/info/attributes (a project-wide .gitattributes
> file), which would allow the rendering of files in historical revisions
> to be customized and would also allow github rendering behavior to be
> defined even in projects that do not want github-specific tags in the
> .gitattributes files in their project.
> 
> Michael

I don't think that the naming is a problem. In fact, we have .txt files
which are asciidoc and some which are not, so renaming the former is an
improvement in itself.

Also, I don't mean to replace our prerendered html. Just a nicer source
view for documentation source.

Since this is about source view, we might not even want to execute an
include - but we don't want the rendering to stop where there is one either.

Besides linkgit and things like apostrophe, all our asciidoc marcos are
workarounds for docbook, and thus a non-issue for html rendering.

Don't know where the parser gets stuck. Maybe cwd is not where one
thinks it is, and safe mode spoils the party.

Michael

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

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

> 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

Personally I am not very interested. Couldn't you just visit the html
branch instead for viewing?

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

[Michael J Gruber]

Junio C Hamano venit, vidit, dixit 09.09.2011 19:37:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
>> 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
> 
> Personally I am not very interested. Couldn't you just visit the html
> branch instead for viewing?

For viewing what you generated yes, of course. Though there's some
fiddling if you want to view a specific version. And even for the latest
version it is more direct to click on the file in the tree and see it
rendered.

But what I had in mind was being able to view anyone's branches like
that, to aid review of a patch which is on list and in a branch on
GitHub, say for restructuring layout or presentation of some man pages.
The linkgit and include issues are a bit of a showstopper (looks like
lots of digging in foreign code).

Michael

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

[Jeff King]

On Fri, Sep 09, 2011 at 10:37:24AM -0700, Junio C Hamano wrote:

> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
> > 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
> 
> Personally I am not very interested. Couldn't you just visit the html
> branch instead for viewing?

I agree that it's not very nice for release-quality documentation. But
if I understand correctly, Michael means that you can go straight to any
blob at any commit of any fork on github, and get the rendered (or raw)
version. Which is neat.

How frequently do you build the html branch? I always assumed it was
once in a while (every push?), not for every commit.

We could help that along by giving our documentation a more descriptive
filename. But it would be cool if GitHub respected gitattributes for
this, too.

-Peff

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

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

> How frequently do you build the html branch? I always assumed it was
> once in a while (every push?), not for every commit.

I don't ;-)

Every time "master" is updated to the official distribution point, i.e.,
kernel.org (which currently is down). A post-update hook runs there,
fetches the "master" branch commit into a separate repository, rebuilds
the documentation, updates "html" and "man" branches and pushes the
results back to that distribution point repository.

The mirrors will pick the result up after all that happens (or they may
lag but they will eventually catch up).

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

[Giuseppe Bilotta]

Scott Chacon wrote:

> Hey,
> 
> On Fri, Sep 9, 2011 at 7:34 AM, Michael J Gruber
> <git@drmicha.warpmail.net> wrote:
>> which has all the renaming (*.txt -> *.asciidoc) and Makefile and script
>> changes, but is missing some include changes (because include breaks
>> anyway, see below).
> 
> I can change this so we can render .asc if that's less ugly.  I've
> been meaning to do this for a while, but I don't think I ever
> incorporated it.

Rather than forcing a rename on the repository, do you think it would be
possible to implement some form of gitattribute support in GitHub?
The user could then specify something like render=asciidoc (as opposed to,
say, render=markdown or render=rdoc or whatever else you support): a few
simple additions to .gitattributes and the user would be able to customize
the cooked file view without needing to use GitHub's expected extension.

-- 
Giuseppe Bilotta