Re: WIP: asciidoc replacement

From: Sam Ravnborg <sam@ravnborg.org>
Date: Oct 3, 2007, 10:52 UTC
Message-ID: <20071003105221.GA11409@uranus.ravnborg.org>
In-Reply-To: <85k5q4v6jb.fsf@lola.goethe.zz>

Hi David.

Show 7 quoted lines

> 
> But it is not all _all_ easily writeable the moment you try to do
> something with _structural_ impact.  In fact, it is pretty much
> impossible for anybody except wizards to do that.  And when the
> wizards do it, they can't actually document what they have been doing
> since that would mean cluttering the purported "plain text
> documentation" with formatting comments.

When I converted part of the kbuild documentation to ascii doc is was a strightforward excercise. The txt file was equally readable before and after, and the generated HTML looks OK.

Up until 3.6 in following link were properly converted: http://www.ravnborg.org/kbuild/makefiles.html

But I did not convince asciidoc to generate an index - is it this you refer to as magic?

Using the kbuild doc as my background I would say that with or without asciidoc there were a requirment for a consistent style used throughout the file. And that style was and are simple to use just by copying relevant examples.

What asciidoc gave me was a simple syntax chack of what I did. I found wrong references when playing with asciidoc as one example.

If the asciidoc replacement prove a success for git I would consider suggesting it for the kernel too. It would be good to generate some nicer loking online documentation and here an asii tool like thing would be a help.

Sam