This is the mail archive of the docbook-tools-discuss@sources.redhat.com mailing list for the docbook-tools project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

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

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]