RE: XML case study for e- publishing?

[Larry Kollar <Larry.Kollar@xxxxxxxxxxx>]

>Sorry for this OT posting but I have read quite a lot about the XML basics
>and still I don't have a clear idea about the practical steps to set up an
>XML publishing project.

I'm just getting under way with one here, but I can sum it up
with a quote:

	I've seen the future, and it works.

To be sure, XML publishing with FrameMaker isn't simple -- indeed,
it may work best when you've already decided to completely uproot
your current templates & start over like we did. I assumed that:

  - round-tripping is *not* a requirement (we'll do all edits in
    Frame & export as needed)

  - XML-enabled browsers are readily available (IE5 has been for
    some time, and Netscape/Mozilla are getting their acts together)

  - a structured template is needed

Starting with a fairly stable structured template, I was able to
get something satisfactory for internal use in about a day & a half.


To make a long story short, I've found that the best way to go is
to put things like procedures and the like -- basically, anything
you want as a standone page online -- into their own files, and
save the book as XML. WWP (and saving individual files from Frame)
drop cross-refrerences to other files. What you end up with is a
CSS file and an XML "top sheet" that you can discard & a bunch of
XML-formatted files with extensions like ".e08" (a two-digit number
indicating the file's position in the book).

I also found that XML+CSS just doesn't cut it. WWP outputs a really
nasty XSL stylesheet, keying on "style" attributes to format the
tags, but if you've never seen XSLT it's better than nothing. I
spent a few nights reading the XSLT spec; that and the stylesheet
from WWP were enough to let me create something useful.

<aside type="flame" intensity="medium">Are you getting the idea
that I don't think much of WWP? You're right. You're ever so much
better off learning how to deal with XSL directly.</aside>


One thing that Frame does weird is convert tags like "<task_list>"
to "<task-list>" under XML. I set up read/write rules to change
it to "<tasklist>" and just have done with it. Set up a new SGML
application to handle stuff like this. It doesn't take a lot of
time, and you only have to do it once.

The resulting XML files need a small amount of massaging. Most
obviously, you need to fix the extensions & add a stylesheet
reference. While WWP can remove now-unneeded page references
like "on page 2-4" from xrefs, like I said before it completely
removes other xrefs. Saving the book preserves xrefs to other
files, but they point to the original Frame file. A few lines
of Perl are sufficient to handle stuff like this.

Not so obviously, IE5 doesn't handle auto-inserted text. For
example, in my Frame template I define notes as <p type="note">
and have the EDD insert the "Note:" prefix. You can supposedly
do the same in XSLT, but like I said IE5 doesn't do it. So I
worked around that in the Perl script as well.

Frame converts embedded equations and the like to GIFs, but for
some reason missed a referenced EPS file. The GIF'ed equations
were about 2-3 times the size they needed to be. These are one-
time fixes and changing ".eps" references to ".gif" is one more
line in the Perl script.

<aside type="informative">This sounds like a lot of work, but
it's just a notch or two beyond trivial. Writing the stylesheet &
conversion script are things you do once. Converting or scaling
graphics is once per book. Once you have a book established,
re-publishing is a matter of 10 minutes or less. On the internal
department web server, a 66MHz [sic] PowerMac running Linux, the
script can fix a dozen files faster than I can type the command
("xfix *.e??") to start it.</aside>


Developing the style sheet was a matter of adding one template
at a time & testing the results with IE5. On the MacOS version
of IE5, you need to clear the cache or quit before it sees the
changes to the stylesheet. Creating an XSLT template is dead-easy
if you're doing a straight conversion from a structured Frame
document. For example, if you have a "task" tag with a rule like
"label,p?,step+" then the template looks like this:

	<xsl:template match="task">
		<xsl:apply-templates match="label" />
		<xsl:apply-templates match="p" />
		<ol>
		  <xsl:apply-templates match="step" />
		</ol>
	</xsl:template>


There are a couple of glitches that I haven't worked around yet.
For example, if you have an xref that breaks to a second line,
Frame drops all text following the end-of-line hyphen for some
reason. Stuff like that requires some hand-editing. The easy
workaround in this case is to turn off auto-hyphenation. Other
than that, I've converted two short (~50 page) books and haven't
run across anything else that can't be scripted away.


At this point, I'm working on the window dressing. I want to
build a linked ToC for each book, preferably automatically.
A sidebar with the ToC and other handy links is in the works.
I'm planning to find or write a CGI that solicits comments &
prints them at the end of the page (for internal reviews and
the like). Search functions will come later; I designed the
Frame template to contain attributes providing convenient
handles for searches so I also expect that to be simple.

There's a container called "background" that I use to wrap
background info in procedures and chapters. Eventually, I plan
to break out that info into a separate page & link to it from
the original.


I'm looking forward to improvements in Frame (or even WWP)
that will reduce -- or even eliminate -- post-processing.
But with a little sweat equity, you can get started with
e-publishing right away.

	Larry



** To unsubscribe, send a message to majordomo@omsys.com **
** with "unsubscribe framers" (no quotes) in the body.   **