This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: [docbook] First Attempt at Writing a Manual Not Going Well
- From: "Brian M. Sutin" <sutin at ociw dot edu>
- To: docbook at lists dot oasis-open dot org
- Date: Thu, 17 Apr 2003 10:47:45 -0700
- Subject: Re: [docbook] First Attempt at Writing a Manual Not Going Well
- Organization: The Observatories of the Carnegie Institution of Washington
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 (www.docbook.org) 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:
<section>
<sectioninfo>
<author>
...stuff...
</author>
</sectioninfo>
</section>
and
<section>
<author>
...stuff...
</author>
</section>
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 oasis-open.org.
In summary, is there something I can go read that will educate me?
DocBook for Dummies? Idiots Guide to SGML?
Brian
--
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