<<< Date Index >>>     <<< Thread Index >>>

Re: Updating the manual



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!