Easy Authoring In – Structured Content Out

Some of my work involves clients that submit content from authors and editors (produced on word processors like MS Word) that needs to be formatted for high-quality print output. I may be using InDesign or FrameMaker for the print output, but the process is pretty much the same: import the content into the page layout program and apply styles, etc. This can be a tedious, error-prone process, compounded by edits that happen after the pagination process has begun.

One possible solution that appeals to me is a light-weight editor that could be configured for content-specific authoring and editing. It would allow you to specify an underlying schema so you could control and guide the development of content. But it would also have a simple editing environment so that it would be easy to add and format content without messing with the underlying XML. The editor could have ways to insert commonly used items that conform to the required structure. And if such an environment was browser-based, it could make collaboration easier. With solid XML, I could then use XSLT to machine-convert the content to InDesign or FrameMaker for high-quality output.

I recently saw a demo for a product that may finally be the solution I have been looking for: FontoXML. First a disclosure: I am not in any way officially associated with them. But I was very impressed with what I saw. They developed FontoXML as a custom solution for several of their clients, but it was so well received that they decided to make a general-purpose product for others. I only saw an hour-long demo so I am not going to try to provide a detailed review, but here are some of the things I liked:

  • It was developed with a modular architecture that lends itself to customization and extension.
  • It can work with other schemas besides DITA, including custom schemas.
  • The authoring environment can be customized through HTML/CSS.
  • Placeholders and boilerplate content can be developed to streamline the authoring process.
  • It can be integrated with content management systems.
  • The demo was very polished and showed a high attention to detail.
  • The prices were very reasonable, even for small-volume clients.

I am sure there are similar products out there that I don’t know about. If you know of any, please feel free to leave a comment below. But, I would highly-recommend that you take a look at FontoXML. It is expected to ship 1st Q 2015.

Running a FrameScript Script from DITA-FMx

DITA-FMx is a great plugin for working with DITA in FrameMaker. One of its best features is the ability to create a complete FrameMaker book from a ditamap. In some situations you may want to run a script on the book before creating the PDF. Scott Prentice, the developer of DITA-FMx, has a blog post explaining how you can call an ExtendScript script from DITA-FMx. This article will show you how to call a FrameScript script from DITA-FMx.

To set this up in DITA-FMx, you will need to edit the BookBuildOverrides section of the book-build INI file that you are using with DITA-FMx. Here are the three keys that need to be edited:

[BookBuildOverrides]
...
RunScript=1
ScriptName=fsl
ScriptArgs=myEventScript

RunScript is a 0 or 1 value. Setting it to a 1 tells DITA-FMx that you want run one or more scripts or FDK clients. ScriptName for FrameScript is fsl. The ScriptArgs value is the name of the installed FrameScript “event script” that you want to run.

Before we go further, let me give a little background on FrameScript scripts. FrameScript has two kinds of scripts: Standard scripts and Event scripts. A standard script can consist of functions, subroutines, and events, but it always has an entry point that is not inside of a function, subroutine, etc. Typically, you “run” a Standard script, it loads into memory, runs to completion, then is flushed from memory.

Event scripts are not run directly; they are “installed” first and then “wait” for some kind of event to happen; for example, a menu command, a FrameMaker event, an outside call, etc. All of the code in an event script must be inside of a function, subroutine, or event. The entry point for an event script is some kind of an event inside of the script. One point that is pertinent to this post is that an installed Event script has a name, and this name is the value you use for the ScriptArgs key.

Instead of installing your event script manually, it is best to install it automatically with an “Initial Script”, which runs automatically whenever you start FrameMaker. That way, your event script will installed automatically when you start FrameMaker. Here is an example Initial Script:

// InitialScript.fsl Version 0.1b August 26, 2013

Local sPath('');

// Get the path to this script.
Set sPath = eSys.ExtractPathName{ThisScript};

// Install the event script that will receive the DITA-FMx call.
Install Script File(sPath+'Script1.fsl') Name('myEventScript');

This command will install the script “Script1.fsl” that is in the same folder as the Initial Script (InitialScript.fsl). The important parameter on the Install Script command is Name; the name supplied must match the name you give to the ScriptArgs key in DITA-FMx’s book-build INI file. Here we are using “myEventScript”.

To run this script automatically whenever FrameMaker starts, choose FrameScript > Options and click the Browse button next to the Initial Script Name field. Navigate to the InitialScript.fsl file and select it, and then click Save to close the Options dialog box.

FrameScript Options dialog box

Before you quit and restart FrameMaker, you will need to have Script1.fsl in the same folder as the InitialScript.fsl file. Here is a shell you can use for this script:

// Script1.fsl Version 0.1b August 26, 2013

Event NoteClientCall
//	
If ActiveBook
  Set iResult = ProcessBook{ActiveBook};
EndIf
//
EndEvent

Function ProcessBook oBook
//
//... Do something with the book here ...
//
EndFunc

The NoteClientCall event is a built-in event that “waits” for the outside call; in this case, from DITA-FMx. We test to make sure that there is an active book, which should be the book that DITA-FMx just created from the ditamap. If there is an active book, we call the ProcessBook function, which is where we process our book with FrameScript code. We could have our book code right in the ProcessBook function, or we could use this function to call other scripts or functions.

Please let me know if you have any questions or comments about calling FrameScript scripts with DITA-FMx.

Renaming DITA Map Topics

I have a client using MIF2Go to generate DITA from unstructured FrameMaker documents. They are very happy with the entire process with one exception: They want an easy way to rename the href values in the DITA map, and the corresponding topics on disk. I have proposed a set of FrameScript scripts that will automate the process. The script proposes new topic names, based on the topicref’s navtitle value. You can have the script automatically use the new names, or you can use a “semi-automatic mode” where the old names and proposed new names are written to and Excel file. Then you can use Excel to fine-tune the new names. A second script quickly applies the spreadsheet names to the DITA map and corresponding topic files.

You can take a look at the documentation here. The cost for the set of scripts is $95 US. To purchase the scripts, please contact rick@frameexpert.com.

–Rick

FrameSLT: A Great FrameMaker Plugin

There are many useful FrameMaker plugins out there, but one of my favorites is FrameSLT by West Street Consulting, operated by Russ Ward. I was reminded of how powerful it is when I recently helped a client add structure to a large number of unstructured documents. One issue was a very specific sequence of elements where text nodes needed to be wrapped in <cmdname> elements. In the screenshot below, I have the text nodes indicated by red rectangles. The yellow highlighting indicates the specific context where the text nodes needed to be located.

Continue reading “FrameSLT: A Great FrameMaker Plugin”