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 - To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
