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

[Jeff Biss <jeff at marco-inc dot com>]

Brian,

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:
> > [...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?
>     
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. 
    
Also, I can't even find the DocBook DTD on SourceForge (http://sourceforge.net/projects/docbook/).
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:
>
> 	<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.
>
>       
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:
      
 Book
     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)
      
 OR:
      
 Set
     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 oasis-open.org.
>
> 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
> Brian
>
>
>