W2XML v2.5 Help Documentation

Introduction

W2XML will convert *.doc, *.rtf, *.asp, *.htm, *.html and *.jsp to well-formed XML. The software can also apply eXtensible Style Language Transformations (XSLTs) to the standard output so that you can match virtually any Schema's tag set.

Customers who use W2XML to convert Word to XML must understand the relatively complex concepts behind conversion from an unstructured format to a structured format. For this reason, DocSoft recommends that customers who are new to structured content or do not have the expertise to develop sometimes complex XSLTs, contract with DocSoft's consulting services to develop XSLTs to convert the standard output to a Schema or tag set for their specific needs.

Features Available in Version 2.5

• Use W2XML to convert embedded Equation Objects to MathML
• New "Remove revision information" option allows users to ignore revision information when publishing Word documents to xml
• New "Remove SmartTags" option allows users to ignore SmartTags when publishing Word documents to xml

Features Available in Version 2.4

• Use W2XML to preserve page numbering from original Word documents to xml

New parameters available to XSLT processor in Version 2.4

• New element function w2x:cdata, available attributes "xml | html | text"

Features Available in Version 2.3

• Use EXSLT library for transformation
• Use multiple output transformation

Parameters available to XSLT processor in Version 2.3

• Extended object functions in namespace "urn:schemas-docsoft-com:word-to-xml:extensions", such as GetOptionValue(Name)
• OutputExtension - Specify any extension for exporting (versus only XML)
• CustomOptions - Accessed in XSLT via GetOptionValue()

Features Added in Version 2.2

• Group field content
• Remove space before punctuation
• User Mode

Features Added in Version 2.1

• Remove extraneous anchor and bookmark tags
• Export Images from Word® into single subfolder
• Post Publishing

System Requirements

Please review the following requirements to ensure optimum application performance and operability:

• Windows Platform w/.NET® Framework 1.1;
• 512 RAM;
• 700K of hard disk space (additional 300K for the Universal Application Console);
• MSWord® 2000 (or greater) installed on host system;
• Mouse or suitable pointing device;
• Some knowledge of XSL is mandatory to create custom output.

UAC Product Description

The Graphical User Interface (GUI) is simple and easy to learn. There are four main areas in the interface (see accompanying Figure 1):

1. Menu Bar
2. Toolbar
3. Workspace List Window
4. Options Window

Figure 1 - Interface Description

UAC Menu Bar Description

When the GUI is first launched, the Menu Bar contains only three top-level menu options (as shown in Figure 2):

1. File
2. Workspace
3. Help

As soon as you load an application plug-in, the third top-level menu item inherits an application-specific menu item, usually named something similar to the loaded application. The UAC inherently comes packaged with a search-and-replace application called "Replace", which once loaded, applies menu items specific to the Replace application, as shown in Figure 3. Also notice the Options Window has also loaded application specific information as well.

Figure 2 - Standard Menu Bar List Items

Figure 3 - Dynamic Menu Bar Loaded As Third Menu Item

File Menu

The File Menu is used to Create, Open, Save, and Save as Workspaces. You may also exit out of the UAC by choosing the "Exit" menu item.

Figure 4 - File Menu

Workspace Menu

The Workspace Menu is used for actions specifically oriented around Workspace information, such as adding or removing files from a workspace, and/or changing the application plug-in for use within the Workspace.

Figure 5 - Workspace Menu

The Workspace Menu is also used to load an installed application plug-in, using the Change Plug-in... menu item. This launches the Select Plug-in dialog (Figure 7).

Figure 6 - UAC Drop Pad

One of the features in the UAC is the Drop Pad (Figure 6). It is a shortcut that always stays on top, and appears at the lower, right-hand corner of the screen (it can be placed anywhere on the screen). The Drop Pad provides a quick method of adding files to the UAC. Simply drag-and-drop the files you want to add to the current UAC workspace to the Drop Pad.

Figure 7 - Select Plug-in Dialog

Dynamic Application Menu

The Dynamic Application Menu is a menu item that is dynamically generated each time an application plug-in is loaded. It loads application-specific menu items depending on what application plug-in is currently loaded. The example in Figure 8 shows that the standard "Replace" application plug-in has been loaded and thereby shows menu items specific to the "Replace" application.

The one standard menu item that will appear here is the Options... item. Choosing this option on any application plug-in will launch the "Options" dialog box, in which you can modify current associated options within the current workspace.

Figure 8 - Dynamic Application Menu - Replace Application Example

