Re: Where, what and how - The future of DocBook

[Michael Smith <smith@xml-doc.org>]

Alan W. Irwin <irwin@beluga.phys.uvic.ca> writes:

> I am a member of a two-man team that converted a largish piece (more
> than 100 pages) of technical documentation from latexinfo to DocBook
> 4.1 XML. [...]
>
> Since the conversion was completed I have been entering lots of
> extra content with an ordinary editor (jed). I understand there is a
> great DocBook interface available with emacs, but I haven't bothered
> with it yet because it is not really needed. From my experience I
> would assert you don't need any special tool to edit and improve
> documentation written in DocBook. The tags that are ordinarily used
> are easy to memorize. Of course, it probably helps that I am a good
> touch typist. If you don't have that skill I guess you need to find
> some tool that gives you WYSIWYG. But it wasn't necessary in my
> case, and I suspect that is true for most documenters.

Yipes -- all due respect, but I think your suspicion may be way off.

The big advantage of an editor like Emacs/psgml is that it takes much
of the guesswork out of document authoring. Validating editors by
design make it hard to produce invalid documents. Using a validating
editor, you really have to go out of your way to make something that
won't validate. Only way you can do it is to type tags in manually --
which you should never need to do with a good XML editing app.

Sure, jed's great (so's Vim -- better syntax highlighting), but if
you've never used a validating editor like Emacs/psgml, you don't know
what you're missing.

I read a thread on the LDP list in which a writer said that one
advantage of LinuxDoc was its short element names. It baffled me why
he would care how long the names were -- until I realized he was
probably typing them by hand using a regular text editor.

Once I realized that, I was baffled as to why -- when Emacs/psgml is
free, great, and so widely used -- why any skilled Linux user would
rely on a regular (non-SGML-validating) editor to work with XML/SGML.

First of all, it ain't quicker -- don't care how fast you can type.
And although it's great to memorize as much of DocBook as you can, I
wonder what kind of agreement you'd get on what tags are "ordinarily
used". I think that depends very much on what you're documenting. 

Confronted with DocBook's 375 elements (including 100+ "inline"
elements that can occur in paragraphs) and 100+ attributes, I doubt
that "most documentors" would find a validating editor uneccessary.

Most of the DocBook users I know (and I include myself) are not so
familiar with the DTD that we can always judge with confidence what
elements and attributes are -valid/required- where -- and why bother
when you've got a DTD-aware validating editor to tell you that?

In fact, one of the main concerns I hear from SGML/XML authors --
especially new ones -- is that their editing tools just aren't smart
enough, and don't go far enough in simplifying the editing process.

No, I wouldn't suggest to anyone that they author DocBook docs using
jed or any other non-validating editor -- unless they've got a lot of
extra time on their hands, really enjoy typing, and really like the
process of running documents through a parser, post-authoring, and
fixing them manually to get them to validate.

  -- Mike Smith

-- 
Michael Smith          mailto:smith@xml-doc.org
XML-DOC                http://www.xml-doc.org/