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 in collaborative editing, managing access to the content, keeping track of changes, and the reuse of content. 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. While the concepts are easy to understand, there is no formal definition or adoption of such concepts. This is exactly why the word-import-config.xml allows for the flexible mapping of headings, outline levels, sections, lists, and paragraphs. Where the import process splits a Word file into a hierarchical collection of files, it will create 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 paragraph, character, list, and table styles. It also supports mapping bookmarks, document types, and other IDs.

• Linking – arguably either structure or semantics, there are many reasons why users rarely add many links to Word documents. 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

For aspects of the Word documents that the import process ignores, consideration must be given to modifying the Word, before importing it. For example, where software documentation includes code samples, replace any monospace font setting with a Word style like HTML Preformatted before importing into PageSeeder. Information that the import 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 – there is no processing of the many measurements such as tab stops, margins, indents, column widths, line spacing, borders into PageSeeder. Exceptions include table settings that use percentages, and image size.
• 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, other fields such as index entries and footnotes require configuration – to preserve other field content will require processing them in Word before importing.
• Security – PageSeeder has a separate permission model for accessing content, so the process ignores Word security settings.

Background

To better understand the complementary relationship between Word and PageSeeder, and the role of the word-import-config, it helps to have some understanding of how Word files work.

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.

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.
• 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.

OX – analyse data before import

Using the OX tool  can provide valuable insight about the quality of the markup in your source data.

Typical use cases include the following:

• Analysis of different markup used in source documents such as XML, PDF or DOCX file formats.
• Compare two or more XML instances and generate a report of the different XPath expressions or attribute values.
• Batch validate XML instances against XSD or Schematron schema.
• Convert documents from one format to another, including conversion rules for specific data sets.
• Convert docx or PDF files into a generic interim format (PageSeeder PSML) before further processing into other structures or syntaxes.

Architecturally, the idea behind OX is to allow developers to configure processing scripts into a pipeline without worrying about creating an interface for end-users who might not be comfortable using the command line. Both the OX interface and the pipelines are expressed as XML files. It can be deployed with either a user interface or as a service, or both.

OX supports processes that might require user input – see the screenshot below, where a user can add bookmarks to a PDF document one entry at a time or by pasting a list of entries into the editor. OX will process these entries to create a new PDF that is better suited for epub or other applications.

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 configuration of bullet and numbered list styles.

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

Users unfamiliar with Word multilevel lists, or list styles might find it easier to modify, or refer to, the already-configured word-import-config.xml.

For this, edit the default word-import-config.xml for your project on PageSeeder – click the icon in the header bar, then in the main section, click Project administration menu > Template > Template configuration, then in the Media types table, Word Import column and in the docx row, click default.

Modify the declarations in the word-import-config.xml and save the changes.

Word import config file

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:styleId="Heading3"> 

 <w:name w:val="heading 3" />

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

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 option 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 option 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 option 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 attribut 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 to numbered paragraphs or lists in PageSeeder. For numbered paragraphs, set the value of the @select attribute to true. If false, the value will convert 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 style, either a bulleted style or numbered style, is applied to the content, it imports as a <para> element.
• No "Bullets" or "Numbering" selected – 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>

Processes non-automated numbering values in Word files. To convert manual paragraph numbering values, set the @select attribute to true.

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

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 ).

The <value> element accepts 3 options:

• <prefix/> – generates a @prefix attribute with the contents of the current numbering "value" for each of the Word paragraphs containing the regular expression value.

• <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.

<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*[0-9]+[A-Z]*$">
      <autonumbering/>
   </value>
</convert-manual-numbering>

Values that match the following regular expression are output in an <inline> element with an attribute of @label="numbering-lowercase".

^[\(|\[|\{][a-z]+[\)|\]|\}]

Values that match any of the following regular expressions are output as the "value" of a @prefix attribute in a <para> element. 

^[\(|\[|\{][A-Z]+[\)|\]|\}]
Part [A-Z0-9]+
Note:\s*

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

\s*[0-9]+[A-Z]*$

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 )

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 'inlineLabel' -->
      <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, use the following:

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

<default>

See examples above. 

<paragraphStyles>

Process 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 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:

• <heading>
• <para>
• <block>
• <preformat>
• <caption>
• <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 ID  Heading4 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  HTMLpreformat 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.

@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>

The Word default Caption style is imported as psmlelement="caption". 

Table captions

To apply to all tables requires a @table attribute with a value of "default". For only specific table styles, use table style ID as the @table attribute value.

• When applied to a Word Default table style (w:styleId="TableGrid") – The caption is not attached to the table – it imports in a block label above the table element.

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

Example PSML

<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>

• When applied to a Custom table style (e.g. w:styleId="tableYellow") – The contents of the caption are imported inside a <caption> element.

<wordstyle name="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>

Image captions

The default conversion of the default Word paragraph style ‘Caption’, when attached to an Image, is into a psmlelement="block".

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

Example PSML

<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>

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"/>