Re: Single source PDF

["Tim Altom" <taltom -at- simplywritten -dot- com>]

To quote Robert Heinlein as closely as I can remember: Any sufficiently
advanced technology is indistinguishable from magic.

No, Word doesn't have an XML heart. It's still a .doc at its center. It
exports HTML, and it uses XML and some other tricks to do that, but it only
*uses* XML, it doesn't *support* XML. IE 5,  now, will open XML, but only if
it has a CSS attached to it. Otherwise, you get to see all the text
as-tagged.

You're right that XML has drifted mostly into database applications, because
it allows businesses to speak a lingua franca between themselves. But XML
creates a blurry boundary between data and doc, to the point where they're
not readily separable. The very same technology that lets a database talk to
a foreign database lets you output in many formats. With the advent of CSS,
and later XSL, you can now format XML in any way you want. And with XSLT, a
transform language, you can reshape any XML set into any other XML set. You
don't need XML to do single source, but it's going to be the centerpiece of
single source in the future.

To pull off the scenario I've described, you really need to start with
high-end stuff, like Frame +SGML, Arbortext, or something equally powerful.
Something that eats, breathes, and plays well with SGML/XML. You'll need a
DTD to go with it, so you need a strong structure to your documentation,
just as you would with a database. No structure, no way it'll work right. At
this level of automation and expectation, predictability is king, so you
absolutely must have a predefined structure. That's where our Clustar Method
comes into the picture, by creating the structural piece of the
infrastructure. I've had way more experience with Frame than with ArborText,
so I'll focus on it as the central software.

Just using these components, you can create doc in a very reliable fashion,
because with a good DTD you can't very well go wrong...the software tells
you immediately if you're off the beam. Multiple writers can be at work, and
Frame +SGML keeps them all in line with your DTD.

Frame +SGML can now, after the doc is written, output as RTF (badly,
unfortunately), PostScript, HTML, XML, SGML, MIF, or a native frame file.
Store the XML or SGML. Or, with XML...more on that in a minute.

Output as MIF, run the output through MIF2GO (a third-party filter) and you
can automatically get a compiled WinHelp, HTML, or HTML Help file. Run it
through Quadralay Webworks Publisher and ditto, ditto, ditto.

Output as XML, and now you have to enter the realm of the XML conversion
tools. There are several you can look up at xml.com. The industry is still
young, so tools come and go. But with XML, you can now convert one XML
fileset into another with XSLT, or publish it as-is with a CSS or XSL
stylesheet, producing any sort of online look you can imagine. XSLT is where
the hard part is. XSL is easier. CSS is easier still.

For print, all you have to do is output native PostScript from Frame and
store it for later download to a printer of your choice for high-res
printing. The same document is sent to a watched folder where Acrobat, on
command or at a preset hour, pulls it out, makes it into PDF, and puts the
resulting PDF into a Web folder, ready for download.

If you want to standardize on XML, you can. It's not as easy as MIF (a
native Frame file type), but with Frame +SGML, you can store docs as XML,
open them in Frame, edit them, then store them again in XML. From Frame,
send a PostScript'ed file out for PDF and print. Attach a new template in
Frame and you now have a totally different look, suitable for PDF or other
online viewing. Same doc, different look.

These processes vary in difficulty from trivial to engineer-tough. But the
beauty is that once even the hardest things are automated, that process
works by itself for a long, long time before needing update. Now you can
work on a single document and produce, without any rewrite or significant
manual intervention:

*Print in several forms
*WinHelp
*PDF
*XML in several looks
*SGML
*HTML Help
*JavaHelp
*HTML with several looks (thanks to CSS)

Again, the hardest path is XML and XSLT, because it's kinda-real programming
stuff. It does, however, offer the greatest power and flexibility. It's like
having a piece of software that morphs docs into any other kind of doc.
Easiest is PDF. For that, all you need is Frame, Acrobat, and access to two
key directories. Between are the other solutions.

I don't know of any books or magazines specifically on XML for doc. You can
check out xml.com for whatever's up there. A book I find helpful in general
is Style Sheets for HTML and XML, from WROX. It's a touch dated, but it's
still a good 'un. A fairly good XML book for newcomers who want to get
serious fast is XML, a Primer, Second Edition, from MIS Press.


Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar Method(TM)
"Better communication is a service to mankind."
317.562.9298
http://www.simplywritten.com


> Which software?
> Why not Word -- doesn't Word 2000 use XML as its underlying code?
> How much programming experience is needed for this "technological
> chicanery"? especially the automatic part !
>
> I've kept an eye on XML for a while, but I'd gotten the impression
> it's more intended to facilitate business-to-business communication
> & e-commerce. Maybe because the bias of most web magazines
> (print & web) are towards business not documentation.
>
> Do you have any suggestions for resources for learning to use XML
> for  technical documentation?
>