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