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

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:
> [...snip...]
> Reading your message, it seems you do not have (yet) a clear
> understanding about what DocBook is and isn't.
> [...snip...]

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?

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.

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?

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?


Brian M. Sutin      Instrument Scientist       Pasadena, CA
The Observatories of the Carnegie Institution of Washington

To unsubscribe, e-mail: docbook-unsubscribe at lists dot oasis-open dot org
For additional commands, e-mail: docbook-help at lists dot oasis-open dot org

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