Modifying .mws files

The .mws file controls the substitution, or mapping, of Microsoft Word styles into DBT styles for importing documents from Word. The substitution is directed by the instructions contained in the .mws file. Before discussing the syntax of the .mws file, let us address some basic questions:

What .mws files are supplied with DBT? And when are they used?

There are six .mws files. Certain .mws files are paired with certain DBT templates.

Where are the .mws files stored? Can I modify an existing .mws file?

On a 64-bit system, the normal DBT home directory is c:\Program files (x86)\Duxbury\[DBT n.n] (where "n.n" stands in for the version number). The .mws files are located in the Templates subdirectory.

This is a protected location on your computer! Copy the file(s) to a folder on your computer where you can make changes. Then you need to copy the revised file(s) back to the protected location using an elevated process. It is a good idea to save a backup copy in case your revised version does not work as planned.

Are there drawbacks to modifying my DBT files?

If you need to install DBT on a different computer or you install a new version of DBT, you need to copy over your modifications. If you want to have someone else be able to use your tools, you need to assist them with installing your customized files. It is easy to forget, to produce a document containing the wrong results, and then remember you forgot to install your customizations. However, as long as you can appropriately track your customized files, you should have no trouble.

How is the .mws file referenced? If I make a new one, how to I get DBT to use it?

When you create a new DBT template, you get the option to reference a specific .mws file.

Note: In your new template, you also have the freedom to add new DBT styles or modify existing DBT style names. You need to exercise some caution about style names. (From a mapping standpoint, modifying the pre-existing DBT style names is usually a very bad idea!) Remember that the .mws file maps to DBT styles by name, and it will not recognize new or modified names unless you update it as well.

How do I interpret the contents of the .mws file?

The .mws file consists of two parts: Comments, which tell the user about the .mws file, and Mapping Elements, which tell DBT how to do the import from MS-Word styles to the corresponding DBT styles.

Comment lines begin with a number sign "#", which causes the program to skip them. These lines can contain anything you wish. It is a good idea to use the comments to describe the function of the file, items of special interest, and key information others will want to know if they need to modify the file later.

Mapping Elements specify the name of the MS-Word style, its type, and the name of the DBT style to which it should be mapped. In addition, the definition may contain instructions that control how the DBT style is applied.

The next section describes the format and parameters of Mapping Elements.

MWS File Syntax

The general structure of a mapping element is a two-part identifier and a definition within curly braces:

<type> "<MSWord-style-name>"

{

  <parameter> = <value>

  …

}

Note: all the items inside angle brackets "< >" indicate generic terms that must be replaced with specific values (like a style name).

Below, wherever you see a vertical bar "|" between values, the bar separates the alternative values in a list of options.

We now discuss each item of the mapping element structure in detail.

<type>

The <type> item holds one of the following values: BuiltIn | User

"BuiltIn" styles are those defined by Microsoft as part of Word. Note that the names of built-in styles change based on your locale for Word. See more on this below.

The type User indicates that the MS-Word style is user-defined. All styles that are not pre-defined in MS-Word are "User" styles.

For examples, look at the dbt.mws file in your DBT templates folder. It handles all of Word's built-in styles.

"<MSWord-style-name>"

The <MSWord-style-name> item is the name of the specific Word style to be mapped. This name must match the Word style name in spelling and capitalization. This item, and all other items in this file, are case sensitive. Furthermore, the style name is surrounded by quote marks to delimit names that contain spaces. (The quotes are required.)

Note that you should always use the original English MS-Word style name, because DBT can map from the localized style name (from a localized copy of Word) to the English style name. For example, the rus.mws file uses English style names, not the Russian ones.

Following the type and Word style name are opening and closing braces "{" and "}". Inside the braces are one or more parameter/value pairs, each joined by an equals sign "=". These pairs make up the body of the mapping element definition. Next we discuss each of these name/value pairs.

MappedName = “<DBTStyleName>” | none

The value paired with the MappedName parameter is a specific DBT style name, enclosed in quote marks.