Help Menu

The Help Menu contains items relating to application help, both for the UAC and the installed application plug-ins. The Plug-in Info... item opens the Plug-in Info dialog (Figure 10), which displays information specific to the currently-loaded plug-in, such as Plug-in Name, Version and Valid Files, or files that the plug-in can effect or modify.

Figure 9 - Help Menu

Figure 10 - Plug-in Info Dialog

UAC Toolbar Description

The Toolbar provides a quick, graphical interface to most of the functionality provided by the UAC. The following information describes each button's purpose.

New Workspace Button

Figure 11 - New Workspace Button

The New Workspace button is used to create a new workspace.

Open Workspace Button

Figure 12 - Open Workspace Button

The Open Workspace button is used to open a previously-created workspace.

Save Workspace Button

Figure 13 - Save Workspace Button

The Save Workspace button is used to save a new or modified workspace.

Add Files Button

Figure 14 - Add Files Button

The Add Files button launches the Open dialog, which is used to browse and load files for use within the UAC.

Remove Files Button

Figure 15 - Remove Files Button

The Remove Files button removes selected files from the Workspace List Window.

Process All Files Button

Figure 16 - Process All Files Button

The Process All Files button initiates the run sequence using the parameters as defined in the application plug-in options on the files in the Workspace List Window.

UAC Workspace List Window Description

The Workspace List Window displays the currently selected files the UAC will effect. It shows the File name, file Size, Location of each file, and the date/time the file was last Modified.

You can add files to this window by using Workspace > Add Files... to launch the Open dialog, or copy- or cut-and-paste files into the window, or simply drag-and-drop files into the window.

If file types dragged into the window do not match the proper type for the loaded plug-in, the non-compatible file will be listed in red text (see Figure 18). Keeping these non-compatible files can be useful within a workspace in case you have multiple plug-ins you want to use on a single group of files, allowing you to create a single workspace of files to be effected through multiple plug-ins.

Figure 17 - Workspace List Window

Figure 18 - Workspace List Window with Non-Compatible Files

Installation

The UAC can be installed from CD or via an Electronic Software Distribution (ESD) file downloaded from the DocSoft website. You will need a valid key code to install the full version. After purchase, you will have seven (7) days to activate the software electronically. If you do not activate the software within seven (7) days, the software will not operate until it is properly activated.

Installation Procedure

The Universal Application Console is easy to install, and can be installed with just a few clicks. Use the following procedure to install the UAC.

1. Double-click the UACSetup.msi installer file. This will launch the installer wizard as shown in the following figure. Click "Next >" to continue.



Figure 19 - Universal Application Console Installer Wizard


2. Read the license agreement. If you agree to the license agreement, click "I agree" and press the "Next >" button to continue.



Figure 20 - UAC License Agreement


3. Select the folder in which to install the UAC files. Default is to "C:\Program Files\DocSoft Universal Application Console\". You may press the "Browse..." button to select a different folder. Press the "Disk Cost..." to see how much space will be needed to install the UAC. Select the "Everyone" radio button to install the UAC for everyone that will use the client computer, or "Just me" radio button to only allow the currently-logged-in user to use software. Press "Next >" to continue.



Figure 21 - Select Installation Folder


4. This screen allows the user to go back and change installation configuration before installing. If configuration is correct, press "Next >" to continue. If changes need to be made, press "< Back" to modify before continuing.



Figure 22 - Confirm Installation


5. Upon successfully entering installation path information, the Installing Universal Application Console screen appears. A progress bar details the progress of the installation.



Figure 23 - Installing Universal Application Console


6. Once installation is successful, the "Installation Complete" screen appears. Press "Close" to complete installation.



Figure 24 - Installation Complete

Creating a New Workspace

The UAC uses workspaces to save information for which files to effect, and which plug-in(s) and associated options to use within a workspace. You may create a workspace that does not contain any specific files, but rather only plug-in and options, so that you may add different files each time you need to effect different files over a period of time.

The UAC also provides a method of using command line instructions to automatically schedule files to effect, or to run a series of workspaces in chronological order. Please see Using Command Line Instructions for detailed information.

To create a new workspace, choose File > New Workspace from the Menu Bar (as shown in Figure 25), or press Ctrl+N.

Figure 25 - Creating New Workspace from File Menu

Adding Files to a Workspace

The UAC provides 4 ways of adding files to a workspace. The following defines and described each method.

