Microsoft Word DOCX – import config usage

For creating a PSML file from a DOCX document.

For the default word-import-config.xml, see the default config example.

Overview

Editable by developers or technically-minded end users, the word-import-config.xml modifies the conversion of Word DOCX files to PSML. Changing the file requires familiarity with XML syntax, and a solid understanding of Microsoft Word. Depending on the import workflow, modifying the word-import-config.xml might require elevated permission.

The location of the default file is:

/WEB-INF/template/default/document/docx/word-import-config.xml

The word-import-config.xml does not process all properties of the .docx file format. There are many aspects of a Word document where Word provides better and more immediate feedback. This is especially true where Word controls document formatting and page layout.

PageSeeder excels at collaborative editing, managing content access, tracking changes, and enabling content reuse. Therefore, the focus of the import process is:

• Document structure – Word expresses structure explicitly, Heading 1 style contains Heading 2 styles, and implicitly, bullet items in a table cell might be seen as less important than bullet items in the Overview section. The concepts are easy to understand, but Word lacks any formal definition of structure. This is why the word-import-config.xml provides flexibility for mapping Word styles for headings, outline levels, sections, lists, and paragraphs.

• File organization – The import split process creates a hierarchical collection of files from a single Word document. It creates links from the references document to the component documents.

• Semantics – Extending the question of structure is that of semantics. Do the names that users create in their documents mean something? Or, are they simply to help format and organize objects in the document? The lack of any uniform answer to these questions is why the word-import-config.xml supports mapping the style names of Word paragraphs, characters, lists, and table styles. It also supports mapping bookmarks, document types, and other IDs.

• Linking – Users rarely add many links to Word documents because of structural or semantic issues. However, the strong linking in PageSeeder, and ability of the word-import-config.xml to transform Word cross-references into PageSeeder xrefs and links, is worth mentioning.

Pre-import considerations

Not all aspects of a Word document are processed upon import. This means parts of the document that might be important are outside what PageSeeder can process.

To ensure that information isn’t lost, attention should be given to the contents of the Word document before importing it. For example, where software documentation includes code samples, replace any monospace font setting with a Word paragraph style like HTML Preformatted, or Word character style HTML Code, before importing into PageSeeder.

Information that PageSeeder discards includes:

• Fonts / typefaces – operating system dependencies and font licenses make the preservation of fonts from one system to another impractical.
• Style settings – the import only processes the name (or ID, really) of the style. Any other settings, such as indents, must be part of the mapping rule.
• Measurements – PageSeeder doesn’t process many measurements such as tab stops, margins, indents, column widths, line spacing, and borders. Exceptions include table settings that use percentages, and image size.
• Characters – characters such as tabs or style separators are discarded on import – these could be changed to a space character, for example, so the content doesn’t run together after import.
• Headers / footers – move any meaningful content in the headers or footers into the body of the document before importing.
• Macros – the import ignores any macro code.
• Content controls – a forms-based user interface will require building a document template.
• Fields – some DOCX field data such as bookmarks and cross-references will import automatically,  an other fields such as index entries and footnotes require configuration. To preserve other field content requires processing them in Word before importing.
• Security – PageSeeder has a separate permission model for accessing content, so the process ignores Word security settings.

Background

Understanding the complementary relationship between Word and PageSeeder, along with the role of word-import-config.xml, requires a basic understanding of how Word files function.

One place to start is Microsoft Open XML  and the Open Packaging Conventions . Another is a tool such as the Google Chrome browser extension for OpenXML . Alternatively, simply copy a .docx file, rename it with a .zip extension, and open the zip archive to view the underlying XML.

Another issue that can make a big difference is understanding how heading and paragraph numbers work in Word documents – Word numbering is famously hard to tame. Many people find this aspect of Word frustrating, but with a proper implementation, this feature works consistently and correctly. For further understanding of its complexities, consider reading Word’s Numbering Explained. 

