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 DBTTemplates.
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 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. In your new template, you also have the freedom to add new DBTstyles or modify existing DBTstyle names. You need to exercise some caution about this. (For example, modifying existing DBTstyle names is usually a very bad idea!) Remember that the .mws file maps to DBTstyles by name and 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 styles in DBT.
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.
The Mapping Elements are used to specify the name of the MS-Word style, its type, and the name of the DBT style to which this MS-Word style should be mapped. It can also contain additional instructions that control how the DBT style is handled and other attributes.
The rest of this topic describes the format and parameters of mapping elements and discusses the limitations of the .mws file.
The general structure of a mapping element is:
<type> "<MSWord-style-name>"
{
<parameter> = <value>
…
}
We now discuss each item of this structure in detail.
<type>
This item has one of the following values: "Built-In" 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 other type is "User", which indicates that the MS-Word style is user-defined. All styles that are not defined by default in MS-Word are "User"styles. For an example, look at the dbt.mws file in your DBT Templates folder. It handles all of the built-in styles.
<MSWord-style-name>
This is the name of the style defined in Word. This name must match the Word style name in spelling and capitalization. (This item, and all other items in this file, are case sensitive.) 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 mapping element name are opening and closing braces "{" and "}". Inside the braces are the parameter/value pairs that make up the body of the mapping definition. Next we discuss each of these name/value pairs.
MappedName = “DBTStyleName” | none
The value of the MappedName parameter is the target DBT style name. Note: If the DBT name ends with a dot "." (as in the "para." style), you must delete the dot from the DBTstyle name. As an example, "para." becomes "para" (no dot). The value "none" indicates that there is no style mapping for this MS-Word style. Finally, as shown above, the DBT style name must be surrounded with double quotes.
MappedNameInNote = "DBTStyleName"
The MappedNameInNote parameter is used only for Footnote Reference and Endnote Reference styles. In these cases, the MappedName keyword specifies the DBT style used where the reference appears in the body of the document, and the MappedNameInNote keyword specifies the DBT style used where the reference appears within the footnote or endnote.
Ignore = Always | IfBlank | IfOrnamental
This 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 did.
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 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 of 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.
To close, here are some good things to consider when you set out to modify one of these files. First, please remember that there are limitations to what you can do with an .mws file even though it is a very powerful tool. And the prime rule is, "Make sure you make a backup copy of the file you want to modify." If you do not, you may end up sadder but wiser.