From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: Peter Ring , "'docbook-tools-discuss@sourceware.cygnus.com'" Subject: RE: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: <00070707205600.18330@ehome.inhouse> References: X-SW-Source: 2000/msg00245.html 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