YAWC Pro Administration Guide

Software Recommendations

Although YAWC may be run from an application other than Word, YAWC requires that Word is installed and operational. We recommend that Word is open before YAWC is invoked from another application. Naturally, this is implied if you are running YAWC from within Word.

YAWC requires MS-Word 97 or later. YAWC has been tested with Word 97 and 2000. Word 2000 is preferred for such features such as HTML importing. YAWC is also compatible with Word XP, but has not been extensively tested.

YAWC has been tested mainly with Windows 98, NT 4 and 2000, but also runs with Windows 95 and Windows XP. YAWC also runs correctly under non-English versions of Word and Windows.

Libraries Used

The following libraries are required to run YAWC. The setup program should automatically install these into C:\Windows\System\¹.

Yawc.log

YAWC writes details of each document conversion to the log file yawc.log. For each operation, the following information is recorded:

• the full filename of the current document;
• the version of YAWC, including the version number, edition and debug mode indicator
• the full filename of the configuration file;
• the time at which the operation was started;
• the type of operation.

The conversion operation also appends extra useful information:

• the full filenames of the XSLT stylesheet(s);
• the intermediate XML filename;
• the output XML filename;
• the conversion time.

Each operation also logs whether it succeeded or failed and why. This is a good place to check to see why YAWC did not complete an operation. The log file is especially useful for debugging conversion errors. Often, errors that are reported here are in more detail than in the YAWC progress window, particularly with errors whilst applying the XSLT stylesheet(s). Debug messages and warnings are also recorded here.

Yawc.dot

This file is a copy of Word's normal.dot template file, and is used in converting tables, as the normal.dot file can become corrupt and prevent successful conversion. Do not edit, modify or delete this file.

YawcBatch.exe

This program is a batch conversion utility, which can be used to convert a number of files together. This is documented in Appendix A.

Target DTD Folders

The sub-folders of YAWC's folder contain the set of settings for each individual conversion type. For example, there may be sub-folders such as 'docbook', 'wml', 'html' or something relevant to your organization. In each of these are the configuration files relevant to that type of conversion.

YAWC Pro supplies Word to XML mappings for two target DTDs, HTML and Simplified DocBook. Each mapping is contained in its own folder, and consists of a number of different files.

• YAWC Configuration file
• Word template file
• 1 or more XSLT post-processing scripts
• A sample Word document
• A generic HTML template (in the HTML folder only)
• A target DTD file

Installing TidyCom

YAWC needs TidyCOM (a utility to convert HTML to XHTML). Download TidyCOM from http://perso.wanadoo.fr/ablavier/TidyCOM/TidyCOM.zip. Use Winzip (http://www.winzip.com) or a similar program to extract the 'TidyCOM.dll' file into your Windows system directory. Use the supplied 'regsvr32.exe' program to register the dll file. To do this, click 'Start' -> 'Run' and type the following: "regsvr32 c:\winnt\system32\TidyCOM.dll" (or wherever you placed the TidyCOM.dll file.

Installing MSXML

YAWC needs MSXML Version 3.0. To find out what version of MSXML you have installed, there is a utility at http://www.bayes.co.uk/xml/index.xml called 'MSXML Sniffer'.

MSXML v3.0 can be downloaded from http://msdn.microsoft.com/xml/ or http://download.microsoft.com/download/xml/Install/3.0/WIN98Me/EN-US/msxml3.exe. Full installation instructions are provided with the package.

Creating a Word Template

To create a new Word template for use in converting Word documents into your own DTD, copy the existing YAWC HTML Word template (HTML\HTML-en.dot) and place it in a new directory. This ensures that the new template already has the YAWC toolbar and menu. Edit the user-defined styles to suit your own requirements, and add any default text and styles you require. Create a shortcut to the file, and move the shortcut to the Word template directory (C:\Program Files\Microsoft Office\Templates in the english edition), to make it easy to access for users.

Testing the Template

Close this new template. Open a new document by clicking 'File' -> 'New', and select the shortcut to your template. Type some sample text using different styles and save the document. Run YAWC>Export, and check that content has been converted and placed in a file in the same directory as the saved document, with a .xml or .htm suffix.

Prolog and Epilog

The prolog contains fixed XML content, which is prepended at the beginning of the initial XML file output. Similarly, the epilog contains fixed XML content, which is appended at the end of the initial XML file output.

