This is the mail archive of the
docbook-tools-discuss@sources.redhat.com
mailing list for the docbook-tools project.
Re: I'm trying to set up docbook-tools...
Wrote Norman Walsh on Thu, Jul 06, 2000 at 12:21:20PM -0400:
> / Eric Lee Green <eric@badtux.org> 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.
>
> <sigh/> 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