1. Workspace Menu - Go to Workspace Menu > Add Files..., which will launch the Open dialog in which you can browse and select files to add to the workspace.
2. Drop Pad - Go to Workspace Menu > Drop Pad or use the Ctrl+D shortcut to toggle. The Drop Pad will be located at the bottom-right corner of the screen and always stay on top. You can drag-and-drop files to the Drop Pad to add to the current workspace.
3. Drag-and-Drop - You may drag-and-drop files directly to the workspace window.
4. Copy-and-Paste - You may copy-and-paste files to the workspace window. You may paste using Ctrl+V shortcut or paste via the Workspace Menu (Workspace Menu > Paste From Clipboard).

Saving a Workspace

After you have created and/or modified a workspace, you will probably want to save the workspace for later use. When you save a workspace, the UAC saves the workspace as a *.uac file (as shown in Figure 26).

To save a newly created or modified workspace, simply press Ctrl+S or choose File > Save Workspace or File > Save Workspace As... menu items.

Figure 26 - Saving a Workspace

Opening a Workspace

To open a previously-created workspace, use the File > Open Workspace menu item (see Figure 27), or Ctrl+O shortcut.

Figure 27 - Accessing Replace Application Plug-in Help

Removing Files from a Workspace

To remove files from a workspace, highlight the file(s) you want to remove from the workspace, and press the Remove Files button (see Figure 15), or from the Menu Bar, go to Workspace Menu > Remove Files. You may also press the Del key to remove selected files from Workspace.

To remove ALL files from the workspace, go to Workspace Menu > Remove All Files.

Executing Workspaces From Context Menu

You may execute a saved workspace directly without opening the UAC by right-clicking on a workspace file (*.uac) and choosing "Execute" from the context menu (as shown in Figure 28). This will run the workspace in the background without opening the UAC interface. This is especially useful when you want to run specific workspaces from a scheduler, such as Microsoft's Scheduled Tasks.

Figure 28 - Executing a Workspace From the Context Menu

After a workspace has been executed, a log file will be created in the same directory in which the *.uac workspace file resides. You can view this log file to see the results of the executed workspace (see Figure 29).

Figure 29 - Workspace Log Created After Execting a Workspace File

Using Command Line to Run UAC

The UAC provides a method of using command line parameters to run workspaces. This is especially helpful if you need to schedule the operation of workspaces for a particular time of the day or week using Scheduler.

Use the following command line parameters to run the UAC via the Run command line:

UniversalConsole.exe [workspace_file] [options]

Loading the W2XML Application Plug-in

Loading the W2XML application plug-in is simple. Perform these three easy steps to properly load the application.

1. Go to Workspace > Change Plug-in... (Figure 30) to launch the Select Plug-in dialog (Figure 31).



Figure 30 - Change Plug-in


2. A list of all of your installed application plug-ins is shown. Highlight the W2XML v2.5 application plug-in, then press OK.



Figure 31 - Select Plug-in Dialog


3. The W2XML v2.5 application plug-in is now loaded. Notice there is now a W2XML menu on the UAC menu bar, and the name of the application plug-in is shown on the UAC title bar and the Options Window reflects current W2XML options configuration (Figure 32).



Figure 32 - W2XML Application Plug-in Loaded

How W2XML Works

W2XML uses Microsoft's .NET® framework and Tidy Open Source technology, along with some of DocSoft's own conversion technology to output pure, structured XML from MSWord®, RTF, ASP*, and JSP* files.

W2XML first opens each *.doc and *.rtf document in Word, saves as HTML, then uses Tidy technology to save as raw XHTML. Then the W2XML application applies special technology to clean up the raw exported data and apply custom configuration options and XSLTs to the XML to provide you with XML your organization can use to add life to your legacy information.

This version of W2XML also exports named styles from Word and uses them as attributes within the exported document's elements. Because of this technology, you can use MSWord to author all of your documentation, by applying custom, named styles from a custom template, then using a custom XSLT to transform the exported XML to a complete, custom XML document that conforms to any Schema or DTD you desire. See Using Named Styles in Word for Custom XML Attributes for complete details.

W2XML Options

The W2XML Options Window contains four links that are used to modify the output configuration:

1. Mode Link
2. Output Folder Link
3. Open Output Folder
4. Options Link

Explanations for each of the links are included below:

Mode Link

