"J. Bruce Fields" <bfields@xxxxxxxxxxxx> writes: > On Wed, Oct 03, 2007 at 12:25:44PM +0200, David Kastrup wrote: > >> The problem is that we are not editing plain text, but Docbook >> source masquerading as plain text. > > I do a fair amount of editing of the asciidoc source, but 99% of it > is done by just blind imitation of what's already there. But not everything is already there, and when something surprising happens, there is little chance to see how it came about. > Maybe my experience would be the same with Docbook--I have no idea, > never having worked with it--but if you're suggesting that knowledge > of Docbook is a prerequisite for working with asciidoc, that > certainly hasn't been my experience. "making use of" and "working with" are two different things. >> 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. > > I'm not sure what you're talking about here. Example? Try including the manual pages as a (properly linked when man pages are referenced) appendix in the user manual, so that the printed form (or PDF) of the user manual is a single coherent document with all information inside. That's what I tried for about a week, digging into the various available (and unavailable) documentation and then postponing the project indefinitely because it both exceeded my current capability as well as demonstrating that there was no reasonably outlined path for acquiring the necessary skills. In Texinfo, this takes few commands, all of which are well-documented and in a reasonable place in the Texinfo manual (which is all you need to consult in order to write Texinfo documents). But with git's AsciiDoc information, not only is the required information scattered through half a dozen of different manuals all describing completely different systems, but the necessary other documentation is, at best, only mentioned in passing in every single relevant document. So while you may know where you want to start and end your journey, there is nothing which would tell you how to get from start to end. You have to randomly pick your road until you may or may not find something closer to the end. -- David Kastrup, Kriemhildstr. 15, 44793 Bochum - 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
