Hi, * Michael(tm) Smith [07-03-01 19:26:36 +0900] wrote:
One reason why not would be to make sure that asciidoc could actually provide the same level of semantic markup to capture the semantics of the current manual marked up in DocBook, and to do it in a way that does not end up making the source document even harder to read than it is in DocBook form.
Though I'm fairly new to asciidoc, I think it supports custom macros which is probably the same as generating DocBook from some other XML document.
There are many elements in DocBook for which asciidoc doesn't have equivalent markup. And though asciidoc does in fact provide a some degree of sophistication for marking up your content semantically, in my experience at least, if you use very much of it, you end up with source that looks at least as arcane as, say, a groff/troff source document -- and the only way you or anybody else who looks at the file is going to remember what the markup means is by looking at it side-by-side with the asciidoc user guide to try to decipher it.
Well, the manual now makes use of only very few DocBook tags. But the problem to me seems that neither DocBook nor asciidoc contain those we need like one for referencing variables (including layout, cross-reference, auto-indexing, etc). That is a mess to type and maintain with either solution.
So with either way we'd have to define custom wrappers which simply expand to longer constructs. And that would be hidden from the writer, at least it doesn't appear on screen since the expansion would be done by the machine and the document wouldn't look too ugly.
But since asciidoc only provides LaTeX, HTML and DocBook backends, I'm not really sure any longer if it makes so much sense to switch to it.
Pro: The format is less complicated than DocBook and for long editing sessions and may encourage more people to hack on the manual, you don't need an XML editor (at least I need one for long DocBook sessions). The manual would remain mostly readable without the required tools installed.
Contra: We have another build dependency and an intermediate build step. bye, Rocco -- :wq!