Unfortunately, the good use of Word styles  is essential to get the most out of any DOCX file, and the word-import-config.xml offers some, but not much scope for improving the document quality on import. If the DOCX is consistently styled, using List Styles, and no manual overriding of paragraph or character styles, then the import process can covert the document to valid PSML.

Usage

To change from the PageSeeder default word-import-config.xml, follow the steps below:

Converting Word styles to PSML

Formatting

By design, there is no formatting information in PageSeeder content. This is not because formatting isn’t important, rather, it is to support the concept of separating content and format. The architectural objective for this is that the exclusion of formatting leads to:

• Better reuse of content.
• Better productivity for writers.
• More flexibility of delivery formats.

In PageSeeder, formatting is moved further along the document lifecycle, to the export stage, and adding it programmatically instead of manually, improves quality and consistency.

Getting the best import result

Using Word to get the most out of PageSeeder requires first creating a Word document with content that is consistently styled, automatically numbered, and ideally, free from manual overrides.

Word styles are mapped to PSML content and labels, using the following relationships:

• Characters – equivalent to an inline label.
• Paragraphs – equivalent to a block label.
• Tables – can be categorized in PageSeeder by the use of the @role attribute.
• Lists – can be categorized in PageSeeder by the use of the @role attribute on <list> or <nlist>.
• Images – can have a character style in PSML.
• Metadata – map pre-defined properties.
• Fields – including footnotes, endnotes, index entries.
• References – including Xrefs and links.

Often the best way to import Word documents into PageSeeder is to clean them up first. In this circumstance, the best way to clean up Word files is in Word itself.

Analyse data before import – OX and Docs Toolkit

Word import – Numbering

In order to get the right results from the PageSeeder import, the word-import-config.xml and the Word document to be converted, ideally, should have the proper numbering configuration.

Users who are familiar with Word multilevel lists know their importance to enabling accurate numbering. If the numbering in your List Style works well in Word, then it will work just as well in PageSeeder.

Numbering is hierarchical

Numbering is hierarchical and a List Style defines this hierarchy – without a List Style, Word can’t know what this hierarchy is. It is the heirarchical logic defined in your List Style that PageSeeder imports – which paragraph style should follow which and which paragraph the numbering should restart at. PageSeeder doesn't import the actual numbering you see in Word, as the numbers are generated by the logic defined in your List Style and Word doesn’t store this actual numbering - only the hierarchical logic that is generating it.

The defining of the List Style provides a definition that can be replicated in PageSeeder.

Benefits of using List Styles in Word

New List Styles, beneficially, can be:

• named
• shared
• modified, and
• deleted.

List Styles are essential for consistency across a document. They enable the editing/updating of multiple paragraphs with the same style across the document.

When should you use a List Style? – Always when you are numbering paragraphs

These are just examples:

• If you have unusual number schemes, for example: First, Second or 00001, 00002 (new to Word 2010), irregular indents for numbering levels, number font formatting that is different from the content of the heading style it is linked to, or appendix numbering.
• If you have many writers collaboratively writing – and need to handle cut and pasted content.
• To help other contributors to use the document correctly with minimal learning.

Stability in numbering – Use List Styles

List Styles, as defined in Word, only provide the numbering and its formatting, with the assigned levels determining the incrementation. Word paragraph and character styles provide the formatting for content that is not the numbering, for example, the text of a heading that follows the number, or the text of a paragraph that follows the number.

A Word List Style defines a numbering scheme, including the form of number to be used and the tabs and indents for the number. They add stability to multilevel numbering, but the crucial part is:

• Linking each level in a List Style to a unique Word paragraph style,

and conversely

• Each paragraph or heading style can point to only one List Style.

When you set up your document with unique Word paragraph styles and a List Style, you can make changes to numbering by modifying the list. Using List Styles makes implementing changes across documents highly flexible, and results in much greater numbering consistency.

