Single Sourcing, Some New Ideas

["Smith, Martin" <smithmr -at- ENCORP -dot- COM>]

I have long been interested in the concept of single source publishing.
After using and evaluating many of the products on the market that
purport to allow one to publish simultaneously in printed and on-line
formats I grew frustrated and began looking for other alternatives. I
came to the conclusion that since many of these products require one to
do a fair amount of macro programming anyway, I might as well try
writing a program to perform the conversion myself. I chose Frame Maker
as my authoring tool and Frame Script as my programming language. Frame
Script is an object-oriented scripting language that completely exposes
the object model that Frame Maker uses internally to create and store
documents. Best of all, it only costs $150.00 and is extremely well
documented. I have since built a successful consulting business,
preparing custom scripts and templates for publishing printed and
on-line documents specifically tailored to the needs of the customer.
Following is a brief description of how this approach works.

I begin by running a script that walks through every file in a Frame
Maker book and builds a look-up table listing all of the paragraph
styles present in the various chapters. This table contains an
assortment of blank fields into which I type the HTML code that the
script will insert before and after each paragraph. Additional fields
allow me to identify the structure of the document and specify whether
the script should break the chapters into separate HTML files at
specific headings.

I then run another script that concatenates all of the chapters in the
book into a new file. The script proceeds to mark up this file, adding
HTML code before and after each paragraph by comparing the paragraph
styles against the styles recorded in the look-up table. The script then
figures out the structure of the document, builds navigational aids,
constructs a browse sequence, index, table of contents, incorporates
graphics, converts tables, and breaks the file into separate HTML files.


In the cases where people want to completely change the structure of the
resulting HTML files, I generate a look-up table that provides a table
of contents for the manual. Additional fields allow me to instruct the
script to omit specific sections, include others, promote and demote
headings, and specify the order in which the various sections should be
linked together.

Some of my clients want the resulting HTML files to use cascading style
sheets and JavaScript navigational aids---a table of contents with
chapters and sections that expand and collapse like the Windows Explorer
interface, for example. Other clients want dynamic HTML--still
attractive with buttons that change color when the mouse passes over
them but with fewer compatibility headaches. Still other clients want
plain vanilla HTML, capable of running on the widest range of browsers
possible.

My main point is that by combining the disciplines of structured
technical writing and computer programming, it really is possible to
treat documentation as data and write scripts that build on-line
documents to your own specifications. However, no canned off the shelf
program that I've ever seen offers this kind of flexibility. At the end
of the day, you can hardly avoid getting your hands dirty and doing some
programming. But for those who endeavor to integrate the two
disciplines, a great many things are indeed possible. The ability to
access and manipulate your documents programmatically adds tremendous
value to existing documentation.

> Martin R. Smith
> Technical Writer / Audiophile
> ENCORP: The Energy Automation Company, http://www.encorp.com
> (970) 686-2017 x 223

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=