This is the mail archive of the mailing list for the DocBook project.

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: [docbook] First Attempt at Writing a Manual Not Going Well


See my 2 cents below:

Brian M. Sutin wrote:
Thank you, everyone who responded.  There is one comment I would like
to respond to myself:

On Thu, Apr 17, 2003 at 09:26:25AM +0200, Stephane Bortzmeyer wrote:
Reading your message, it seems you do not have (yet) a clear
understanding about what DocBook is and isn't.

You got that right!

I *think* I understand the general idea of DocBook; it is the
implementation on my part the boggles me.

Boggle #1:

When I actually try to sit down and write, I find myself
spending vastly more time paging throught the (relatively
incomprehensible) manual from O'Reilly that I do actually
entering information. I don't even have a recent manual.
The online version ( has wonderful bits like:

AuthorBlurb and Affiliation will be removed from the inline
content of SectionInfo in DocBook V4.0. A new wrapper element
will be created to associate this information with authors,
editors, and other contributors.

I am using DocBook V4.1, and the most recent online manual
is not even V4.0? Am I looking in the right place?
Something went wrong with the Oasis site where I used to be able to find links to the DocBook DTD ( I would like to point you to the DTD so you could download it for your enjoyment but I can't find it. Hopefully someone in the know can fix this or tell us what happened to the links.

Also, I can't even find the DocBook DTD on SourceForge ( The reason I bring this up is that you could read through the DTD, the O'Reilly book, and an XML reference to see what is going on. The point is moot without the DTD though.

Boggle #2:

DocBook appears to be something which grew, rather than
something which was designed. I know I would not create it
this way! There is no uniformity over scale. For example,
there could be a <who wrote this> wrapper which could be
included in sets, books, chapters, sectn, &c. Instead,
there appears to be something slightly different for each.
No wrapper at all would work; there is no syntactic
informational difference between:




Either way, the <author> information must be describing the
<section>. I must be missing something here.

Take a deep breath. I can't give you the rationale as to how the DocBook grew but here's what I suggest you try to do. First try to structure your document in a tree. For example:

    User Guide (chapter with its editor's name)
        Section (with its author's name)
    Technical Reference (chapter with its editor's name)
        Section (with its author's name)


    User Manual (book with its editor's name)
        Chapter (with its author's name)
    Technical Reference (book with its editor's name)
        Chapter (with its author's name)

Getting this structure down will allow you to focus on the required elements as indicated in the O'Reilly book. It is a bit confusing but the answers are there if you couple that information with XML DTD coding. Now, as for the authors' names, they can be added as specified in the O'Reilly book (as specified in the DocBook DTD) to denote who wrote what within the structure. The problem here is that the stylesheet you use to produce output (such as HTML) would have to be altered to present the editor's and authors' names as you require. This is a separate issue from the structure permitted by the DocBook DTD.
Boggle #3:

I would think that the importance of a piece of information
would be part of DTD, and not part of the style sheets. Yet
the style sheets determine whether a particular bit of info
is printed or not. I realize that we have "Separation of
Church and State" here, but couldn't the DTD and the style
sheets at least communicate? Something like, "Hey, who
wrote this is important, don't forget to print it somewhere!"
After all, <emphasis> contains no information as to the
content of the surrounded text, only that it should be
marked up in a special way. We've broken the paradigm
already. Why not a <showthiscauseitsimportant> tag?

The stylesheet takes the valid XML file and converts it to an outlut file, such as HTML, as directed by its programming. The stylesheet determines what is important in the XML file. The stylesheet  could be programmed to ignore everything except the authors' names and produce the names as the only output. In other words, the XML file indicates structure while the stylesheet (or other programming interface) determines what is important.

Boggle #4:

(Not really DocBook) Where can I learn about ENTITY? Can I
use it as a sort of macro system for things I don't want to
type fifteen times? Chapter 2 of O'Reilly's DocBook is, again,
incomprehensible. All it does is give a link to some useless
document at

In summary, is there something I can go read that will educate me?
DocBook for Dummies? Idiots Guide to SGML?
I have the XL Bible by Elliotte Rusty Harold which provides some insight into XML. I have the XSLT Programmer's Reference by Michael Kay for stylesheet stuff. I have been teaching myself by using these books and the DocBook DTD and XSL files.

Start small, like making your structure trees for your documents. You also need a validator to verify your XML tagging attempts. I can help point you to a few things if you need, but I am in no way an expert.

Sincerely, Jeff Biss


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