These sections allow you to place fixed markup around your document content. The epilog and prolog determine the header and footer of the initial XML file, i.e. the temporary XML file that is generated directly by YAWC from your Word document. So, depending on your XSLT transformation, this may or may not be in the final XML file.

The prolog and epilog must contain the start and end tags of the root element. Failure to do this will cause YAWC to output non-well-formed XML. The prolog should also contain the XML declaration and specify the character encoding.

The special processing instruction <?yawc custom-properties?>, can also be included in the prolog. This will be replaced by all user-defined document properties with non-nullvalues, during the conversion process.

[prolog]

<?xml version="1.0" encoding="US-ASCII"?>

<article>

[/prolog]

Element Mappings

A large portion of the configuration file concerns itself with mapping Word styles into XML elements or tags. This is evidently the most important part of the configuration file, and is crucial to the correct output of your XML. It is divided into four separate groups.

Metadata

Options for configuring the document's meta-data output are contained in the 'METAInformation' section. Each line in this section represents a single metadata element, i.e. its name and its value. Each metadata element may be either built-in or custom.

The built-in metadata elements are those defined in the Dublin Core Metadata Element Set, and their value can be changed on a per-document basis by theYAWC>Edit Metadata... command. The following are valid built-in meta-tags: DC.Title, DC.Publisher, DC.Date.Created, DC.Identifier, DC.Description, DC.Creator, DC.Type, DC.Subject, DC.Date.Modified, DC.Contributor, DC.Format, DC.Source, DC.Language, DC.Relation, DC.Coverage, DC.Rights and DC.Keywords.

Note: the examples in this section are taken from a typical HTML configuration file.

DC.Format text/html

Note: The DC.Type and DC.Creator metadata element values are slightly unusual in that they describe the contents of the dropdown list box to be displayed in the dialog box, rather than default values. These property values take the form of square parentheses with a vertical bar delimiting each value choice. The first value is the default should none be chosen in the dialog box.

DC.Creator [Creator-1|Creator-2|Creator-3|Creator-4]

The second type are custom metadata elements. These can take any name, but cannot be modified by the user in the standard dialog box (although you could create a special dialog box to do so). An example of the use of custom meta-tags is for storing organisation-wide data, which should be contained in every document, e.g. a postal address or phone number.

Organisation.Telephone 555-1234

Both built-in and custom metadata elements can contain either static text or a YAWC variable or a combination of the two. A variable is a keyword contained in curly parentheses, and is replaced by normal text when the document is converted. The variables are usually information about the version of YAWC, the user or the document, e.g. "{createdDate}". A full list of these variables is available in the next section under "Customizing Metadata".

A useful way for the user to overwrite a custom meta-tag is to define a custom property in the document with the same name as the meta-tag. YAWC will use this value instead of the value in the configuration file. This also applies to built-in properties, which are in fact stored internally in this way. An alternative method for outputting custom metadata is to define a custom property with that name in the document template, so each document created using this template will inherit this custom property and therefore output this metadata.

Conversion Options

The "ConversionOptions" section relates to how YAWC applies XSLT stylesheets to your document. Depending on your version of YAWC, you can have either one or many transformations. The options in this section are specified using an XML data format, and each child element ("yawcXSLTTransformation") describes an individual transformation. The "pass" attribute of this element dictates the order in which the stylesheets are applied to your XML file. The yawcXSLTTransformation element uses the following children to describe the transformation.

<yawcXSLTTransformation pass="1">

...

</yawcXSLTTransformation>

Note: If the conversion options section has no yawcXSLTTransformation elements, the intermediate XML file (in your temporary folder) will simply be copied to the destination folder.

Verification Options

YAWC supports a limited form of checking of the Word document, which is not equivalent to XML validation. Two checks are carried out. A structural check ensures that heading styles are nested correctly. A sequence check ensures that the first styles used in the document conform to the order defined in the yawcVerifySequence property. This enables YAWC to enforce an order of styles that must be contained in the document. If the document does not meet the criteria described by this option, then YAWC will not convert it. The YAWC>Verify command (not available in YAWC Lite) will display the errors to the user.

The syntax of this property is similar to a DTD content model description: a comma-separated list of style names, either word built-in styles or user-defined styles, separated by commas. The order of styles here dictates the order that the styles must be in the document. A "?" character at the end of a style name indicates that this style is optional. A "%" character at the end indicates that any style may be next.