The Mode Link, when clicked, opens a menu dialog allowing the user to choose from a list of preset output configurations or to choose a Custom mode (see Figure 33). The menu consists of four preset configurations and the custom option (which is default). When one of the four preset configurations is chosen, the link changes to reflect which configuration is current (see Figure 34).

Figure 33 - Preset Configuration Menu from Options Window

Figure 34 - Mode Link Shows Current Configuration Mode

When the Custom mode is chosen from the menu dialog (Figure 35), the Options dialog is launched. The Options dialog's interface provides a means to fully customize the configuration. (The Options dialog will be covered in depth in "Configuring W2XML Options.")

Figure 35 - Choosing Custom Mode from Menu Dialog

Figure 36 - Options Dialog

The preset configuration output options are defined in the following list. The fewer tags you select, the smaller the XML. In some instances you will choose to use many tags for maximum information; other times, you will require less information and, consequently, fewer tags. It is recommended to test the output to see what preset configuration is best for your needs or to create a custom configuration.

• All Information - Exports all data from the source document, including all the MS Office® tags, styles information, and other information that otherwise might not be useful for XML.
• All Information Except Styles - Exports all source information except styles data.
• Minimum Tags with Document Properties - Exports all source information (except styles data), with minimum MS Office® tags including the document properties Office tags (such as author, lastauthor, revision, company, etc.).
• Minimum Tags - Outputs only tags specifically used to markup textual information in the source document. Styles, MS Office® document property tags and other tags are eliminated.

Output Folder Link

The Output Folder Link launches the Browse For Folder dialog, which you can use to navigate to a folder or create a new folder for output. (See Figure 37).

Figure 37 - Browse For Folder Dialog

Open Output Folder

The Open Output Folder link opens the folder you specified in the Browse For Folder dialog, which you can launch using the Output Folder Link. (See Figure 38).

Figure 38 - Launching the W2XML Output folder

Options Link

Pressing the Options Link will launch the Options dialog (see Figure 39). You can also access this dialog by choosing W2XML > Options... from the menu bar (Figure 39).

Figure 39 - Launching the W2XML Options Dialog from the Options Window Link

Figure 40 - Launching the W2XML Options Dialog from the W2XML Menu

Configuring W2XML Options

The W2XML Options Dialog (see accompanying Figure 41) provides access to all of the options needed to perform XML conversion. It consists of three main areas used for configuring options:

1. Output Folder
2. Export Settings
3. Apply Custom XSLT

Figure 41 - W2XML Options Dialog

The following sections describe each of the above option items.

Output Folder

The Output Folder option can be used to choose a specific folder for output or to create a new folder for output. The Output Folder text field shows the currently-selected path in which the XML files will be exported. To change the path, click the Browse... button to launch the Browse For Folder dialog (as shown in Figure 37).

Export Settings

The Export Settings option contains four preset configuration options and a custom option. The custom option can be saved for future use by saving the workspace with the custom settings selected. Choosing one of the preset configurations, selects predetermined settings in the configuration list.

Each configuration item checkbox is listed and exlained below:

• Add possible list attributes - Sometimes Word confuses actual lists with paragraphs and inherently uses a paragraph (<p>) tag instead of a list item (<li>) tag. Checking this option will add w2x:list attributes to the <p> tag so that you can capture these as lists. The resultant output would look something like <p w2x:list-item-class="1" w2x:list-item-level="1">.
  
  
• Clean HTML header - Checking this option removes meta tags and other data from the <head> tags. The information contained in the meta tags is data like <meta name="ProgId" content="Word.Document" /><meta name="Generator" content="Microsoft Word 10" > and <meta name="Originator" content="Microsoft Word 10" /> and may or may not be useful to your specific project. You can always choose to export the data using a custom XSLT of your own (Apply Custom XSLT) to ignore or manipulate your data as needed.
  
  
• Convert Equation objects to MathML - Allows W2XML to process an embedded Equation object to the MathML equivalent, enabling you to post process the MathML as needed.
  
  
  
  

  NOTE:

  Choosing the 'Remove XML data islands' or 'Remove IE hide/show tags' options may cause the 'Convert Equation objects to MathML' option to not function properly. Please ensure these options are not selected when using this option.

  
  
  