• A List Style creates a set or group of heading and paragraph styles – Word comes with built-in paragraph styles named Heading 1, Heading 2, Heading 3. A List Style ‘groups’ those Word paragraph styles into some order. The List Style determines that Heading 1 is followed by Heading 2 and that it is followed by Heading 3, and that the numbering for Heading 2 restarts after the occurrence of a Heading 1. Although there are 9 levels in any Word List Style, it is very uncommon for nine levels to be used in a document – PageSeeder only uses six levels.
• A List Style defines the information about how to number each level – That includes the format of the number ( "1" or "a" or "i"), whether the number is preceded by text (eg “Chapter 1” or “Part A”), whether the number includes previous levels’ numbers (eg paragraph 1.4.3), and the indents (the distance from margin to number and from number to text).

When you apply a numbered paragraph style to content, Word automatically applies the numbering according to the definition in the List Style and list level linked to that style, and you don’t need to access the List Style directly. All other paragraphs that you apply that numbered paragraph to will belong to the same List Style and its numbering will automatically increment from the previous paragraph in the same style.

Create a List Style

Ideally:

• When creating a new document –
• In the Word Styles pane, format the paragraph styles to include in your List Style – this formatting is for any content other than numbering on each paragraph.
• Then, create a List Style before creating your content.
• Then, apply paragraph styles that are included in your List Style to your content as you write.
• When dealing with legacy content – The content is likely already using a List Style, but in some cases, the document content could have paragraphs which styles that are manually overridden, or paragraph styles might not have been applied consistently.

Next steps – configure the import process

When you have your List Styles, there are two configuration files needed for the import process:

1. word-import-config.xml – Specifies the mapping of Word paragraph styles to PSML elements.
2. publication-config.xml – Among other properties, this controls the way a “Publication” is auto-numbered in PageSeeder.

Word import config file – word-import-config.xml

The location of the default import config for a project is:

WEB-INF/config/template/[project-name]/document/docx/word-import-config.xml

The information below describes different ways that the word-import-config.xml file transforms DOCX format into PSML.

In Word, styles can have multiple names, separated by commas. For the import, only the name before the first comma is processed.

<w:style w:type="paragraph" w:customStyle="1" w:styleId="BROWNParagraphStyLE">
  <w:name w:val="BROWN Paragraph StyLE"/>
  ...
</w:style>

<wordstyle name="BROWNParagraphStyLE" psmlelement="para">
  <indent value="4" />
</wordstyle>

• Only refer to styles in use in the Word document.
• The heading styles built-in to Word are special – refer to them using their style ID which is upper case, for example, <wordstyle name="Heading1" psmlelement="heading">.
• Sometimes Word style names display as upper case in the Styles pane but are actually lower case – if a style doesn’t apply, try changing the reference to lower case.

See the default word-import-config.xml document here.

Create a word-import-config.xml

Publication and the publication config file – publication-config.xml

A “publication” is a hierarchical collection of PSML component documents joined by “embed” or “transclude” type xrefs. When published, the components are resolved into a single document for numbering and presentation. Publications are at group level.

The publication-config.xml file recreates the hierarchy logic that is present in the Word List Style and uses that logic to process and generate the numbering you see displayed in PageSeeder.

Create a publication-config.xml

Configurable import components

The following components process the conversion:

• <split> – handles MathML (equations), footnotes, and endnotes.
• <lists> – configures lists.
• <styles> – translates the implied semantics and structure of Word styles into PageSeeder objects.

Store – <split>

In the import config, the <split> element relates only to MathML, footnotes, and endnotes, to control the conversion of these into files or fragments.

<split>
   <mathml select="true"
           output="generate-files"
           convert-to-mml="true"/>
   <footnotes select="true"
              output="generate-files"/>
   <endnotes select="true"
             output="generate-files"/>
</split>

<mathml>

This element generates files for <mathml> objects that exist in the Word document.

<mathml select="true" 
        output="generate-files" 
        convert-to-mml="true"/>

The attributes for <mathml> are:

• @select – to disable the generation of <mathml> content, set select to "false", (default true).
• @output – setting this attribute value to "generate-files", places each <mathml> object in a separate file, under a /mathml folder. Setting it to "generate-fragments", places each equation in its own fragment, in a document with the path mathml/mathml-[n].psml (default generate-fragments). Requires pso-docx version 0.7.8 or higher.
• @convert-to-mml – setting value to "true" converts equations to the original <mathml>. If the value is "false", objects retain the Office Open <mathml> syntax (default true, and always true for generate-fragments option).