yawcVerifySequence wdStyleTitle,%

yawcConfigFile

Specifies the configuration file that YAWC uses. This filename may be an absolute path or a relative filename. YAWC will look in the conversion type folder for the configuration file with this name. If this custom property is omitted, YAWC will assume the file is called yawc.ini.

yawcHTMLTemplate

Specifies the HTML template to be used in the HTML XSLT transformation. Simply said, this property overrides the HTML template param option in the configuration file. YAWC also recognises the custom property yawcHTMLTemplateFile as having the same function, but this notation is deprecated.

These two custom properties should be stored in your document template for your organisation. Having multiple Word templates each with different values of these attributes allows for greater flexibility in the document conversions. For example each section of your website may have a different appearance and may need a different yawcHTMLTemplate. In fact, each individual document may define these custom properties.

Document Properties

Use the command YAWC>Options to change the values of the yawcConfigFile and perhaps the yawcHTMLTemplate properties for this template.

Customizing Menus

You may need or wish to modify the YAWC menu to suit your needs. To do this, click on the 'Tools' menu in Word then the 'Customize' item and finally 'Commands'. You may need to select your document template from the 'Save In' drop down list in order to display the YAWC menu. To rename or remove the menu or menu items, simply right click on the item and select delete or type in the new name.

YAWC Variables

Note: some of these options depend on your operating system, and whether your computer is connected to a network or not.

• {applicationBrandname}
  The application name set by the advanced option of the same name. Default is "YAWC".
• {computerName}
  The hostname of the computer that this copy of YAWC is running on.
• {errMessages}
  Deprecated.
• {exeName}
  The name of the YAWC application. This should be 'yawccom.dll' in most cases.
• {generator}
  The YAWC generator string used by the standard "generator" meta-tag. This is normally "YAWC" followed by YAWC's website's URL.
• {iniFile}
  The configuration file used by YAWC to convert this document.
• {logFile}
  The file to which YAWC logged this conversion.
• {originalDocument}
  The full file name of the Word document that this file was converted from.
• {os}
  The operating system that this documents was converted on.
• {userDomain}
  The domain name of the network that this computer is connected to.
• {username}
  The Windows NT username of the user that converted this document.
• {windowsDirectory}
  The Windows directory path. Usually "C:\windows" or "C:\winnt".
• {xmlFilename}
  The XML file name of the final XML document.
• {yawcCompanyName}
  The company name that this computer was registered to.
• {yawcEdition}
  The edition of YAWC, ie Lite, Plus, Pro or Enterprise.
• {yawcVersion}
  The unique version string that identifies this copy of YAWC. Consists of the string "YAWC", the application brandname, the version number (major.minor.revision), the edition (see above), the name of the application and a debug mode identifier.

Document Variables

Note:these properties apply to the original Word document and some may be inaccurate when the document is converted to XML.

• {appname}
  The name of the application that created this document. Normally "MSWORD".
• {attachedTemplate}
  The file name of the template attached to this document.
• {bytes}
  The size (in bytes) of this Word document.
• {category}
  The category or this document, as described by the document properties dialog.
• {characters}
  The number of characters in the document.
• {charactersWithSpaces}
  The number of characters (including spaces) in the document.
• {comments}
  Comments about this document, as described by the document properties dialog.
• {company}
  The company that owns the document, as described by the document properties dialog.
• {createdDate}
  The date this document was created.
• {format}
  The format of this document, ie DOC, HTML, etc.
• {hyperlinkBase}
  The hyperlink base property, as described by the document properties dialog.
• {keywords}
  Keywords for this document, as described by the document properties dialog.
• {lastAuthor}
  The name of the last person to edit this document.
• {lastPrintedDate}
  The date that this document was last printed.
• {lines}
  The number of lines in the document.
• {manager}
  The manager of this document, as described by the document properties dialog.
• {modifiedDate}
  The date this document was last modified.
• {pages}
  The number of pages in the document.
• {paras}
  The number of paragraphs in the document.
• {revision}
  The revision number of this document. Ie, how many times it has been saved.
• {security}
  The security of this document.
• {subject}
  The subject of the document, as described by the document properties dialog.
• {title}
  The title of the document, as described by the document properties dialog.
• {totalEditingTime}
  The total editting time for this document.
• {words}
  The number of words in the document.
• {titleFromDocument}
  The title of the document taken from the document's first paragraph with the 'Title' style (if any).