Re: XML in documentation

["Mark Baker" <mbaker -at- omnimark -dot- com>]

Techwhirl Reader wrote

> I was wondering if anybody is currently implementing XML in any fashion in
their documentation systems, be it online or print...

We use big brother, SGML, in our system. The differences between what we do
in SGML and what could be done in XML are trivial. Basically we would have
to do a little more typing to close all our tags.

The system produces both online and print output using OmniMark program to
process the XML data into HTML, RTF (for WinHelp), and MIF.


> What are some tips you might have for someone looking to do a full
implementation of XML? How are you handling online display (XSL, CSS,
etc.?), and the print format (maybe you use Frame+SGML or some other tool?).

The biggest tip is this. Don't get mixed up with the associated standards:
XSL, XLink, XPointer, Namespaces etc.

In the SGML world, the base standard that defines the syntax has been quite
successful and is used successfully in many industries. The associated
processing, presentation, and linking standards (DSSSL and HyTime) have been
abject failures with little serious use. XSL, XLink, etc are warmed over
version of these failed standards. Nothing has changed in them to address
the reasons the originals failed. (CSS, on the other hand, seems like a good
and workable idea, once reliable browser support becomes available.)

The other big tip is this: Know the structure of your information. I don't
mean "know the structure of your documents". I mean "know the structure of
your information." Use XML and a database to express the structure of your
information. Process the structure of your information to structure
documents for output.

> Does anyone have any ideas about the best combo of tools? If I hear
>anything good offline, I'll share with the group. Also, over the next month
as I >implement this new system, I'd be glad to keep folks posted about how
my >experience goes if you're interested.

Our system is built using an Access database, a few simple SGML DTDs, a
simple editor written in Visual Basic, and output and validation programs
written in OmniMark. You can't buy it off the shelf, but you can build it
yourself relatively easily. (It is no different from implementing any custom
database solution.)

The key thing is that we make no attempt to display SGML or XML directly.
Not only are there no mature browser solutions for doing this kind of
display, it really isn't necessary to display SGML or XML directly. We
transform out SGML to HTML to create a web page. We transform it to MIF for
import to Frame for Paper/PDF. (Frame is used purely as a pagination engine,
without user intervention.) We transform it to RTF and feed the RTF to the
Help compiler to produce WinHelp.

If we ever do get browsers that do a good job of XML/CSS, we will write
another OmniMark program to transform our Database/SGML data to that form
for output. In fact, no matter what formats come along in the future, our
data will be ready. We will simply write another output routine to create
the appropriate format.

I will be giving a detailed explanation and demonstration of our system at
the WinWriters 2000 conference in March in SanDiego.


---
Mark Baker
Senior Technical Communicator
OmniMark Technologies Corporation
1400 Blair Place
Ottawa, Ontario
Canada, K1J 9B8
Phone: 613-745-4242
Fax: 613-745-5560
Email mbaker -at- omnimark -dot- com
Web: http://www.omnimark.com