<footnotes>

This element configures Word footnote handling.

<footnotes select="true" output="generate-files"/>

The attributes for <footnotes> are:

• @select – to disable generation of footnote content, set select to "false" (default true).
• @output – set value to "generate-files" to place each reference in a separate file under a /footnotes folder. Selecting "generate-fragments" places each footnote in its own fragment, in a footnotes/footnotes.psml document (default generate-fragments).

<endnotes>

This element configures Word endnote handling.

<endnotes select="true" output="generate-files"/>

The attributes for <endnotes> are:

• @select – to disable generation of endnote content, set this attribute value to "false" (default true).
• @output – to place each reference in a separate file under an /endnotes folder, set this value to "generate-files". To place each endnote in its own fragment, in a endnotes/endnotes.psml document, set this value to "generate-fragments" (default generate-fragments).

Order and organize – <lists>

Processes Word lists, and paragraph numbering, and some manual numbering.

<lists>   
   <convert-to-list-roles select="false"/>

             <!-- generate numbered attribute
                  to paragraphs for lists -->
   <convert-to-numbered-paragraphs select="true">
      <level value="1" output="prefix"/>
             <!-- attach prefix or numbering
                  or inline=[label] or text -->
      <level value="2" output="prefix"/>
      <level value="3" output="prefix"/>
      <level value="4" output="numbering"/>
      <level value="5" output="numbering"/>
      <level value="6" output="inline=level6"/>
   </convert-to-numbered-paragraphs>

   <convert-manual-numbering select="true">
      <value match="^[\(|\[|\{][a-z]+[\)|\]|\}]">
         <inline label="numbering-lowercase" />
      </value>        
      <value match="^[\(|\[|\{][A-Z]+[\)|\]|\}]">
         <prefix/>
      </value>
      <value match="^[\(|\[|\{][ivx]+[\)|\]|\}]">
         <list role="numbering-roman"/>
      </value>
   </convert-manual-numbering>
</lists>

<convert-to-list-roles>

Adds a @role attribute to a <list> or <nlist>, with the value of the Word paragraph style. To invoke, set the @select attribute to true (default false). This attribute enables meaningful lists that store a semantic or formatting value, such as “procedures” or "guidance", that can be used for processing, validation or presentation.

<convert-to-list-roles select="true"/>

<convert-to-numbered-paragraphs>

Controls the conversion of numbered paragraph styles in Word to numbered paragraphs or lists in PageSeeder. For numbered paragraphs, set the value of the @select attribute to true. If false, the value converts to <list> or <nlist>, depending on the type of numbered value.

<convert-to-numbered-paragraphs select="true">

The "number" in the @value attribute of the <level> element corresponds to the position in the Word list hierarchy – use 1 to 6. It converts to the "value" of the @indent on the PSML element <para>.

Paragraph numbering "display" is in the @option attribute for each <level> element. See below for examples:

• "prefix" – to generate a prefix with the value of the current numbering value for each of the Word numbered paragraphs.

• "numbering" – to generate numbered paragraphs.

• "inline=[labelname]" – wraps the Word paragraph number in an inline label.

• "text" – puts the Word numbers in the paragraph content.

<convert-to-numbered-paragraphs select="true">
   <-- prefix or numbering or inline=[label] or text -->
   <level value="1" output="prefix"/>
   <level value="2" output="prefix"/>
   <level value="3" output="text"/>
   <level value="4" output="numbering"/>
   <level value="5" output="numbering"/>
   <level value="6" output="inline=level6"/>
</convert-to-numbered-paragraphs>

Example DOCX

Example in PageSeeder document view mode

Example PSML

Word Style – List Paragraph

Native Word paragraph style, List Paragraph, is a complex, difficult to control concept in Word – if possible, avoid using it! It imports by default as a <para> element, with a "number" in the @indent attribute, which corresponds to the position in the Word list hierarchy.

