Re: XML-based Help Authoring tools for customized help

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

Eric Dunn wrote:

> Mark, you've fallen into exactly the same trap as others in this
discussion.
> Docbook is in no way whatsoever comparable to FrameMaker. You don't choose
> Docbook instead of FrameMaker. You're mixing the concepts up I'm afraid.

Oh Eric! It was so much more fun when you agreed with me. But I'm afraid
your statement is over the top.

Docbook is comparable to FrameMaker in some ways and not in others.

The key respect in which they are the same is that each represents a set of
document oriented data semantics which has a particular set of strength and
weaknesses.

Now it is true that the word "DocBook" attached primarily to a DTD and that
the word "FrameMarker" attaches primarily to an executable program.
Nonetheless, people can and do talk about "adopting FrameMaker" and
"adopting DocBook" by which they do mean, in each case, adopting a
comprehensive set of data semantics and executable functionality.

Yes, The FrameMaker executable (in its structured version) does have the
ability to edit and publish data formats other than its own. It is, in
effect, both a generic structured editor bolted on to a specific document
publishing system. It is bolted on quite well in many respects, though I
can't say that I find the result to my personal taste as a work environment.
However my point remains true that native Frame has one set of data
semantics and Docbook has another, and that those semantics are broadly
similar.

> You can use Docbook and a FrameMaker inclusive toolset.
> You can use Docbook and MSWord inclusive toolset (I'll assume the XML
aware
> version of Word anyway).
> You can use Docbook and one of several other commercial toolsets.
> You can use Docbook and one of several open-source toolsets.
> You can use Docbook and a unique assembly of tools.

You want to argue that Structured Frame can be use as a universal toolset,
regardless of the data semantics involved. That is fair enough. My point was
never to dispute that. My point was and is to dispute the notion that to
adopt Docbook is to adopt XML.

And that really brings us back to the one and only essentail point here:

ADOPTING DOCBOOK IS NOT ADOPTING XML. IT IS JUST ADOPTING DOCBOOK.

We can argue round and round as much as we like about that the word
"application" means or what the precise technical configuration of Frame and
Word may be in respect to DocBook or their own file formats but one clear
and simple point still needs to be understood:

ADOPTING DOCBOOK IS NOT ADOPTING XML. IT IS JUST ADOPTING DOCBOOK.

> Whether you start with your own DTD, a pared down Docbook DTD, or a
variation
> Docbook plus your own requirements, the Docbook standard is still useful
for
> interchange with other Docbook conscious systems.

Agreed completely. But the choice among the alternative you present is based
on the data semantics you need to drive the process you need to efficiently
create and deliver the information you need. The choice is between existing
formats with existing tools, and custom formats for which you will have to
create custom tools. But until you start to create custom formats you are
not using XML yourself, you are just using something that uses XML,
because...

ADOPTING DOCBOOK IS NOT ADOPTING XML. IT IS JUST ADOPTING DOCBOOK.

> That's what XSLT is for.

Now whose doing it?! XSLT is just one on many approaches you can use to
transform data from one representation to another. The are many
alternatives.

> All this discussion, at not one word of the advantages or disadvantages of
> Docbook structure. Blech.

Mostly agreed. I have repeatedly asked the proponents of Docbook to defend
its specific merits as a format. All they come back with is the assertion
that it is a standard.

I, on the other hand, have written about some of the disadvantages of the
Docbook structure, pointing out that it is too big, too loose, and too
generic for ease of authoring or for ease of processing.

> If we move back a step or three and look at the requirements again there
are
> several things to look at individually:
>
> - How is the information best structured. (Which DTD for information
gathering)
> - What tools are best for gathering the information.
> - How is the information best stored. (which has an impact on the input
DTD(s))
> - What tools are best to store the information.
> - How is the information best assembled for delivery and in how many
different
> ways. (output DTD(s))
> - What tools are best to assemble the information.
> - How are the various outputs formatted.
> - What tools are best to produce the various required formatting.

Yes, these are all important questions. But before you ask any of them you
need to ask what process will support the most efficient creation,
management, and delivery of information. The question "how is the
information best structured" can only be answered when you know what process
you are going to use. The answer is the structure that best supports the
process.

> And often 'best' is purely subjective.

I humbly suggest that if it is purely subjective it is only because you have
failed to examine and express the objective criteria on which the decision
should be made.

> We now save all FM generated SGML
> fragments into a document repository and then use scripts to further
splinter
> the fragments and then assemble the final deliverable SGML and FM to
format it
> for paper and PDF. Another group of tools produces electronic output.

In my last job we used a custom-built forms-based interface with a number of
very small, tight, topical DTDs. We stored the components created through
this interface in a relational database and used scripts to assemble
documents which were then delivered to the web by directly generating HTML,
to WinHelp by directly generating RTF, and to PDF by importing a synthesized
document into Frame and saving to PDF.

I had Frame enthusiasts resist using this interface at first, but after a
few weeks on the system they told me they never wanted to go back to Frame.
The custom interface was so simple and easy to use that it made their lives
so much easier than Frame.

On the other hand, they got so enthusiastic about the system that they tried
to use it for types of documents for which it was not intended and soon got
themselves into a real mess. We had to back out that work and create a new
DTD for the new document type.

Topical interfaces are always easiest to use, simply because they are
topical. However, they don't work when you get off topic.

> But, for another project it was far more intelligent to use many of
FrameMaker's
> strengths that are impossible/very difficult to reproduce and maintain in
SGML
> and we store all content in FM documents and at production time run
numerous
> scripts to obtain the production paper and PDF and save as SGML to feed
the
> electronic document production workflow.

Given a reasonably powerful set of tools, you can usually come up with
workable strategies for getting stuff done. And it is certainly true that
you cannot implement a different completely topical, completely optimized
toolset for every set of documents you produce. You go for the big wins on
the big projects and you look for sufficiently flexible generic tools that
will allow you to do the rest.

Which brings me yet again to the chorus of this little ditty. Docbook is a
generic tool, like Word and Unstructured Frame. XML is a standard for
defining tagging languages, which allows you, therefore, to create topical
markup languages for use in specific information gathering processes. Thus
demonstrating once again that...

ADOPTING DOCBOOK IS NOT ADOPTING XML. IT IS JUST ADOPTING DOCBOOK.

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.