Re: XML-based Help Authoring tools for customized help

[Sean Wheller <seanwhe -at- yahoo -dot- com>]

----- Original Message ----- 
From: "Chris Gooch" <chris -dot- gooch -at- lightworkdesign -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Wednesday, December 17, 2003 7:00 PM
Subject: XML-based Help Authoring tools for customized
help


Chris Gooch wrote:
> Q. Is DocBook a suitable application-specific
language for doing
> technical documentation?
>
> But then if I give my doc to another technical
writer somewhere in the
> world, they would need to know my extensions (so
like, that's OK I give
them the
> DTD along with the file just as I'd give them the
style file along with a
> LaTeX file or a .dot along with a .doc).

Hello Chris,

By extensions I assume that you mean, extensions to
the language. If this is
the case, I will assume that your have used a standard
DTD/XSD such as
Docbook and have written a customization layer. That
is to say, you have not
modified the Docbook DTD files, rather you have
created a new DTD and
included the Docbook DTD into your DTD. Within your
DTD you may overide
elements etc. and add your own new elements
(extensions). Your new DTD is a
customization.

To identify your DTD to other authors, you should
provide Document Type
Definition. For Docbook this is:

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML
V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd";>

You will not use this Document Type Definition, you
will use your own. This
could look something like this:

<!DOCTYPE article PUBLIC "-//LIGHTWORKDESIGN//DTD
DocBook XML V4.2//EN"
                        
"http://www.lightworkdesign.com/dtd/lwd-0.1.dtd";>

This DTD contains your extensions or customizations
and includes by
reference the Docbook DTD. From your DTD I can see
that it is a
customization, specific to LWD thatis based on
Docbook. I can also see that
the DTD is published on a URL. Before I use this DTD I
would examine it. So
I would take a copy of lwd-0.1.dtd. As I already know
DTD DocBook XML
V4.2//EN I will only need to read your DTD to learn
the customizations. For
less technical users it is advised that you provide a
document of your
customizations and their use.

When I use the DTD, there is no need for me to have a
local copy (I will not
bring XML Catalogs into this now). I can receive an
XML file from you that
specifies your DTD and knowing the extension, I can
modify and validate my
version of the document. When I am writing I will
markup the text using the
elements available in your DTD. This includes the
Docbook elements and your
own.

Let's say that you added a block element called
document. It is a wrapper
for the Docbook book or article elements.
An example XML instance could look like this (without
the SOF and EOF):
--SOF
<!DOCTYPE document PUBLIC "-//LIGHTWORKDESIGN//DTD
DocBook XML V4.2//EN"
                        
"http://www.lightworkdesign.com/dtd/lwd-0.1.dtd";>
<document>
    <article>
        <title>Article Title</title>
        <sect1>
            <title>Section1 Title</title>
            <para>Text</para>
        </sect1>
    </article>
</document>
--EOF

If I tried to validate this document against the
Docbook DTD using the Saxon
Parser it would throw two error messages that may look
something like this:

- Document root element "document", must match DOCTYPE
root "article".
- Element type "document" must be declared.

If were to validate agains the LWD DTD I would not get
any error. The XML
instance will be valid.

The document element is sematic it represents a
document that may be a book
or an article. It must be spelt correctly, must have a
fore and aft tag and
must contain either a book or an article element.
Because of this, other
authors will find it hard to make mistakes. If they do
Saxon will give them
an error. Providing that an author validates a
document before sending it
back to you, you can be assured that the structure of
the markup is as
required. If you're not sure just validate it
yourself. Assuming that the
author understands the purpose of each element in the
new DTD and the
Docbook DTD, then the content should be marked with
the correct semantic
meaning.

In this way, XML instances that specify a Document
Type Definition can be
easily exchanged between authors without having to
send the DTD along with
the XML instance. Combined the XML instances and its
DTD/XSD are
self-describing. All authors can work from a
centralized DTD, regardless of
thier geographic location. All can markup documents in
the same way. A few
carefully thoughtout guidelines will help reduce the
senario where an author
uses the wrong tag for a piece of content.

A word of note. Since you have modified the Docbook
DTD, the Docbook XSL's
will also need a customization layer. This layer will
enable transformations
to handle your extensions, such as the document
element. Without this your
transformations will fail. These to can be located on
a URL, although both
the DTD and the XSL's will be heavy and will slow
processing. To overcome
this problem, we use XML Catalogs. XML Catalogs
resolve Document Type
Definitions to local copies of a DTD. This may be in
your LAN or on your
hard drive. Whithout an XML Catalog authors, wanting
to speed processing,
would modify your Document Type Definition to point at
a URI that is local.
It may look like this:

<!DOCTYPE document SYSTEM "-//LIGHTWORKDESIGN//DTD
DocBook XML V4.2//EN"
                         "~/dtd/lwd-0.1.dtd">

This inevitably results in authors sending out XML
instances specifing URI's
that do not correlate to the DTD location on remote
systems. With XML
Catalog nobody needs to modify the Document Type
Defintion, but everyone can
have a local copy of the DTD to speed processing.
Indirection of this type
is widely employed with Docbook, but it not unique to
Docbook.

>
> Does anyone have practical coal-face experience of
using DocBook to:
>
> 1) 2) 3) 4) .... 11)
The answer to all these questions is "Yes".

Docbook is widely used for a variety of computer
software and hardware
related documents. It is also flexible enough to be
adapted for other types
of writing.

> Anyway what I'm wondering is, what are people
actually managing to
> achieve? (for example, using DocBook). I would at
this point find that
> more instructive than further philosophical debate
(I can see where
> everyone stands I think).

There is no definite answer as there are any number of
permutations to the
reasoning of why people adopt. However, I will
attempt:

Docbook XML instances are platform and XML application
(tool) independent.
Document data can be opened and edited using a wide
range of XML Editor
applications on any operating system, training is
reduced. This in turn
promotes a collaborative authoring process. Document
data, being XML, is
also easily transportable via the Web using standard
Internet protocols. In
a collaborative environment authors can access and
contribute on a central
repository using familiar tools. This reduces content
duplication, promotes
change control, information discovery and
reutilization.

Docbook XML instances only describe document data and
specify processing
instructions. The data is therefore void of any
presentational
characteristics. With the aid of XSLT multiple
formatted file types can be
targeted, without having to modify content. When
content is placed within a
larger application, content can be dynamically
transformed to the format
required by the reader or for input to another system,
consumption is not
limited to humans but also includes machines. In
addition, content may be
personalized to suit the particular platform or
user-requirements. Taken a
step further, it is not hard to visualize that a users
will be able to
obtain a version of a document that is specific or
tailored to their needs.
This may be determined by a system profile or by
personal user choices and
interaction. Something like DVD movies where you can
select the outcome.

The application of XML for authoring and publishing
can result in
significant savings in a number of areas. However, it
should be noted that
many of the benefits will only be realized in large or
industrial scale
publishing environments. In addition, savings are not
immediate.

This is not everything, but I hope that it gives some
idea and possible hint
of the future. To quote a futurist:
<epigraph>
      <attribution>William Gibson</attribution>
      <para>The future is here. It's just not widely
distributed yet.</para>
</epigraph>

Sean Wheller





__________________________________
Do you Yahoo!?
New Yahoo! Photos - easier uploading and sharing.
http://photos.yahoo.com/

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

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.