• "Bullets" or “Numbering” list icons are selected – the Word default paragraph style is List Paragraph. Where no other Word paragraph style, either a bulleted style or numbered style, is applied to the content, it imports as a <para> element.
• No "Bullets" or "Numbering" selected – Word paragraph imports in a <block>. Alternatively, one of the default Word paragraph styles List Continue, List Continue 2, List Continue 3, ... can be applied to import the content in a <para> element.

<convert-manual-numbering>

The <convert-manual-numbering> element processes non-automated, manual numbering values in Word files. To convert manual paragraph numbering values in Word, set the @select attribute to true.

<convert-manual-numbering select="true">

In the configuration from the default word-import-configuration.xml shown below, the <value> element contains a @match attribute, that has to follow the normal conventions of XSLT regular expressions (www.w3.org/TR/xslt20/#regular-expressions) . As of pso-docx v1.5.0 @match may contain a single group and only text matching this group is used for @prefix .

The <value> element accepts 3 options:

• <prefix level="[1-6]"/> – generates a @prefix attribute with the contents of the current numbering "value" for each of the Word paragraphs containing the regular expression value. If @level is specified generates an @indent or @level attribute with this number (overrides <wordstyle>). Requires pso-docx v1.5.0 or later for @level.

• <inline label="[numbering-format]" /> – to generate an <inline> element with content equal to the current numbering "value" for each of the Word paragraphs containing the regular expression value.

• <autonumbering/> – generates a @numbered="true" attribute.

This is the configuration from the default word-import-configuration.xml:

<convert-manual-numbering select="true">
   <value match="[\(|\[|\{][a-z]+[\)|\]|\}]">
      <inline label="numbering-lowercase" />
   </value>
   <value match="[\(|\[|\{][A-Z]+[\)|\]|\}]">
      <prefix/>
   </value>
   <value match="Part&#160;[A-Z0-9]+">
      <prefix />
   </value>
   <value match="Note:\s*">
      <prefix />
   </value>
   <value match="\s*([^\|]+)\|\t\s*">
     <prefix level="1"/>
   </value>
   <value match="\s*[0-9]+[A-Z]*$">
      <autonumbering/>
   </value>
</convert-manual-numbering>

Any number of <value> elements can be added, as long as the @match attribute is a valid regular expression (check www.w3.org/TR/xslt20/#regular-expressions) .

Import manual numbering in DOCX in a PSML <inline>

From the default configuration shown above, values, that match this regular expression are output in an <inline> element with an attribute of @label="numbering-lowercase":

<value match="[\(|\[|\{][a-z]+[\)|\]|\}]">
  <inline label="numbering-lowercase" />
</value>

Import manual numbering in DOCX as a prefix attribute on a PSML <heading> or <para>

From the default configuration shown above, values that match any of the following regular expressions are output as the "value" of a @prefix attribute in a <heading> or <para> element:

<value match="[\(|\[|\{][A-Z]+[\)|\]|\}]">
  <prefix/>
</value>
<value match="Part&#160;[A-Z0-9]+">
  <prefix />
</value>
<value match="Note:\s*">
  <prefix />
</value>

Import manual numbering in DOCX as a prefix attribute on a PSML <heading> or <para> that has an attribute level value of 1

From the default configuration shown above, values that match the following regular expression group (the pattern between the parenthesis) are output as the "value" of a @prefix attribute in a <para indent="1"> element. For example 5a|{tab} becomes <para prefix="5a" indent="1">. Requires pso-docx v1.5.0 or later:

<value match="\s*([^\|]+)\|\t\s*">
  <prefix level="1"/>
</value>

Example – Import manual numbering as attribute prefix on a PSML <heading> and <para>

The following examples show the import of manual numbering in a custom Word document imported using the following import configuration:

<convert-manual-numbering select="true">
  <value match=".*?\|">
    <prefix />
  </value>
</convert-manual-numbering>

Example DOCX

Example in PageSeeder document view mode

Example PSML

Import manual numbering in DOCX as a numbering attribute on a PSML <heading> or <para>

Values that match the following regular expression output an @numbering="true" attribute.

<value match="\s*[0-9]+[A-Z]*$">
  <autonumbering/>
</value>

Semantics and formatting – <styles>

For general transformations of DOCX styles to PSML, the options are <ignore>, <default> and <wordstyle>. There are descriptions of the examples below.

<styles>
   <ignore>
      <wordstyle value="TOC1" />
      <wordstyle value="TOC2" />
      <wordstyle value="TOC3" />
      <wordstyle value="TOC4" />
   </ignore>

   <default>
      <paragraphStyles value="block" />
          <!-- possible values: 'para' or 'block' -->
      <characterStyles value="inline" />
          <!-- possible values: 'none' or 'inline' -->
      <smart-tag keep="true" />
          <!--  possible values: 'false' or 'true' -->
      <references psmlelement="link" />
          <!-- required when using PSML split config -->
          <!-- 
              <property name="prefix" value="true" /> 
               possible values: 'false' or 'true'
           -->
   </default>

         <!-- Values accepted: Word style ID of the Word style name available
              in document -->

   <wordstyle name="Title" psmlelement="block">
      <label type="block" value="title"/>
   </wordstyle>

   <wordstyle name="Subtitle" psmlelement="block">
      <label type="block" value="subtitle"/>
   </wordstyle>

   <wordstyle name="Heading1" psmlelement="heading">
      <level value="1" />
   </wordstyle>

   <wordstyle name="Heading2" psmlelement="para">
   </wordstyle>

   <wordstyle name="Heading3" psmlelement="inline">
      <label value="Heading3" />
   </wordstyle>

   <wordstyle name="Heading4" psmlelement="block">
      <label value="Heading4" />
   </wordstyle>

   <wordstyle name="Heading5" psmlelement="heading">
      <level value="5" />
      <label type="block" value="Heading5" />
   </wordstyle>

   <wordstyle name="Heading6" psmlelement="heading">
      <level value="6" />
   </wordstyle>

</styles>

<ignore>

Determines the content to NOT process. For example, to discard the Table of Contents paragraphs from Word, use the following:

<ignore>
   <wordstyle value="TOC1" />
   <wordstyle value="TOC2" />
   <wordstyle value="TOC3" />
   <wordstyle value="TOC4" />
</ignore>

<default>

See examples above.

<paragraphStyles>

Process Word paragraph styles with no explicit mapping using <wordstyle> or <lists>, and the following options for the @value attribute:

• "para" – Word paragraph styles with no explicit mapping are output as a PSML <para> element.

• "block" – Word paragraph styles without an explicit mapping will be output as a PSML <block> element with the "value" of a @label attribute equal to the Word paragraph style ID (note: the ID is different from Word paragraph style name).

<characterStyles>

Defines general rule for any Word character style not mapped with <wordstyle>. @value supports the following:

• "none" – Word character styles without an explicit mapping are stripped.

• "inline" – this option converts Word character styles to a PSML <inline> element with the “value” of a @label attribute equal to the Word character style ID (note: the ID is different from Word character style name).

<smart-tag>

Capture Word smart tag  information as an inline label equal to the smart tag ID, by setting the @keep attribute value to "true". Otherwise, the import will discard smart-tag markup.

<references>

To determine whether to process internal references as PSML <link> or <xref> elements, set the @psmlelement attribute to a value of "link" or "xref" (default is "xref"). Using "link" also imports all bookmarks as <anchor> elements. Requires pso-docx v0.8.3 or higher.

<wordstyle>

These rules transform Word paragraph or character styles into the following PSML elements:

• Word paragraph styles
• <heading>
• <para>
• <block>
• <preformat>
• <caption>
• Word character styles:
• <bold>
• <inline>
• <italic>
• <monospace>
• <underline>

There is a description of these rules below.

 <wordstyle name="Heading1" psmlelement="heading">
   <level value="1" />
 </wordstyle>

 <wordstyle name="Heading2" psmlelement="para">
 </wordstyle>

 <wordstyle name="Heading3" psmlelement="inline">
   <label value="instruction" />
 </wordstyle>
 
 <wordstyle name="Heading4" psmlelement="block">
   <label value="requirement" />
 </wordstyle>

 <wordstyle name="Heading5" psmlelement="heading">
    <level value="5" />
    <label type="block" value="Section_highlight" />
 </wordstyle>

 <wordstyle name="HTMLCode" psmlelement="monospace"/>

 <wordstyle name="HTMLPreformatted" psmlelement="preformat"/>

 <wordstyle name="TableCaption" psmlelement="caption" table="default"/>

 <wordstyle name="Strong" psmlelement="bold"/>

 <wordstyle name="Emphasis" psmlelement="italic"/>

 <wordstyle name="IntenseEmphasis" psmlelement="underline"/>

The rules above perform the following transformations.

• A Word paragraph style ID of Heading1 transforms to <heading> with an attribute @level="1".

• A Word paragraph style ID Heading2 transforms to <para>.

• A Word paragraph style ID Heading3 transforms to an <inline> label with an attribute @label="instruction".

• A Word paragraph style IDHeading4 transforms to <block> with an attribute @label="requirement".

• A Word paragraph style ID Heading5 transforms to <heading> with an attribute @level="5", and a <block> element wrapper with attribute @label="Section_highlight".

• A Word paragraph style ID HTMLCode transforms to <monospace>.

• A Word paragraph style ID HTMLpreformatted transforms to <preformat>.

• A Word paragraph style ID TableCaption transforms to <caption> for all tables.

• A Word paragraph style ID Strong transforms to <bold>. Requires pso-docx v1.1.0 or higher.

• A Word paragraph style ID Emphasis transforms to <italic>. Requires pso-docx v1.1.0 or higher.

• A Word paragraph style ID IntenseEmphasis transforms to <underline>. Requires pso-docx v1.1.0 or higher.

<wordstyle> – @psmlelement

"heading"

Possible child elements are:

<wordstyle name="Heading1" psmlelement="heading">
  <level value="1" />          
  <label type="block" value="heading1">          
</wordstyle>

• <level> with attribute @value ranging from "1" to "6".

• <label> with attributes:

• @type with values "block" or "inline".

• @value with value of a [valid label name].

"para"

Possible child elements are:

<wordstyle name="paragraph1" psmlelement="para">
  <indent value="1" /> 
  <label type="block" value="para1"/>
  <numbering select="true" value="inline"/>
</wordstyle>

<wordstyle name="paragraph2" psmlelement="para">
  <indent value="2" /> 
  <label type="inline" value="para2"/>
  <numbering select="true" value="prefix"/>
</wordstyle>

<wordstyle name="paragraph3" psmlelement="para">
  <indent value="3" /> 
  <numbering select="true" value="inline">
    <label value="num3"/>
  </numbering>
</wordstyle>

• <indent> with attribute @value from "1" to "6".

• <label> with attributes of:

• @type with values of block or inline.

• @value with value of a [valid label name].

• <numbering> with attributes of:

• @select with values of "true" or "false".

• @value options of:

• "inline"– requires specifying a nesting label <label value="[valid label name]"> to wrap the paragraph number in.

• "text" – include the number in paragraph text.

• "prefix" – express the paragraph number as a @prefix attribute.

"Caption" and <caption>

By default, whether on an image or a table, the Word paragraph style "Caption" imports as a <block> element with <label> @value "Caption". The <block> is not inside/attached to the table or image – in the PSML it is before a <table> element, and after an <image> element. This import is useful when tables and images don’t have numbering, so can be treated the same.

Default import – <block> with label "Caption"

<wordstyle name="Caption" psmlelement="block">
  <label value="Caption" />
</wordstyle>

Example PSML – table caption default import

<block label="Caption">Table 1 A caption for a default table style Table Grid</block>
<table role="TableGrid">
  <col width="50%" part="header"/>
  <col width="50%"/>
    <row part="header">
      <cell><para>Cell 1 col 1</para></cell>
      <cell><para>Cell 1 col 2</para></cell>
    </row>
    <row>
      <cell><para>Cell 1 col 2</para></cell>
      <cell><para>Cell 2 col 2</para></cell>    
     </row>
</table>

Example PSML – image caption default import

<para>Image with caption:</para>
<para>
  <image src="images/image1.jpg" alt="image1.jpg" width="601" height="451"/>
</para>
<block label="Caption">Figure 1 Caption</block>

<para>Image without caption:</para>
  <para>
    <image src="images/image%20%2B%21%27%28%29%7E.2.jpeg"
           alt="image%20%2B%21%27%28%29%7E.2.jpeg"
           width="261"
           height="196"/>
  </para>

Tables and images with different numbering (or formatting)

Where numbering (or formatting) of tables and figures differs, they need to be treated differently, so they cannot both have label @value "Caption". This mapping is also used where the captions for table and images have different formatting.

Table captions

For tables, the default export template for the report publication type (and sample files) uses a block label @value of table-caption to output to custom Word paragraph style “Table Caption” – add this Word paragraph style to your document to import. Use the following in your word-import-config.xml.

<wordstyle name="Table Caption" psmlelement="block">
  <label value="table-caption" />
</wordstyle>

Image captions

For images, the default export template for the report publication type (and sample files) uses a block label @value of figure-caption to map the default Word paragraph style “Caption” – use  the Word paragraph style "Caption" for image captions in your document to import. Use the following in your word-import-config.xml.

<wordstyle name="Caption" psmlelement="block">
  <label value="figure-caption" />
</wordstyle>

Import table captions as PSML element <caption>

Table captions can be imported as element <caption> – the content is inside/attached to the <table> element. This can also be done programmatically.

Table captions as element <caption>

To apply to all tables requires a @table attribute with a value of "default" – see the default import configuration under Mapping to a Word Default table style (w:styleId="TableGrid") to a <caption> element below.

For only specific table styles, map them using their table style ID as the @table attribute value — see under Mapping a specific/custom table design to a <caption> element below.

• Mapping to a Word Default table style (w:styleId="TableGrid") to a <caption> element – To import in an element <caption>, use the following in your import config:

<wordstyle name="Caption"
           psmlelement="caption"
           table="default"/>

If you have styled table captions as Word style "Table Caption", follow this example:

<wordstyle name="Table Caption"
           psmlelement="caption"
           table="default"/>

Example PSML

<table role="TableGrid">
<caption>Table 1 A caption for a default table style Table Grid imported in a caption element</caption>
  <col width="50%" part="header"/>
  <col width="50%"/>
    <row part="header">
      <cell><para>Cell 1 col 1</para></cell>
      <cell><para>Cell 1 col 2</para></cell>
    </row>
    <row>
      <cell><para>Cell 1 col 2</para></cell>
      <cell><para>Cell 2 col 2</para></cell>    
     </row>
</table>

• Mapping a specific/custom table design to a <caption> element (e.g. w:styleId="tableYellow") – where table captions have Word style “Caption”, to import them in an element <caption>, use the following in your import config:

<wordstyle name="Caption"
           psmlelement="caption"
           table="tableYellow"/>

If table captions have Word style "Table Caption", you can follow this example:

<wordstyle name="Table Caption" 
           psmlelement="caption" 
           table="tableYellow"/>

Example PSML

<table role="tableYellow">
<caption>Table 2 A caption for a custom table style tableYellow</caption>
  <col width="50%" part="header"/>
  <col width="50%"/>
    <row part="header">
      <cell><para>Cell 1 col 1</para></cell>
      <cell><para>Cell 1 col 2</para></cell>
    </row>
    <row>
      <cell><para>Cell 1 col 2</para></cell>
      <cell><para>Cell 2 col 2</para></cell>    
     </row>
</table>

Deprecated

<add-numbering-to-document-titles>

To number the document titles output from the split process, set the value of the @select attribute to "true".

<add-numbering-to-document-titles select="true"/>