Using XML to integrate database content and desktop publishing
This article shows how Scriptorium helped one company use XML to integrate information in a database with desktop publishing content.
In most enterprises, useful content exists in a number of different tools or databases. To include that content in your publications, you might use traditional ways of moving the information, such as copy and paste. However, it can be far more reliable, repeatable, and efficient to automate conversion from those tools and integrate the result directly into your publishing solutions.
A large manufacturer of integrated circuits used Adobe FrameMaker (unstructured) to produce reference and conceptual documentation for their very complex processors. Each processor had thousands of registers. Most registers contained multiple bit fields, each containing specific pieces of information, all of which needed to be documented.
The information necessary for documenting the processors and their registers was maintained in the manufacturer’s chip-design database. To produce reference documentation, the writers copied the information from the chip design database and pasted it into FrameMaker. The writers could—and did—edit the information, but usually they were constrained to copy content and apply formatting.
The descriptions for each register consisted of two main parts:
- A table, which described the bit fields and enumerated values (if any).
- A diagram, which provided a quick reference to the name, location, and size of each bit field in the register, in addition to other information about the bit fields.
Depending on the size of the register, and the number of fields, these diagrams could be quite complicated. The diagrams were constructed using FrameMaker tables (tables were easier to manipulate than using FrameMaker drawing tools or a separate drawing program).
There were several problems inherent in the documentation process:
- When a chip was in development, the specifications for the registers and their contents could change rapidly. The copy-and-paste methodology made it hard to keep up with the changing and evolving design.
- If the writers modified text when copying and pasting, those changes weren’t preserved in the chip design database.
- Creating and maintaining the illustrations required a large amount of time and thought. Manipulating FrameMaker tables and table cell borders was inefficient and the whole process was potentially prone to errors.
Additionally, the manufacturer did not want to transition to a new tool set, so remaining in FrameMaker was a requirement. Unstructured FrameMaker was perfectly good for documenting the conceptual information; it was only the reference information that was difficult to maintain.
The manufacturer was aware that the reference information could be exported from the database in IP-XACT, an XML-based, vendor-neutral schema for describing chips and their components. However, they needed some help converting the IP-XACT into something that could integrate with FrameMaker, which is when they reached out to Scriptorium.
Scriptorium suggested that an XSL transform could convert the IP-XACT sources into files that could be imported into structured FrameMaker. FrameMaker allows mixing structured and unstructured files in FrameMaker books, so all of the conceptual information could still be maintained as unstructured FrameMaker files. The reference sections could be replaced in the book files whenever they were updated.
Writers were granted access access to the chip design database, so that text corrections to the register and field descriptions could be made in one place.
In addition to solving the basic problem (extracting the descriptions from the database and converting them to FrameMaker), the transform organized the registers in a coherent series of chapters or sections, including a linked summary table for each set of registers, and built the register diagrams. The transform also created persistent cross-reference targets, so that writers could easily create cross-references to register descriptions from conceptual content.
Once the structured files were imported to structured FrameMaker, a Scriptorium-created custom ExtendScript performed final cleanup.
The resulting documentation and diagrams were clear, consistent, and could be re-created from updated sources in a matter of minutes.
The manufacturer (and the success of the project) benefited from these factors:
- The chip-design database contained almost all the information needed to document the registers.
- The chip-design database could export XML (IP-XACT).
- The content in the chip-design database was consistent and of sufficient quality to expose to customers.
- The writing team could access the chip-design database to enhance and correct the information, where necessary.
Automatically converting content from reliable and consistent sources produced reliable and consistent documentation, which then freed the team to focus their energies on conceptual content.
Janice Karin
You raised the issue of the database reflecting changes made by the writer – how is this solved by your solution above? Do you export any Frame changes back to the database using the reverse transformation? Do they make changes directly in the database then export them to the docs from there?
Simon Bate
Hi Janice,
Rather than make changes directly in the Structured FrameMaker files, writers were able to make changes in the database (my fourth wrap-up bullet). Those changes were then reflected in the next time the reference documents were exported from the database.
To keep the article brief, I omitted mentioning that our solution also included writer-maintained configuration files, which could contain introductory text for each register and register group. This text was inserted as part of the transform process.
We had considered (and rejected) ways to round-trip information back to the database. However, using the configuration files—along with writer access to the database—gave the client the flexibility they needed.
Simon Bate