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

["Alan W. Irwin" <irwin at beluga dot phys dot uvic dot ca>]

Mike, I was reacting against those who implied DocBook was so difficult that
you absolutely required sophisticated tools to deal with it.  Also, you
have, IMO a weak argument about validation since it actually doesn't take
very long to do it on a modern PC independently of the editing process if
you do editing in one window and validation in another. My particular
project had a variety of tags, but the vast majority of them had quite
repetitive patterns so a working example was always nearby in the document.
Thus, I rarely (about 4 times in the whole project) had a validation error.
So things went really fast for the simple method I chose. That is an
important point I hope we can agree on; DocBook ain't difficult and doesn't
absolutely *require* sophisticated tools.

That said, you have been a good advocate for emacs/psgml (and so was my
partner in the project) so I will probably try it next time, but I don't
regret for a moment doing my first DocBook project this simple and
straightforward way. I seem to learn the best if I solve problems with
low-end tools to start, and then move on up to more sophisticated tools
later on.  YMMV, of course.

This has been an interesting discussion about methods and perhaps even
valuable as well, but I sure wish I could get as quick a response on this
list to the practical problem of Cygnus pdfjadetex not working in the
latest release.

Alan

email: irwin@beluga.phys.uvic.ca
phone: 250-727-2902	FAX: 250-721-7715
snail-mail:
Dr. Alan W. Irwin
Department of Physics and Astronomy,
University of Victoria, P.O. Box 3055,
Victoria, British Columbia, Canada, V8W 3P6 
__________________________

Linux-powered astrophysics
__________________________

On 5 Dec 2000, Michael Smith wrote:

> 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/
> 
> 
> 
>