[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] First Attempt at Writing a Manual Not Going Well
20030417104745.A31249@zot.ociw.edu">Something went wrong with the Oasis site where I used to be able to find links to the DocBook DTD (http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook). 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.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?
20030417104745.A31249@zot.ociw.edu">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:
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.
20030417104745.A31249@zot.ociw.edu">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?
20030417104745.A31249@zot.ociw.edu">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.
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?
20030417104745.A31249@zot.ociw.edu">
Brian
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]