• Group field content - Allows grouping of Word's field content (index entry, reference, input form field) using specific XML tags. It uses w2x:field tag to border content: <p class="msonormal">Sample of <w2x:field code="FILENAME">Document5.doc</w2x:field></p> (file name field)
  
  
• Insert page markers - Inserts anchor tags with prefix "_PgM" when a new page is encountered in the Word document.
  
  
• Make CLASS attribute value in lower case - Choose this option if you want to use named styles from Word that may contain capital letters and use as lower case XML elements (i.e. <p class="Para"> to <p class="para">).
  
  
• Place Word images into single subfolder - Checking this option will allow images from different documents to be placed into one folder. This folder will be named "images" and will be created as a subfolder of the output folder.
  
  
• Post process of 'cdata' attributes - Checking this option will allow W2XML to process elements that have the CDATA attribute in <![CDATA[text here]]> Tags. This would allow you to add preformatted code such as 'code' examples into your output XML without errors.
  
  
• Post Publishing - Checking this option will allow post publishing instructions to be specified in the resulting XML file. A custom XSLT can then be used to implement these post publishing instructions. Post publishing sample:
  <?w2x-publish extension=".fo" xslt="genfo.xsl" output="C:\GeneratedFO\"?>
  <?w2x-publish extension=".htm" xslt="genhtm.xsl" output="C:\GeneratedHTML\"?>
  
  
• Remove Auto-Numeration - Checking this option removes numbers added by Word used in various types of numeration, such as numbered lists and topics. It will replace items similar to <span w2x:class="w2x_style_10012" w2x:list-number="yes">1. </span>list item 1</p> with <p w2x:list-item-class="2" w2x:list-item-level="1">list item 1</p>
  
  
• Remove extraneous anchor and bookmark tags - Removes anchor tags and office SPAN bookmarks that are not referenced inside the document. This option removes only bookmarks with id's that start with "_Ref" or "_Toc".
  
  
• Remove generated HTM file - (For *.doc and *.rtf files only) - As part of the conversion process, W2XML transforms *.doc and *.rtf documents to HTML for easier manipulation. This intermediate HTML file can be saved as an additional output from W2XML.
  
  
• Remove IE hide/show tags - As part of the conversion process, some constructs are exported using standard syntax for Internet Explorer use, such as <!--[if ...]>...<![endif]--> and <![if ...]> ... <![endif]>. Unchecking this option will perform the following substitutions:
  
  
  • Construct "<!--[if ...]>...<![endif]-->" will be substituted with "<w2x:hide> ... </w2x:hide>"
  • Construct "<![if ...]> ... <![endif]>" will be substituted with "<w2x:show> ... </w2x:show>"
  • Construct "<% ... %>" will be substituted with "<w2x:script> ... </w2x:script>"
  
  
  
