Re: XML-based Help Authoring tools for customized help

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

Karen Casemier wrote:

> (I can't believe how many tools I've found that claim to be "XML" tools,
but hide all the functionality
> of XML so it is basically a poor man's RoboHelp).

This is pretty much inevitable. The functionality of XML is that it allows
you to create your own tagging languages. (That is the only functionality of
XML per se.) Tools, however, implement specific functionality and you cannot
implement specific functionality for a custom data model. All you can do to
support the use of custom data models is to provide a genertic authoring
model, and generic storage model, and a domain specific processing language.
This is what RDBMS products do for tabular data and it is what structured
editors, XML databases, and markup-aware programming languages do for XML.

> This is an example of what I'd like to be able to do with our source
files:
> Create a "field" element for all field definitions.
> Assign an ID attribute to each field element.
> If a client customizes their system to hide some of the fields, we can
filter the XML content to
> exclude the fields (based on the ID attribute) that they have hidden.
Basically, we would
> build the client a customized help system to match their unique
configuration.

And there is the crux of the matter. You want to create a custom data model
and perform custom processing on that data model.

Your basic problem is that for now you only want one custom field. But you
still need to provide markup for all the other elements of your content. And
as Sean and Bill have pointed out, you need a "tool chain" -- a series of
processing steps that will take your custom markup language and process it
to produce the help files you want.

There are three approaches you can take:

1. Adopt an existing markup language like Docbook and either take advantage
of built in customization features in the language or create your own
extension. You then inherit the entire Docbook tool chain, however, you will
have to do some modification of that tool chain to make it perform the
custom processing steps that you want. The upside to this approach is that
most of the work is done for you. The downsides these: First, Docbook, like
all generic markup languages, is overblown, unwieldy, and too loose. It will
be harder for authors to learn and use effectively. Second, modifying an
existing tool chain, even in the most minimal way, can be more difficult and
error prone than creating your own, and can lead to complicated upgrade
issues. The extent of this problem, however, depends on the nature of the
custom processing you need. It may not be significant in your case.

2. Create your own tagging language from scratch, keeping it as simple as
possible. In many cases, you need less than a dozen tags that can be
borrowed from HTML: p, h1, h2, h3, ul, ol, li, table, tr, td, and possible
b, i, and pre. Add your custom tags to that set and you have something that
is small, tight, and easy to learn and process. If you need something more
complex later on, you can easily transform this simple language into
something else. However, complexity is something to be shunned in any
author-facing tagging language. You now build your own tool chain by
creating a simple processing routine to convert from your custom language
into the HTML help format. The is pretty much a one step process. Perform
your custom processing on your highly simple input format, and create HTML
help markup as output.

3. Create your own tagging language from scratch, as in 2. But rather than
creating your own tool chain, hijack the DocBook tool chain (or the DITA
tool chain, or any other existing tool chain) by writing your custom
processing routine to output DocBook (or DITA, or whatever.) Then feed the
result through the existing tool chain.

The choice between 2 and 3 comes down to whichever is easiest to program. 3
may give you more choices because the existing Docbook to HTMLHelp converter
may be more sophisticated and offer more options than you have time to
create for yourself.

However, I would definitely recommend you choose 2 or 3 over 1. It makes
life simpler for your authors and makes it easier for you to expand the
scope of your custom processing as you develop your applications. You don't
want to saddle everybody involved, from authors to programmers, with dealing
with the complexity of Docbook just to save the work involved in creating
your own language up front.

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.