[NTLUG:Discuss] Re: good "book" format for html? -- take a look at an example DocBook document

[Bryan J. Smith]

On Mon, 2004-11-29 at 01:03, Bryan J. Smith wrote:
> I don't need an 18 blade Swiss army knife,

I think you don't realize that DocBook is kinda like a 5 knife kitchen
set.  It's pretty straight-forward, does one job, and does it well.

If I want something I can give to someone else, then I often use a
stylesheet to turn DocBook into that.

> my little 4 bladed one (HTML :-) works just fine.

I think you have some misconceptions on what DocBook really is.  You
should really look at some example DocBook documents.

Here's an example:  
http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/segmentedhtml/ch08s03.html

First off, note the general structure:  

    <chapter><title>Part 1, Chapter 1</title>
      <sect1><title>Part 1, Chapter 1, Section1</title>
        <para>
	  GoodDay there!
	<para>
        ...
      </sect1> 
      ...
    </chapter>
    ...

Pretty straight forward.

Now note all the things you _don't_ see.

TOC, indicies, various things that would have to be manually generated
with HTML.  These can typically be added with a _single_ tag or, more
flexible yet, done in the stylesheet when I turn out the PDF, HTML,
etc...  In fact, there are countless DocBook Templates to "try out" to
find a format you like.

What if I want to turn a few of my chapters into appendices?  At some
point, I can merely add a _single_ tag mid-document and all chapter
after that are now appendicies.

Simple, straightforward, but powerful.  That's the difference between a
"formal structure" for an "article" or "book" and what I would get with
a "free-form, published" format that consists of "styles" without such
context.

Normally HTML will do fine.  But when you start talking about "parsers"
and/or piecing together submissions from different authors, then you're
in for a shocker.  You need a well-defined "formal structure" and a way
to apply style uniform.  HTML will never give you that, it too free-form
in the document (even if you use CSS).

Again, I said you can do this yourself.  You can take HTML, and add in
your own "meta-tags" -- e.g., "<!-- chapter -->" -- and write parsers
for it.  The "<!--" is a comment which still makes it standard HTML. 
Many "dynamic" HTML-based languages do this.  It doesn't have to be
formal, and it can work only for you.  Of course, it still doesn't solve
the issue with your additional submissions not conforming to your
"meta-tags," that would have to be manual.

Or you can be more formal and write a completely new XML instance based
on a "basic HTML subset" and extend it as you desire.  That would create
a brand new, but very well-defined XML instance.  If it worked well,
others might take an interest.  And if not, you'd still have a set of
tags that _could_ be enforced by a parser. 

But "raw" HTML, trying to piece together submissions from multiple
authors, let alone build a parser, I wish you the best of luck.


-- 
Bryan J. Smith                                    b.j.smith at ieee.org 
-------------------------------------------------------------------- 
Subtotal Cost of Ownership (SCO) for Windows being less than Linux
Total Cost of Ownership (TCO) assumes experts for the former, costly
retraining for the latter, omitted "software assurance" costs in 
compatible desktop OS/apps for the former, no free/legacy reuse for
latter, and no basic security, patch or downtime comparison at all.