From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: 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: <76em56j7ps.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> <20000706195444.D27191@thyrsus.com> <87wviym26y.fsf@nwalsh.com> X-SW-Source: 2000/msg00254.html Norm's thought process for not documenting a specific set of tools is quite valid: the various tool sets were immature then, and are still so now. Let's not forget that the whole thread began because the person who started it did not read the docbook-tools home page: that home page points you to my tutorial which has a "get going" approach and an appendix on downloading and installing the tools. There are also many examples of how to run the tools. The main fault in my get-going document is that it is not up-to-date, but since the packages have changed little, it is no big deal. As the list maintainer I have asked the person who posted insulting messages to not do so. Sadly they continued to do so. I recommend that everyone ignore these inflammatory posts and get back to contributing useful information. From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Mark Galassi Cc: "Eric S. Raymond" , 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: <20000704115407.A15973@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <76vgymvstw.fsf@odie.lanl.gov> <20000704113106.A15838@thyrsus.com> <76r999x6e4.fsf@odie.lanl.gov> X-SW-Source: 2000/msg00207.html Mark Galassi : > I'm surprised you don't find it. I went to the first mirror and found > the non-source noarch RPM for stylesheets at: > ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/RPMS/noarch/ Thanks. The mirror I checked was missing the docware/RPMS part. The docbook-tools page ought to mention that the db2* scripts live in the stylesheets RPM. Otherwise it's way too easy to get sidetracked by the docbook RPM. -- Eric S. Raymond When only cops have guns, it's called a "police state". -- Claire Wolfe, "101 Things To Do Until The Revolution" From mboxrd@z Thu Jan 1 00:00:00 1970 From: To: docbook-tools-discuss Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: <00081817110500.03504@needaguru> References: <877l9hffel.fsf@nwalsh.com> <399D1972.41D2ABAC@cybercable.tm.fr> X-SW-Source: 2000/msg00331.html Hi, On Fri, 18 Aug 2000, eric wrote: > Norman Walsh wrote: > > > > / Volker Paul was heard to say: > > | Hello, > > update your catalog(s). Or convert the public ID to DocBook V3.1, which > > you probably have on your system and which is backwards compatible with > > 3.0. > > Or if you want to use the latest docbook-tools: > - make sure you installed docbook-dtd30-sgml package > - that's all ;-). jw now autodetects the catalogs to use. > > -- > Éric Bischoff - Documentation and Localization it would have helped volker paul and many others including me if it was mentioned from where it can be downloaded regards maddy From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Sam Roberts" To: Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: <002501bfe690$04331940$1403a8c0@cogent.ca> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> <00070422425701.09328@ehome.inhouse> X-SW-Source: 2000/msg00216.html ----- Original Message ----- From: Eric Lee Green > Still, TeX and LaTeX still exist. They are thoroughly documented. They run the > same way everywhere. They look ghe same everywhere. So while they are not the > be-all and end-all of structured document design, they'll have to do, since the > SGML crowd has committed collective suicide. A pity, that. This is just a variant of the classic complaints about Unix: I just want to do X, but the docs don't tell me how. LaTeX is a single tool that does it all, to use sgml you have to use a set of tools, and you can mix and match them. You can use jade without docbook or norm's style sheets, you can use jadetex without using docbook, the db2* scripts are so optional most people write their own, and you don't have to use emacs to edit sgml, but it helps. As for the sgml crowd committing suicide, judging from the increased traffic on the oasis docbook lists, which led to a split into two still very busy mailing lists this spring, and the increasing number of open source projects whos docs appear to be docbook generated, I'd say people are perservering and getting the job done. Sam From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Norman Walsh Cc: Eric Lee Green , "Eric S. Raymond" , 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: <20000706131959.A25726@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> X-SW-Source: 2000/msg00224.html Norman Walsh : > / Eric Lee Green was heard to say: > | That puzzles me too. Even Norm Walsh's so-called "Docbook" book > | reads as if it were a briefly written summary written in a foreign > | language to be as terse as possible. > > I'm sorry you found it to be that way. That wasn't the intent. I don't think anybody doubts that it was your intention to be clear. Your execution, however, completely failed in that respect. The failure seems to me to be an indicator of a wider problem in the technical culture surrounding SGML, one I've bitched about before. I looked forward to your book with the hope that it would dispel the thick fog surrounding DocBook -- only to be disappointed in pretty much the same way Eric Lee Green was. What was missing was (a) motivation, and (b) any mention of the tools ordinary mortals might use to format actual documents. It's symptomatic that the chapter titled "Publishing DocBook Documents" -- which one might reasonably expect to answer questions like "How do I generate HTML or Postscript from a DocBook document?" -- consists mainly of pages and pages of mind-numbing detail about stylesheet languages, with not a sample command line or complete example of production code in it anywhere. Two years ago, I complained vociferously on the DocBook list that the SGML culture had a pathological case of self-absorption and seemed to be chronically unable to address the needs or questions of people who actually want to get some formatting done without first memorizing fourteen different sacred tomes of document theology. all filled with an impenetrable jargon that the priests of the cult seem unwilling or unable to explain. For bringing this unwelcome news, I was flamed and shunned. Sadly, there seems to have been little or no improvement since. The SGML- and DocBook-related pages on the Web are marvels of their kind -- exhaustively detailed and *completely* unhelpful. (And remember, this judgment is coming from someone with a very high tolerance for complexity and lots of expertise in related technical areas!) As a result, SGML-related markup now has all the appeal to me of chewing on barbed wire. I wouldn't be messing with it at all if it weren't a political requirement for one of my projects. Can this be fixed? I don't know. The problem isn't any lack of intelligence or good intentions on the part of the DocBook group. There's something fundamentally disconnected and broken in the attitude department, though -- an inability to see what the SGML world looks like from the point of view of somebody who just wants to get some work done. Again, a symptom, In the document "A Practical Introduction to DocBook", the Tools section contains the following blatant cop-out: "Unfortunately, installing and configuring DocBook Tools is (currently) outsidethe scope of this document." Anyone not already eyebrow-deep in the dysfunctional culture surrounding this software would realize that this lacuna makes the rest of the chapter a bad joke. -- Eric S. Raymond Alcohol still kills more people every year than all `illegal' drugs put together, and Prohibition only made it worse. Oppose the War On Some Drugs! From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: esr@thyrsus.com Cc: Norman Walsh , Eric Lee Green , "Eric S. Raymond" , 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: <76g0pnjhmt.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000/msg00225.html Eric> I don't think anybody doubts that it was your intention to Eric> be clear. Your execution, however, completely failed in Eric> that respect. The failure seems to me to be an indicator of Eric> a wider problem in the technical culture surrounding SGML, Eric> one I've bitched about before. Please do not post rude messages to this list. On this list we should not tell people that "they have failed" just because their pedagogical approach did not work for us. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Gregory Leblanc To: 'Norman Walsh' , 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: X-SW-Source: 2000/msg00267.html > -----Original Message----- > From: Norman Walsh [ mailto:ndw@nwalsh.com ] > Sent: Friday, July 07, 2000 2:43 PM > To: docbook-tools-discuss@sourceware.cygnus.com > Subject: Re: I'm trying to set up docbook-tools... > > / "Eric S. Raymond" was heard to say: > | Norman Walsh : > | > Second, I'm tired of your whining about the theology and > jargon. I'm > | > sorry if TDG didn't answer your questions, I'll try to do > better next > | > time (although I still think it's an authors prerogative to decide > | > what is and what is not in scope), but I don't think it's either > | > theological or jargon-filled. > | > | In this respect (if not in others), you and the other core DocBook > | people who share this belief are still out to lunch. And > that's sad, > | because it seriously hinders the deployment of your good work. > > Moments after sending this message, I regretted making the assertion > that it wasn't jargon-filled. That's nonsense and I knew better. (I > really don't think it's theological, but if you do, I won't argue the > point any further.) > > There's a definite tension when it comes to vocabulary and it bites > very deeply in SGML, possibly because I'm familiar with it, although > my intuition is that it bites deeply in SGML in part because it's > worse in SGML than in many other jargons. 8879 was written by a lawyer > after all :-) > > As I expressed earlier, perhaps badly: using the precise 8879 > terminology (which I don't claim to have done, in the interest of > trying to fight this exact problem, even if you think I failed) is a > way of describing things in a precise, technically unabiguous way. > Alas, it comes at the expense of the poor reader who could care less > about the distinction between a "tag" and a "generic identifier". The > trouble is that using loose, informal terms eventually leads to > confusion in those areas where it really makes a difference. > > Maybe I got the balance wrong. I could have done better. I have to say that I've been reading this thread with a fair bit of interest, since there are some huge holes in documentation for actually doing useful things with DocBook. As for this jargon thing, I don't think that there is ANY hope of being able to usefully write a Definitive Guide on DocBook without a lot of fairly specific jargon. The terminology allows things to be described much better than simply using proper English, or even vernacular for the author and readers. The problem here, I think, is that it's bloody hard to figure out which words mean what without working with it for a good while. I've finally figured out what DSSSL is, and where all of the pieces fit together, but it's NOT easy to do, and I don't think I'm an idiot (which may or may not be relevant). DocBook: TDG is NOT a gentle introduction to DocBook, or to writing using DocBook. It's a reference guide, and as such, must use terminology suitable for people using a reference guide. I don't recall finding a good glossary of SGML terms, or a good flow-chart (doesn't anybody use them for anything anymore?) of how publishing a DocBook document work anywhere that I looked. These two things together would probably help clarify a lot of things for people getting started with DocBook publishing. > | So why didn't *you* figure one out this out two years ago? > Why does > | it take an outsider, jumping up and down and screaming, to point out > | the obvious? I have to say that while it may be obvious to you, it is NOT to some other people. I happen to find the flow of most chemical equations totally intuitive, whereas Norm probably finds the flow of taking a DocBook document and turning it into HTML totally intuitive. You happen to have a different point of view, and are able to see things that we may miss. Isn't that why open sores works? Different viewpoints helping each other out, making for a better end product. Grego From mboxrd@z Thu Jan 1 00:00:00 1970 From: Peter Ring To: "'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: X-SW-Source: 2000/msg00243.html A few minutes searching might pop up some immediately useful "Getting started with DocBook"-type documents. Useful for those that just need to get things done, as well as those who wants to make SGML and DocBook more palatable. Try for instance these: A Practical Introduction to DocBook http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook -Intro/docbook-intro/index.html DocBook HOWTO http://metalab.unc.edu/godoy/using-docbook/using-docbook.html Practical information about the use of SGML/XML and DocBook on Debian http://www.debian.org/~bortz/SGML-HOWTO/potato/howto.html Practical information about the use of SGML/XML and DocBook on WindowsNT http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html A fairly complete guide to O'Reilly's DocBook based production system http://www.oreilly.com/people/staff/crism/dsssl/orastyle/index.html 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. 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). If you disagree, reflect for a moment just how much prior knowledge and experience is needed before these tools become productive. Now of course, it has 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? Kind regards, Peter Ring From mboxrd@z Thu Jan 1 00:00:00 1970 From: "richard offer" To: 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: <1000706095536.ZM1901@sgi.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> X-SW-Source: 2000/msg00223.html * $ from ndw@nwalsh.com at "6-Jul:12:21pm" | sed "1,$s/^/* /" * * * / Eric Lee Green was heard to say: * | That puzzles me too. Even Norm Walsh's so-called "Docbook" book * | reads as if it were a briefly written summary written in a foreign * | language to be as terse as possible. * * I'm sorry you found it to be that way. That wasn't the intent. * Although the bulk of the book is intended as a reference and not a * how-to, the introductory chapters were supposed to be readable by the * novice. Can you explain, in any more detail, what you found most * troubling? I didn't find anything really wrong with the book... A few additions would have helped... A reference card of the hierarchy of markups---this was what I used the book for the most initially. More stylessheet specfic text, perhaps including some more examples of different stylesheets for print/HTML and how they can change the outlook of the whole doc. While you're trying to document docbook, people are most likely to be using Jade/your stylesheets to produce the output. I've hacked mine and still can get what I'm (visually) looking for. I guess the limitation is in the generalities of DocBook, since I could get it if I was using raw LaTeX. More details on linking documents, I've got 6 docs that I'm writing in parallel and would really like to link between them. I gave up. * * * Be seeing you, * norm richard. ----------------------------------------------------------------------- Richard Offer Widget FAQ --> http://reality.sgi.com/widgetFAQ MTS-Core Design (Motif) ___________________________________________ http://reality.sgi.com/offer From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "David C. Mason" Cc: 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: <20000706190044.A27191@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000/msg00237.html David C. Mason : > Please stop referring to people's work with words that are meant only > to insult. David, you ain't *seen* me being insulting yet. So far, all I've done is call a spade a spade. You, and Deb, and Mark, and Norman, can start being offended the day I don't respect you enough to criticize your work. Criticism is the tribute you pay adults who are capable of better than they have done. Indifference or dismissal would be the real insult. > I'm sure plenty of people could refer to your essays with > venom, they perhaps choose not to as they know your heart is in the > right place for writing them in the first place. And since when is "having your heart in the right place" worth a damn? If that's the best thing anyone could find to say about my work, *I'd* be insulted. I hold myself to higher standards than that. You should too. > > -- basically so I could pull Red Hat's nuts out of the fire after > > Bob Young asked me nicely to fix the godawful mess their old > > TeX-centric production process had degenerated into. > > What a gentleman like approach to telling me you worked on it. The *point* is, I was called in to solve a nasty problem under emergency conditions, and I did it. I didn't get a lot of thanks for it, either. After "Linux Undercover" Bob decided that the mere fact of designating me the editor of the book and putting my name on the cover didn't actually mean that I could have editorial control. I declined to produce any more books unless my authority was equal to my responsibility, and there hasn't been another edition since. -- Eric S. Raymond Let us hope our weapons are never needed --but do not forget what the common people knew when they demanded the Bill of Rights: An armed citizenry is the first defense, the best defense, and the final defense against tyranny. If guns are outlawed, only the government will have guns. Only the police, the secret police, the military, the hired servants of our rulers. Only the government -- and a few outlaws. I intend to be among the outlaws. -- Edward Abbey, "Abbey's Road", 1979 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 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Gregory Leblanc To: 'Mark Galassi' , "Eric S. Raymond" Cc: 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: X-SW-Source: 2000/msg00210.html Not to be rude, but what ever happened to getting the tools by Eric Bischoff onto the sourceware site? I was under the impression (perhaps mistaken), that his tools were going up on the sourceware site, as well as into a CVS repository someplace. Can somebody fill me in? > -----Original Message----- > From: Mark Galassi [ mailto:rosalia@galassi.org ] > Sent: Tuesday, July 04, 2000 8:06 AM > To: Eric S. Raymond > Cc: docbook-tools-discuss@sourceware.cygnus.com > Subject: Re: I'm trying to set up docbook-tools... > > Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page > Eric> directs me to > Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That > Eric> server is perpetually swamped. Going to one of the mirrors, > Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain > Eric> any of the db2* scripts referenced on the DocBook page. > Eric> Where are those scripts? > > There should be several RPMs on that ftp site. The scripts you seek > are in the stylesheets RPM. Also make sure you don't only get the > noarch RPMs. > From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Bischoff To: egcs@cygnus.com Cc: 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: <3981C236.9E85D170@cybercable.tm.fr> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <1000706095536.ZM1901@sgi.com> X-SW-Source: 2000/msg00298.html richard offer wrote: > > More details on linking documents, I've got 6 docs that I'm writing in > parallel and would really like to link between them. I gave up. We are also suffering a lot with at kde. I'm just trying to figure out a mechanism to link an HTML file to another one at DocBook level without knowing where this file will be implemented on the user's hard disk (this prevents from using "SYSTEM" FPIs), just because some distributions use /opt/kde and other ones /usr. To complicate everything, the target file can be in the middle of the docbook file, and its name results from the ID of a chapter or section! And the target file might exist or not, according to whether it is already translated or not, or whether the user installed it or not. So far, to rely on a CGI helper program seems to be the nearest thing from this holy graal, but first I don't see exactly how to implement it, and second I'm worried about assuming there is an HTTPD server up and running. -- Éric Bischoff - mailto:ebisch@cybercable.tm.fr __________________________________________________ \^o~_. .~. ______ /( __ ) /V\ Toys story \__ \/ ( V // \\ \__| (__=v /( )\ |\___/ ) ^^-^^ \_____( ) Tux Konqui \__=v __________________________________________________ From mboxrd@z Thu Jan 1 00:00:00 1970 From: Volker Paul To: 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: <3997CC44.ACF5698F@dohle.com> X-SW-Source: 2000/msg00325.html > It isn't. The person who started this thread said there was no > tutorial which includes setting up the tools, but there actually was. > Although things are out of date, this whole thread is mostly > unnecessary. No, it's not unnecessary. I have a master in Computer science but for several days now, I'm trying to make my way throught the jungle of SGML stuff. This mail thread showed me that it's not me who is completely stupid, but other people have problems with the documentation, too. Thanks, Eric Raymond. Once you figured out how it works, could you please publish a good tutorial? Yours, Volker Paul From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: Eric Lee Green Cc: "Eric S. Raymond" , 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: <76lmzhwyc8.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000/msg00209.html I'm surprised nobody came across my tutorial: http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html It has been improved on by several people, but always in a specific context, like the FreeBSD documentation guidelines. It is mentioned in the sourceware web page. From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: docbook-tools-discuss@sourceware.cygnus.com Subject: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: <200007041511.LAA15779@snark.thyrsus.com> X-SW-Source: 2000/msg00202.html I'm trying to set up docbook-tools, and finding it a hideously frustrating experience. Why does all the SGML software and documentation in the world read as though it was carefully designed to prevent any actual document production from getting done? The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That server is perpetually swamped. Going to one of the mirrors, I find a docbook-3.1-5.noarch.rpm, but it does not contain any of the db2* scripts referenced on the DocBook page. Where are those scripts? -- Eric S. Raymond "The best we can hope for concerning the people at large is that they be properly armed." -- Alexander Hamilton, The Federalist Papers at 184-188 From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "David C. Mason" Cc: 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: <20000706180129.C26696@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> X-SW-Source: 2000/msg00235.html David C. Mason : > Then I still don't understand the problems you are having... or at > least, I still haven't seen a detail of what you would like to see. I'd like to see documentation that spends less time genuflecting before the wonderfulness of semantic markup and stylesheets, and more time telling me how I can install and configure working tools and make HTML and Postscript from actual documents. Let's start with replacing that cop-out in the so-called "Practical Introduction". It's inexcusable, absurd, perverse, that a so-called "Practical Guide" doesn't tell you (a) where to find installable versions of the tools it's describing, and (b) how to set them up so you can do the examples in the guide. Let's continue with the fact that in the entire 635 pages of "DocBook: The Definitive Guide", I found *not one* example of a command line that could be used to produce actual, viewable HTML or Postscript from an actual document. Is it just me? Am I crazy to think there's something wrong with a 600-page tome on document production tools that *never once tells you how to format a document?* The unbelievable part is that it's *all* like that. It's not just the individual authors of these particular documents that are high priests of the Cult of Obscurity -- every piece of documentation I've ever seen from the DocBook/SGML community is pretty much off in theoretical cloud-cuckoo land. I can learn more than I ever wanted to know about DSSL and FOSI and fifty other acronyms, but I can't find any clue about what to do when jadetex generates bad Postscript that makes gs choke. What I want to see is a practical guide that is truly a practical guide -- something like what I wrote for SGML-tools, but covering DocBook. > I had no idea you did the first SGML-Tools and I apologize, you are a > single entity in that case. Otherwise, I find that most hackers ignore > these tools altogether. My apologies. Don't get an exaggerrated idea of my creds, either. I didn't write SGML-tools, nor was I ever its official maintainer. I did one really serious burst of work on it around 0.99-1.0 -- basically so I could pull Red Hat's nuts out of the fire after Bob Young asked me nicely to fix the godawful mess their old TeX-centric production process had degenerated into. And I did write the User's Guide. But I had very little to do with the design of the tool. -- Eric S. Raymond Idealism is the noble toga that political gentlemen drape over their will to power. -- Aldous Huxley From mboxrd@z Thu Jan 1 00:00:00 1970 From: Chuck Mead To: "Eric S. Raymond" Cc: Mark Galassi , "Eric S. Raymond" , 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: References: <20000704113106.A15838@thyrsus.com> X-SW-Source: 2000/msg00206.html On Tue, 4 Jul 2000, Eric S. Raymond spewed into the bitstream: ESR>Mark Galassi : ESR>> ESR>> Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page ESR>> Eric> directs me to ESR>> Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That ESR>> Eric> server is perpetually swamped. Going to one of the mirrors, ESR>> Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain ESR>> Eric> any of the db2* scripts referenced on the DocBook page. ESR>> Eric> Where are those scripts? ESR>> ESR>> There should be several RPMs on that ftp site. The scripts you seek ESR>> are in the stylesheets RPM. Also make sure you don't only get the ESR>> noarch RPMs. ESR> ESR>OK, what is the actual stylesheet RPM? You didn't specify, and all I ESR>can find is SRPMs and tarballs. ESR> ESR>Would it be too much to ask that these things actually be described ESR>on the DocBook tools page? ESR> ESR>Every time I go near SGML I get headaches... I started fooling with this stuff early last fall and I went through similiar travails. I captured what I did in a colophon for one of the documents I created in docbook/sgml. Maybe this will help: http://www.moongroup.com/docs/mailhelp-HOWTO/z632.html hth! -- Chuck Mead, CTO, LinuxMall.com csm@LinuxMall.com GnuPG Public Key Available: http://pgp.ai.mit.edu/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <87puopaa7c.fsf@nwalsh.com> References: <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> <20000706195444.D27191@thyrsus.com> <87wviym26y.fsf@nwalsh.com> <20000707122209.B30286@thyrsus.com> X-SW-Source: 2000/msg00266.html / "Eric S. Raymond" was heard to say: | Norman Walsh : | > Second, I'm tired of your whining about the theology and jargon. I'm | > sorry if TDG didn't answer your questions, I'll try to do better next | > time (although I still think it's an authors prerogative to decide | > what is and what is not in scope), but I don't think it's either | > theological or jargon-filled. | | In this respect (if not in others), you and the other core DocBook | people who share this belief are still out to lunch. And that's sad, | because it seriously hinders the deployment of your good work. Moments after sending this message, I regretted making the assertion that it wasn't jargon-filled. That's nonsense and I knew better. (I really don't think it's theological, but if you do, I won't argue the point any further.) There's a definite tension when it comes to vocabulary and it bites very deeply in SGML, possibly because I'm familiar with it, although my intuition is that it bites deeply in SGML in part because it's worse in SGML than in many other jargons. 8879 was written by a lawyer after all :-) As I expressed earlier, perhaps badly: using the precise 8879 terminology (which I don't claim to have done, in the interest of trying to fight this exact problem, even if you think I failed) is a way of describing things in a precise, technically unabiguous way. Alas, it comes at the expense of the poor reader who could care less about the distinction between a "tag" and a "generic identifier". The trouble is that using loose, informal terms eventually leads to confusion in those areas where it really makes a difference. Maybe I got the balance wrong. I could have done better. | > It seems to me that the bulk of your ranting boils down to: | > | > "The tools one needs to format a DocBook document and get HTML or | > print output are insufficiently documented and too hard to install and | > use." | | Nope, see above. Above only asserts that I'm out to lunch, it doesn't actually describe any specific problem that I might be able, even anxious, to help you with. | The fact that SGML initiates can't see how | impenetrable their sacred texts are is a larger problem than the lack | of documentation for specific tools -- because it means that said | documentation is unlikely to get written or reviewed by exactly those | who ought to be best qualified to do it. I don't think that follows. I'd love to expand on the publishing sections of TDG to provide practical answers to practical problems in more detail. And now that the tool sets are becoming more mature, I think there's a good chance I'll be able to do that. I'd still like to see a tool set that ran on both NT and Linux, but that may not yet be practical. And I'll happily review anything written on the subject if I'm asked. | "Floggings will continue until morale improves." :-) No, in fact, I'm | not flogging you for moving too slowly. I'm flogging you for an | apparent inability to understand "motion" at all. I'll stop when you | either clue in or my arm gets tired. Your polite, reasoned demeanor invariably improves my morale. Thank you, sir! May I have another, sir! | So why didn't *you* figure one out this out two years ago? Why does | it take an outsider, jumping up and down and screaming, to point out | the obvious? It must be wonderful to always have all the right ideas at the right time. Alas, I have not your gift in that regard. Oh, and by the way, while it may take an outsider, it does not take an outsider jumping up and down and screaming. That has very nearly driven me to stop reading your posts. Be seeing you, norm -- Norman Walsh | DNA neither cares nor knows. DNA just http://nwalsh.com/ | is. And we dance to its music.--Richard | Dawkins From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: "Eric S. Raymond" Cc: 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: <76vgymvstw.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> X-SW-Source: 2000/msg00203.html Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page Eric> directs me to Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That Eric> server is perpetually swamped. Going to one of the mirrors, Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain Eric> any of the db2* scripts referenced on the DocBook page. Eric> Where are those scripts? There should be several RPMs on that ftp site. The scripts you seek are in the stylesheets RPM. Also make sure you don't only get the noarch RPMs. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "David C. Mason" , esr@thyrsus.com Cc: 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: <00070616070800.15706@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000/msg00238.html On Thu, 06 Jul 2000, David C. Mason wrote: > What a gentleman like approach to telling me you worked on it. Welcome to the Open Source world :-). If we weren't passionate, we wouldn't do it. And when the tools suck, we do one of two things -- use different tools, or fix the tools. In my case, I'm using different tools for my next project, ones that I know are reliable and work correctly. I have a sneaking suspicion that ESR's passion here is going to lead him to fixing the tools, but on the other hand, he may have concluded that his contributions aren't welcome in the SGML community, because they don't meet some purity test (i.e., they're practically oriented, rather than being pretty, theoretical, and utterly useless). -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: Derek Simkowiak To: Norman Walsh Cc: 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: References: <87wviym26y.fsf@nwalsh.com> X-SW-Source: 2000/msg00259.html -> Second, I'm tired of your whining about the theology and jargon. There's a great T-Shirt from the geekshirts project: http://geekshirts.sourceforge.net/shirts/bitchandmoan//bitchfix.png It seemed to apply here... --Derek From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: Volker Paul Cc: Eric Bischoff , 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: <877l9hffel.fsf@nwalsh.com> References: <3998DF53.D2C430F5@cybercable.tm.fr> <399A9F34.A10C59AB@dohle.com> X-SW-Source: 2000/msg00329.html / Volker Paul was heard to say: | Hello, | | trying to run Jade, I get the following error message: | | jade:myfile.sgml:1:59:W: cannot generate system identifier for public | text "-//Davenport//DTD DocBook V3.0//EN" | jade:myfile.sgml:2:1:E: reference to entity "BOOK" for which no system | identifier could be generated | jade:myfile.sgml:1:0: entity was defined here | jade:myfile.sgml:2:1:E: DTD did not contain element declaration for | document type name | jade:myfile.sgml:3:6:E: element "BOOK" undefined | jade:myfile.sgml:4:12:E: element "BOOKINFO" undefined | | I suppose Jade hasn't the (right) DTD. How do I tell Jade | where it is? Get DocBook V3.0 from OASIS, put it somewhere on your system, and update your catalog(s). Or convert the public ID to DocBook V3.1, which you probably have on your system and which is backwards compatible with 3.0. Be seeing you, norm -- Norman Walsh | Nothing will ever be attempted, if all http://nwalsh.com/ | possible objections must be first | overcome.--Dr. Johnson From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: 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: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000/msg00217.html > > I'm trying to set up docbook-tools, and finding it a hideously > > frustrating experience. Why does all the SGML software and > > documentation in the world read as though it was carefully designed > > to prevent any actual document production from getting done? This is one of those cases where certain documentation projects have taken up the call more so than the tools side. For example, both the GNOME and KDE doc groups have manuals to help people get involved with writing documentation for their projects. Both tell the writer where to get everything they need for Docbook and how to use it - but both also describe it in terms that are particular to their style of writing. I like this approach as it narrows the focus to projects and those who wish to write for those projects. Outside of that the best resources I have seen are Mark's tutorial and Deb Richardson's HOWTO at OSWG. The main problem with it is that describing SGML is not as trivial as you might think. Describing DocBook is easier, but it still comes as very foreign to those who come from either the word processor world, or the format driven mark-up world. The best way to learn is by trying, not by reading IMHO. Can the documentation be better? Sure it can, and we shall try. Still, I find it somewhat humorous at the trouble many hackers (who would never dream of documenting their code) have when they can read the source :-) Cheers, Dave -- David Mason Red Hat AD Labs dcm@redhat.com http://people.redhat.com/dcm From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: madhu Cc: "Eric S. Raymond" , 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: <00070422425701.09328@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> X-SW-Source: 2000/msg00214.html On Tue, 04 Jul 2000, madhu wrote: > On Tue, 04 Jul 2000, you wrote: > > On Tue, 04 Jul 2000, Eric S. Raymond wrote: > > > I'm trying to set up docbook-tools, and finding it a hideously > > > frustrating experience. Why does all the SGML software and > > > documentation in the world read as though it was carefully designed > > > to prevent any actual document production from getting done? > > > > That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it > > were a briefly written summary written in a foreign language to be as terse as > > possible. You would suspect that the authors of documentation tools would > > themselves be enamored of documentation. WIth the exception of Donald Knuth, > > that, alas, does not appear to be the case. > an html.zip file exists on the officail docbook site oasis with enough details > for anybody to start with Are you talking about Paul Prescod's tutorial? That was one of the things that got me going. Right now the manual I'm working on is >200 pages and still growing, so obviously I figured out how to get things going, but I'm still puzzled by the lack of understandable documentation. Donald Knuth's stuff about TeX is not exactly the world's most accessible documentation either, but it is complete, it is clear and unambiguous (except where he deliberately simplifies things for the heathen :-), and it clearly documents all parts of the system. Unfortunately, the SGML purists appear to believe that their job is done once they've created the raw DTD... "just read the DTD!" appears to be the notion. > the problems you are mentioning are mostly to do with SGML tools not with > docbook by itself. Correct. I've already discussed the notion that SGML purists appear to believe that their job is done once they've created the raw DTD and (optionally) style sheet. This attitude is what has prevented SGML from supplanting TeX/LaTeX for structured document creation. As I mentioned earlier, as soon as I'm finished with the current document, I'm falling back to LyX and TeX/LaTeX. > If you use the scripts like db2pdf it doesn,t some time run > jadtex thrice for the numbers to be printed right . I have taken to running jadetex by hand until the 'unresolved reference' messages go away, then running dvi2ps by hand. Some of my page references STILL turn out to be -999. > that situation is not likely to improve what with SGML is dead proclamations > doing the rounds and shift is towards XML . but again tools for XML are not unix > favorable at all . I have come to that conclusion. A pity. Especially since Microsoft seems bound and detirmined to subvert XML into a Microsoft-only standard if in any way possible. Still, TeX and LaTeX still exist. They are thoroughly documented. They run the same way everywhere. They look ghe same everywhere. So while they are not the be-all and end-all of structured document design, they'll have to do, since the SGML crowd has committed collective suicide. A pity, that. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <87lmzenirl.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <1000706095536.ZM1901@sgi.com> X-SW-Source: 2000/msg00253.html / "richard offer" was heard to say: | be using Jade/your stylesheets to produce the output. I've hacked mine and | still can get what I'm (visually) looking for. I guess the limitation is in the | generalities of DocBook, since I could get it if I was using raw LaTeX. I'm curious about this. Can you provide a couple of examples of things you can't do in DocBook that you could do in LaTeX? I'm not interested in the mechanics, per se, but in what markup distinction you feel you've lost. | More details on linking documents, I've got 6 docs that I'm writing in | parallel and would really like to link between them. I gave up. These are six separate documents, or six parts of the same document? SGML doesn't really have a good cross-document linking solution (though you can cobble one together, see my tutorials about olink on nwalsh.com). XPointer and XLink should do better, but there are still some problems given that you don't typically publish the source. Be seeing you, norm -- Norman Walsh | A moment's insight is sometimes worth a http://nwalsh.com/ | life's experience.--Oliver Wendell | Holmes From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "David C. Mason" Cc: 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: <20000706150802.A26225@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000/msg00230.html David C. Mason : > Your problem installing the tools seemed (as I read back through the > thread) to be one of finding a mirror that was bad. Once you found a > mirror which contained the RPMs needed are we to assume the > installation went according to plan? Oh, no. That wasn't my only problem by a long shot. I actually went through three different attempts to get three different sets of tools running -- Jade, OpenJade, and the DocBook tools. Not one of them had adequate documentation for beginners, even technically sophisticated beginners like me with considerable prior knowledge of SGML (I did a lot of of extension work on SGML-Tools for the LDP). All three have web pages that are remarkable for the amount of detail they convey without actually saying anything useful. > Can all of this be improved for the newbie - it sure can. In fact new > scripts or even applications can be written. You are a hacker, would > you like to write them? Can I assume the answer is no? Do you mean like the user's guide I once wrote for SGML-Tools to address exactly this problem? :-) Sorry, David. You don't get to accuse *me* of carping without contributing. I happen to be the person who made SGML-Tools 1.1 usable for fast-turnaround book publishing, proved it by producing "Linux Undercover" for Red Hat, and then documented what I did. But don't take my word for any of that -- go ask Ed Bailey about it. You'd probably find the story both entertaining and instructive. > Slamming someone's book certainly cannot help you learn can it? Slamming someone's book for lack of clarity certainly *can* be helpful if it wakes the author (and the dysfunctional culture surrounding the author) up to a problem. I did not mean to imply that Norman Walsh's book is without value. If I already knew most of what was in it, I'm sure it would make a dandy reference. But that's the problem -- the book is only useful for people who already have a working SGML toolset and considerable pre-acquired expertise. The fact that it was not useful to a person who had already done substantial SGML publishing and extension work on SGML tools *should* be an important message. > I say 'kudos' to Norm for the following: I'll cheerfully say Norm is a wonderful guy too, if that will make you or him feel any better. He's done a lot of good things. Unfortunately, none of those things includes actually making SGML accessible to the un-initiated. *And that is the issue here*. The DocBook community has a huge blind spot. The consequences of that blind spot drive away people like Eric Lee Green or myself who would otherwise love to contrivbute more. -- Eric S. Raymond "Today, we need a nation of Minutemen, citizens who are not only prepared to take arms, but citizens who regard the preservation of freedom as the basic purpose of their daily life and who are willing to consciously work and sacrifice for that freedom." -- John F. Kennedy From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "David C. Mason" , esr@thyrsus.com Cc: 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: <00070614422402.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <20000706150802.A26225@thyrsus.com> X-SW-Source: 2000/msg00234.html On Thu, 06 Jul 2000, David C. Mason wrote: > Still, my problem is this thread has been about the lack of > documentation for DocBook - but I still don't understand what the > problem you are having is. I The problem is not the lack of documentation. The problem is the lack of attention to documenting DocBook as an actual document production system, rather than as a theoretical exercise. There is plenty of good theoretical documentation, but a paucity of Get The Job Done tools and documentation. This, alas, has always been a problem of the SGML crowd. I've been following SGML off and on since 1995 or so, when the original LinuxDoc project adopted that LaTeX-like DTD, and aside from that project and one other that died aborning (don't remember what it was, it was written using 'bigloo' Scheme and a DTD that was similar to but simpler than DocBook), there has been absolutely no attention at all amongst the SGML literati to the problems of producing practical systems for ordinary users' purposes. And I'm talking as someone who used to read Robin Cover's web page on a monthly basis looking for links that would solve some actual problem that I had... it just never happened. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Mark Galassi Cc: Norman Walsh , Eric Lee Green , "Eric S. Raymond" , 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: <20000706134507.D25726@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <76g0pnjhmt.fsf@odie.lanl.gov> X-SW-Source: 2000/msg00226.html Mark Galassi : > On this list we should not tell people that "they have failed" just > because their pedagogical approach did not work for us. You're quite right. We tell people they have failed when their pedagogical approach has been reported to be ineffective by independent multiple observers. That is, that's what we do if we actually care about improving matters. If all we want to do is wrap the failure in a thick layer of feel-good batting so it can be ignored, then perhaps we do something else. -- Eric S. Raymond Americans have the will to resist because you have weapons. If you don't have a gun, freedom of speech has no power. -- Yoshimi Ishikawa, Japanese author, in the LA Times 15 Oct 1992 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: esr@thyrsus.com Cc: "Eric S. Raymond" , 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: <76r999x6e4.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <76vgymvstw.fsf@odie.lanl.gov> <20000704113106.A15838@thyrsus.com> X-SW-Source: 2000/msg00205.html Eric> OK, what is the actual stylesheet RPM? You didn't specify, Eric> and all I can find is SRPMs and tarballs. I'm surprised you don't find it. I went to the first mirror and found the non-source noarch RPM for stylesheets at: ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/RPMS/noarch/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: Kendall Clark To: docbook-tools-discuss@sourceware.cygnus.com Cc: Mark Galassi , Norman Walsh , Eric Lee Green , esr@thyrsus.com Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: <14692.50781.521325.126382@cmpu.net> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <76g0pnjhmt.fsf@odie.lanl.gov> <20000706134507.D25726@thyrsus.com> X-SW-Source: 2000/msg00227.html >>>>> "Eric" == Eric S Raymond writes: Mark Galassi : >> On this list we should not tell people that "they have failed" >> just because their pedagogical approach did not work for us. Eric> You're quite right. We tell people they have failed when Eric> their pedagogical approach has been reported to be Eric> ineffective by independent multiple observers. Eric> That is, that's what we do if we actually care about Eric> improving matters. If all we want to do is wrap the failure Eric> in a thick layer of feel-good batting so it can be ignored, Eric> then perhaps we do something else. Well if it's about adjudicating pedagogy, then I should chime in with "Norm's book helped me tremendously, as has Norm personally on the several occasions when I emailed him with questions." I figured out SGML and DocBook well before Norm's book came out, well before I learned to program in fact. There are other SGML books, some of which are rather practical. Those helped too. As for actually setting up and installing the various permutations of the free tool chain, I just don't see why it's *so* hard for someone with a bit of technical ability or experience. Could it be *easier*? Of course. But so could nearly every bit of free software I've ever used. I started working with SGML on Linux in '96, well before anyone was making nice RPM packages for it; maybe that's an advantage in a perverse way? I'm not sure. Best, Kendall Clark From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: Gregory Leblanc Cc: "Eric S. Raymond" , 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: <76k8f1v7l9.fsf@odie.lanl.gov> References: X-SW-Source: 2000/msg00212.html Gregory> Not to be rude, but what ever happened to getting the Gregory> tools by Eric Bischoff onto the sourceware site? I was Gregory> under the impression (perhaps mistaken), that his tools Gregory> were going up on the sourceware site, as well as into a Gregory> CVS repository someplace. Can somebody fill me in? Eric and I are working on it. We're obviously being slower than you would like us to :-), but it will happen. Of course that has nothing to do with this issue. If RPMs are missing on a mirror (as esr implies they are), Eric B's enhancements will not help. Also, esr was trying to get basic db2html working. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: Ismael Olea Cc: 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: <76vgyktswi.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> <00070422425701.09328@ehome.inhouse> <002501bfe690$04331940$1403a8c0@cogent.ca> <396368E9.95CC5D75@hispalinux.es> X-SW-Source: 2000/msg00220.html Ismael> We have a little problem with these tools. There Ismael> aren't a more-or-less sgml suite made of components Ismael> (packages) with well made package dependeces. Then, if you Ismael> want to use linuxdoc, your package system'll ask for sp, Ismael> linuxdoc-dtd and its filters. If you want XML DocBook, the Ismael> packages we all know. Add a new package (TEI?) could need Ismael> to add it's dtd, the stylesheets and maybe some interface. These problems exist, but are on their way out. It will eventually be possible to just install a nice suite of sgml-based tools. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: Gregory Leblanc , "'Norman Walsh'" , 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: <00070716141700.19764@ehome.inhouse> References: X-SW-Source: 2000/msg00268.html On Fri, 07 Jul 2000, Gregory Leblanc wrote: > I have to say that I've been reading this thread with a fair bit of > interest, since there are some huge holes in documentation for actually > doing useful things with DocBook. As for this jargon thing, I don't think > that there is ANY hope of being able to usefully write a Definitive Guide on > DocBook without a lot of fairly specific jargon. Quite obviously. The question then becomes one of how you handle the jargon. For example, here's a glossary entry from DB:TDG: entity: A name assigned (by means of a declaration) to some chunk of data so that it can be referred to by that name; the data can be of various ckinds (a special character or a chapter or a set of declarations in a DTD, for instance), and the way in which it is referred to depends on the type of data and where it is being referenced: SGML has parameter, general, external, internal, and data entities. Here's a glossary entry from an internal document that I wrote: Encryption A method of scrambling data such that it cannot be read (see decryption) without possession of the proper passphrase or key. Note that a) it's short, b) it's precise, c) it doesn't go into details about various methods of encryption etc. Though further on, we get the following glossary entry: Private Key (Symmetrical) Cryptography A mechanism via which each end of a communication share a common key, which is used by both ends to both to encrypt and decrypt the data. The common key is usually transmitted using the (much slower) process of public key cryptography (see below), which allows communications to take place without transmitting a common key in a way that can be intercepted. This glossary entry is less satisfactory, but still is much more readable than the typical DB:TDG glossary entry. Note that this glossary, as you might gather, deals with the very technical details of encryption, a field which has its own arcane terminology (quick, what's a Feistel-network symmetric cipher with a 64-bit block length and 128-bit key length and key-dependent S-boxes?! And what about our IV, is it necessary with CFB feedback mode to use a random IV, or will a unique one in counter mode provide adequate protection?). But no matter how arcane the terminology, it is possible to express it in a manner that is both easy to read and accurate. Unfortunately, in many places DB:TDG appears to be written under the delusion that it is impossible to be both easy to read and accurate. For example, page 17: "These declarations form what is known as the internal subset. The declarations stored in the file referenced by the public or seystem identifier in the DOCTYPE declaration is called the external subset and it is technically optional. ..." What's a declaration? what's a public identifier? What's a system identifier? What's a subset? Who's on first? While accurate, the above paragraph is totally incomprehensible to someone who is not well versed in the arcane vocabulary of SGML. Meanwhile, a snippet from one of my own documents: "The Diffie-Hellman authentication chat is succeptible to man-in-the-middle attacks (see Schneir, p516). In response, shared-secret chats such as SPEKE were created, but those will not work in our application. In order to deal with the problem of man-in-the-middle attacks, the server public key X will be by default deployed as a hard-coded public key and the user will be cautioned to initiate the initial connection as soon after installation time as possible. As long as the network is secured at the time of the initial chat, future transactions are no longer succeptible to man-in-the-middle attacks. Note that all public key encryption methods which do not use a shared secret or a hard-coded public key are succeptible to man-in-the-middle attacks (that is why 'ssh' asks you for the password - a shared secret - until the connection has been authenticated both ways with a password). The SSL protocol, by contrast, relies upon having a hard-coded public key (the public key of the certificate server), an Internet path to the certificate server, and a secure certificate server. The latter two problems are why we do not use SSL here. " Not the most clear of passages, and it refers to another text for a definition of a man-in-the-middle attack, but it does have some attributes of good documentation: it refers to the way some other program that the user is familiar with operates (this is in a highly technical document intended for network engineers), it compares and contrasts it with other ways of handling the problem, and it does tell how the problem is solved in a real-life instance. There's other possible models that could have been discussed (such as the PGP "trust" model), but that's hardly relevant. > vernacular for the author and readers. The problem here, I think, is that > it's bloody hard to figure out which words mean what without working with it > for a good while. I've finally figured out what DSSSL is, and where all of > the pieces fit together, but it's NOT easy to do, and I don't think I'm an > idiot (which may or may not be relevant). DocBook: TDG is NOT a gentle > introduction to DocBook, or to writing using DocBook. It's a reference > guide, and as such, must use terminology suitable for people using a > reference guide. I don't recall finding a good glossary of SGML terms, or a > good flow-chart (doesn't anybody use them for anything anymore?) of how > publishing a DocBook document work anywhere that I looked. These two things > together would probably help clarify a lot of things for people getting > started with DocBook publishing. Indeed :-). There is a glossary. But it confuses more than it enlightens. For example: "cooked: "Cooked" data, as distinct from "raw", is a collection of elements and character data that's ready for presentation. The processor is not expected to rearrange, select, or suppress any of the elements, but simply present them as specified. Also see RAW. " Utterly incomprehensible. > I have to say that while it may be obvious to you, it is NOT to some other > people. I happen to find the flow of most chemical equations totally > intuitive, whereas Norm probably finds the flow of taking a DocBook document > and turning it into HTML totally intuitive. Indeed. That's why I was a better math teacher than I was a computer science teacher -- for me, the notion of describing a problem in a terse English subset such that it can be executed by a computer is natural and totally intuitive, whereas for my students, it was not. Meanwhile, never having been the math maven, I found that presenting mathematic concepts in a clear, concise, understandable manner not only helped the students, but it helped organize my thinking about mathematics. Mathematics, not being intuitive to me, was much easier for me to explain an an easy-to-understand manner that was both accurate and accessible. Yes, I regularly cursed the authors of the math texts that I was forced to use (or not use, actually, in my case -- I taught out of notebooks, because high school math texts are so horrible). -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: madhu To: Eric Lee Green Cc: "Eric S. Raymond" , 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: <00070510365404.00678@needaguru> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000/msg00213.html On Tue, 04 Jul 2000, you wrote: > On Tue, 04 Jul 2000, Eric S. Raymond wrote: > > I'm trying to set up docbook-tools, and finding it a hideously > > frustrating experience. Why does all the SGML software and > > documentation in the world read as though it was carefully designed > > to prevent any actual document production from getting done? > > That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it > were a briefly written summary written in a foreign language to be as terse as > possible. You would suspect that the authors of documentation tools would > themselves be enamored of documentation. WIth the exception of Donald Knuth, > that, alas, does not appear to be the case. an html.zip file exists on the officail docbook site oasis with enough details for anybody to start with . it is also linked from normans website from where you can download the latest stylesheets for the docbook, oasis wesite is http://www.oasis-open.org/docbook/ and normans website is http://nwalsh.com/~ndw/ > > It's bad enough that the authors of every book and document that exists on SGML > have invented their own inscrutable terminology for the process of marking up > documentation... but none of them, zero, zilch, appears to have considered the > notion of a GLOSSARY, and the very thought of explaining complex terms in a > simple, clear manner appears to break every single SGML author out in hives. > Yes, it's difficult. I've done it before, I know how difficult it is. But it's > as if the creators of SGML DTD's and tools have a death wish... or else they're > trying to protect their cult's purity by keeping out the riff-raff (same > thing). > > Despite all of the above, I have become reasonably proficient in using the > Docbook-Tools set and in Docbook itself. But the tool kits still do not work > well enough for me to actually use them to produce real documentation. I am > using Docbook for the design documentation for a major project at the office, > but nobody on this list has been able to explain to me why half the entries in > my index have "-999" as the page number, even when the 'jadetex' script does not > complain about unresolved references. I've even tried updating everything > from the Docbook-tools site thinking maybe Red Hat had a wonked out > docbook-tools installation. I even tried using Caldera eDesktop 2.4 rather than > Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No > go. I'm on the verge of abandoning the tool kit in frustration. LyX will now > generate decent HTML output, which was my main reason for using DocBook in the > first place (the difficulty of getting good HTML output out of "latex2html" and > its ilk). My only issue with LyX is the difficulty of maintaining multi-source > documentation in a CVS depository... CVS won't do merges of multi-author edits > of .lyx files, sigh. But if it's a choice of LyX or using StarOffal, I know > which I'll choose -- at least LyX is a structured markup tool, whereas > StarOffal.. no, don't get me started. the problems you are mentioning are mostly to do with SGML tools not with docbook by itself. if you use the scripts like db2pdf it doesn,t some time run jadtex thrice for the numbers to be printed right .the db2* scripts are a sort of primer a starting point so to say but without them you can produce docbook documents , please refer to the readme's of jade, jadetex etc.and be warned that situation is not likely to improve what with SGML is dead proclamations doing the rounds and shift is towards XML . but again tools for XML are not unix favorable at all . additionally i would suggest you subcribe to docbook-apps@lists.oasis-open.org, and docbook@lists.oasis-open.org lists whree you might get more help than this list since this is of late a very low traffic list. and as Mark's excellent tutorial, please don't forget this http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html regards -- maddy ------------------------------------------------------------------------- Fishing baskets are employed to catch fish; but when the fish are got, the men forget the baskets; Words are employed to convey ideas; but when the ideas are grasped, the men forget the words; --"Chuang Tzu" ------------------------------------------------------------------------- From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: esr@thyrsus.com Cc: 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: X-SW-Source: 2000/msg00241.html "Eric S. Raymond" writes: > David, you ain't *seen* me being insulting yet. So far, all I've > done is call a spade a spade. You, and Deb, and Mark, and Norman, > can start being offended the day I don't respect you enough to > criticize your work. Criticism is the tribute you pay adults who > are capable of better than they have done. Indifference or > dismissal would be the real insult. I will at this point simply have to ignore. Not as an insult, rather, I thought I could get something constructive that I could personally add to the DocBook Tools project and the use of DocBook in general. All I have gotten is repeated insults of my friends. I do not subscribe to your definition of an insult. I tend to believe that to treat someone with indignity is the real definition of an insult. To treat Bob Young (who I can assure you is not on this list to defend himself) with the words you have chosen, is to treat with indignity. Period. Besides I find more in one post from Ed than I have of all the posts you have given us so far. The more I try to figure out what it is you want or need I find that the old saying remains true: "For every action, there is an equal and opposite criticism." And with that, I will sign off with Mr Richard Livingstone's quote: "...criticism is only the burying beetle that gets rid of what is dead, and, since the world lives by creative and constructive forces, and not by negation and destruction, it is better to grow up in the company of prophets than of critics." Dave From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <87zonunjyf.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <76lmzhwyc8.fsf@odie.lanl.gov> X-SW-Source: 2000/msg00246.html / Mark Galassi was heard to say: | I'm surprised nobody came across my tutorial: | http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html That one's on the DocBook documentation page: http://www.oasis-open.org/docbook/documentation/other.html Be seeing you, norm -- Norman Walsh | All the labors of the ages, all the http://nwalsh.com/ | devotion, all the inspiration, all the | noonday brightness of human genius, are | destined to extinction--Bertrand Russell From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <8766pq40b3.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <1000706095536.ZM1901@sgi.com> <3981C236.9E85D170@cybercable.tm.fr> X-SW-Source: 2000/msg00299.html / Eric Bischoff was heard to say: | or whether the user installed it or not. So far, to rely on | a CGI helper program seems to be the nearest thing from this | holy graal, but first I don't see exactly how to implement | it, and second I'm worried about assuming there is an HTTPD | server up and running. I can't help with the second part, but I did the first part. Look over the olink docs on my website, I think it's described in there and let me know if you have questions. Be seeing you, norm -- Norman Walsh | When we are tired, we are attacked by http://nwalsh.com/ | ideas we conquered long ago.--Nietzsche From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Bischoff To: b_maddy_016@yahoo.com Cc: docbook-tools-discuss Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: <399D3222.9D842AB5@cybercable.tm.fr> References: <877l9hffel.fsf@nwalsh.com> <399D1972.41D2ABAC@cybercable.tm.fr> <00081817110500.03504@needaguru> X-SW-Source: 2000/msg00332.html b_maddy_016@yahoo.com wrote: > > Hi, > On Fri, 18 Aug 2000, eric wrote: > > Norman Walsh wrote: > > > > > > / Volker Paul was heard to say: > > > | Hello, > > > update your catalog(s). Or convert the public ID to DocBook V3.1, which > > > you probably have on your system and which is backwards compatible with > > > 3.0. > > > > Or if you want to use the latest docbook-tools: > > - make sure you installed docbook-dtd30-sgml package > > - that's all ;-). jw now autodetects the catalogs to use. > > > > -- > > Éric Bischoff - Documentation and Localization > > it would have helped volker paul and many others including me if it was > mentioned from where it can be downloaded Bis repetita non semper placent, sed... ftp://sourceware.cygnus.com/pub/docbook/new-trials/ -- Éric Bischoff - Documentation and Localization Caldera (Deutschland) GmbH - Linux for eBusiness Tel: +49 9131 7192 300 - Fax: +49 9131 7192 399 http://www.caldera.de/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: esr@thyrsus.com Cc: 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: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000/msg00229.html "Eric S. Raymond" writes: > Again, a symptom, In the document "A Practical Introduction to DocBook", > the Tools section contains the following blatant cop-out: > > "Unfortunately, installing and configuring DocBook Tools is > (currently) outsidethe scope of this document." > > Anyone not already eyebrow-deep in the dysfunctional culture surrounding > this software would realize that this lacuna makes the rest of the > chapter a bad joke. Your problem installing the tools seemed (as I read back through the thread) to be one of finding a mirror that was bad. Once you found a mirror which contained the RPMs needed are we to assume the installation went according to plan? If so, I would say you found help rather easily (through this list) and it is indeed outside the scope of the document I pointed you to.(If you want the packages for Debian please 'apt get' them) Now you will find that such a document - and Norm's book will give you a fine introduction on how to create a DocBook document. Is this correct? After that you need to find out how to use the scripts - correct? Well the document I sent you to *has* each script and how to use it. That *was* within the scope... or did you stop reading after the installation section? Can all of this be improved for the newbie - it sure can. In fact new scripts or even applications can be written. You are a hacker, would you like to write them? Can I assume the answer is no? It is very easy to blame the SGML community for the problems inherent to understanding the technology, it is not as easy to lend a hand. Why is that? Do hackers think that documentation tools are beneath them until they actually have to use them? Slamming someone's book certainly cannot help you learn can it? Especially when you are talking about someone who has put more into bringing SGML/XML into the open source community than even he might realize. Would you rather him not have written *any* book? I say 'kudos' to Norm for the following: 1) Keeping DocBook moving and up to date with the trends of writing for computer documentation 2) Keeping two sets of fully functional stylesheets (DSSSL and XSL) applicable to DocBook and ready to use 'out of the box'. 3) Convincing a company to publish a *free* book on DocBook 4) Taking his time to write said book 5) Keeping the reference documentation up to date (have you seen the quick guide reference section? I use it everyday and I know most of the tags in docbook) 6) Finally, doing all of this in a cross platform, open source model. Oh, and lets not forget the fact that even though he eclipses me in the number of mailing lists he is on, he still answers every personal question I have ever sent (and probably everyone else's). Can you find an equivalent figure in the open source community? I would say that this person is following the model presented in the 'Cathedral and the Bazaar' rather closely - are you? Dave -- David Mason Red Hat Advanced Development Labs dcm@redhat.com (919)547-0012 x248 From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: esr@thyrsus.com Cc: 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: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> X-SW-Source: 2000/msg00232.html "Eric S. Raymond" writes: > Oh, no. That wasn't my only problem by a long shot. I actually went > through three different attempts to get three different sets of tools > running -- Jade, OpenJade, and the DocBook tools. Not one of them had > adequate documentation for beginners, even technically sophisticated > beginners like me with considerable prior knowledge of SGML (I did a > lot of of extension work on SGML-Tools for the LDP). All three have > web pages that are remarkable for the amount of detail they convey > without actually saying anything useful. Then I still don't understand the problems you are having... or at least, I still haven't seen a detail of what you would like to see. I think the ' Practical Guide...' is a very good intro to the scripts and creating a DB document - its short, to the point, and includes, what I think, you need to get started. But again, I can't figure out except the mirror stuff, what is wrong...I'd like to help > Do you mean like the user's guide I once wrote for SGML-Tools to > address exactly this problem? :-) > > Sorry, David. You don't get to accuse *me* of carping without > contributing. I happen to be the person who made SGML-Tools 1.1 > usable for fast-turnaround book publishing, proved it by producing > "Linux Undercover" for Red Hat, and then documented what I did. But > don't take my word for any of that -- go ask Ed Bailey about it. You'd > probably find the story both entertaining and instructive. I had no idea you did the first SGML-Tools and I apologize, you are a single entity in that case. Otherwise, I find that most hackers ignore these tools altogether. My apologies. Still, my problem is this thread has been about the lack of documentation for DocBook - but I still don't understand what the problem you are having is. I feel there is quite a bit of documentation out there, and if I knew the problem I could point you to it... if not, I could write it (especially since I am going to do a DocBook talk at OLS, this info would help me). Otherwise complaining about one or two particular documents doesn't do any good. You have stated why you didn't like Norm's book, you stated you didn't like the installation section in the 'Practical Guide...' HOWTO... so what do you want? Need? Is it *really* helpful to point out flaws in those particular documents when there might be one that answers your question? Dave -- David Mason Red Hat Advanced Development Labs dcm@redhat.com (919)547-0012 x248 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: 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: <768zvf9mdh.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <76g0pnjhmt.fsf@odie.lanl.gov> <20000706134507.D25726@thyrsus.com> <14692.50781.521325.126382@cmpu.net> X-SW-Source: 2000/msg00228.html Kendall> As for actually setting up and installing the various Kendall> permutations of the free tool chain, I just don't see why Kendall> it's *so* hard for someone with a bit of technical Kendall> ability or experience. It isn't. The person who started this thread said there was no tutorial which includes setting up the tools, but there actually was. Although things are out of date, this whole thread is mostly unnecessary. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: Mark Galassi , 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: <00070613480700.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <14692.50781.521325.126382@cmpu.net> <768zvf9mdh.fsf@odie.lanl.gov> X-SW-Source: 2000/msg00231.html On Thu, 06 Jul 2000, Mark Galassi wrote: > Kendall> As for actually setting up and installing the various > Kendall> permutations of the free tool chain, I just don't see why > Kendall> it's *so* hard for someone with a bit of technical > Kendall> ability or experience. > It isn't. The person who started this thread said there was no > tutorial which includes setting up the tools, but there actually was. > Although things are out of date, this whole thread is mostly > unnecessary. Futile, perhaps. Unnecessary, no. I am constantly fighting The Cult Of Obscurity both on the job and off it, because so many good technical people just don't see what's wrong with their documentation and programming. "It makes sense to me, other people must just be stupid" is the attitude of the typical adherent of the Cult of Obscurity. I sometimes have to fuss at my own co-workers about "Look, I don't care about details x, y, and z, I, the hypothetical the end user, just want to get job 'n' done", and I'm certainly not going to be reticient about doing the same elsewhere, even if I'm not being paid to do it elsewhere :-). People do not care about elegance. They do not care about how terse and formal the language is surrounding a topic. They just want to get a job done with as few keystrokes or mouse clicks as possible, and learning as few details as possible to do it. This is one place where Lamport's LaTeX book shines (despite how aweful it is otherwise), the first thing he does is say, "Here is how you write a letter in LaTeX." What genius! Regarding Norm Walsh's book: the biggest problem was a lack of examples of how to use DocBook to create entire documents. There's reasonably good examples of the use of many of the individual elements, but nothing like where Lamport says, "Here is how you create a document. Here is how you create a letter. Here is how to create a document that has a table in it." Lamport's LaTeX book sucks... but it sucks in a way that lets most people write simple documents after reading it. Note that I'm not calling the SGML crowd stupid. I'm not saying that their documentation "sucks" for people who are already initiated into the Cult Of SGML. What I'm saying is that a) there's a paucity of documentation about how to Get The Job Done, the only one I know about is the FreeBSD one, and b) there has been a lack of attention to Getting The Job Done on the part of the SGML community as a whole, they have been absorbed in the technical excellence of SGML, the theoretical possibilities of parsing SGML, the stylistic elegance of DSSL and stylesheet languages, whilst ignoring the whole point of the exercise. I realize this is not an attitude that is restricted to the SGML crowd. This sort of attitude is rampant in the computer biz, those of us who have a good understanding of end user wants and needs are always the minority, and those of us with both technical skills and writing skills are even rarer. But, as the other Eric mentioned, this sort of attitude is also what kept SGML from sweeping the world over the last five years, and is what basically has killed SGML (with the exception of the HTML DTD and XML subset, the former of which isn't really SGML anymore). 'Nuff said. I'm sure I'll find many more flames in my mailbox from adherents of the Highly Theoretical Cult of SGML Gurus. But (shrug), when it comes to document production, I'm an end user. I design tape backup and related software for a living, not documentation tools. All I want to do is to get a job done. I don't CARE about how elegant DSSL is, or how flexible the Docbook DTD is... it's a tool, for cryin' out loud, not a religion. And if it doesn't Do The Job, I'll dump it and use some other tool. Which, apparently, has been the conclusion of most others who would use SGML, too, with the exception of a few of the Open Source projects which use it because that's what the LinuxDoc project uses. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <87wviym26y.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> <20000706195444.D27191@thyrsus.com> X-SW-Source: 2000/msg00249.html / "Eric S. Raymond" was heard to say: With respect to this comment, | As it is, the fact that the | power of these techniques is surrounded by a near-impenetrable thicket | of theology and jargon is deeply frustrating to me -- and the apparent | inability of SGML people to see that this is an issue is maddening! And bearing in mind something you said earlier, | You [...] can | start being offended the day I don't respect you enough to criticize | your work. I feel compelled to reply: First, you're mistaken. As the reader of your comments, I'm free to become offended whenever I bloody well choose. Second, I'm tired of your whining about the theology and jargon. I'm sorry if TDG didn't answer your questions, I'll try to do better next time (although I still think it's an authors prerogative to decide what is and what is not in scope), but I don't think it's either theological or jargon-filled. It seems to me that the bulk of your ranting boils down to: "The tools one needs to format a DocBook document and get HTML or print output are insufficiently documented and too hard to install and use." I haven't heard a single person disagree with you. And in the two years since you first encountered DocBook, tremendous progress has been made. I'm committed to seeing that, to the extent I can contribute, the progress continues until it's as nearly dead easy as possible. Now would you please stop flogging me for not moving fast enough. I ain't your whipping boy, son. | Really. What would it have cost to supply *one* explicit example of | a document-production flow on Unix and Windows? A few pages could have | made a huge difference -- in helpful symbolism, even if it couldn't | cover all the substance. Now that's an interesting question. You might be right. | As it is, one is left with the impression that Mr. Walsh was so caught | up in the arcana of Scheme and CSS and DTD composition that he couldn't be | bothered to descend to the level of actually showing the reader how to | actually use any of it. For the record, my thought process went something like this. "Today (when I was writing) things are still pretty immature. I could try to document one of the many possible tool sets, but then I'd be leaving out all the others, not to mention the commercial tools from Arbortext, Frame, and Softquad to name but three. And there's no tool set that works equally well on Unix and NT, so I'd have to do at least two. Things will be better soon and the installation instructions for the individual tool sets can do a better job on installation than I can. Heck, I don't even have a Linux box at hand these days. The vast majority of questions that I get aren't about specific tools, people seem to get those installed, they're about how to customize X, Y, or Z in the stylesheets. Since the DSSSL stylesheets form the core of several tool sets, end users would be better served by some explanation of how to use and customize those." | (All right, everybody. Calm down -- I'm not claiming that was his actual | state of mind, simply that that is the message the book sends.) And the message you send is...oh, nevermind. | > The important point | > here is that we need to get away from the mentality that | > introductory/tutorial texts are for clueless newbies, that hard-core | > reference material is the only truly important documentation. The | > introductory stuff makes the technology accessible to people that | > would otherwise not have access. | | Amen. Squared... Cubed, even. Be seeing you, norm -- Norman Walsh | Whatever you may be sure of, be sure of http://nwalsh.com/ | this: that you are dreadfully like | other people.--James Russell Lowell From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Edward C. Bailey" To: 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: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000/msg00239.html >>>>> "esr" == Eric S Raymond writes: esr> David C. Mason : >> Then I still don't understand the problems you are having... or at >> least, I still haven't seen a detail of what you would like to see. esr> I'd like to see documentation that spends less time genuflecting esr> before the wonderfulness of semantic markup and stylesheets, and more esr> time telling me how I can install and configure working tools and make esr> HTML and Postscript from actual documents. I wonder if SGML documentation's current focus on the theoretical versus the practical is an evolutionary backwater from the days when people using the technology had to explain why they were "doing things the 'hard' way with SGML" when most people doing documentation were simply using whatever tools they happened to have available. Even if this was the case at one point in time, I think we all agree that most people "get it" when it comes to markup languages (if for no other reason than all the hype XML has brought to our part of the world). So it's time to move on, and leave the Cult of the Sacred Tag mentality behind us now... :-) ... esr> Is it just me? Am I crazy to think there's something wrong with a esr> 600-page tome on document production tools that *never once tells you esr> how to format a document?* To be honest, and at least in the case of _DocBook: The Definitive Guide_, I think it's just you. The book is a reference describing a particular markup language. That markup language is processed by a wide variety of software (both open source and non-) on a wide variety of platforms (again, both open source and non-). To have this particular reference guide get into how the markup language is processed by one particular application on a subset of the possible platforms would be something similar to HP including a chapter called "Using Your New Printer to Print Romance Novels" in every LaserJet owner's manual. :-) That's not to say that there *shouldn't* be a book that does just what you describe. I strongly agree with you that this kind of information should be in a book somewhere. I just don't think _DocBook: TDG_ is that book. esr> The unbelievable part is that it's *all* like that. It's not just the esr> individual authors of these particular documents that are high priests esr> of the Cult of Obscurity -- every piece of documentation I've ever esr> seen from the DocBook/SGML community is pretty much off in theoretical esr> cloud-cuckoo land. I can learn more than I ever wanted to know about esr> DSSL and FOSI and fifty other acronyms, but I can't find any clue esr> about what to do when jadetex generates bad Postscript that makes gs esr> choke. esr> What I want to see is a practical guide that is truly a practical esr> guide -- something like what I wrote for SGML-tools, but covering esr> DocBook. I feel compelled to preface my comments by saying that my goal is neither to cut anyone down, nor to build myself up. But I have a bit of background here that leads me to the following observations: o If you were to change a few of the terms in ESR's comments, you'd have almost exactly the same kinds of feedback we at Red Hat get from users regarding the state of Linux documentation today. So those of us that do documentation for one or more open source software projects should keep in mind that we ain't done yet -- not by a long shot. This complaint is true for DocBook documentation, and it's true for many (most? all?) open source software projects. o Since ESR has worked with me, he knows I'm not the sharpest knife in the kitchen (and hopefully feels that I'm at least not the dullest, either :-). Yet he's confounded trying to format DocBook documents, while I've been able to convert over 1500 pages of LaTeX-based documentation into DocBook, and to create the tools necessary to support a production environment to produce DocBook-based content here at Red Hat. What's the difference? Time. It was my full-time job to make the move to DocBook, while ESR is probably lucky if he can devote an hour here and there to the task. The important point here is that we need to get away from the mentality that introductory/tutorial texts are for clueless newbies, that hard-core reference material is the only truly important documentation. The introductory stuff makes the technology accessible to people that would otherwise not have access. And as I'm sure ESR can vouch, being treated like a clueless newbie, on the outside looking in, sucks. esr> Don't get an exaggerrated idea of my creds, either. I didn't write esr> SGML-tools, nor was I ever its official maintainer. I did one really esr> serious burst of work on it around 0.99-1.0 -- basically so I could esr> pull Red Hat's nuts out of the fire after Bob Young asked me nicely to esr> fix the godawful mess their old TeX-centric production process had esr> degenerated into. Point of clarification -- ESR helped us replace a contractor (with a largely manual and TeX-centric production process) that seemed to be unable to deliver the goods when promised. That said, the end result still was the extraction of said gonads from the conflagration -- and in a most elegant fashion... :-) Ed -- Ed Bailey Red Hat, Inc. http://www.redhat.com/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Norman Walsh Cc: 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: <20000707122209.B30286@thyrsus.com> References: <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> <20000706195444.D27191@thyrsus.com> <87wviym26y.fsf@nwalsh.com> X-SW-Source: 2000/msg00256.html Norman Walsh : > Second, I'm tired of your whining about the theology and jargon. I'm > sorry if TDG didn't answer your questions, I'll try to do better next > time (although I still think it's an authors prerogative to decide > what is and what is not in scope), but I don't think it's either > theological or jargon-filled. In this respect (if not in others), you and the other core DocBook people who share this belief are still out to lunch. And that's sad, because it seriously hinders the deployment of your good work. > It seems to me that the bulk of your ranting boils down to: > > "The tools one needs to format a DocBook document and get HTML or > print output are insufficiently documented and too hard to install and > use." Nope, see above. The fact that SGML initiates can't see how impenetrable their sacred texts are is a larger problem than the lack of documentation for specific tools -- because it means that said documentation is unlikely to get written or reviewed by exactly those who ought to be best qualified to do it. Instead, hapless schlubs like me end up jerry-rigging together things like the SGML-Tools user's guide...and feeling very ill-served by an SGML community that seems unwilling to climb down from their heights of abstraction. > Now would you please stop flogging me for not moving fast enough. I > ain't your whipping boy, son. "Floggings will continue until morale improves." :-) No, in fact, I'm not flogging you for moving too slowly. I'm flogging you for an apparent inability to understand "motion" at all. I'll stop when you either clue in or my arm gets tired. If we're both committed to excellence of results, it *is* my job to do that, and your job to cope with it. Welcome to the sharp end of peer review, daddy-o. > | Really. What would it have cost to supply *one* explicit example of > | a document-production flow on Unix and Windows? A few pages could have > | made a huge difference -- in helpful symbolism, even if it couldn't > | cover all the substance. > > Now that's an interesting question. You might be right. And this is a perfect example of not understanding motion. You are, by all accounts, an intelligent and well-intentioned person with a considerable capacity for both creativity and hard work. You are also a pretty good writer -- there is nothing wrong with DTG's prose at the microlevel. So why didn't *you* figure one out this out two years ago? Why does it take an outsider, jumping up and down and screaming, to point out the obvious? If and when you achieve enlightenment on this koan, I think the root problem of the SGML culture will also be clear to you. (I deeply regret that I wasn't on DTG's pre-pub review list...) > | (All right, everybody. Calm down -- I'm not claiming that was his actual > | state of mind, simply that that is the message the book sends.) > > And the message you send is...oh, nevermind. Uh huh. "The meaning of a communication is not what is sent, but what is received." If you really understood that and had acted on it, DTG would have been a better book. This is not academic criticism, nor is it consigning DTG to the trash heap. I've written two pretty successful books (one technical, one mass-market) and substantial portions of three others. I do a lot of technical review work. DTG's strengths and its weaknesses are both characteristic of books written by experts with both an unsurpassed grasp of their technical domain and a near-complete inability to view that domain from outside. -- Eric S. Raymond "They that can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety." -- Benjamin Franklin, Historical Review of Pennsylvania, 1759. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "David C. Mason" , esr@thyrsus.com Cc: 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: <00070614320401.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000/msg00233.html On Thu, 06 Jul 2000, David C. Mason wrote: > "Eric S. Raymond" writes: > > Anyone not already eyebrow-deep in the dysfunctional culture surrounding > > this software would realize that this lacuna makes the rest of the > > chapter a bad joke. > > It is very easy to blame the SGML community for the problems inherent > to understanding the technology, it is not as easy to lend a hand. Why > is that? Do hackers think that documentation tools are beneath them > until they actually have to use them? Well, unfortunate but true, most hackers are no good at documentation. This applies to SGML software creators as well :-(. Equally unfortunate but true, most hackers have no idea how end users think, and thus have no idea how to create software that is easy to understand and easy to use that solves problems that end users actually have. They tend to get caught up in making the software super-flexible and super-swiss-knife, which is nice but not at the expense of ease of solving particular problems. I had to fight for the concept of "click this single button, and it does what 90% of users want out of our software" when it came to prototyping a potential future product, because the hacker who designed the thing had a screen cluttered with stuff that would confuse the typical end user and which was not intuitive at all. But it made sense to him. He didn't understand that most people are not hackers and don't think like hackers. Finally: those of us who are actually being paid to write documentation rarely are getting paid to write documentation tools at the same time, and in most cases even writing documentation is not our full-time job (I write documentation as part of designing software -- you know, requirements docs, functional specifications, design docs, class heirarchy docs, etc.). In addition, we're often fighting pointy-haired bosses who want us to use Microsoft Word or StarOffice or whatever "standard" office suite the corporation has adopted, and who (having never written anything larger than a letter) don't understand that structured document layout systems are much more appropriate for technical documentation. To put the blame on the end user for the poor state of Docbook/SGML documentation and tools is a case of blaming the victim... we're just out here trying to do a job, not fight religious wars, and we have enough trouble getting permission to use any kind of SDL system without having to fight a buggy one as well. As it is, I have to continually justify to my bosses my use of DocBook... they don't understand why I would want to use a SDL instead of the "corporate standard" office suite. Now you're going to blame me for the fact that I'm getting "-999" for half the page numbers in my index?! Sad but true, here in the real world the pointy haired boss's response to problems that we have generating documentation with the Docbook tools is "quit that Docbook BS and use Microsoft Word [StarOffice, WordPerfect, etc.] like the rest of us." WHich is why my next set of documentation is going to be using LyX/LaTeX. The tools work, they work reliably, they've worked reliably for years and years and years, they're not ideal but they get the job done and dammit, that's all I care about. And that's why SGML has remained a cult rather than a real solution for most people's documentation problems. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Mark Galassi Cc: "Eric S. Raymond" , 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: <20000704113106.A15838@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <76vgymvstw.fsf@odie.lanl.gov> X-SW-Source: 2000/msg00204.html Mark Galassi : > > Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page > Eric> directs me to > Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That > Eric> server is perpetually swamped. Going to one of the mirrors, > Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain > Eric> any of the db2* scripts referenced on the DocBook page. > Eric> Where are those scripts? > > There should be several RPMs on that ftp site. The scripts you seek > are in the stylesheets RPM. Also make sure you don't only get the > noarch RPMs. OK, what is the actual stylesheet RPM? You didn't specify, and all I can find is SRPMs and tarballs. Would it be too much to ask that these things actually be described on the DocBook tools page? Every time I go near SGML I get headaches... -- Eric S. Raymond Government is actually the worst failure of civilized man. There has never been a really good one, and even those that are most tolerable are arbitrary, cruel, grasping and unintelligent. -- H. L. Mencken From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "Edward C. Bailey" Cc: 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: <20000706195444.D27191@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000/msg00240.html Edward C. Bailey : > So it's time to move on, and leave the > Cult of the Sacred Tag mentality behind us now... :-) Indeed. And an important point: I wouldn't be so exercised about the Cult of the Sacred Tag if, on some level, I didn't grok that the SGML people have some reason behind the religion. If it was all just just bullshit, I could ignore it and go away. As it is, the fact that the power of these techniques is surrounded by a near-impenetrable thicket of theology and jargon is deeply frustrating to me -- and the apparent inability of SGML people to see that this is an issue is maddening! > esr> Is it just me? Am I crazy to think there's something wrong with a > esr> 600-page tome on document production tools that *never once tells you > esr> how to format a document?* > > To be honest, and at least in the case of _DocBook: The Definitive Guide_, > I think it's just you. [...] To have this particular reference guide get > into how the markup language is processed by one particular application on > a subset of the possible platforms would be something similar to HP > including a chapter called "Using Your New Printer to Print Romance Novels" > in every LaserJet owner's manual. :-) No, I'd say it's more like supplying schematics and chip masks for the printer's electronics and neglecting to document the front-panel controls. Really. What would it have cost to supply *one* explicit example of a document-production flow on Unix and Windows? A few pages could have made a huge difference -- in helpful symbolism, even if it couldn't cover all the substance. As it is, one is left with the impression that Mr. Walsh was so caught up in the arcana of Scheme and CSS and DTD composition that he couldn't be bothered to descend to the level of actually showing the reader how to actually use any of it. (All right, everybody. Calm down -- I'm not claiming that was his actual state of mind, simply that that is the message the book sends.) > o If you were to change a few of the terms in ESR's comments, you'd > have almost exactly the same kinds of feedback we at Red Hat get from > users regarding the state of Linux documentation today. So those of > us that do documentation for one or more open source software > projects should keep in mind that we ain't done yet -- not by a long > shot. This complaint is true for DocBook documentation, and it's > true for many (most? all?) open source software projects. Yup. That's why I maintain, at last count, eight (8) different technical FAQ documents. > The important point > here is that we need to get away from the mentality that > introductory/tutorial texts are for clueless newbies, that hard-core > reference material is the only truly important documentation. The > introductory stuff makes the technology accessible to people that > would otherwise not have access. Amen. Squared... -- Eric S. Raymond "Rightful liberty is unobstructed action, according to our will, within limits drawn around us by the equal rights of others." -- Thomas Jefferson From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ismael Olea To: 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: <396368E9.95CC5D75@hispalinux.es> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> <00070422425701.09328@ehome.inhouse> <002501bfe690$04331940$1403a8c0@cogent.ca> X-SW-Source: 2000/msg00219.html Sam Roberts escribió: > them. You can use jade without docbook or norm's style sheets, you can use > jadetex without using docbook, the db2* scripts are so optional most people > write their own, and you don't have to use emacs to edit sgml, but it helps. We have a little problem with these tools. There aren't a more-or-less sgml suite made of components (packages) with well made package dependeces. Then, if you want to use linuxdoc, your package system'll ask for sp, linuxdoc-dtd and its filters. If you want XML DocBook, the packages we all know. Add a new package (TEI?) could need to add it's dtd, the stylesheets and maybe some interface. What do you think? -- A.Ismael Olea González mailto:olea@hispalinux.es http://www.hispalinux.es/~olea 2:345/108.9@fidonet.org El mundo debe empezar a tener miedo a un planeta DEF From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Bischoff To: Norman Walsh Cc: Volker Paul , 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: <399D1972.41D2ABAC@cybercable.tm.fr> References: <3998DF53.D2C430F5@cybercable.tm.fr> <399A9F34.A10C59AB@dohle.com> <877l9hffel.fsf@nwalsh.com> X-SW-Source: 2000/msg00330.html Norman Walsh wrote: > > / Volker Paul was heard to say: > | Hello, > | > | trying to run Jade, I get the following error message: > | > | jade:myfile.sgml:1:59:W: cannot generate system identifier for public > | text "-//Davenport//DTD DocBook V3.0//EN" > | jade:myfile.sgml:2:1:E: reference to entity "BOOK" for which no system > | identifier could be generated > | jade:myfile.sgml:1:0: entity was defined here > | jade:myfile.sgml:2:1:E: DTD did not contain element declaration for > | document type name > | jade:myfile.sgml:3:6:E: element "BOOK" undefined > | jade:myfile.sgml:4:12:E: element "BOOKINFO" undefined > | > | I suppose Jade hasn't the (right) DTD. How do I tell Jade > | where it is? > > Get DocBook V3.0 from OASIS, put it somewhere on your system, and > update your catalog(s). Or convert the public ID to DocBook V3.1, which > you probably have on your system and which is backwards compatible with > 3.0. Or if you want to use the latest docbook-tools: - make sure you installed docbook-dtd30-sgml package - that's all ;-). jw now autodetects the catalogs to use. -- Éric Bischoff - Documentation and Localization Caldera (Deutschland) GmbH - Linux for eBusiness Tel: +49 9131 7192 300 - Fax: +49 9131 7192 399 http://www.caldera.de/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: Chuck Dale To: 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: <20000707145703.A23174@aphid.net> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> X-SW-Source: 2000/msg00242.html Wrote Norman Walsh on Thu, Jul 06, 2000 at 12:21:20PM -0400: > / Eric Lee Green was heard to say: > | That puzzles me too. Even Norm Walsh's so-called "Docbook" book > | reads as if it were a briefly written summary written in a foreign > | language to be as terse as possible. > > I'm sorry you found it to be that way. That wasn't the intent. > Although the bulk of the book is intended as a reference and not a > how-to, the introductory chapters were supposed to be readable by the > novice. Can you explain, in any more detail, what you found most > troubling? Get to the point. An introduction should explain the essence of DocBook, give a few examples of how to do it, and give the user some ideas where to start using the tools. Some diagrams would be useful. Such as: Structured document editing ( DocBook markup + stylesheet = output ) Don't talk about SGML/XML explicitly in the introduction - explain an example of DocBook. DocBook is very easy and mostly self explanatory so you will have little to do. I had to read more than half TDG to get the bigger picture of DocBook - I was reading about Public/System Identifiers before I even knew the very basics of writing a DocBook document. All the entities and identifiers stuff went straight over my head first time through. Other than that I liked TDG a lot! =) Chuck From mboxrd@z Thu Jan 1 00:00:00 1970 From: Volker Paul To: Eric Bischoff Cc: 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: <399A9F34.A10C59AB@dohle.com> References: <3998DF53.D2C430F5@cybercable.tm.fr> X-SW-Source: 2000/msg00328.html Hello, trying to run Jade, I get the following error message: jade:myfile.sgml:1:59:W: cannot generate system identifier for public text "-//Davenport//DTD DocBook V3.0//EN" jade:myfile.sgml:2:1:E: reference to entity "BOOK" for which no system identifier could be generated jade:myfile.sgml:1:0: entity was defined here jade:myfile.sgml:2:1:E: DTD did not contain element declaration for document type name jade:myfile.sgml:3:6:E: element "BOOK" undefined jade:myfile.sgml:4:12:E: element "BOOKINFO" undefined I suppose Jade hasn't the (right) DTD. How do I tell Jade where it is? Regards, Volker Paul From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <87vgyinj8n.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> <00070422425701.09328@ehome.inhouse> X-SW-Source: 2000/msg00250.html / Eric Lee Green was heard to say: | Unfortunately, the SGML purists appear to believe that their job is | done once they've created the raw DTD... "just read the DTD!" | appears to be the notion. Reading the DTD isn't going to help at all with the problem of setting up a toolchain, so I'm confused. Are you saying that SGML/XML are not well described? Or that a particular DTD (e.g, DocBook) is not well described? Or that the mechanics of setting up a toolchain (on your system, for the output you want) are not well described? | Correct. I've already discussed the notion that SGML purists appear | to believe that their job is done once they've created the raw DTD | and (optionally) style sheet. An SGML purist *is done* when they've created the doctype (or Schema). That's the job you hire them to do. (Note that a doctype includes prose documentation, a .dtd file isn't enough and was never believed to be enough.) That said, I don't consider myself a purist and I've spent a lot of time writing stylesheets and documenting them as best I could under the constraints of time and a day job. No one (that I know) would be silly enough to argue that you *don't need* a toolchain, but there is tremendous variablity in setting up the toolchain. Thanks to the tremdous effort of folks involved in efforts like docbook-tools, we're beginning to see open source distributions of tools that can be reasonably documented and will produce results for lots of folks on lots of platforms. This is a welcome change for those of us who have been lamenting the fact that SGML was almost completely a "build your own" environment for so many years. | This attitude is what has prevented | SGML from supplanting TeX/LaTeX for structured document creation. Prevented where? Oh, nevermind, it's an inflammatory remark. | I have taken to running jadetex by hand until the 'unresolved | reference' messages go away, then running dvi2ps by hand. Some of my | page references STILL turn out to be -999. I've forgotten where this started. These are TOC page references or index page references? | > that situation is not likely to improve what with SGML is dead | proclamations > doing the rounds and shift is towards XML . but | again tools for XML are not unix > favorable at all . For the purposes of this discussion, XML is SGML. There's no appreciable difference. Be seeing you, norm -- Norman Walsh | All professional men are handicapped by http://nwalsh.com/ | not being allowed to ignore things | which are useless.--Goethe From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <87d7kqni2o.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <14692.50781.521325.126382@cmpu.net> <768zvf9mdh.fsf@odie.lanl.gov> <00070613480700.15291@ehome.inhouse> X-SW-Source: 2000/msg00251.html / Eric Lee Green was heard to say: | Regarding Norm Walsh's book: the biggest problem was a lack of | examples of how to use DocBook to create entire documents. There's | reasonably good examples of the use of many of the individual | elements, but nothing like where Lamport says, "Here is how you | create a document. Here is how you create a letter. Here is how to | create a document that has a table in it." Lamport's LaTeX book Fair cop. It needs more of that. Be seeing you, norm -- Norman Walsh | An ill-humoured man is a prisoner at http://nwalsh.com/ | the mercy of an enemy from whom he can | never escape.--Sa'di From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <874s62oypi.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <76vgymvstw.fsf@odie.lanl.gov> <20000704113106.A15838@thyrsus.com> X-SW-Source: 2000/msg00247.html / "Eric S. Raymond" was heard to say: | OK, what is the actual stylesheet RPM? You didn't specify, and all I | can find is SRPMs and tarballs. | | Would it be too much to ask that these things actually be described | on the DocBook tools page? No, that's a good idea. If someone sends me some appropriate text, I'll be happy to put it on the tools page. Be seeing you, norm -- Norman Walsh | If you are hankering after certainty, http://nwalsh.com/ | you are better advised to seek it in | religion: the stock-in-trade of science | is not certainty but doubt.--K.C. Cole From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: Eric Lee Green Cc: "Eric S. Raymond" , 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: <873dlnjklb.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000/msg00221.html / Eric Lee Green was heard to say: | That puzzles me too. Even Norm Walsh's so-called "Docbook" book | reads as if it were a briefly written summary written in a foreign | language to be as terse as possible. I'm sorry you found it to be that way. That wasn't the intent. Although the bulk of the book is intended as a reference and not a how-to, the introductory chapters were supposed to be readable by the novice. Can you explain, in any more detail, what you found most troubling? | It's bad enough that the authors of every book and document that exists on SGML | have invented their own inscrutable terminology for the process of marking up | documentation... but none of them, zero, zilch, appears to have considered the | notion of a GLOSSARY, and the very thought of explaining complex terms in a | simple, clear manner appears to break every single SGML author out in hives. | Yes, it's difficult. I've done it before, I know how difficult it is. But it's | as if the creators of SGML DTD's and tools have a death wish... or else they're | trying to protect their cult's purity by keeping out the riff-raff (same | thing). It is an unfortunate fact that Goldfarb created a set of concise, technical terms for describing the various components of SGML markup. On the one hand, using these terms precisely tends to be awkward for novices. On the other, using other terms causes confusion among other audiences. I really tried to be clear in this regard. Be seeing you, norm -- Norman Walsh | Everything is temporary. http://nwalsh.com/ | From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "Eric S. Raymond" , 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: <00070410352500.07357@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> X-SW-Source: 2000/msg00208.html On Tue, 04 Jul 2000, Eric S. Raymond wrote: > I'm trying to set up docbook-tools, and finding it a hideously > frustrating experience. Why does all the SGML software and > documentation in the world read as though it was carefully designed > to prevent any actual document production from getting done? That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it were a briefly written summary written in a foreign language to be as terse as possible. You would suspect that the authors of documentation tools would themselves be enamored of documentation. WIth the exception of Donald Knuth, that, alas, does not appear to be the case. It's bad enough that the authors of every book and document that exists on SGML have invented their own inscrutable terminology for the process of marking up documentation... but none of them, zero, zilch, appears to have considered the notion of a GLOSSARY, and the very thought of explaining complex terms in a simple, clear manner appears to break every single SGML author out in hives. Yes, it's difficult. I've done it before, I know how difficult it is. But it's as if the creators of SGML DTD's and tools have a death wish... or else they're trying to protect their cult's purity by keeping out the riff-raff (same thing). Despite all of the above, I have become reasonably proficient in using the Docbook-Tools set and in Docbook itself. But the tool kits still do not work well enough for me to actually use them to produce real documentation. I am using Docbook for the design documentation for a major project at the office, but nobody on this list has been able to explain to me why half the entries in my index have "-999" as the page number, even when the 'jadetex' script does not complain about unresolved references. I've even tried updating everything from the Docbook-tools site thinking maybe Red Hat had a wonked out docbook-tools installation. I even tried using Caldera eDesktop 2.4 rather than Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No go. I'm on the verge of abandoning the tool kit in frustration. LyX will now generate decent HTML output, which was my main reason for using DocBook in the first place (the difficulty of getting good HTML output out of "latex2html" and its ilk). My only issue with LyX is the difficulty of maintaining multi-source documentation in a CVS depository... CVS won't do merges of multi-author edits of .lyx files, sigh. But if it's a choice of LyX or using StarOffal, I know which I'll choose -- at least LyX is a structured markup tool, whereas StarOffal.. no, don't get me started. > The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to > < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That server is > perpetually swamped. Going to one of the mirrors, I find a > docbook-3.1-5.noarch.rpm, but it does not contain any of the db2* > scripts referenced on the DocBook page. Where are those scripts? On Red Hat 6.2 Linux, they're in "stylesheets-1.54.13rh-1.xxx.rpm" (put architecture of choice in place of 'xxx'). Red Hat ships with what is basically a slight tweak of the docbook-tools kit. 'docbook-3.1-5.noarch.rpm' is just the DTD (Data Type Definition), it does not contain the other software you'll need to convert programs written using that DTD into a useful form. You'll need 'jade' and 'stylesheets' to do that. 'jade' is the actual grunt engine, while 'stylesheets' is the Scheme and scripts that the grunt engine uses to know how to do the conversion. export SGML_CATALOG_FILES=/usr/lib/sgml/CATALOG export SGML_ROOT=/usr/lib/sgml are also nice to tell Emacs's psgml mode where to find the overall catalog and SGML dtd and tools. I use 'xemacs', which puts up a nice SGML menu at the top. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Bischoff To: Peter Ring Cc: 'Volker Paul' , "'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: <3998DF53.D2C430F5@cybercable.tm.fr> References: X-SW-Source: 2000/msg00327.html Peter Ring wrote: > > I missed the re-start of this thread. Anyway, in case you didn't care to > search the archives, I'd like to re-post a list of a number of > introductions, most of which have been available for a while (read: long > before Eric Raymond started whining). Mark, What about putting all these links on the web page? Here is a completed list: A Crash-Course to DocBook http://public.lst.de/~eric/index.html An Introduction to DocBook http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html A Practical Introduction to DocBook http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html DocBook HOWTO http://metalab.unc.edu/godoy/using-docbook/using-docbook.html Practical information about the use of SGML/XML and DocBook on Debian http://www.debian.org/~bortz/SGML-HOWTO/potato/howto.html Practical information about the use of SGML/XML and DocBook on WindowsNT http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html A fairly complete guide to O'Reilly's DocBook based production system http://www.oreilly.com/people/staff/crism/dsssl/orastyle/index.html A fairly complete guide for contributors to the FreeBSD Documentation Project http://www.freebsd.org/tutorials/docproj-primer/ -- Éric Bischoff - mailto:ebisch@cybercable.tm.fr __________________________________________________ \^o~_. .~. ______ /( __ ) /V\ Toys story \__ \/ ( V // \\ \__| (__=v /( )\ |\___/ ) ^^-^^ \_____( ) Tux Konqui \__=v __________________________________________________ From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: esr@thyrsus.com Cc: 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: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000/msg00236.html "Eric S. Raymond" writes: > I'd like to see documentation that spends less time genuflecting > before the wonderfulness of semantic markup and stylesheets, and more > time telling me how I can install and configure working tools and make > HTML and Postscript from actual documents. Hmmm I just don't see either of the online documents (Mark's or Deb's) "genuflecting before the wonderfulness of semantic markup.." I do see them telling you how to use the tools to "produce actual, viewable HTML or Postscript from an actual document". You are correct that there is not very good documentation for the installation and that is partly due to the fact that depending on the flavor of Linux or UNIX you are using, it is different. However, that will change with the new DB Tools being created which includes a nice proposal to the LSB to make sure it is the same across the board. Once it is done I will be happy to write an installation guide for it. You are catching DocBook at a time when it is finally being recognized and used throughout many projects in Linux. The tools are not 100% satisfactory but they are being worked on as we speak. When tools are in flux, documentation is either non-existent or also in flux. That is the nature of the beast. We release early and release often, usually at the expense of good documentation and translation. If you want really good docs *now* perhaps try a commercial Windows product that uses DocBook. Otherwise wait, ask questions here or in other forums, or pitch in with the effort. The new tools will be used in a very different way, but with more functionality... I personally would like to start documenting those even though they are not available yet. > Let's start with replacing that cop-out in the so-called "Practical > Introduction". Please stop referring to people's work with words that are meant only to insult. I'm sure plenty of people could refer to your essays with venom, they perhaps choose not to as they know your heart is in the right place for writing them in the first place. > What I want to see is a practical guide that is truly a practical guide -- > something like what I wrote for SGML-tools, but covering DocBook. A technical author tends to want other's writing to be exactly as they write - its one reason why people have a hard time writing a book together. There isn't much to be done about that except write it yourself. I personally think that the Practical Guide is a great start - it is still in progress mind you, but it tells you the *exact* things you mentioned (besides the installation which I dealt with above)... I am staring at it... it tells you how to use the scripts, how to create a document, etc. Also keep in mind that DocBook Tools is not the only set of tools available for using DocBook. There are *many* tools available for the XML side of it... and I guarantee you you would come in with both guns blazing if you tried those tools... not one word of documentation. Why? They released early at the expense of good documentation/translation. > -- basically so I could pull Red Hat's nuts out of the fire after > Bob Young asked me nicely to fix the godawful mess their old > TeX-centric production process had degenerated into. What a gentleman like approach to telling me you worked on it. Dave -- David Mason Red Hat Advanced Development Labs dcm@redhat.com (919)547-0012 x248 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Peter Ring To: 'Volker Paul' , "'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: X-SW-Source: 2000/msg00326.html I missed the re-start of this thread. Anyway, in case you didn't care to search the archives, I'd like to re-post a list of a number of introductions, most of which have been available for a while (read: long before Eric Raymond started whining). A Practical Introduction to DocBook http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook -Intro/docbook-intro/index.html DocBook HOWTO http://metalab.unc.edu/godoy/using-docbook/using-docbook.html Practical information about the use of SGML/XML and DocBook on Debian http://www.debian.org/~bortz/SGML-HOWTO/potato/howto.html Practical information about the use of SGML/XML and DocBook on WindowsNT http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html A fairly complete guide to O'Reilly's DocBook based production system http://www.oreilly.com/people/staff/crism/dsssl/orastyle/index.html A fairly complete guide for contributors to the FreeBSD Documentation Project http://www.freebsd.org/tutorials/docproj-primer/ Kind regards, Peter Ring -----Original Message----- From: Volker Paul [ mailto:vpaul@dohle.com ] Sent: Monday, August 14, 2000 12:39 PM To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... > It isn't. The person who started this thread said there was no > tutorial which includes setting up the tools, but there actually was. > Although things are out of date, this whole thread is mostly > unnecessary. No, it's not unnecessary. I have a master in Computer science but for several days now, I'm trying to make my way throught the jungle of SGML stuff. This mail thread showed me that it's not me who is completely stupid, but other people have problems with the documentation, too. Thanks, Eric Raymond. Once you figured out how it works, could you please publish a good tutorial? Yours, Volker Paul From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: 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: <87hfa2ni9t.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000/msg00248.html / "Eric S. Raymond" was heard to say: | I don't think anybody doubts that it was your intention to be clear. | Your execution, however, completely failed in that respect. The Completely? Thanks. | failure seems to me to be an indicator of a wider problem in the | technical culture surrounding SGML, one I've bitched about before. Yes, you have. | Two years ago, I complained vociferously on the DocBook list that the | SGML culture had a pathological case of self-absorption and seemed to And with such vitriol and ranting that several respectable members of the list asked you to please be polite or go away. | unable to explain. For bringing this unwelcome news, I was flamed and | shunned. Is that how you saw it. How, um, symmetrical. | Can this be fixed? I don't know. The problem isn't any lack of | intelligence or good intentions on the part of the DocBook group. | There's something fundamentally disconnected and broken in the | attitude department, though -- an inability to see what the SGML | world looks like from the point of view of somebody who just | wants to get some work done. That's not really fair, IMHO. Two years ago, when you ranted on the DocBook list, there *were no tool sets that we could point to*. SGML was a build-it-yourself world. Now, as I've said, thanks to the tremdous efforts of lots and lots of people, we *do have tool sets* that we can point to. They aren't perfect yet, they don't install easily enough, and they don't satisfy everyone. But we've come a long way and the efforts continue. Not only do I think the problem can be fixed, I'm confident it will be. Be seeing you, norm -- Norman Walsh | The worst enemy of life, freedom and http://nwalsh.com/ | the common decencies is total anarchy; | their second worst enemy is total | efficiency.--Aldous Huxley From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Sam Roberts" To: Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 27 Dec 2000 06:36:00 -0000 Message-id: <001901bfe68f$01e59c40$1403a8c0@cogent.ca> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> X-SW-Source: 2000/msg00215.html > > Despite all of the above, I have become reasonably proficient in using the > > Docbook-Tools set and in Docbook itself. But the tool kits still do not work > > well enough for me to actually use them to produce real documentation. I am They work well enough for us, so it is possible! See: http://www.cogent.ca/Download/Documents.htm The slang programmin language and cascade db docs are all from docbook. I wrote my own scripts and makefiles to drive jade and [pdf]jadetex based on taking a peek into the db2* scripts. It took a while, but it was no harder than dealing with LaTeX, back when I used it in university. Sgml isn't really a documentation language, it's a markup language, the markup is then used to generate documentation, by some people, and with some tools. For those of us who actually want documentation, the vagueness of all the sgml docs when it comes to actually generating documentation is frustrating, but sgml+docbook+jade+jadetex are still the best tools around. > additionally i would suggest you subcribe to > > docbook-apps@lists.oasis-open.org, I second this. docbook-apps is very active, and very helpful, if you're trying to use docbook you should be on this list. Sam From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: docbook-tools-discuss@sourceware.cygnus.com Subject: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 08:02:00 -0000 Message-ID: <200007041511.LAA15779@snark.thyrsus.com> X-SW-Source: 2000-q3/msg00000.html Message-ID: <20000704080200.HtfUC1aNP92tBIdINk1M2CRwL3wxVUshCSHteTFmc8A@z> I'm trying to set up docbook-tools, and finding it a hideously frustrating experience. Why does all the SGML software and documentation in the world read as though it was carefully designed to prevent any actual document production from getting done? The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That server is perpetually swamped. Going to one of the mirrors, I find a docbook-3.1-5.noarch.rpm, but it does not contain any of the db2* scripts referenced on the DocBook page. Where are those scripts? -- Eric S. Raymond "The best we can hope for concerning the people at large is that they be properly armed." -- Alexander Hamilton, The Federalist Papers at 184-188 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: "Eric S. Raymond" Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 08:05:00 -0000 Message-ID: <76vgymvstw.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> X-SW-Source: 2000-q3/msg00001.html Message-ID: <20000704080500.czih55HL1_5iNt6V0v7pAB6Wb7mDcjMS8iDl3-UHjKs@z> Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page Eric> directs me to Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That Eric> server is perpetually swamped. Going to one of the mirrors, Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain Eric> any of the db2* scripts referenced on the DocBook page. Eric> Where are those scripts? There should be several RPMs on that ftp site. The scripts you seek are in the stylesheets RPM. Also make sure you don't only get the noarch RPMs. From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Mark Galassi Cc: "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 08:22:00 -0000 Message-ID: <20000704113106.A15838@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <76vgymvstw.fsf@odie.lanl.gov> X-SW-Source: 2000-q3/msg00002.html Message-ID: <20000704082200.2NKkAXTcjUCi0Ej7v47ebSXgP_Yr2zRGhxROf53YDKU@z> Mark Galassi : > > Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page > Eric> directs me to > Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That > Eric> server is perpetually swamped. Going to one of the mirrors, > Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain > Eric> any of the db2* scripts referenced on the DocBook page. > Eric> Where are those scripts? > > There should be several RPMs on that ftp site. The scripts you seek > are in the stylesheets RPM. Also make sure you don't only get the > noarch RPMs. OK, what is the actual stylesheet RPM? You didn't specify, and all I can find is SRPMs and tarballs. Would it be too much to ask that these things actually be described on the DocBook tools page? Every time I go near SGML I get headaches... -- Eric S. Raymond Government is actually the worst failure of civilized man. There has never been a really good one, and even those that are most tolerable are arbitrary, cruel, grasping and unintelligent. -- H. L. Mencken From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: esr@thyrsus.com Cc: "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 08:27:00 -0000 Message-ID: <76r999x6e4.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <76vgymvstw.fsf@odie.lanl.gov> <20000704113106.A15838@thyrsus.com> X-SW-Source: 2000-q3/msg00003.html Message-ID: <20000704082700.Gk2Yz8EO_Xai7Qo5S6msm0UKy3WUX97zKq3k0UQOER0@z> Eric> OK, what is the actual stylesheet RPM? You didn't specify, Eric> and all I can find is SRPMs and tarballs. I'm surprised you don't find it. I went to the first mirror and found the non-source noarch RPM for stylesheets at: ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/RPMS/noarch/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Mark Galassi Cc: "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 08:45:00 -0000 Message-ID: <20000704115407.A15973@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <76vgymvstw.fsf@odie.lanl.gov> <20000704113106.A15838@thyrsus.com> <76r999x6e4.fsf@odie.lanl.gov> X-SW-Source: 2000-q3/msg00005.html Message-ID: <20000704084500.F1_GhYblBko9HpJ9dFfbbIb9ksaH31bj8Q3DOEYIbds@z> Mark Galassi : > I'm surprised you don't find it. I went to the first mirror and found > the non-source noarch RPM for stylesheets at: > ftp://ftp.freesoftware.com/pub/sourceware/docbook-tools/docware/RPMS/noarch/ Thanks. The mirror I checked was missing the docware/RPMS part. The docbook-tools page ought to mention that the db2* scripts live in the stylesheets RPM. Otherwise it's way too easy to get sidetracked by the docbook RPM. -- Eric S. Raymond When only cops have guns, it's called a "police state". -- Claire Wolfe, "101 Things To Do Until The Revolution" From mboxrd@z Thu Jan 1 00:00:00 1970 From: Chuck Mead To: "Eric S. Raymond" Cc: Mark Galassi , "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 08:45:00 -0000 Message-ID: References: <20000704113106.A15838@thyrsus.com> X-SW-Source: 2000-q3/msg00004.html Message-ID: <20000704084500.0QDNyGhI7h5Cb0pS76ap7S3IOl-xhJE-7-7IxtAxL3g@z> On Tue, 4 Jul 2000, Eric S. Raymond spewed into the bitstream: ESR>Mark Galassi : ESR>> ESR>> Eric> The < http://sourceware.cygnus.com/docbook-tools/ > page ESR>> Eric> directs me to ESR>> Eric> < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That ESR>> Eric> server is perpetually swamped. Going to one of the mirrors, ESR>> Eric> I find a docbook-3.1-5.noarch.rpm, but it does not contain ESR>> Eric> any of the db2* scripts referenced on the DocBook page. ESR>> Eric> Where are those scripts? ESR>> ESR>> There should be several RPMs on that ftp site. The scripts you seek ESR>> are in the stylesheets RPM. Also make sure you don't only get the ESR>> noarch RPMs. ESR> ESR>OK, what is the actual stylesheet RPM? You didn't specify, and all I ESR>can find is SRPMs and tarballs. ESR> ESR>Would it be too much to ask that these things actually be described ESR>on the DocBook tools page? ESR> ESR>Every time I go near SGML I get headaches... I started fooling with this stuff early last fall and I went through similiar travails. I captured what I did in a colophon for one of the documents I created in docbook/sgml. Maybe this will help: http://www.moongroup.com/docs/mailhelp-HOWTO/z632.html hth! -- Chuck Mead, CTO, LinuxMall.com csm@LinuxMall.com GnuPG Public Key Available: http://pgp.ai.mit.edu/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 10:25:00 -0000 Message-ID: <00070410352500.07357@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> X-SW-Source: 2000-q3/msg00006.html Message-ID: <20000704102500.Ind9SX9x2i0wouyUl6UP8IbhkPp_PmgXE2QEbiN4AOE@z> On Tue, 04 Jul 2000, Eric S. Raymond wrote: > I'm trying to set up docbook-tools, and finding it a hideously > frustrating experience. Why does all the SGML software and > documentation in the world read as though it was carefully designed > to prevent any actual document production from getting done? That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it were a briefly written summary written in a foreign language to be as terse as possible. You would suspect that the authors of documentation tools would themselves be enamored of documentation. WIth the exception of Donald Knuth, that, alas, does not appear to be the case. It's bad enough that the authors of every book and document that exists on SGML have invented their own inscrutable terminology for the process of marking up documentation... but none of them, zero, zilch, appears to have considered the notion of a GLOSSARY, and the very thought of explaining complex terms in a simple, clear manner appears to break every single SGML author out in hives. Yes, it's difficult. I've done it before, I know how difficult it is. But it's as if the creators of SGML DTD's and tools have a death wish... or else they're trying to protect their cult's purity by keeping out the riff-raff (same thing). Despite all of the above, I have become reasonably proficient in using the Docbook-Tools set and in Docbook itself. But the tool kits still do not work well enough for me to actually use them to produce real documentation. I am using Docbook for the design documentation for a major project at the office, but nobody on this list has been able to explain to me why half the entries in my index have "-999" as the page number, even when the 'jadetex' script does not complain about unresolved references. I've even tried updating everything from the Docbook-tools site thinking maybe Red Hat had a wonked out docbook-tools installation. I even tried using Caldera eDesktop 2.4 rather than Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No go. I'm on the verge of abandoning the tool kit in frustration. LyX will now generate decent HTML output, which was my main reason for using DocBook in the first place (the difficulty of getting good HTML output out of "latex2html" and its ilk). My only issue with LyX is the difficulty of maintaining multi-source documentation in a CVS depository... CVS won't do merges of multi-author edits of .lyx files, sigh. But if it's a choice of LyX or using StarOffal, I know which I'll choose -- at least LyX is a structured markup tool, whereas StarOffal.. no, don't get me started. > The < http://sourceware.cygnus.com/docbook-tools/ > page directs me to > < ftp://sourceware.cygnus.com:/pub/docbook-tools >. That server is > perpetually swamped. Going to one of the mirrors, I find a > docbook-3.1-5.noarch.rpm, but it does not contain any of the db2* > scripts referenced on the DocBook page. Where are those scripts? On Red Hat 6.2 Linux, they're in "stylesheets-1.54.13rh-1.xxx.rpm" (put architecture of choice in place of 'xxx'). Red Hat ships with what is basically a slight tweak of the docbook-tools kit. 'docbook-3.1-5.noarch.rpm' is just the DTD (Data Type Definition), it does not contain the other software you'll need to convert programs written using that DTD into a useful form. You'll need 'jade' and 'stylesheets' to do that. 'jade' is the actual grunt engine, while 'stylesheets' is the Scheme and scripts that the grunt engine uses to know how to do the conversion. export SGML_CATALOG_FILES=/usr/lib/sgml/CATALOG export SGML_ROOT=/usr/lib/sgml are also nice to tell Emacs's psgml mode where to find the overall catalog and SGML dtd and tools. I use 'xemacs', which puts up a nice SGML menu at the top. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: Eric Lee Green Cc: "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 11:21:00 -0000 Message-ID: <76lmzhwyc8.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000-q3/msg00007.html Message-ID: <20000704112100.2ufNPyhB9pWQxFtnT0ljzLOEjOuN3GjsXtOlVTtp-tQ@z> I'm surprised nobody came across my tutorial: http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html It has been improved on by several people, but always in a specific context, like the FreeBSD documentation guidelines. It is mentioned in the sourceware web page. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: Gregory Leblanc Cc: "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 15:44:00 -0000 Message-ID: <76k8f1v7l9.fsf@odie.lanl.gov> References: X-SW-Source: 2000-q3/msg00010.html Message-ID: <20000704154400.slbEZ7sTfwpHeBW1M_TUxiHM46e2Gbd0SEOWCm9S_ko@z> Gregory> Not to be rude, but what ever happened to getting the Gregory> tools by Eric Bischoff onto the sourceware site? I was Gregory> under the impression (perhaps mistaken), that his tools Gregory> were going up on the sourceware site, as well as into a Gregory> CVS repository someplace. Can somebody fill me in? Eric and I are working on it. We're obviously being slower than you would like us to :-), but it will happen. Of course that has nothing to do with this issue. If RPMs are missing on a mirror (as esr implies they are), Eric B's enhancements will not help. Also, esr was trying to get basic db2html working. From mboxrd@z Thu Jan 1 00:00:00 1970 From: madhu To: Eric Lee Green Cc: "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Tue, 04 Jul 2000 22:01:00 -0000 Message-ID: <00070510365404.00678@needaguru> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000-q3/msg00011.html Message-ID: <20000704220100.BcEoph-7dhEAUCYcgsdZZlYxfxd96TkqwK7eXWfrA2k@z> On Tue, 04 Jul 2000, you wrote: > On Tue, 04 Jul 2000, Eric S. Raymond wrote: > > I'm trying to set up docbook-tools, and finding it a hideously > > frustrating experience. Why does all the SGML software and > > documentation in the world read as though it was carefully designed > > to prevent any actual document production from getting done? > > That puzzles me too. Even Norm Walsh's so-called "Docbook" book reads as if it > were a briefly written summary written in a foreign language to be as terse as > possible. You would suspect that the authors of documentation tools would > themselves be enamored of documentation. WIth the exception of Donald Knuth, > that, alas, does not appear to be the case. an html.zip file exists on the officail docbook site oasis with enough details for anybody to start with . it is also linked from normans website from where you can download the latest stylesheets for the docbook, oasis wesite is http://www.oasis-open.org/docbook/ and normans website is http://nwalsh.com/~ndw/ > > It's bad enough that the authors of every book and document that exists on SGML > have invented their own inscrutable terminology for the process of marking up > documentation... but none of them, zero, zilch, appears to have considered the > notion of a GLOSSARY, and the very thought of explaining complex terms in a > simple, clear manner appears to break every single SGML author out in hives. > Yes, it's difficult. I've done it before, I know how difficult it is. But it's > as if the creators of SGML DTD's and tools have a death wish... or else they're > trying to protect their cult's purity by keeping out the riff-raff (same > thing). > > Despite all of the above, I have become reasonably proficient in using the > Docbook-Tools set and in Docbook itself. But the tool kits still do not work > well enough for me to actually use them to produce real documentation. I am > using Docbook for the design documentation for a major project at the office, > but nobody on this list has been able to explain to me why half the entries in > my index have "-999" as the page number, even when the 'jadetex' script does not > complain about unresolved references. I've even tried updating everything > from the Docbook-tools site thinking maybe Red Hat had a wonked out > docbook-tools installation. I even tried using Caldera eDesktop 2.4 rather than > Red Hat, thinking maybe Red Hat had something totally foobar in their setup. No > go. I'm on the verge of abandoning the tool kit in frustration. LyX will now > generate decent HTML output, which was my main reason for using DocBook in the > first place (the difficulty of getting good HTML output out of "latex2html" and > its ilk). My only issue with LyX is the difficulty of maintaining multi-source > documentation in a CVS depository... CVS won't do merges of multi-author edits > of .lyx files, sigh. But if it's a choice of LyX or using StarOffal, I know > which I'll choose -- at least LyX is a structured markup tool, whereas > StarOffal.. no, don't get me started. the problems you are mentioning are mostly to do with SGML tools not with docbook by itself. if you use the scripts like db2pdf it doesn,t some time run jadtex thrice for the numbers to be printed right .the db2* scripts are a sort of primer a starting point so to say but without them you can produce docbook documents , please refer to the readme's of jade, jadetex etc.and be warned that situation is not likely to improve what with SGML is dead proclamations doing the rounds and shift is towards XML . but again tools for XML are not unix favorable at all . additionally i would suggest you subcribe to docbook-apps@lists.oasis-open.org, and docbook@lists.oasis-open.org lists whree you might get more help than this list since this is of late a very low traffic list. and as Mark's excellent tutorial, please don't forget this http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html regards -- maddy ------------------------------------------------------------------------- Fishing baskets are employed to catch fish; but when the fish are got, the men forget the baskets; Words are employed to convey ideas; but when the ideas are grasped, the men forget the words; --"Chuang Tzu" ------------------------------------------------------------------------- From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Sam Roberts" To: Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 05 Jul 2000 07:32:00 -0000 Message-ID: <001901bfe68f$01e59c40$1403a8c0@cogent.ca> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> X-SW-Source: 2000-q3/msg00013.html Message-ID: <20000705073200.9MpWD7BnxDXbdropIgvfpGOhWZlpnxiz3UO6Ii9EZnw@z> > > Despite all of the above, I have become reasonably proficient in using the > > Docbook-Tools set and in Docbook itself. But the tool kits still do not work > > well enough for me to actually use them to produce real documentation. I am They work well enough for us, so it is possible! See: http://www.cogent.ca/Download/Documents.htm The slang programmin language and cascade db docs are all from docbook. I wrote my own scripts and makefiles to drive jade and [pdf]jadetex based on taking a peek into the db2* scripts. It took a while, but it was no harder than dealing with LaTeX, back when I used it in university. Sgml isn't really a documentation language, it's a markup language, the markup is then used to generate documentation, by some people, and with some tools. For those of us who actually want documentation, the vagueness of all the sgml docs when it comes to actually generating documentation is frustrating, but sgml+docbook+jade+jadetex are still the best tools around. > additionally i would suggest you subcribe to > > docbook-apps@lists.oasis-open.org, I second this. docbook-apps is very active, and very helpful, if you're trying to use docbook you should be on this list. Sam From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Sam Roberts" To: Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 05 Jul 2000 07:40:00 -0000 Message-ID: <002501bfe690$04331940$1403a8c0@cogent.ca> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> <00070422425701.09328@ehome.inhouse> X-SW-Source: 2000-q3/msg00014.html Message-ID: <20000705074000.7kR7vw9k9h8gmVqcIYpCzLIS4wlwMOjtOIKPploGwiY@z> ----- Original Message ----- From: Eric Lee Green > Still, TeX and LaTeX still exist. They are thoroughly documented. They run the > same way everywhere. They look ghe same everywhere. So while they are not the > be-all and end-all of structured document design, they'll have to do, since the > SGML crowd has committed collective suicide. A pity, that. This is just a variant of the classic complaints about Unix: I just want to do X, but the docs don't tell me how. LaTeX is a single tool that does it all, to use sgml you have to use a set of tools, and you can mix and match them. You can use jade without docbook or norm's style sheets, you can use jadetex without using docbook, the db2* scripts are so optional most people write their own, and you don't have to use emacs to edit sgml, but it helps. As for the sgml crowd committing suicide, judging from the increased traffic on the oasis docbook lists, which led to a split into two still very busy mailing lists this spring, and the increasing number of open source projects whos docs appear to be docbook generated, I'd say people are perservering and getting the job done. Sam From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 05 Jul 2000 07:41:00 -0000 Message-ID: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000-q3/msg00015.html Message-ID: <20000705074100.g1BnpdUPI-DjZbuZwxcSs_46XZaq9naCQupqUjzyHeU@z> > > I'm trying to set up docbook-tools, and finding it a hideously > > frustrating experience. Why does all the SGML software and > > documentation in the world read as though it was carefully designed > > to prevent any actual document production from getting done? This is one of those cases where certain documentation projects have taken up the call more so than the tools side. For example, both the GNOME and KDE doc groups have manuals to help people get involved with writing documentation for their projects. Both tell the writer where to get everything they need for Docbook and how to use it - but both also describe it in terms that are particular to their style of writing. I like this approach as it narrows the focus to projects and those who wish to write for those projects. Outside of that the best resources I have seen are Mark's tutorial and Deb Richardson's HOWTO at OSWG. The main problem with it is that describing SGML is not as trivial as you might think. Describing DocBook is easier, but it still comes as very foreign to those who come from either the word processor world, or the format driven mark-up world. The best way to learn is by trying, not by reading IMHO. Can the documentation be better? Sure it can, and we shall try. Still, I find it somewhat humorous at the trouble many hackers (who would never dream of documenting their code) have when they can read the source :-) Cheers, Dave -- David Mason Red Hat AD Labs dcm@redhat.com http://people.redhat.com/dcm From mboxrd@z Thu Jan 1 00:00:00 1970 From: Ismael Olea To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 05 Jul 2000 09:57:00 -0000 Message-ID: <396368E9.95CC5D75@hispalinux.es> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> <00070422425701.09328@ehome.inhouse> <002501bfe690$04331940$1403a8c0@cogent.ca> X-SW-Source: 2000-q3/msg00017.html Message-ID: <20000705095700.hw5dZyDkBSdwn0lPAbQiElx3f9rnsVU36Vf20wb37aE@z> Sam Roberts escribió: > them. You can use jade without docbook or norm's style sheets, you can use > jadetex without using docbook, the db2* scripts are so optional most people > write their own, and you don't have to use emacs to edit sgml, but it helps. We have a little problem with these tools. There aren't a more-or-less sgml suite made of components (packages) with well made package dependeces. Then, if you want to use linuxdoc, your package system'll ask for sp, linuxdoc-dtd and its filters. If you want XML DocBook, the packages we all know. Add a new package (TEI?) could need to add it's dtd, the stylesheets and maybe some interface. What do you think? -- A.Ismael Olea González mailto:olea@hispalinux.es http://www.hispalinux.es/~olea 2:345/108.9@fidonet.org El mundo debe empezar a tener miedo a un planeta DEF From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: Ismael Olea Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 05 Jul 2000 09:59:00 -0000 Message-ID: <76vgyktswi.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <00070510365404.00678@needaguru> <00070422425701.09328@ehome.inhouse> <002501bfe690$04331940$1403a8c0@cogent.ca> <396368E9.95CC5D75@hispalinux.es> X-SW-Source: 2000-q3/msg00018.html Message-ID: <20000705095900.sMPHn7TE2L72crsawTMBSQxZUeN6LqEK-LGJC2OM1KQ@z> Ismael> We have a little problem with these tools. There Ismael> aren't a more-or-less sgml suite made of components Ismael> (packages) with well made package dependeces. Then, if you Ismael> want to use linuxdoc, your package system'll ask for sp, Ismael> linuxdoc-dtd and its filters. If you want XML DocBook, the Ismael> packages we all know. Add a new package (TEI?) could need Ismael> to add it's dtd, the stylesheets and maybe some interface. These problems exist, but are on their way out. It will eventually be possible to just install a nice suite of sgml-based tools. From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: Eric Lee Green Cc: "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 09:21:00 -0000 Message-ID: <873dlnjklb.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> X-SW-Source: 2000-q3/msg00019.html Message-ID: <20000706092100.7OsaCjM2QKYibFhHw2jb3Wa40lutnxFpduE50b8FhpI@z> / Eric Lee Green was heard to say: | That puzzles me too. Even Norm Walsh's so-called "Docbook" book | reads as if it were a briefly written summary written in a foreign | language to be as terse as possible. I'm sorry you found it to be that way. That wasn't the intent. Although the bulk of the book is intended as a reference and not a how-to, the introductory chapters were supposed to be readable by the novice. Can you explain, in any more detail, what you found most troubling? | It's bad enough that the authors of every book and document that exists on SGML | have invented their own inscrutable terminology for the process of marking up | documentation... but none of them, zero, zilch, appears to have considered the | notion of a GLOSSARY, and the very thought of explaining complex terms in a | simple, clear manner appears to break every single SGML author out in hives. | Yes, it's difficult. I've done it before, I know how difficult it is. But it's | as if the creators of SGML DTD's and tools have a death wish... or else they're | trying to protect their cult's purity by keeping out the riff-raff (same | thing). It is an unfortunate fact that Goldfarb created a set of concise, technical terms for describing the various components of SGML markup. On the one hand, using these terms precisely tends to be awkward for novices. On the other, using other terms causes confusion among other audiences. I really tried to be clear in this regard. Be seeing you, norm -- Norman Walsh | Everything is temporary. http://nwalsh.com/ | From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: esr@thyrsus.com Cc: Norman Walsh , Eric Lee Green , "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 10:25:00 -0000 Message-ID: <76g0pnjhmt.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000-q3/msg00023.html Message-ID: <20000706102500.KkxWCjpSK2PI1U7kK1enCvoryvnyhGJ71wZG_Ye1Adk@z> Eric> I don't think anybody doubts that it was your intention to Eric> be clear. Your execution, however, completely failed in Eric> that respect. The failure seems to me to be an indicator of Eric> a wider problem in the technical culture surrounding SGML, Eric> one I've bitched about before. Please do not post rude messages to this list. On this list we should not tell people that "they have failed" just because their pedagogical approach did not work for us. From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: Mark Galassi Cc: Norman Walsh , Eric Lee Green , "Eric S. Raymond" , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 10:37:00 -0000 Message-ID: <20000706134507.D25726@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <76g0pnjhmt.fsf@odie.lanl.gov> X-SW-Source: 2000-q3/msg00024.html Message-ID: <20000706103700._1mkEfDPkaqwq4qD4FeZZokDPckzam5fAsV7o3k8fwE@z> Mark Galassi : > On this list we should not tell people that "they have failed" just > because their pedagogical approach did not work for us. You're quite right. We tell people they have failed when their pedagogical approach has been reported to be ineffective by independent multiple observers. That is, that's what we do if we actually care about improving matters. If all we want to do is wrap the failure in a thick layer of feel-good batting so it can be ignored, then perhaps we do something else. -- Eric S. Raymond Americans have the will to resist because you have weapons. If you don't have a gun, freedom of speech has no power. -- Yoshimi Ishikawa, Japanese author, in the LA Times 15 Oct 1992 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Kendall Clark To: docbook-tools-discuss@sourceware.cygnus.com Cc: Mark Galassi , Norman Walsh , Eric Lee Green , esr@thyrsus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 10:48:00 -0000 Message-ID: <14692.50781.521325.126382@cmpu.net> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <76g0pnjhmt.fsf@odie.lanl.gov> <20000706134507.D25726@thyrsus.com> X-SW-Source: 2000-q3/msg00025.html Message-ID: <20000706104800.CYuUpJ2AHLPlVn3v19ESi01y3jVnEo8fmu-P4zCDzUI@z> >>>>> "Eric" == Eric S Raymond writes: Mark Galassi : >> On this list we should not tell people that "they have failed" >> just because their pedagogical approach did not work for us. Eric> You're quite right. We tell people they have failed when Eric> their pedagogical approach has been reported to be Eric> ineffective by independent multiple observers. Eric> That is, that's what we do if we actually care about Eric> improving matters. If all we want to do is wrap the failure Eric> in a thick layer of feel-good batting so it can be ignored, Eric> then perhaps we do something else. Well if it's about adjudicating pedagogy, then I should chime in with "Norm's book helped me tremendously, as has Norm personally on the several occasions when I emailed him with questions." I figured out SGML and DocBook well before Norm's book came out, well before I learned to program in fact. There are other SGML books, some of which are rather practical. Those helped too. As for actually setting up and installing the various permutations of the free tool chain, I just don't see why it's *so* hard for someone with a bit of technical ability or experience. Could it be *easier*? Of course. But so could nearly every bit of free software I've ever used. I started working with SGML on Linux in '96, well before anyone was making nice RPM packages for it; maybe that's an advantage in a perverse way? I'm not sure. Best, Kendall Clark From mboxrd@z Thu Jan 1 00:00:00 1970 From: Mark Galassi To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 10:53:00 -0000 Message-ID: <768zvf9mdh.fsf@odie.lanl.gov> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <76g0pnjhmt.fsf@odie.lanl.gov> <20000706134507.D25726@thyrsus.com> <14692.50781.521325.126382@cmpu.net> X-SW-Source: 2000-q3/msg00026.html Message-ID: <20000706105300.gMQ6-SzP5Z5JOstm3AxOiGA6d3U4phsdfJ50R72_rl4@z> Kendall> As for actually setting up and installing the various Kendall> permutations of the free tool chain, I just don't see why Kendall> it's *so* hard for someone with a bit of technical Kendall> ability or experience. It isn't. The person who started this thread said there was no tutorial which includes setting up the tools, but there actually was. Although things are out of date, this whole thread is mostly unnecessary. From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "David C. Mason" Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 11:59:00 -0000 Message-ID: <20000706150802.A26225@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000-q3/msg00028.html Message-ID: <20000706115900.JDM-xkYjPSZnWzUHwb7DbYcJRAxgJlbWUH7wUz6eLbs@z> David C. Mason : > Your problem installing the tools seemed (as I read back through the > thread) to be one of finding a mirror that was bad. Once you found a > mirror which contained the RPMs needed are we to assume the > installation went according to plan? Oh, no. That wasn't my only problem by a long shot. I actually went through three different attempts to get three different sets of tools running -- Jade, OpenJade, and the DocBook tools. Not one of them had adequate documentation for beginners, even technically sophisticated beginners like me with considerable prior knowledge of SGML (I did a lot of of extension work on SGML-Tools for the LDP). All three have web pages that are remarkable for the amount of detail they convey without actually saying anything useful. > Can all of this be improved for the newbie - it sure can. In fact new > scripts or even applications can be written. You are a hacker, would > you like to write them? Can I assume the answer is no? Do you mean like the user's guide I once wrote for SGML-Tools to address exactly this problem? :-) Sorry, David. You don't get to accuse *me* of carping without contributing. I happen to be the person who made SGML-Tools 1.1 usable for fast-turnaround book publishing, proved it by producing "Linux Undercover" for Red Hat, and then documented what I did. But don't take my word for any of that -- go ask Ed Bailey about it. You'd probably find the story both entertaining and instructive. > Slamming someone's book certainly cannot help you learn can it? Slamming someone's book for lack of clarity certainly *can* be helpful if it wakes the author (and the dysfunctional culture surrounding the author) up to a problem. I did not mean to imply that Norman Walsh's book is without value. If I already knew most of what was in it, I'm sure it would make a dandy reference. But that's the problem -- the book is only useful for people who already have a working SGML toolset and considerable pre-acquired expertise. The fact that it was not useful to a person who had already done substantial SGML publishing and extension work on SGML tools *should* be an important message. > I say 'kudos' to Norm for the following: I'll cheerfully say Norm is a wonderful guy too, if that will make you or him feel any better. He's done a lot of good things. Unfortunately, none of those things includes actually making SGML accessible to the un-initiated. *And that is the issue here*. The DocBook community has a huge blind spot. The consequences of that blind spot drive away people like Eric Lee Green or myself who would otherwise love to contrivbute more. -- Eric S. Raymond "Today, we need a nation of Minutemen, citizens who are not only prepared to take arms, but citizens who regard the preservation of freedom as the basic purpose of their daily life and who are willing to consciously work and sacrifice for that freedom." -- John F. Kennedy From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: Mark Galassi , docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 13:38:00 -0000 Message-ID: <00070613480700.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <14692.50781.521325.126382@cmpu.net> <768zvf9mdh.fsf@odie.lanl.gov> X-SW-Source: 2000-q3/msg00029.html Message-ID: <20000706133800.lOhiTb3rtnscQlezT979G7arOHEmCv0VMOknv_Nn57Q@z> On Thu, 06 Jul 2000, Mark Galassi wrote: > Kendall> As for actually setting up and installing the various > Kendall> permutations of the free tool chain, I just don't see why > Kendall> it's *so* hard for someone with a bit of technical > Kendall> ability or experience. > It isn't. The person who started this thread said there was no > tutorial which includes setting up the tools, but there actually was. > Although things are out of date, this whole thread is mostly > unnecessary. Futile, perhaps. Unnecessary, no. I am constantly fighting The Cult Of Obscurity both on the job and off it, because so many good technical people just don't see what's wrong with their documentation and programming. "It makes sense to me, other people must just be stupid" is the attitude of the typical adherent of the Cult of Obscurity. I sometimes have to fuss at my own co-workers about "Look, I don't care about details x, y, and z, I, the hypothetical the end user, just want to get job 'n' done", and I'm certainly not going to be reticient about doing the same elsewhere, even if I'm not being paid to do it elsewhere :-). People do not care about elegance. They do not care about how terse and formal the language is surrounding a topic. They just want to get a job done with as few keystrokes or mouse clicks as possible, and learning as few details as possible to do it. This is one place where Lamport's LaTeX book shines (despite how aweful it is otherwise), the first thing he does is say, "Here is how you write a letter in LaTeX." What genius! Regarding Norm Walsh's book: the biggest problem was a lack of examples of how to use DocBook to create entire documents. There's reasonably good examples of the use of many of the individual elements, but nothing like where Lamport says, "Here is how you create a document. Here is how you create a letter. Here is how to create a document that has a table in it." Lamport's LaTeX book sucks... but it sucks in a way that lets most people write simple documents after reading it. Note that I'm not calling the SGML crowd stupid. I'm not saying that their documentation "sucks" for people who are already initiated into the Cult Of SGML. What I'm saying is that a) there's a paucity of documentation about how to Get The Job Done, the only one I know about is the FreeBSD one, and b) there has been a lack of attention to Getting The Job Done on the part of the SGML community as a whole, they have been absorbed in the technical excellence of SGML, the theoretical possibilities of parsing SGML, the stylistic elegance of DSSL and stylesheet languages, whilst ignoring the whole point of the exercise. I realize this is not an attitude that is restricted to the SGML crowd. This sort of attitude is rampant in the computer biz, those of us who have a good understanding of end user wants and needs are always the minority, and those of us with both technical skills and writing skills are even rarer. But, as the other Eric mentioned, this sort of attitude is also what kept SGML from sweeping the world over the last five years, and is what basically has killed SGML (with the exception of the HTML DTD and XML subset, the former of which isn't really SGML anymore). 'Nuff said. I'm sure I'll find many more flames in my mailbox from adherents of the Highly Theoretical Cult of SGML Gurus. But (shrug), when it comes to document production, I'm an end user. I design tape backup and related software for a living, not documentation tools. All I want to do is to get a job done. I don't CARE about how elegant DSSL is, or how flexible the Docbook DTD is... it's a tool, for cryin' out loud, not a religion. And if it doesn't Do The Job, I'll dump it and use some other tool. Which, apparently, has been the conclusion of most others who would use SGML, too, with the exception of a few of the Open Source projects which use it because that's what the LinuxDoc project uses. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: esr@thyrsus.com Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 13:55:00 -0000 Message-ID: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> X-SW-Source: 2000-q3/msg00030.html Message-ID: <20000706135500.f7Wp6gSBKJI-xuUJyU6DlA8OyhANjwZ3Bx_pfXm0wMk@z> "Eric S. Raymond" writes: > Oh, no. That wasn't my only problem by a long shot. I actually went > through three different attempts to get three different sets of tools > running -- Jade, OpenJade, and the DocBook tools. Not one of them had > adequate documentation for beginners, even technically sophisticated > beginners like me with considerable prior knowledge of SGML (I did a > lot of of extension work on SGML-Tools for the LDP). All three have > web pages that are remarkable for the amount of detail they convey > without actually saying anything useful. Then I still don't understand the problems you are having... or at least, I still haven't seen a detail of what you would like to see. I think the ' Practical Guide...' is a very good intro to the scripts and creating a DB document - its short, to the point, and includes, what I think, you need to get started. But again, I can't figure out except the mirror stuff, what is wrong...I'd like to help > Do you mean like the user's guide I once wrote for SGML-Tools to > address exactly this problem? :-) > > Sorry, David. You don't get to accuse *me* of carping without > contributing. I happen to be the person who made SGML-Tools 1.1 > usable for fast-turnaround book publishing, proved it by producing > "Linux Undercover" for Red Hat, and then documented what I did. But > don't take my word for any of that -- go ask Ed Bailey about it. You'd > probably find the story both entertaining and instructive. I had no idea you did the first SGML-Tools and I apologize, you are a single entity in that case. Otherwise, I find that most hackers ignore these tools altogether. My apologies. Still, my problem is this thread has been about the lack of documentation for DocBook - but I still don't understand what the problem you are having is. I feel there is quite a bit of documentation out there, and if I knew the problem I could point you to it... if not, I could write it (especially since I am going to do a DocBook talk at OLS, this info would help me). Otherwise complaining about one or two particular documents doesn't do any good. You have stated why you didn't like Norm's book, you stated you didn't like the installation section in the 'Practical Guide...' HOWTO... so what do you want? Need? Is it *really* helpful to point out flaws in those particular documents when there might be one that answers your question? Dave -- David Mason Red Hat Advanced Development Labs dcm@redhat.com (919)547-0012 x248 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "David C. Mason" , esr@thyrsus.com Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 14:22:00 -0000 Message-ID: <00070614320401.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000-q3/msg00031.html Message-ID: <20000706142200.fdEzU-24CW8xRGfHIC0mx2EdyQp6MkjpWqZssBy_PYA@z> On Thu, 06 Jul 2000, David C. Mason wrote: > "Eric S. Raymond" writes: > > Anyone not already eyebrow-deep in the dysfunctional culture surrounding > > this software would realize that this lacuna makes the rest of the > > chapter a bad joke. > > It is very easy to blame the SGML community for the problems inherent > to understanding the technology, it is not as easy to lend a hand. Why > is that? Do hackers think that documentation tools are beneath them > until they actually have to use them? Well, unfortunate but true, most hackers are no good at documentation. This applies to SGML software creators as well :-(. Equally unfortunate but true, most hackers have no idea how end users think, and thus have no idea how to create software that is easy to understand and easy to use that solves problems that end users actually have. They tend to get caught up in making the software super-flexible and super-swiss-knife, which is nice but not at the expense of ease of solving particular problems. I had to fight for the concept of "click this single button, and it does what 90% of users want out of our software" when it came to prototyping a potential future product, because the hacker who designed the thing had a screen cluttered with stuff that would confuse the typical end user and which was not intuitive at all. But it made sense to him. He didn't understand that most people are not hackers and don't think like hackers. Finally: those of us who are actually being paid to write documentation rarely are getting paid to write documentation tools at the same time, and in most cases even writing documentation is not our full-time job (I write documentation as part of designing software -- you know, requirements docs, functional specifications, design docs, class heirarchy docs, etc.). In addition, we're often fighting pointy-haired bosses who want us to use Microsoft Word or StarOffice or whatever "standard" office suite the corporation has adopted, and who (having never written anything larger than a letter) don't understand that structured document layout systems are much more appropriate for technical documentation. To put the blame on the end user for the poor state of Docbook/SGML documentation and tools is a case of blaming the victim... we're just out here trying to do a job, not fight religious wars, and we have enough trouble getting permission to use any kind of SDL system without having to fight a buggy one as well. As it is, I have to continually justify to my bosses my use of DocBook... they don't understand why I would want to use a SDL instead of the "corporate standard" office suite. Now you're going to blame me for the fact that I'm getting "-999" for half the page numbers in my index?! Sad but true, here in the real world the pointy haired boss's response to problems that we have generating documentation with the Docbook tools is "quit that Docbook BS and use Microsoft Word [StarOffice, WordPerfect, etc.] like the rest of us." WHich is why my next set of documentation is going to be using LyX/LaTeX. The tools work, they work reliably, they've worked reliably for years and years and years, they're not ideal but they get the job done and dammit, that's all I care about. And that's why SGML has remained a cult rather than a real solution for most people's documentation problems. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "David C. Mason" , esr@thyrsus.com Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 14:32:00 -0000 Message-ID: <00070614422402.15291@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <20000706150802.A26225@thyrsus.com> X-SW-Source: 2000-q3/msg00032.html Message-ID: <20000706143200.UkOLt0oBQTOI6qhtcixJVaW8Opt7qOPHRigY_RA0BQY@z> On Thu, 06 Jul 2000, David C. Mason wrote: > Still, my problem is this thread has been about the lack of > documentation for DocBook - but I still don't understand what the > problem you are having is. I The problem is not the lack of documentation. The problem is the lack of attention to documenting DocBook as an actual document production system, rather than as a theoretical exercise. There is plenty of good theoretical documentation, but a paucity of Get The Job Done tools and documentation. This, alas, has always been a problem of the SGML crowd. I've been following SGML off and on since 1995 or so, when the original LinuxDoc project adopted that LaTeX-like DTD, and aside from that project and one other that died aborning (don't remember what it was, it was written using 'bigloo' Scheme and a DTD that was similar to but simpler than DocBook), there has been absolutely no attention at all amongst the SGML literati to the problems of producing practical systems for ordinary users' purposes. And I'm talking as someone who used to read Robin Cover's web page on a monthly basis looking for links that would solve some actual problem that I had... it just never happened. -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "David C. Mason" Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 14:52:00 -0000 Message-ID: <20000706180129.C26696@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> X-SW-Source: 2000-q3/msg00033.html Message-ID: <20000706145200.se-QigAw3D133IBylGBFzMwwCTR9LJ_juTQLvbGtgi0@z> David C. Mason : > Then I still don't understand the problems you are having... or at > least, I still haven't seen a detail of what you would like to see. I'd like to see documentation that spends less time genuflecting before the wonderfulness of semantic markup and stylesheets, and more time telling me how I can install and configure working tools and make HTML and Postscript from actual documents. Let's start with replacing that cop-out in the so-called "Practical Introduction". It's inexcusable, absurd, perverse, that a so-called "Practical Guide" doesn't tell you (a) where to find installable versions of the tools it's describing, and (b) how to set them up so you can do the examples in the guide. Let's continue with the fact that in the entire 635 pages of "DocBook: The Definitive Guide", I found *not one* example of a command line that could be used to produce actual, viewable HTML or Postscript from an actual document. Is it just me? Am I crazy to think there's something wrong with a 600-page tome on document production tools that *never once tells you how to format a document?* The unbelievable part is that it's *all* like that. It's not just the individual authors of these particular documents that are high priests of the Cult of Obscurity -- every piece of documentation I've ever seen from the DocBook/SGML community is pretty much off in theoretical cloud-cuckoo land. I can learn more than I ever wanted to know about DSSL and FOSI and fifty other acronyms, but I can't find any clue about what to do when jadetex generates bad Postscript that makes gs choke. What I want to see is a practical guide that is truly a practical guide -- something like what I wrote for SGML-tools, but covering DocBook. > I had no idea you did the first SGML-Tools and I apologize, you are a > single entity in that case. Otherwise, I find that most hackers ignore > these tools altogether. My apologies. Don't get an exaggerrated idea of my creds, either. I didn't write SGML-tools, nor was I ever its official maintainer. I did one really serious burst of work on it around 0.99-1.0 -- basically so I could pull Red Hat's nuts out of the fire after Bob Young asked me nicely to fix the godawful mess their old TeX-centric production process had degenerated into. And I did write the User's Guide. But I had very little to do with the design of the tool. -- Eric S. Raymond Idealism is the noble toga that political gentlemen drape over their will to power. -- Aldous Huxley From mboxrd@z Thu Jan 1 00:00:00 1970 From: "David C. Mason" To: esr@thyrsus.com Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 15:23:00 -0000 Message-ID: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000-q3/msg00034.html Message-ID: <20000706152300.lRAZeskERU_zRYTB1HJ2BIbjqFt_szTX-yTRHc2aaXs@z> "Eric S. Raymond" writes: > I'd like to see documentation that spends less time genuflecting > before the wonderfulness of semantic markup and stylesheets, and more > time telling me how I can install and configure working tools and make > HTML and Postscript from actual documents. Hmmm I just don't see either of the online documents (Mark's or Deb's) "genuflecting before the wonderfulness of semantic markup.." I do see them telling you how to use the tools to "produce actual, viewable HTML or Postscript from an actual document". You are correct that there is not very good documentation for the installation and that is partly due to the fact that depending on the flavor of Linux or UNIX you are using, it is different. However, that will change with the new DB Tools being created which includes a nice proposal to the LSB to make sure it is the same across the board. Once it is done I will be happy to write an installation guide for it. You are catching DocBook at a time when it is finally being recognized and used throughout many projects in Linux. The tools are not 100% satisfactory but they are being worked on as we speak. When tools are in flux, documentation is either non-existent or also in flux. That is the nature of the beast. We release early and release often, usually at the expense of good documentation and translation. If you want really good docs *now* perhaps try a commercial Windows product that uses DocBook. Otherwise wait, ask questions here or in other forums, or pitch in with the effort. The new tools will be used in a very different way, but with more functionality... I personally would like to start documenting those even though they are not available yet. > Let's start with replacing that cop-out in the so-called "Practical > Introduction". Please stop referring to people's work with words that are meant only to insult. I'm sure plenty of people could refer to your essays with venom, they perhaps choose not to as they know your heart is in the right place for writing them in the first place. > What I want to see is a practical guide that is truly a practical guide -- > something like what I wrote for SGML-tools, but covering DocBook. A technical author tends to want other's writing to be exactly as they write - its one reason why people have a hard time writing a book together. There isn't much to be done about that except write it yourself. I personally think that the Practical Guide is a great start - it is still in progress mind you, but it tells you the *exact* things you mentioned (besides the installation which I dealt with above)... I am staring at it... it tells you how to use the scripts, how to create a document, etc. Also keep in mind that DocBook Tools is not the only set of tools available for using DocBook. There are *many* tools available for the XML side of it... and I guarantee you you would come in with both guns blazing if you tried those tools... not one word of documentation. Why? They released early at the expense of good documentation/translation. > -- basically so I could pull Red Hat's nuts out of the fire after > Bob Young asked me nicely to fix the godawful mess their old > TeX-centric production process had degenerated into. What a gentleman like approach to telling me you worked on it. Dave -- David Mason Red Hat Advanced Development Labs dcm@redhat.com (919)547-0012 x248 From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "David C. Mason" Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 15:52:00 -0000 Message-ID: <20000706190044.A27191@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000-q3/msg00035.html Message-ID: <20000706155200.V5w501P_i0UssflcrMgbp4oHg7JcbTFaLgVFE-CAxeQ@z> David C. Mason : > Please stop referring to people's work with words that are meant only > to insult. David, you ain't *seen* me being insulting yet. So far, all I've done is call a spade a spade. You, and Deb, and Mark, and Norman, can start being offended the day I don't respect you enough to criticize your work. Criticism is the tribute you pay adults who are capable of better than they have done. Indifference or dismissal would be the real insult. > I'm sure plenty of people could refer to your essays with > venom, they perhaps choose not to as they know your heart is in the > right place for writing them in the first place. And since when is "having your heart in the right place" worth a damn? If that's the best thing anyone could find to say about my work, *I'd* be insulted. I hold myself to higher standards than that. You should too. > > -- basically so I could pull Red Hat's nuts out of the fire after > > Bob Young asked me nicely to fix the godawful mess their old > > TeX-centric production process had degenerated into. > > What a gentleman like approach to telling me you worked on it. The *point* is, I was called in to solve a nasty problem under emergency conditions, and I did it. I didn't get a lot of thanks for it, either. After "Linux Undercover" Bob decided that the mere fact of designating me the editor of the book and putting my name on the cover didn't actually mean that I could have editorial control. I declined to produce any more books unless my authority was equal to my responsibility, and there hasn't been another edition since. -- Eric S. Raymond Let us hope our weapons are never needed --but do not forget what the common people knew when they demanded the Bill of Rights: An armed citizenry is the first defense, the best defense, and the final defense against tyranny. If guns are outlawed, only the government will have guns. Only the police, the secret police, the military, the hired servants of our rulers. Only the government -- and a few outlaws. I intend to be among the outlaws. -- Edward Abbey, "Abbey's Road", 1979 From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Lee Green To: "David C. Mason" , esr@thyrsus.com Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 15:57:00 -0000 Message-ID: <00070616070800.15706@ehome.inhouse> References: <200007041511.LAA15779@snark.thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000-q3/msg00036.html Message-ID: <20000706155700.wHLFUsBKPvNPrQJc-TIAODDl3mTbmNkBbZrYnfqAFTs@z> On Thu, 06 Jul 2000, David C. Mason wrote: > What a gentleman like approach to telling me you worked on it. Welcome to the Open Source world :-). If we weren't passionate, we wouldn't do it. And when the tools suck, we do one of two things -- use different tools, or fix the tools. In my case, I'm using different tools for my next project, ones that I know are reliable and work correctly. I have a sneaking suspicion that ESR's passion here is going to lead him to fixing the tools, but on the other hand, he may have concluded that his contributions aren't welcome in the SGML community, because they don't meet some purity test (i.e., they're practically oriented, rather than being pretty, theoretical, and utterly useless). -- Eric Lee Green There is No Conspiracy eric@badtux.org http://www.badtux.org From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Edward C. Bailey" To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 16:05:00 -0000 Message-ID: References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000-q3/msg00037.html Message-ID: <20000706160500.2y1SvFtyqkX4Gb0vBm0cYvnw3-rfgD1wHzLqd36R3T4@z> >>>>> "esr" == Eric S Raymond writes: esr> David C. Mason : >> Then I still don't understand the problems you are having... or at >> least, I still haven't seen a detail of what you would like to see. esr> I'd like to see documentation that spends less time genuflecting esr> before the wonderfulness of semantic markup and stylesheets, and more esr> time telling me how I can install and configure working tools and make esr> HTML and Postscript from actual documents. I wonder if SGML documentation's current focus on the theoretical versus the practical is an evolutionary backwater from the days when people using the technology had to explain why they were "doing things the 'hard' way with SGML" when most people doing documentation were simply using whatever tools they happened to have available. Even if this was the case at one point in time, I think we all agree that most people "get it" when it comes to markup languages (if for no other reason than all the hype XML has brought to our part of the world). So it's time to move on, and leave the Cult of the Sacred Tag mentality behind us now... :-) ... esr> Is it just me? Am I crazy to think there's something wrong with a esr> 600-page tome on document production tools that *never once tells you esr> how to format a document?* To be honest, and at least in the case of _DocBook: The Definitive Guide_, I think it's just you. The book is a reference describing a particular markup language. That markup language is processed by a wide variety of software (both open source and non-) on a wide variety of platforms (again, both open source and non-). To have this particular reference guide get into how the markup language is processed by one particular application on a subset of the possible platforms would be something similar to HP including a chapter called "Using Your New Printer to Print Romance Novels" in every LaserJet owner's manual. :-) That's not to say that there *shouldn't* be a book that does just what you describe. I strongly agree with you that this kind of information should be in a book somewhere. I just don't think _DocBook: TDG_ is that book. esr> The unbelievable part is that it's *all* like that. It's not just the esr> individual authors of these particular documents that are high priests esr> of the Cult of Obscurity -- every piece of documentation I've ever esr> seen from the DocBook/SGML community is pretty much off in theoretical esr> cloud-cuckoo land. I can learn more than I ever wanted to know about esr> DSSL and FOSI and fifty other acronyms, but I can't find any clue esr> about what to do when jadetex generates bad Postscript that makes gs esr> choke. esr> What I want to see is a practical guide that is truly a practical esr> guide -- something like what I wrote for SGML-tools, but covering esr> DocBook. I feel compelled to preface my comments by saying that my goal is neither to cut anyone down, nor to build myself up. But I have a bit of background here that leads me to the following observations: o If you were to change a few of the terms in ESR's comments, you'd have almost exactly the same kinds of feedback we at Red Hat get from users regarding the state of Linux documentation today. So those of us that do documentation for one or more open source software projects should keep in mind that we ain't done yet -- not by a long shot. This complaint is true for DocBook documentation, and it's true for many (most? all?) open source software projects. o Since ESR has worked with me, he knows I'm not the sharpest knife in the kitchen (and hopefully feels that I'm at least not the dullest, either :-). Yet he's confounded trying to format DocBook documents, while I've been able to convert over 1500 pages of LaTeX-based documentation into DocBook, and to create the tools necessary to support a production environment to produce DocBook-based content here at Red Hat. What's the difference? Time. It was my full-time job to make the move to DocBook, while ESR is probably lucky if he can devote an hour here and there to the task. The important point here is that we need to get away from the mentality that introductory/tutorial texts are for clueless newbies, that hard-core reference material is the only truly important documentation. The introductory stuff makes the technology accessible to people that would otherwise not have access. And as I'm sure ESR can vouch, being treated like a clueless newbie, on the outside looking in, sucks. esr> Don't get an exaggerrated idea of my creds, either. I didn't write esr> SGML-tools, nor was I ever its official maintainer. I did one really esr> serious burst of work on it around 0.99-1.0 -- basically so I could esr> pull Red Hat's nuts out of the fire after Bob Young asked me nicely to esr> fix the godawful mess their old TeX-centric production process had esr> degenerated into. Point of clarification -- ESR helped us replace a contractor (with a largely manual and TeX-centric production process) that seemed to be unable to deliver the goods when promised. That said, the end result still was the extraction of said gonads from the conflagration -- and in a most elegant fashion... :-) Ed -- Ed Bailey Red Hat, Inc. http://www.redhat.com/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Eric S. Raymond" To: "Edward C. Bailey" Cc: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Thu, 06 Jul 2000 16:46:00 -0000 Message-ID: <20000706195444.D27191@thyrsus.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> X-SW-Source: 2000-q3/msg00038.html Message-ID: <20000706164600.sdvDb7uMULvjfHXLnhkbb9lYACfEXIHQrV-rSKnvpGQ@z> Edward C. Bailey : > So it's time to move on, and leave the > Cult of the Sacred Tag mentality behind us now... :-) Indeed. And an important point: I wouldn't be so exercised about the Cult of the Sacred Tag if, on some level, I didn't grok that the SGML people have some reason behind the religion. If it was all just just bullshit, I could ignore it and go away. As it is, the fact that the power of these techniques is surrounded by a near-impenetrable thicket of theology and jargon is deeply frustrating to me -- and the apparent inability of SGML people to see that this is an issue is maddening! > esr> Is it just me? Am I crazy to think there's something wrong with a > esr> 600-page tome on document production tools that *never once tells you > esr> how to format a document?* > > To be honest, and at least in the case of _DocBook: The Definitive Guide_, > I think it's just you. [...] To have this particular reference guide get > into how the markup language is processed by one particular application on > a subset of the possible platforms would be something similar to HP > including a chapter called "Using Your New Printer to Print Romance Novels" > in every LaserJet owner's manual. :-) No, I'd say it's more like supplying schematics and chip masks for the printer's electronics and neglecting to document the front-panel controls. Really. What would it have cost to supply *one* explicit example of a document-production flow on Unix and Windows? A few pages could have made a huge difference -- in helpful symbolism, even if it couldn't cover all the substance. As it is, one is left with the impression that Mr. Walsh was so caught up in the arcana of Scheme and CSS and DTD composition that he couldn't be bothered to descend to the level of actually showing the reader how to actually use any of it. (All right, everybody. Calm down -- I'm not claiming that was his actual state of mind, simply that that is the message the book sends.) > o If you were to change a few of the terms in ESR's comments, you'd > have almost exactly the same kinds of feedback we at Red Hat get from > users regarding the state of Linux documentation today. So those of > us that do documentation for one or more open source software > projects should keep in mind that we ain't done yet -- not by a long > shot. This complaint is true for DocBook documentation, and it's > true for many (most? all?) open source software projects. Yup. That's why I maintain, at last count, eight (8) different technical FAQ documents. > The important point > here is that we need to get away from the mentality that > introductory/tutorial texts are for clueless newbies, that hard-core > reference material is the only truly important documentation. The > introductory stuff makes the technology accessible to people that > would otherwise not have access. Amen. Squared... -- Eric S. Raymond "Rightful liberty is unobstructed action, according to our will, within limits drawn around us by the equal rights of others." -- Thomas Jefferson From mboxrd@z Thu Jan 1 00:00:00 1970 From: Peter Ring To: "'docbook-tools-discuss@sourceware.cygnus.com'" Subject: RE: I'm trying to set up docbook-tools... Date: Fri, 07 Jul 2000 02:27:00 -0000 Message-ID: X-SW-Source: 2000-q3/msg00041.html Message-ID: <20000707022700.GKsRdfnUu7msTpGG3QJjN9QOisJWH89vL-V3MlNBz34@z> A few minutes searching might pop up some immediately useful "Getting started with DocBook"-type documents. Useful for those that just need to get things done, as well as those who wants to make SGML and DocBook more palatable. Try for instance these: A Practical Introduction to DocBook http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook -Intro/docbook-intro/index.html DocBook HOWTO http://metalab.unc.edu/godoy/using-docbook/using-docbook.html Practical information about the use of SGML/XML and DocBook on Debian http://www.debian.org/~bortz/SGML-HOWTO/potato/howto.html Practical information about the use of SGML/XML and DocBook on WindowsNT http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html A fairly complete guide to O'Reilly's DocBook based production system http://www.oreilly.com/people/staff/crism/dsssl/orastyle/index.html 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. 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). If you disagree, reflect for a moment just how much prior knowledge and experience is needed before these tools become productive. Now of course, it has 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? Kind regards, Peter Ring From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 07 Jul 2000 07:49:00 -0000 Message-ID: <87zonunjyf.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <76lmzhwyc8.fsf@odie.lanl.gov> X-SW-Source: 2000-q3/msg00044.html Message-ID: <20000707074900.Vthn5gk5Prpuyn-BAQMhdmeIOm6tOcWcj5OZ-t7AkoY@z> / Mark Galassi was heard to say: | I'm surprised nobody came across my tutorial: | http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html That one's on the DocBook documentation page: http://www.oasis-open.org/docbook/documentation/other.html Be seeing you, norm -- Norman Walsh | All the labors of the ages, all the http://nwalsh.com/ | devotion, all the inspiration, all the | noonday brightness of human genius, are | destined to extinction--Bertrand Russell From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 07 Jul 2000 07:49:00 -0000 Message-ID: <87hfa2ni9t.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> X-SW-Source: 2000-q3/msg00046.html Message-ID: <20000707074900.xTok_TmLKaBl5kZpboN2k6M0CwnIt2t-xWG2JLmtei0@z> / "Eric S. Raymond" was heard to say: | I don't think anybody doubts that it was your intention to be clear. | Your execution, however, completely failed in that respect. The Completely? Thanks. | failure seems to me to be an indicator of a wider problem in the | technical culture surrounding SGML, one I've bitched about before. Yes, you have. | Two years ago, I complained vociferously on the DocBook list that the | SGML culture had a pathological case of self-absorption and seemed to And with such vitriol and ranting that several respectable members of the list asked you to please be polite or go away. | unable to explain. For bringing this unwelcome news, I was flamed and | shunned. Is that how you saw it. How, um, symmetrical. | Can this be fixed? I don't know. The problem isn't any lack of | intelligence or good intentions on the part of the DocBook group. | There's something fundamentally disconnected and broken in the | attitude department, though -- an inability to see what the SGML | world looks like from the point of view of somebody who just | wants to get some work done. That's not really fair, IMHO. Two years ago, when you ranted on the DocBook list, there *were no tool sets that we could point to*. SGML was a build-it-yourself world. Now, as I've said, thanks to the tremdous efforts of lots and lots of people, we *do have tool sets* that we can point to. They aren't perfect yet, they don't install easily enough, and they don't satisfy everyone. But we've come a long way and the efforts continue. Not only do I think the problem can be fixed, I'm confident it will be. Be seeing you, norm -- Norman Walsh | The worst enemy of life, freedom and http://nwalsh.com/ | the common decencies is total anarchy; | their second worst enemy is total | efficiency.--Aldous Huxley From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 07 Jul 2000 07:49:00 -0000 Message-ID: <874s62oypi.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <76vgymvstw.fsf@odie.lanl.gov> <20000704113106.A15838@thyrsus.com> X-SW-Source: 2000-q3/msg00045.html Message-ID: <20000707074900.Wheug7m-eua78mpc94AGIRfBa3PycymEJbzbD3aMEKQ@z> / "Eric S. Raymond" was heard to say: | OK, what is the actual stylesheet RPM? You didn't specify, and all I | can find is SRPMs and tarballs. | | Would it be too much to ask that these things actually be described | on the DocBook tools page? No, that's a good idea. If someone sends me some appropriate text, I'll be happy to put it on the tools page. Be seeing you, norm -- Norman Walsh | If you are hankering after certainty, http://nwalsh.com/ | you are better advised to seek it in | religion: the stock-in-trade of science | is not certainty but doubt.--K.C. Cole From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 07 Jul 2000 07:49:00 -0000 Message-ID: <87wviym26y.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> <20000706195444.D27191@thyrsus.com> X-SW-Source: 2000-q3/msg00047.html Message-ID: <20000707074900.pneEyHOkTe4cX4DsbN1tZMjxVkRiJD-43rbq4Cawzf0@z> / "Eric S. Raymond" was heard to say: With respect to this comment, | As it is, the fact that the | power of these techniques is surrounded by a near-impenetrable thicket | of theology and jargon is deeply frustrating to me -- and the apparent | inability of SGML people to see that this is an issue is maddening! And bearing in mind something you said earlier, | You [...] can | start being offended the day I don't respect you enough to criticize | your work. I feel compelled to reply: First, you're mistaken. As the reader of your comments, I'm free to become offended whenever I bloody well choose. Second, I'm tired of your whining about the theology and jargon. I'm sorry if TDG didn't answer your questions, I'll try to do better next time (although I still think it's an authors prerogative to decide what is and what is not in scope), but I don't think it's either theological or jargon-filled. It seems to me that the bulk of your ranting boils down to: "The tools one needs to format a DocBook document and get HTML or print output are insufficiently documented and too hard to install and use." I haven't heard a single person disagree with you. And in the two years since you first encountered DocBook, tremendous progress has been made. I'm committed to seeing that, to the extent I can contribute, the progress continues until it's as nearly dead easy as possible. Now would you please stop flogging me for not moving fast enough. I ain't your whipping boy, son. | Really. What would it have cost to supply *one* explicit example of | a document-production flow on Unix and Windows? A few pages could have | made a huge difference -- in helpful symbolism, even if it couldn't | cover all the substance. Now that's an interesting question. You might be right. | As it is, one is left with the impression that Mr. Walsh was so caught | up in the arcana of Scheme and CSS and DTD composition that he couldn't be | bothered to descend to the level of actually showing the reader how to | actually use any of it. For the record, my thought process went something like this. "Today (when I was writing) things are still pretty immature. I could try to document one of the many possible tool sets, but then I'd be leaving out all the others, not to mention the commercial tools from Arbortext, Frame, and Softquad to name but three. And there's no tool set that works equally well on Unix and NT, so I'd have to do at least two. Things will be better soon and the installation instructions for the individual tool sets can do a better job on installation than I can. Heck, I don't even have a Linux box at hand these days. The vast majority of questions that I get aren't about specific tools, people seem to get those installed, they're about how to customize X, Y, or Z in the stylesheets. Since the DSSSL stylesheets form the core of several tool sets, end users would be better served by some explanation of how to use and customize those." | (All right, everybody. Calm down -- I'm not claiming that was his actual | state of mind, simply that that is the message the book sends.) And the message you send is...oh, nevermind. | > The important point | > here is that we need to get away from the mentality that | > introductory/tutorial texts are for clueless newbies, that hard-core | > reference material is the only truly important documentation. The | > introductory stuff makes the technology accessible to people that | > would otherwise not have access. | | Amen. Squared... Cubed, even. Be seeing you, norm -- Norman Walsh | Whatever you may be sure of, be sure of http://nwalsh.com/ | this: that you are dreadfully like | other people.--James Russell Lowell From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 07 Jul 2000 07:49:00 -0000 Message-ID: <87lmzenirl.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <1000706095536.ZM1901@sgi.com> X-SW-Source: 2000-q3/msg00051.html Message-ID: <20000707074900.w5_wRJv7hVtizLLfJzD4OfDQtVhQYdjL0H6d2McBU2U@z> / "richard offer" was heard to say: | be using Jade/your stylesheets to produce the output. I've hacked mine and | still can get what I'm (visually) looking for. I guess the limitation is in the | generalities of DocBook, since I could get it if I was using raw LaTeX. I'm curious about this. Can you provide a couple of examples of things you can't do in DocBook that you could do in LaTeX? I'm not interested in the mechanics, per se, but in what markup distinction you feel you've lost. | More details on linking documents, I've got 6 docs that I'm writing in | parallel and would really like to link between them. I gave up. These are six separate documents, or six parts of the same document? SGML doesn't really have a good cross-document linking solution (though you can cobble one together, see my tutorials about olink on nwalsh.com). XPointer and XLink should do better, but there are still some problems given that you don't typically publish the source. Be seeing you, norm -- Norman Walsh | A moment's insight is sometimes worth a http://nwalsh.com/ | life's experience.--Oliver Wendell | Holmes From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 07 Jul 2000 14:42:00 -0000 Message-ID: <87puopaa7c.fsf@nwalsh.com> References: <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <20000706131959.A25726@thyrsus.com> <20000706150802.A26225@thyrsus.com> <20000706180129.C26696@thyrsus.com> <20000706195444.D27191@thyrsus.com> <87wviym26y.fsf@nwalsh.com> <20000707122209.B30286@thyrsus.com> X-SW-Source: 2000-q3/msg00064.html Message-ID: <20000707144200.wr2zNo84PMcCHBbq4cgb2ySlLDce8kCSOK_fDSngV7k@z> / "Eric S. Raymond" was heard to say: | Norman Walsh : | > Second, I'm tired of your whining about the theology and jargon. I'm | > sorry if TDG didn't answer your questions, I'll try to do better next | > time (although I still think it's an authors prerogative to decide | > what is and what is not in scope), but I don't think it's either | > theological or jargon-filled. | | In this respect (if not in others), you and the other core DocBook | people who share this belief are still out to lunch. And that's sad, | because it seriously hinders the deployment of your good work. Moments after sending this message, I regretted making the assertion that it wasn't jargon-filled. That's nonsense and I knew better. (I really don't think it's theological, but if you do, I won't argue the point any further.) There's a definite tension when it comes to vocabulary and it bites very deeply in SGML, possibly because I'm familiar with it, although my intuition is that it bites deeply in SGML in part because it's worse in SGML than in many other jargons. 8879 was written by a lawyer after all :-) As I expressed earlier, perhaps badly: using the precise 8879 terminology (which I don't claim to have done, in the interest of trying to fight this exact problem, even if you think I failed) is a way of describing things in a precise, technically unabiguous way. Alas, it comes at the expense of the poor reader who could care less about the distinction between a "tag" and a "generic identifier". The trouble is that using loose, informal terms eventually leads to confusion in those areas where it really makes a difference. Maybe I got the balance wrong. I could have done better. | > It seems to me that the bulk of your ranting boils down to: | > | > "The tools one needs to format a DocBook document and get HTML or | > print output are insufficiently documented and too hard to install and | > use." | | Nope, see above. Above only asserts that I'm out to lunch, it doesn't actually describe any specific problem that I might be able, even anxious, to help you with. | The fact that SGML initiates can't see how | impenetrable their sacred texts are is a larger problem than the lack | of documentation for specific tools -- because it means that said | documentation is unlikely to get written or reviewed by exactly those | who ought to be best qualified to do it. I don't think that follows. I'd love to expand on the publishing sections of TDG to provide practical answers to practical problems in more detail. And now that the tool sets are becoming more mature, I think there's a good chance I'll be able to do that. I'd still like to see a tool set that ran on both NT and Linux, but that may not yet be practical. And I'll happily review anything written on the subject if I'm asked. | "Floggings will continue until morale improves." :-) No, in fact, I'm | not flogging you for moving too slowly. I'm flogging you for an | apparent inability to understand "motion" at all. I'll stop when you | either clue in or my arm gets tired. Your polite, reasoned demeanor invariably improves my morale. Thank you, sir! May I have another, sir! | So why didn't *you* figure one out this out two years ago? Why does | it take an outsider, jumping up and down and screaming, to point out | the obvious? It must be wonderful to always have all the right ideas at the right time. Alas, I have not your gift in that regard. Oh, and by the way, while it may take an outsider, it does not take an outsider jumping up and down and screaming. That has very nearly driven me to stop reading your posts. Be seeing you, norm -- Norman Walsh | DNA neither cares nor knows. DNA just http://nwalsh.com/ | is. And we dance to its music.--Richard | Dawkins From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: docbook-tools-discuss@sourceware.cygnus.com Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 28 Jul 2000 10:44:00 -0000 Message-ID: <8766pq40b3.fsf@nwalsh.com> References: <200007041511.LAA15779@snark.thyrsus.com> <00070410352500.07357@ehome.inhouse> <873dlnjklb.fsf@nwalsh.com> <1000706095536.ZM1901@sgi.com> <3981C236.9E85D170@cybercable.tm.fr> X-SW-Source: 2000-q3/msg00097.html Message-ID: <20000728104400.Sk31nUWENTzOuyZ3NGplID8OzZFX_iQdoAJMBhP9SHU@z> / Eric Bischoff was heard to say: | or whether the user installed it or not. So far, to rely on | a CGI helper program seems to be the nearest thing from this | holy graal, but first I don't see exactly how to implement | it, and second I'm worried about assuming there is an HTTPD | server up and running. I can't help with the second part, but I did the first part. Look over the olink docs on my website, I think it's described in there and let me know if you have questions. Be seeing you, norm -- Norman Walsh | When we are tired, we are attacked by http://nwalsh.com/ | ideas we conquered long ago.--Nietzsche From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Bischoff To: Peter Ring Cc: 'Volker Paul' , "'docbook-tools-discuss@sourceware.cygnus.com'" Subject: Re: I'm trying to set up docbook-tools... Date: Mon, 14 Aug 2000 23:07:00 -0000 Message-ID: <3998DF53.D2C430F5@cybercable.tm.fr> References: X-SW-Source: 2000-q3/msg00125.html Message-ID: <20000814230700.YwgCPoMP-X6Kt1c7oDNljiFUi5_fl_ogtmnVzsn6aYw@z> Peter Ring wrote: > > I missed the re-start of this thread. Anyway, in case you didn't care to > search the archives, I'd like to re-post a list of a number of > introductions, most of which have been available for a while (read: long > before Eric Raymond started whining). Mark, What about putting all these links on the web page? Here is a completed list: A Crash-Course to DocBook http://public.lst.de/~eric/index.html An Introduction to DocBook http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro.html A Practical Introduction to DocBook http://www.oswg.org/oswg-nightly/oswg/en_US.ISO_8859-1/articles/DocBook-Intro/docbook-intro/index.html DocBook HOWTO http://metalab.unc.edu/godoy/using-docbook/using-docbook.html Practical information about the use of SGML/XML and DocBook on Debian http://www.debian.org/~bortz/SGML-HOWTO/potato/howto.html Practical information about the use of SGML/XML and DocBook on WindowsNT http://ourworld.compuserve.com/homepages/hoenicka_markus/ntsgml.html A fairly complete guide to O'Reilly's DocBook based production system http://www.oreilly.com/people/staff/crism/dsssl/orastyle/index.html A fairly complete guide for contributors to the FreeBSD Documentation Project http://www.freebsd.org/tutorials/docproj-primer/ -- Éric Bischoff - mailto:ebisch@cybercable.tm.fr __________________________________________________ \^o~_. .~. ______ /( __ ) /V\ Toys story \__ \/ ( V // \\ \__| (__=v /( )\ |\___/ ) ^^-^^ \_____( ) Tux Konqui \__=v __________________________________________________ From mboxrd@z Thu Jan 1 00:00:00 1970 From: Volker Paul To: Eric Bischoff Cc: Peter Ring , "'docbook-tools-discuss@sourceware.cygnus.com'" Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 16 Aug 2000 06:57:00 -0000 Message-ID: <399A9F34.A10C59AB@dohle.com> References: <3998DF53.D2C430F5@cybercable.tm.fr> X-SW-Source: 2000-q3/msg00126.html Message-ID: <20000816065700.7_j9hG_09kZDdkIyqxfp6UCqGQ8mGl4pS51gSg7JRrY@z> Hello, trying to run Jade, I get the following error message: jade:myfile.sgml:1:59:W: cannot generate system identifier for public text "-//Davenport//DTD DocBook V3.0//EN" jade:myfile.sgml:2:1:E: reference to entity "BOOK" for which no system identifier could be generated jade:myfile.sgml:1:0: entity was defined here jade:myfile.sgml:2:1:E: DTD did not contain element declaration for document type name jade:myfile.sgml:3:6:E: element "BOOK" undefined jade:myfile.sgml:4:12:E: element "BOOKINFO" undefined I suppose Jade hasn't the (right) DTD. How do I tell Jade where it is? Regards, Volker Paul From mboxrd@z Thu Jan 1 00:00:00 1970 From: Norman Walsh To: Volker Paul Cc: Eric Bischoff , Peter Ring , "'docbook-tools-discuss@sourceware.cygnus.com'" Subject: Re: I'm trying to set up docbook-tools... Date: Wed, 16 Aug 2000 07:30:00 -0000 Message-ID: <877l9hffel.fsf@nwalsh.com> References: <3998DF53.D2C430F5@cybercable.tm.fr> <399A9F34.A10C59AB@dohle.com> X-SW-Source: 2000-q3/msg00127.html Message-ID: <20000816073000.fAxd-0-0BWh4mmKSB2bZLyiLeZapsChAKINZTIxhEy8@z> / Volker Paul was heard to say: | Hello, | | trying to run Jade, I get the following error message: | | jade:myfile.sgml:1:59:W: cannot generate system identifier for public | text "-//Davenport//DTD DocBook V3.0//EN" | jade:myfile.sgml:2:1:E: reference to entity "BOOK" for which no system | identifier could be generated | jade:myfile.sgml:1:0: entity was defined here | jade:myfile.sgml:2:1:E: DTD did not contain element declaration for | document type name | jade:myfile.sgml:3:6:E: element "BOOK" undefined | jade:myfile.sgml:4:12:E: element "BOOKINFO" undefined | | I suppose Jade hasn't the (right) DTD. How do I tell Jade | where it is? Get DocBook V3.0 from OASIS, put it somewhere on your system, and update your catalog(s). Or convert the public ID to DocBook V3.1, which you probably have on your system and which is backwards compatible with 3.0. Be seeing you, norm -- Norman Walsh | Nothing will ever be attempted, if all http://nwalsh.com/ | possible objections must be first | overcome.--Dr. Johnson From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Bischoff To: Norman Walsh Cc: Volker Paul , Peter Ring , "'docbook-tools-discuss@sourceware.cygnus.com'" Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 18 Aug 2000 04:11:00 -0000 Message-ID: <399D1972.41D2ABAC@cybercable.tm.fr> References: <3998DF53.D2C430F5@cybercable.tm.fr> <399A9F34.A10C59AB@dohle.com> <877l9hffel.fsf@nwalsh.com> X-SW-Source: 2000-q3/msg00128.html Message-ID: <20000818041100.WmYtgUixXQM5UnDF5Ktk75dTtlNXLoBSci8SZwxPwZ4@z> Norman Walsh wrote: > > / Volker Paul was heard to say: > | Hello, > | > | trying to run Jade, I get the following error message: > | > | jade:myfile.sgml:1:59:W: cannot generate system identifier for public > | text "-//Davenport//DTD DocBook V3.0//EN" > | jade:myfile.sgml:2:1:E: reference to entity "BOOK" for which no system > | identifier could be generated > | jade:myfile.sgml:1:0: entity was defined here > | jade:myfile.sgml:2:1:E: DTD did not contain element declaration for > | document type name > | jade:myfile.sgml:3:6:E: element "BOOK" undefined > | jade:myfile.sgml:4:12:E: element "BOOKINFO" undefined > | > | I suppose Jade hasn't the (right) DTD. How do I tell Jade > | where it is? > > Get DocBook V3.0 from OASIS, put it somewhere on your system, and > update your catalog(s). Or convert the public ID to DocBook V3.1, which > you probably have on your system and which is backwards compatible with > 3.0. Or if you want to use the latest docbook-tools: - make sure you installed docbook-dtd30-sgml package - that's all ;-). jw now autodetects the catalogs to use. -- Éric Bischoff - Documentation and Localization Caldera (Deutschland) GmbH - Linux for eBusiness Tel: +49 9131 7192 300 - Fax: +49 9131 7192 399 http://www.caldera.de/ From mboxrd@z Thu Jan 1 00:00:00 1970 From: Eric Bischoff To: b_maddy_016@yahoo.com Cc: docbook-tools-discuss Subject: Re: I'm trying to set up docbook-tools... Date: Fri, 18 Aug 2000 05:55:00 -0000 Message-ID: <399D3222.9D842AB5@cybercable.tm.fr> References: <877l9hffel.fsf@nwalsh.com> <399D1972.41D2ABAC@cybercable.tm.fr> <00081817110500.03504@needaguru> X-SW-Source: 2000-q3/msg00130.html Message-ID: <20000818055500.QR8T6wdG0MsSQsM9mnDE2G5jmxyyP6etfP6PC2vPl6o@z> b_maddy_016@yahoo.com wrote: > > Hi, > On Fri, 18 Aug 2000, eric wrote: > > Norman Walsh wrote: > > > > > > / Volker Paul was heard to say: > > > | Hello, > > > update your catalog(s). Or convert the public ID to DocBook V3.1, which > > > you probably have on your system and which is backwards compatible with > > > 3.0. > > > > Or if you want to use the latest docbook-tools: > > - make sure you installed docbook-dtd30-sgml package > > - that's all ;-). jw now autodetects the catalogs to use. > > > > -- > > Éric Bischoff - Documentation and Localization > > it would have helped volker paul and many others including me if it was > mentioned from where it can be downloaded Bis repetita non semper placent, sed... ftp://sourceware.cygnus.com/pub/docbook/new-trials/ -- Éric Bischoff - Documentation and Localization Caldera (Deutschland) GmbH - Linux for eBusiness Tel: +49 9131 7192 300 - Fax: +49 9131 7192 399 http://www.caldera.de/