Re: XML-based Help Authoring tools for customized help

["Mark Baker" <listsub -at- analecta -dot- com>]

David Neeley wrote
> "Actually, what they are is out of the box applications with specific
> semantics."
>
> Sorry, Mark, but I am totally confused by your remark. Apparently, you and
I have a *VERY*
> different understanding of the word "applications." Of course, various
other people within
> the XML community have likewise been a little loose with the term from
time to time.

Fair point. So let me define how I was using "application" in this sense.

Within the SGML community, a DTD is called an "application" of SGML, so in
that sense, the Docbook DTD itself is an application. However, that wasn't
the sense in which I was using the word.

The word is also used to indicate a single executable computer program. I
don't mean it in that sense either.

What I mean is a application in the same general sense that Word or Frame
are applications. That it, as packages that include standard data formats
and collections of programs that operate on those data formats to accomplish
a defined set of objectives.

Bill's argument in favor of using Docbook rather than a custom markup
language was that the data format is well defined and published and that
there is a ready made set of programs to work with it, including both
editing applications and various processing and publishing programs. My
point was that Docbook, understood not only of the file format itself, but
the whole "tool chain" designed to work with that tool chain, is a packaged
application more or less equivalent to Word of Frame, of, for instance, Open
Office.

To illustrate the parallel further, lets compare Docbook to these other
packaged application on several points.

Published file format: The Docbook format is published and downloadable
separately from the "tool chain", so are RTF, MIF and the Open Office
format.

Standard application package: Docbook has a standard package just like Word,
Frame, etc.

Third party extensions: People can write Docbook processing applications
independent of the standard application package. Ditto for Word and Frame
(RoboHelp, WebWorks, etc., are examples.)

User customizable: Users can extend the functionality of the Docbook tool
chain by writing their own code. People can use a standard parser to parse
the document structure. This is also true of Word. VBA give you direct
access to the internals of a Word document without making you parse the file
format yourself.

User extensible semantics: Users can extend the semantics of the Docbook
file format through standard extension mechanisms or by extending the DTD.
The price for doing so is that you have to write some code yourself to
process those custom semantics. Word and Frame also allow you to extend
their basic semantics. You can do this through the use of embedded fields or
simply by the use of a stylesheet whose tag names have been designed with
some semantic effect. A common case of this is that some people use Word
styles to make Word work as a kind of XML editor, by mapping the style names
to XML elements in a post processing steps.

Now you could certainly argue that Docbook had certain advantages over their
other packaged applications mentioned here (and some people would doubtless
reply with advantages of Word or Frame) but my point remains true: Docbook
is a packaged application like Frame, Word, and OpenOffice, and is designed
and used for broadly the same purpose.

> I truly believe that the parallel you attempt to draw between Frame styles
and DocBook tags is only
> partly accurate. ...  They may be named in a fashion which indicates the
function of the element,
> true enough. However, they are not designed to be altered with any sort of
equivalent to schema
> or DTD...

Sure they have. A Word stylesheet or a Frame template are the equivalent of
an XML DTD: They define a set of named "elements" which can be assigned to
spans of text. You can change a stylesheet or template just as you can
change a DTD, and for much the same purpose

There are some structural differences between DTDs and
Templates/Stylesheets:

 First, Frame and Word have different types of elements (documents,
sections, tables, paragraphs, characters) and predefined content models
based on those types (broadly: documents contain sections, sections contain
paragraphs and tables, tables contain paragraphs, paragraphs contain
characters). XML has only one type of element and allows user defined
content models. Both are useful models for describing the structure
documents. The XML model is more open-ended and can be use to model other
things besides documents.

Second, Frame and Word have open content models. That is, you can insert
direct formatting into your document without using styles. XML Schema now
permits open content models as well, but it also lets you keep your content
models closed (which is a good thing).

Structural differences aside, however, they serve the same function. They
allow you to define and name text spans so that you can apply formatting or
other kinds of processing to those text spans.

> The fact is that DocBook is as a standard a *superset* of what most users
will need; it permits
> various combinations of styles which may work best for one organization
and another subset
> for another without departing from the standard.

That is a very good description of what it does. But notice what the
consequences are of it being a superset of each user's needs. It means that
it is not only bigger and more complex than some users need, it is actually
bigger and more complex than any one user needs.

And Docbook is, at best, only a superset of what most users need from a
document description language. There are document description needs it
doesn't meet. There are also a wide variety of content capture,
customization, automation, and exchange functions that it does not meet.

> With an appropriate schema or DTD, of course, you can produce a wide
variety of appearance
> details for any given instance of a DocBook-compliant document using any
of the *applications*
> which you may prefer that can work with the standard.
>
> That is, in fact, why SGML and later XML were first developed.

SGML and XML were developed for a number of reasons. But they key feature of
both is that they are *generalized* markup languages. They were developed
out of the recognition that no one tagging language was able to meet all
needs and that the development of custom tagging languages was an
unavoidable necessity. They were also developed out of the recognition that
it was easier to develop custom tagging languages if they shared a common
syntax and thus could be interpreted using a common parser. But the point is
this: SGML and XML were both developed out of the explicit recognition that
the development of custom application-specific tagging languages was both
necessary and appropriate.

> As for using DocBook or another XML standard versus some other
custom-built approach, that
> also depends very largely upon the flexibility you wish to have later on
in the life of the document.

Yes, except that if you want flexibility you have to stop thinking in terms
of documents and start thinking in terms of content. Documents are just
presentation mechanisms for content.

> Because of the rapid evolution of products such as content management
systems that
> understand XML, and because of the growing understanding of and tools for
the major
> standards such as DocBook, I believe that the place you should start today
may well be
> a selection of the subset of one of these standards. By selecting the
basics from HTML
> as you suggest would be abandoning the easy introduction of these
fast-maturing tools.

Never start with tools. Never never start with tools. Start with your
content and your business needs, and the process you need to apply to your
content. The choose tools that support those processes in the most robust
and efficient manner possibly.

> Later, should you have enough data to make a CMS appropriate, wouldn't it
be *nice* if you
> *already* have your documents in a form which can immediately be used?

You have to stop thinking of documents as an input. Information is the
input. Documents are the output. In between there are process that act on
information and that eventually produce documents or other information
vehicles. That is what you have to plan for.

Mark Baker
Analecta Communications


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP FOR FRAMEMAKER TRIAL NOW AVAILABLE!

RoboHelp for FrameMaker is a NEW online publishing tool for FrameMaker that
lets you easily single-source content to online Help, intranet, and Web.  
The interface is designed for FrameMaker users, so there is little or no
learning curve and no macro language required! Call 800-718-4407 for 
competitive pricing or download a trial at: http://www.ehelp.com/techwr-l4

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.