Installation

Q: I installed <X>Styler and the menu does not appear or it only has a "Register" command. Selecting the "Register" command does not get me to the web site.

A: <X>Styler installs as a Microsoft Word Professional 2003 plug-in. It requires the use of Microsoft Word 2003 Professional edition to function because this is the only Word edition with XML capabilities

The menu not appearing is either the result of the product being installed into an unsupported version of Word 2003 (not Professional Edition) or in some cases is caused by running the installation with Microsoft Word still open. In the former case, we are correcting the installer to properly warn and exit if an installation is attempted. In the latter case, closing Word and restarting Word will fix the issue. If you do close Word, check that it is still not running in the background (ctrl-alt-del and check that winword.exe is not listed in the running applications).

The "Register" online function will be enabled once the Beta is complete. The downloaded version comes with a license that is active for 30-days.

Using <X>Styler

Q: When inserting an XPath, I get the error "Object reference not set to an instance of object".

A: The schema on disk on the one stored internally in Word are out-of-sync, usually caused by editing the schema and not re-introducing the changed schema to Word. Delete the schema from the Word schema library and re-add it.

Q: I occasionally get an error, "Cannot communicate with machmn1.exe" when opening Word.

A: This has been identified as a potential issue as the license manager is a 16-bit Windows applications that occasionally fails. It does happen on very rare occasions, a restart of Word clears up the issue. We are working on a better integration that will eliminate this issue.

Q: How do I insert the value of an XML attribute?

A: This has been identified as a high-priority feature and will be included in the initial release of <X>Styler. We should note that this is an easy extension to the insertion of XPath that is already in <X>Styler, all that is needed is to extend the tree to attributes.

Q: I cannot save and examine the XSL.

A: That feature is enabled in the full version. We will provide a limit use license for saving a few templates in the future during the trial phase. Just to note, the XSL is generated in memory when you choose to merge the content. It is then merged with the XML data set identified via XSLT and the result is a WordML document. If you select WordML output, this temporary file is written to disk and then opened in Word. If you select PDF output, this WordML file is passed to RenderX with the WordML to XSL FO conversion Stylesheets.

Other Components

By far, the majority of questions we receive are about the fidelity of the output in PDF format. The PDF output is derived from converting the WordML to XSL FO using the RenderX Stylesheets and then running RenderX XEP on the result.

Word is a publishing engine with a set of rules; XEP is a different publishing engine with a different set of rules. Those differences fall into a few categories:

Formatter Core

Algorithms for character spacing, word spacing, kerning, text squeezing and hyphenation are not the same for two different publishing engines. More text will fit on a line in one application vs. another, line spacing may be a little larger in one than the other, one will squeeze characters and words differently, etc. There can be (and should not be) a guarantee that you will get exact results. <X>Styler was not designed as a WYSIWYG formatting application. Its primary output is XSL to produce merged WordML.

XSL FO vs. WordML Differences

FO and WordML have different formatting models. Word is a dynamic engine while XSL FO defines static templates and flows text into those template regions.

One easy example of this behavior is seen in the format of header/footer regions in Word. According to the Word model, the size of the header/footer and consequently the page region can dynamically change based on the content. In XSL FO, these are static areas. If you specify two linear inches of content for a header in Word but specify that header area is 2 linear inch in your page dimensions, Word will grow the header region and shrink the page area. In XSL FO, if you specify a 1 inch header and put in two inches of content, you will see the header overflow onto the page in an overprint condition.

There are many other things that fall into this category like tabs, many WordArt constructs, floating text boxes, etc. A "tab" is an editor specific implementation that has no direct equivalent in XSL FO. Text boxes can be approximated with absolute position blocks are attempted through SVG, but neither maps to all the different ways Word can place a text box on the page an impact flow areas.

Use of Word and WordML

Even while many <X>Styler users are most likely used to structured authoring environments, the moment they touch Word they forget everything they know about structured authoring. They cut and paste across paragraph boundaries, they highlight bold from the middle of one structure to another, they insert everything as Normal with spot formatting all over the place, etc. While the document "looks" fine in Word, this can have various effects on the underlying WordML especially when you apply custom schemas to documents that must remain structured.

We have seen some cases where documents are (under the covers) corrupt and yet still work in Word. Only when you export to WordML and attempt to work with the WordML as an XML structure does the problems manifest themselves.

Considerations for the WordML to XSL FO Conversion

As time goes on, we will present various things to watch for and avoid in your templates. Although it should be noted that RenderX is also constantly enhancing the conversion templates to make them better. We have accomplished some very complex documents by understanding the limitations and working within them to deliver great results.

Some general ideas are:

Use paragraph styles and try to avoid the concept of spot formatting everything. While it certainly is not required, the RenderX stylesheets support styles therefore you should try to use them.

Avoid the use of tabs. There is no direct equivalent in XSL FO. Tabs are mapped to an fo:leader so understanding that helps. Leaders are fixed length, tabs can vary in length depending on the boundary. For example - it is possible to set a tab stop outside the page or table cell boundary in Word and the tabbed text will be placed at the boundary edge, this is not possible with a leader of fixed length when one does not know the length. For the most part, it can be overcome with right alignment of text instead. Also, it is currently not possible to use tabs for aligning items in a list, but this is simple to overcome. Tabbed list structures can be replaced by a tabular structure. Again, this is primarily because the underlying formatting engines are different and the "length" of a tab to align something in Word is different than the "length" of a leader to align something in XSL FO.

Don't use frames. Frames are currently not supported but WordArt Text Boxes are in the latest release. Be careful how you place them on a page as Word has many options for flowing text around them that are not able to be mapped in XSL FO.

Size header/footer areas appropriately. No matter what size you specify for header and footer areas, Word will dynamically grow this area and shrink body content to match the contents. This is not possible in XSL FO. Header/footer regions are fixed sizes so you must ensure that these are set appropriately.

Use supported graphics. RenderX XEP supports GIF, TIFF, PNG and JPG graphics. Do not use BMP or WMF graphics.

Be careful with advanced page/section controls. RenderX provides two templates for conversion, one is Word2FO.xsl and one is Word2FO_ext.xsl. The second one contains some of the RenderX enhancements like supporting "flow-sections". A flow section is somewhat equivalent to Word's "Continuous Section Break". You will have to switch among these to test out advanced section breaks in documents.

Use paragraph properties for controlling pages. Although the RenderX Sytylesheets support things like forced page breaks, it is always good practice to use the equivalent in paragraph properties like "Page Break Before".

Use only supported fonts. There are many fonts in Windows that are not Unicode-compatible fonts and therefore cannot be used with XEP, like WingDings for example. There are some mappings to Unicode equivalents in the RenderX Stylesheets for common characters. Also, you must make sure that you have set up the correct fonts in the RenderX configuration file (xep.xml).

Don't use the AutoFormat function for tables. This function applies advanced styles to tables that are as of yet not mapped by RenderX XEP.

Be careful with text boxes and other WordArt. If you do use them, realize the way that text boxes are formatted and set them to be absolutely positioned on the page. Text boxes in Word can impact flows, even across columns and have many settings that do not directly equate to XSL FO.

As the Beta program runs, we will be collecting FAQ's and discussions from the various testers and present comments on the FAQ page.