• Remove Office tags (o:*) except document properties - Checking this option will remove MS Office-specific tags, such as <o:smarttagtype> and <o:p> tags.
  
  
• Remove revision information - Checking this option will disregard change information, when publishing to xml, and only place current text in output.
  
  
• Remove script elements and attributes - Removes script elements and attributes that otherwise are reserved for use in web browsers.
  
  
• Remove SmartTags - Checking this option will remove MS Office SmartTags while leaving the data intact, tags such as <st2:personname> and <st2:place> tags.
  
  
• Remove space before punctuation - Removes 'extra' spaces before punctuation sometimes left behind by TIDY after document processing.
  
  
• Remove SPAN tags - Removes sometimes un-needed SPAN tags often used with formatting. Since XML can separate content from formatting, using this option may be beneficial to your project.
  
  
• Remove styles elements and attributes - This option removes the inline styles information from the exported XML. Can be used in conjunction with the Save CSS file option to remove styles information from the exported XML into an external *.css file.
  
  
• Remove VML tags (v:*) - Removes extra Office-specific VML (Microsoft's Vector Markup Language) tags, such as <v:shapes>.
  
  
• Remove XML data islands - Microsoft stores some information into what is termed "XML Data Islands". Choosing this option will remove these usually Word-specific items from the exported XML.
  
  
• Replace NBSP to regular space - There may be some instances in which non-breaking spaces (&nbsp;) are used and you may want to be remove since non-breaking spaces are usually associated with format and not content. If you intend to keep your XML clean of formatting, use this option to replace the &nbsp; character entity with a regular space.
  
  
• Save CSS file - Exports any styles information into an external *.css file. The exported *.css file will have the same name as the exported *.xml file.
  
  
• Save raw XML file - Exports a separate, "raw" XML file that contains all of the original exported data before applying any of the configuration options. The exported raw *.xml file will have the same name as the regular exported *.xml file, but has an extension of "*.raw.xml".
  
  
• Separate header tags and content by DIV - Choosing this option adds DIV tags that separate out headers within the original Word document. This adds more structure to the exported XML file.
  
  
• Use EXSLT library for transformation - Choosing this option adds EXSLT functionality to your applied Custom XSLT.
  
  
• Use multiple output transformation - Used in conjunction with the EXSLT library option to output multiple files from one custom XSLT; Uses EXSLT:DOCUMENT function: see the "Producing Multiple Outputs from an XSL Transformation" article at MSDN for more details.
  
  

Hidden Options

• User Mode - You may enable this option by editing a workspace file with your text editor. Setting the "usermode" tag to "true" (true) will disable the Options Dialog link and disallow potential end-users from modifying the options Settings. This capability is provided so that W2XML can be distributed throughout an organization without the hassles of settings options or inadvertent mistakes by accidental modification of the Workspace Options.
  
  
• OutputExtension - Set this option to set the output extension to a value other than the default ".xml"
  
  
• CustomOptions - Introduced in v.2.3 of W2XML, the ability to set custom options in your XSLT and read them using w2x:GetOptionValue.
  GetOptionValue parameter sample:
  <xsl:value-of select="w2x:GetOptionValue('CustomOptions')"/>
  
  

Apply Custom XSLT

The Apply Custom XSLT checkbox, when checked, provides the ability to create and use custom XSLTs to further customize the exported output. You may press the Browse... button to choose a custom XSLT that you have created, or press the Set Docbook XSLT button to auto-select an XSLT that will transform the standard XHTML output to Docbook-compliant XML (which is included as part of the installation package).

The Check XSLT will check the selected XSLT to ensure it is a valid XSLT in terms of structure and error.

Remember, since W2XML exports named styles from Word as attributes, you can use them to fully customize the exported XML. For more information on using named styles as attributes, see Using Named Styles in Word for Custom XML.

Creating XSLTs for Custom XML Output

To fully take advantage of W2XML's capabilities, one of the prerequisites is a good understanding of XML and XSL. If you don't have a good understanding, or do not have access to someone within your organization who does, then you may want to inquire with DocSoft or some other consulting agency that can build the XSLT you need to take advantage of the rich capabilities W2XML offers. The following information is provided to give a high-level understanding of the standard output so that one can build a custom XSLT to create a completely custom output.

W2XML's standard output is XHTML (which is well-formed XML using HTML tags). If you retain the raw xml file (an option in the options list), you will see that there is a lot of information that is exported from the Word document. So much so, that you could write an XSLT to convert it back to a properly formatted Word document. The first thing to do when starting the development of an XSLT is to determine which options to select to give you the output that you want to start with. Familiarizing yourself with the standard output and options is one of the most important things to do.

W2XML also wraps div tags around each section (such as <div class="section1">) that will enable you to identify sections throughout your XML document for proper nesting and hierarchy.

You also need to determine if your legacy documents contain style names that you can key on to produce specific XML elements. This will help you gain some leverage in creating your custom XSLT, since each style name is exported as a class attribute value for each element (an example is shown below):

In the above example, many p tags are used, but contain style name information that was included in the source Word document. The source document has a style named sectionTitle that formats the section title. It has a style named "para" that formats the normal paragraphs for the Word document. It has a style named "subsectionTitle" that formats each subsection title. These class attributes are valuable in creating an XSLT that produces custom XML. Even though each element in the standard output (in the fragment above) uses the "p" element, the XSLT can easily transform these to custom element names. There are sample XSLTs available from the W2XML Updates page you can use to modify or you can use as a learning tool. You may use the docbook.xslt that is included in the installation to modify or learn from as well.

Setting W2XML Options Through Custom XSLTs

W2XML v2.5 provides the capability of including Workspace information in the XSLT to set specific options whenever a custom XSLT is applied (through the "Apply Custom XSLT checkbox"). This makes it easier to distribute this application with specific options settings throughout your organization. This is especially helpful to organizations using W2XML as an enterprise-wide solution.

Including option settings information into your XSLT can be accomplished in two ways: (1) by creating a workspace with options information saved within the workspace and copying to your XSLT or (2) by creating workspace information via notepad using the Workspace Schema.

To add workspace information to your XSLT from a previously-created Workspace, open the *.uac workspace file in a text editor and copy everything between (and including) the WordXMLOptionsData element, then paste into the top portion of your XSLT, directly after your xsl:output declaration (if applicable, such as <xsl:output method="xml" encoding="utf-8" indent="yes" omit-xml-declaration="no" /> and before the <xsl:template match="/"> template.

Once the workspace information is properly placed within your XSLT, attempt to apply the XSLT from the W2XML Options interface. Notice that when the XSLT is loaded, a dialog box will appear (as shown in Figure Figure 42) asking if you would like to import options. Selecting "Yes" will change the appropriate options in the W2XML Options Dialog. You are now ready to process files.

Figure 42 - Importing Options From XSLT Dialog

Working with the EXSLT Library

Introduced in v.2.5 of W2XML, the EXSLT.NET implementation of EXSLT brings the funcanality of EXSLT to your custom XSLT development.

What Is EXSLT.NET?

The EXSLT.NET library is a community-developed implementation of the EXSLT extensions to XSLT for the .NET platform.

EXSLT.NET fully implements the following EXSLT modules:

• Dates and Times
• Common
• Math
• Random
• Regular Expressions
• Sets
• Strings

In addition EXSLT.NET library provides a proprietary set of useful extension functions.

Multiple Output

EXSLT.NET partially supports exsl:document extension element. Not all exsl:document attributes and their values are supported in this version of W2XML. The supported subset of attributes and values is as follows:

exsl:document extension element assumes the transformation is always done in XML, so EXSLT produces XHTML result documents. More specifically, main result document is always XML, but subsidiary result documents may be written either as XML or as text, depending on the method attribute value of the appropriate <exsl:document> element.

Moreover, the <xsl:output> element is ignored when creating subsidiary result documents. The <xsl:output> only affects outputting of the main result document, the <xsl:output> element does not affect outputting of any subsidiary result documents. It's completely controlled by the <exsl:document> element. Instead, you can get some control over outputting of the main result document using the encoding and indentation value of the appropriate <exsl:document> element.

For more information about how Multiple Output is implemented see "Producing Multiple Outputs from an XSL Transformation" article.

References

1. EXSLT community initiative - http://www.exslt.org
2. EXSLT.NET Workspace home - http://workspaces.gotdotnet.com/exslt
3. EXSLT.NET online documentation - http://www.xmland.net/exslt
4. "EXSLT: Enhancing the Power of XSLT" by Dare Obasanjo, MSDN
5. "EXSLT Meets XPath" by Dare Obasanjo, MSDN
6. "Building Practical Solutions with EXSLT.NET" by Oleg Tkachenko, MSDN
7. EXSLT.NET enabled command line XSLT utility - nxslt.exe

Examples

The Multiple Output option allows you to create, as its name implies, multiple output files from a custom XSLT. Below you will find an example XSLT using this new "Multiple Output" option.

The example XSLT above takes the W2XML output and produces two files. The main output and a toc file of that main output.

Along with creating external files, such as a table of contents, this new "Multiple Output" could also be used to create pagination of your Word Document. This would be accomplished by dividing the document into sections.

Working with Equation Objects

Introduced in v.2.5 of W2XML, the Equation Objects to MathML option allows for the conversion of Equation Objects to XML. This conversion is done using the MathML Schema as the result base. Using this option to convert your Equation Objects to XML allows for the posibility of applying a custom XSLT to this XML to customize W2XML's output even further.

What is MathML?

MathML is a low-level specification for describing mathematics as a basis for machine to machine communication.

References

1. W3C Math Home - http://www.w3.org/Math/
2. Latest MathML Recommendation - http://www.w3.org/TR/MathML/
3. Zvon MathML Reference - http://www.zvon.org/xxl/MathML/Output/index.html

Examples

The Equation Objects to MathML option allows you to create MathML instances of your Equation Objects. Below is an example:

Equation Object

MathML

Preserving Page numbering

Now, throught the use of the "Insert Page Markers" option, you can preseve paging information from your Word Documents. Preserving Page numbering would allow you to recreate page formatting outside of your Word document.

Examples

The Insert Page Markers option allows you to create xml anchor tags that will be placed at the beginning of all sections that start a new page in your word documens.

Creating <![CDATA[ ]]> Commenting

Now, throught the use of the "Post process of 'cdata' attributes" option and custom XSLT, you can include 'non parsed' chunks of code from your Word Documents by placing them inside <![CDATA[ ]]> tags.

Examples

The Post process of 'cdata' attributes option allows you to create CDATA elements that will inclose tags that represent code you have placed in your Word Documents.

W2XML Extensions Schema

Use the following Schema to aid in developing workspace settings within your custom XSTL. You may also view the Schema documentation online.

Using Named Styles in Word for Custom XML

One powerful feature of W2XML is that it can retain named styles used within MSWord and use them in the exported XML. This allows developers to create named styles and save them as templates so authors can apply styles to the Word document and then export that information for a complete, custom solution that suits the individual needs of each organization.

1. Open Word, then go to Format > Styles and Formatting (Figure 43) to open the Styles and Formatting task pane (as shown in Figure 44).



Figure 43 - Accessing the Styles and Formatting Task Pane


2. The Styles and Formatting task pane is launched, showing available styles in the current template.



Figure 44 - Style and Formatting Task Pane Launched


3. Figure 45 shows a sample Word document containing titles, paragraphs, and a bulleted list. We will create a named style for each of these elements that will allow W2XML to export the name of the style as an attribute.



Figure 45 - Sample Word Document


4. We will create a named style named "title" for the titles (highlighted in red), a style named "para" for the paragraphs (highlighted in blue), and another named style named "ulist" for the bulleted list items (see accompanying Figure 46).



Figure 46 - Color-Coded Elements


5. To create a new named style, click the New Style button (Figure 47). This launches the New Style dialog (as shown in Figure 48).



Figure 47 - New Style Button


6. Enter the name of the style in which you want to add. In this example, we are adding a style named "title", which we will use for the titles of each paragraph. This name will become a custom attribute in the exported XML. You can also set formatting for this style here as well. Be sure and check the Add to template checkbox to add this style to the template.



Figure 48 - New Style Dialog


7. After creating a new style, the new, named style appears in the Styles and Formatting task pane, as shown in Figure 49.



Figure 49 - Named Style Added to Styles and Formatting Task Pane


8. Continue the above process for each named style you want to add. For this example, we have added a named style for each of the 3 elements we spoke of earlier (title, para and ulist), as shown in the following figure.



Figure 50 - Three Named Styles Added to Styles and Formatting Task Pane


9. To apply a named style, simply highlight the text in the Word document that you want to add the style (Figure 51), then select which named style to apply from the Styles and Formatting task pane. In this example, we highlighted a title and chose to apply the "title" named style (Figure 52).



Figure 51 - Highlighted Text in Word





Figure 52 - Named Style Applied


10. After the document is saved and W2XML has processed the document to XML, the output shows how the named styles are applied (as shown in Figure 53 and Figure 54). Notice <p class="title">Lorem Ipsum</p> has a class attribute of "title" and <p class="para"> has a class attribute with the value of "para". Figure 54 shows the list style we create contains list data (inside the DIV tag) and the values of the p tags have an attribute of "ulist".
    
    With this powerful capability, you can create and apply a custom XSLT to transform this document using only the values of the class attributes as elements, simply and easily authoring your XML documents in Word.



Figure 53 - Title and Para Named Styles Shown as Values in Class Attributes





Figure 54 - Ulist Named Style Shown as Values in Class Attributes

Converting ASP and JSP to XML

W2XML's ability to export ASP and JSP to XML is somewhat more limited than from MSWord, because we are not able to key off of attributes and styles like we can in MSWord. W2XML does provide structure for any HTML code that is used within these two formats, and puts w2x:script tags around any specific processing instructions (such as <% if request("productID") <> "" then %> is converted to <w2x:script>if request("productID") <> "" then</w2x:script>), so it is still useful to some developers to have this capability.

DocSoft suggests that you test how your ASP and/or JSP is exported by W2XML, then develop and apply a custom XSLT that will make the most of your data.

When exporting ASP or JSP the "Remove script elements and attributes" option of W2XML must be unchecked.

Running the W2XML Application

DocSoft's W2XML Application Plug-in affects only certain file types, as listed under Help > Plug-in Info.... Caution should be exercised when selecting files for modification. Any files highlighted in red are not valid files (as shown in Figure 55). If you try to process all files by pressing the Go button, an alert will appear telling you that you cannot process all files. Clicking OK will close the alert, but no files will be processed. You can either remove the invalid files from the workspace or you can highlight the valid files, then choose W2XML > Process Selected Files (as shown in Figure 57).

To process a single file from the workspace, you may right-click on the selected file and choose Process from the context menu.

Figure 55 - Invalid File Types Highlighted in Red

Figure 56 - Error Alert Displayed When Attempting to Process Invalid File Types

Figure 57 - Processing Selected Files Only

After you have properly added files to the workspace and have properly configured the options, you are ready to process your files.