Note: If the DBT name ends with a dot "." (as in the "para." style), you must delete the dot from the DBT style name in this entry. Here, "para." becomes "para" (no dot). The alternate value "none" indicates that there is no style mapping for this MS-Word style.

MappedNameInNote = "<DBTStyleName>"

The MappedNameInNote parameter is used only for Footnote Reference and Endnote Reference styles. In these cases, the MappedName keyword (described previously) specifies the DBT style to be used where the reference appears in the body of the document, and the MappedNameInNote keyword specifies the DBT style to be used where the reference appears within the footnote or endnote itself.

Ignore = Always | IfBlank | IfOrnamental

The Ignore parameter controls when to eliminate a paragraph from the imported document. It can take the following values: Always, which can be used to eliminate print-only items like a header or footer from the document being imported; IfBlank, which is used to eliminate blank paragraphs; and IfOrnamental, which is used to eliminate paragraphs whose contents are just lines of characters like dashes "-----", or asterisks "*****".

AggregateForward = Always | Never | IfSameName | IfSameCategory

AggregateBackward = Always | Never | IfSameName | IfSameCategory

The AggregateForward and AggregateBackward parameters are used to check the next and previous paragraphs and determine their treatment relative to the current paragraph style mapping. Each parameter can have the following values: IfSameName, which aggregates the paragraphs into a single block of the specified style; Always, which indicates that the paragraph should always be aggregated into the current style; Never, which indicates that the paragraph should never be aggregated into the current style (this means that the paragraph will always be imported into a DBT linear paragraph style independent of the style being used before or after it); and finally, IfSameCategory, which is only applicable if the mapping element body also has a "Category=Index" or "Category=TOC" item in it.

Level = <a number>

The Level keyword is the DBT style level that should be applied to the mapped style, where the mapped style is the style specified in the MappedName parameter.

Note that Level is most often useful when a series of paragraphs is aggregated. The combination of these three parameters: Level, AggregateForward, and AggregateBackward, bridges the gap between the way the designers of MS-Word conceived of styles and the way Duxbury has.

Category = None | TOC | Index

This parameter specifies the category of the mapping. The Category parameter can have one of three values: TOC, which indicates that this is a table of contents; Index (for an index); or None (no category).

IgnoreEmphases = Never | InDef

This parameter tells DBT how to handle emphasis indicators. The two possible values to this parameter are: Never, which means emphasis used in the style will be shown in braille; and InDef, which indicates DBT will ignore emphasis that is part of the style definition, but will show emphasis that has been added to characters within the style.

DisableInToc = True | False

This parameter can have one of two values: True or False. False is the default. When set to True, the style will be ignored when it occurs in a Word table of contents. (That is, it will not be mapped to a DBT style.) Word makes hyperlinks out of table of contents entries. This parameter can be used to avoid putting these entries into computer braille.

IgnoreCentering = True | False

This parameter can be set to True or False. False is the default. Normally, DBT looks upon centering of a paragraph (or line) in a Word file as significant, because users generally want centered lines in the print document to be centered in braille. However, when this flag is set to True, the text that is centered in the Word style will not be centered in DBT unless centering is part of the DBT style being mapped.

IgnoreSuperscript = True | False

This parameter can be set to True or False. False is the default. This flag is typically set for character styles. When set to true, DBT omits the [ps] and [pe] codes to indicate that the text is a superscript, if the superscripting is part of the Word style definition.

IgnoreContents = Always | IfBlank | IfOrnamental

This parameter is similar to the Ignore parameter above, and it takes the same values. The difference is that while Ignore eliminates the whole paragraph including the start and end tags, this parameter eliminates the contents but leaves the tags.

A Word of Caution

To close, here are two good things to consider when you set out to modify sensitive system files such as these.

First, kindly remember that there are limitations to what you can do with an .mws file even though it is a very powerful tool.

Second (and this is a cardinal rule), please, make a backup copy of the file before you modify it. Doing so gives you a quick out if your modifications go wrong. If you do not, you may end up sadder but wiser.