Now that we’ve got our FrameMaker documents in XML, how can we exploit their new format? One of the first things I did was to create new ways of reading (eventually changing) the simple data stored within them. This isn’t all that earth-shattering, but when you consider how difficult it is to find and change some values in the FrameMaker UI this is a big win. Where to start? Bookfiles.

To be able to apply stylesheets or data-collection tools to books (rather than individual files), I need to be able to collect a books components. So, convert your bookfile to MX (yeah, it works on bookfiles as well as chapter files), and search through it for one of the filenames you know is a part of the book (you’ll probably want to pretty-print the XML first). I get something like this:

  <BookComponent>
    <FileName>`&lt;c\&gt;ch01'</FileName>
    <Unique>27107</Unique>
    <StartPageSide>StartRightSide</StartPageSide>
    <PageNumbering>Restart</PageNumbering>
    <PgfNumbering>Continue</PgfNumbering>
    <PageNumPrefix>`'</PageNumPrefix>
    <PageNumSuffix>`'</PageNumSuffix>
    <DefaultPrint>Yes</DefaultPrint>
    <DefaultApply>Yes</DefaultApply>
  </BookComponent>

MX in this case has a pretty comprehensible structure, so we’ll need to grab a BookComponent/FileName, do a little text processing to remove the funky characters, and potentially append our MX file extension (I chose “.mx”). Here’s a very simple stylesheet to do just that:

<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
                xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:output method="xml" indent="yes"/>

  <xsl:template match="@*|node()">
    <xsl:apply-templates/>
  </xsl:template>  

  <xsl:template match="/">
    <xsl:element name="components">
      <xsl:apply-templates/>
    </xsl:element>
  </xsl:template>

  <xsl:template match="//BookComponent/FileName">
    <xsl:param name="extension" select="'.mx'"/>
    <xsl:variable name="str-after">
      <xsl:value-of select="substring-after(., '>')"/>
    </xsl:variable>
    <xsl:element name="component">
      <xsl:value-of select="substring($str-after,
                                      1,
                                      string-length($str-after) - 1)"/>
      <xsl:value-of select="$extension"/>
    </xsl:element>
  </xsl:template>

</xsl:stylesheet>

When you run that on a MX bookfile, you should see an output like this (note that the file extension is customizable above):

<?xml version="1.0"?>
<components>
  <component>svcTOC.fm.mx</component>
  <component>foreword.mx</component>
  <component>ch00.mx</component>
  <component>ch01.mx</component>
  <component>ch02.mx</component>
  <component>ch03.mx</component>
  <component>ch04.mx</component>
  <component>ch05.mx</component>
  <component>ch06.mx</component>
  <component>ch07.mx</component>
  <component>ch08.mx</component>
  <component>ch09.mx</component>
  <component>appa.mx</component>
  <component>appb.mx</component>
  <component>appc.mx</component>
  <component>appd.mx</component>
  <component>appe.mx</component>
  <component>svcIX.fm.mx</component>
  <component>svcAPL.fm.mx</component>
  <component>svcLOR.fm.mx</component>
</components>

That’ll give us a nice structure to direct other processes to the individual component files.

The code is also available here or darcs get http://kfahlgren.com/code/mx/.

The first step of doing anything useful with MX is the ability to get back out into MIF. Thankfully, this is an entirely trivial job in XSLT.

[This code thanks to my boss, Andrew Savikas.]

<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
 xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <!-- author: Andrew Savikas, O'Reilly Media -->

  <xsl:output method="text" encoding="ascii"/>
  <xsl:strip-space elements="_facet"/>

  <xsl:template match="/|MIF_ROOT">
    <xsl:apply-templates/>
  </xsl:template>

<!-- This template needs to remain flush left for correct output -->
<xsl:template match="_facet">
<xsl:text>
</xsl:text>
<xsl:apply-templates/>
</xsl:template>

  <xsl:template match="*">
    <xsl:text>&lt;</xsl:text>
      <xsl:value-of select="name()"/>
    <xsl:text> </xsl:text>
    <xsl:apply-templates/>
    <xsl:text>&gt;</xsl:text>
    <xsl:text> </xsl:text>
  </xsl:template>

</xsl:stylesheet>

The code is also available here or darcs get http://kfahlgren.com/code/mx/.

[Update: Series continues here with getting back into MIF, and reading bookfiles.]

Background

After helping to get DocBook off the ground in the early 90s, the company moved away from DocBook toward FrameMaker in the late 90s. FrameMaker continues to be our standard page layout program today for the core series: Cookbooks, Animal books, and Hacks books. InDesign controls our graphically rich series and we’ve recently started pushing DocBook heavily again thanks to the DocBook-XSL project (see the Rails Cookbook, Unicode Explained, or future Short Cuts for examples using DocBook-XSL).

Getting our corpus of hundreds of past and present FrameMaker titles into a round-trippable XML format was the basis for a huge technological breakthrough in all of O’Reilly’s underlying book production software. Andy was not the first O’Reilly employee to work on two-way converters, but his work came at a time when the entire XML toolchain was finally reaching maturity.

Uses

Some examples of what we did with MX (some of which I’ll try to highlight in future posts):

Conversions

We rewrote every single conversion path (both into FrameMaker and out of it) around MX over the course of a year:

• Word to Frame (Word 2003 XML)
• Frame to DocBook (using XSLT2)
• Frame to Word (for new revisions)
• DocBook to Frame [partway] (but this was scrapped in favor of DocBook-XSL)

Templates

MX allowed us to transform our templates into spec documents describing in detail all of our default styles (this was invaluable writing our DocBook-XSL customization layer)

Data Queries

We built some proof-of-concept data gatherers (much like labs.oreilly.com).