From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Fri, 09 Sep 2011 16:05:24 GMT
Subject: Re: RFD: leveraging GitHub's asciidoc rendering for our Documentation/
Message-ID: <4E6A3944.8000403@drmicha.warpmail.net>
In-Reply-To: <4E6A378E.6020704@alum.mit.edu>

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