Re: WIP: asciidoc replacement

[Sam Ravnborg <sam@ravnborg.org>]

Hi David.
> 
> 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