RE: I'm trying to set up docbook-tools...

[Eric Lee Green <eric at badtux dot org>]

On Fri, 07 Jul 2000, Peter Ring wrote:
> A few minutes searching might pop up some immediately useful "Getting
> started with DocBook"-type documents. 

You forget the most useful one of all -- the FreeBSD Documentation Project
primer, which explains the use of DocBook in a "real life" situation. 

http://www.freebsd.org/tutorials/docproj-primer/

I found this invaluable. When I first started on Norm's book, I was lost in all
the talk of entities and such, none of which was explained in plain English. 
The creator of the FDP primer, however, were more concerned about getting it
done. They did cover some basics of the SGML terminology. Once I finished this,
things were much more reasonable. 

>  I've got many more if you care ...
> 
> I can't see how whining about the esoteric SGML community can be
> justified (see link above). I can't see how blaming a single person
> (Norman Walsh) for the lack of shrink-wrapped SGML and DocBook tools can
> be justified. 

I don't think people are blaming Norm Walsh for the lack of easy-to-use SGML
tools. In his own modest way he's made an attempt in the area. He is definitely
more practical-minded than, say, James Clark, who has this irritating habit of
creating totally undocumented tools (it's not a new phenomenon for him
either, he's been doing it for years, all the way back to 'groff'). 

> SGML is no more a holy grail than C++ or Lisp, and about
> as immediately useful (that is to say, useless). DocBook is about as
> immediately useful as STL (that is to say, useless). 

Err, the difference is that STL and C++ in general is very well documented.
Stroustrup's C++ book, for example, is very long and comprehensive, but also
fairly readable, even taking time to cover the basic terminology and
philosophies involved (though the previous edition, prior to templates, was a
lot more readable, bit I digress).  In addition, one does not need to know STL
in order to be productive in C++. There are still many of us "dinosaurs" out
here who use C++ as "C with Classes", mostly because we don't use it often
enough to dedicate the time to using the newer features of C++ (the last time I
used C++ was, hmm, '96? Most of my object-oriented programming since has been
in Python, though I've done considerable "C" also).  

> reflect for a moment just how much prior knowledge and experience is
> needed before these tools become productive. 

You are correct. "C" was easy for me to learn because I knew PDP-11 assembly
language and "C" is basically a high level PDP-11 assembler.  But the clarity
and simplicity of K&R's book "The C Programming Language" had something to do
with it too. I doubt that "C" would ever have become popular outside of Unix if
the documentation had been restricted to a cryptic language definition
document.  Similarly, C++ was easy to learn because I knew "C" and Python (and
also because they had not invented templates and STL at the time :-).  But
again, Stroustrup's excellent C++ book sped C++ on its way. Objective C in
many ways is a much cleaner language than C++,  but never caught on, in part
because there was no equivalent book for Objective C. 

> become a lot easier to use C++ and STL during the years, easy
> installation, integrated development environments, tutorials, etc. etc.
> It takes time and the contributions of a lot of people. Why should SGML
> and DocBook be any different?

I think you're incorrect about it becoming easier to use C++ during the years.
As a Unix type,  my IDE is /bin/sh. (Well, /bin/bash, okay? :-). C++ has always
been easy to use in a Unix environment. If anything, the creation of templates
and STL has made things harder, because they have added yet more "bags on the
side" of a language that was already a "bag on the side" of the "C" language. 
However, there is a variety of good books on the subject, starting with
Stroustrup's own definitive book, the one that made C++ a household world in
programming circles in the first place. One should never underestimate the
value of one good book. Just ask Stroustrup or K&R where they think C++ or C
would have been without that one good book.

One example I would like to add is Python.  One of the reasons Python is used
more often than languages such as, say, Ruby, or ML, is because Python is well
documented, and the documentation is readable.  Python incorporates some very
high level concepts that may be new to its target audience (scripting language
users), but by having clear and readable documentation (at least its tutorial
is!),  and by having a decidedly practical bent (one of Guido's goals was
to be able to access "C" functionality from Python), Python has achieved
modest success where most other languages originating in academia have never
left the novelty stage.  

    -- 
Eric Lee Green      There is No Conspiracy
eric@badtux.org     http://www.badtux.org