git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Michael J Gruber <git@drmicha.warpmail.net>
Date
Sep 9, 2011, 16:05 UTC
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:
Show 25 quoted lines
> 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
Previous: Michael HaggertyNext: Giuseppe Bilotta
Message 4 of 10 in “RFD: leveraging GitHub's asciidoc rendering for our Documentation/”
  1. Michael J GruberSep 9, 2011
  2. Scott ChaconSep 9, 2011
  3. Michael HaggertySep 9, 2011
  4. Michael J GruberSep 9, 2011
  5. Giuseppe BilottaSep 10, 2011
  6. Junio C HamanoSep 9, 2011
  7. Michael J GruberSep 9, 2011
  8. Jeff KingSep 9, 2011
  9. Junio C HamanoSep 9, 2011
  10. Fwd: RFD: leveraging GitHub's asciidoc rendering for our Documentation/Sitaram Chamarty, Sep 9, 2011

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.