Microsoft Word output reference for designing templates

Review this information to learn more about generating Microsoft Word documents with IBM Engineering Lifecycle Optimization - Publishing (PUB).

Purpose

To output the template into the following document-style reports:
Extension Format of generated document-style report
.doc Microsoft Word binary documents
.docx Microsoft Word documents without the ability to run macros
.docm Microsoft Word documents with the ability to run macros

Supported content viewers

For a list of products that are supported for viewing this output type:
  1. Open the System Requirements.
  2. In the By type section, click Software.
  3. Scroll to the Content viewers section. Product names and versions that are supported for viewing PUB output are listed.

The default PDF driver produces version 1.5 PDF files. The Legacy PDF driver is no longer supported. If your document specification points to the old legacy PDF driver, modify the specification to refer to the default PDF driver.

Template elements

Review the available template elements:
Table 1. Template elements available to use for the Microsoft Word output format
Element Description Can contain other elements Can contain content values and expressions

Paragraph icon Paragraph

Use to group a section of elements. Adds a carriage return around its child elements in the output.

Yes

No

Container icon Container

Use to group a section of elements. Cannot be styled and does not affect the formatting of the output.

When used inside other elements, the child elements available to use within the container might be limited. For example:
  • Inside rows, containers can host cells only.
  • Inside lists, containers can host list-detail elements only.

Yes

No

Text icon Text

The content renders with the same, specified formatting.

No

Yes

Styled text icon Styled text

A block of text that can have unique formatting on individual words. Use bold, italic, underline, strikeout, or color formatting on a selection of words within the element. The text is static.

No

Yes

Hyperlink icon Hyperlink

Creates a hyperlink in the output. The hyperlink can point to a location inside the document-style report or to an external location.

No

Yes

Image icon Image

Displays a .gif, .png, .jpg, emf, or wmf image in the output. The report designer can specify the image path in the template or the report generator can specify the path at run time.

No

Yes

Table icon Table

Creates a table in the output. A table can contain rows or container elements.

Yes

No

Row icon Row

Creates a row in the current table.

Yes

No

Cell icon Cell

Creates a cell in the current row of the current table.

Yes

No

List icon List

Creates a bulleted or numeric list in the output.

Yes

No

List item icon List Item

Creates a list item in the current list in the output.

Yes

No

Data Source configuration icon Data source configuration

See Adding a data source configuration element.

No

No

Include file icon Include file

Includes the specified file in the output as an INCLUDETEXT field. See Adding an include file element.

  • The included file can have a .doc, .docx, .txt, or .rtf extension.
  • For Microsoft Word output, you can show a link or the file contents. You must update all fields with the macro to see the included file.
  • For HTML and XSL-FO output, the included file is a hyperlink to the document-style report.

No

Yes

Footnote icon Footnote

Creates a footnote in the current output page. The text of the footnote is the content of the footnote element. Supported for Microsoft Word output only.

No

Yes

Region icon Region

Regions are static elements that allow you to alter the output flow by redirecting the content of other elements or groups of elements. If an element has the target region property that is specified with the name of a region element, its content renders in the specified region instead of in its position in the document-style report.

No

No

Bookmark icon Bookmark

Defines a bookmark in the document-style report. The name of the generated bookmark is the content for the bookmark. When generating the document-style reports, Engineering Publishing generates a unique name for each bookmark. The name is based on the name that is provided at design time and a unique identifier that is generated at run time.

No

Yes

Comment icon Comment

Adds a comment to the output. The format of the output comment is specific to the output format.

Supported for Microsoft Word and PDF.

No

Yes

Page Break icon Page Break

Adds a page break to the output.

No

No

Section Break icon Section Break

Adds a section break to the output.

No

No

Document break

Generates an output file that combines all the separate document-style reports; you must set the multipart property in your document specification.

Yes

No

Table of Contents icon Table of Contents

Adds a table of contents to the output.

No

No

Table of Tables icon Table of Tables

Adds a table of tables to the output. You must add Table Captions in your document template to generate a table of tables in the output.

Supported for Microsoft Word output only.

You must update all fields in the Microsoft Word document to see and be able to update the value of the field.

No

No

Table of Tables icon Table of Tables

Adds a table of tables to the output. You must add Table Captions in your document template to generate a table of tables in the output.

Supported for Microsoft Word output only.

You must update all fields in the Microsoft Word document to see and be able to update the value of the field.

No

No

Field icon Field

Adds a generic Microsoft Word field element. Then, you can type any valid Microsoft Word code in the field code property.

Supported for Microsoft Word output only.

You must update all fields in the Microsoft Word document to see and be able to update the value of the field.

No

No

Page Number icon Page Number

Adds a page number in the output. Supported in Microsoft Word and PDF output only.

No

No

Total Pages Number icon Total Pages Number

Adds the total number of pages in the output. Supported for Microsoft Word and PDF output only.

No

No

Table Caption icon Table Caption

Adds a table caption. While you cannot specify dynamic content into a table caption, any subsequent text element is concatenated to it.

Supported for Microsoft Word, HTML, and PDF outputs.

You must update all fields in the Microsoft Word document to see and be able to update the value of the field.

No

Yes

Figure Caption icon Figure Caption

Adds a figure caption. While you cannot specify dynamic content in a figure caption, any subsequent text element is concatenated to it.

Supported for Microsoft Word and PDF outputs.

You must update all fields in the Microsoft Word document to see and be able to update the value of the field.

No

Yes

Element properties

Review these notes to understand more about specifying the element properties for templates that are designed to generate Microsoft Word documents.
Table 2. Cell properties
Cell properties Notes
Border width You must specify a border width value between 1 and 30 pixels to create a border in the output.
Cell alignment This property specifies the position of the text within the cell. The justify value is not supported for this output format.
Cell width Enter a value in points or pixels. If you enter a value in pixels, the value is converted to points and assumes that the display is 96 dpi. If you enter a value as a percentage, the value is ignored. When you are combining tables, you must set the cell width property to ensure that the column sizes are the same.
Table 3. Comment properties
Comment properties DescriptionNo
Content If you include hyperlinks in the Content property of Comment elements, the hyperlinks are not clickable in the Microsoft Word output.
Table 4. Figure caption properties
Figure caption properties Description
Border width N/A
Field code Arabic or Roman numerals display sequentially on each caption.
Table 5. Footnote properties
Footnote properties Description
Style name If you apply a style to inline elements such as footnotes, text, styled text, or tables, the style is applied to all of the inline elements until the next block element, such as a paragraph. For example, if you add a style to a footnote element and there is a styled text element before it, the style is also applied to the styled text element.
Table 6. Image properties
Image properties Description
Border width N/A
Content Supported image formats: .bmp, .emf, .gif, .jpg, .png, .wmf

.svg images are supported by PUB, but are not supported by Microsoft Word. To generate the document-style report correctly into Microsoft Word output, .svg images are converted to .png images. The conversion process can distort the display of the image in the output.

Table 7. List-detail properties
List-detail properties Description
Border width N/A
Table 8. Page number properties
Page number properties Description
Border width N/A
Table 9. Paragraph properties
Paragraph properties Description
Border width You must specify a border width value between 1 and 30 pixels to create a border in the output.
Paragraph alignment Space the text across the page with a certain alignment.

Left, right, and center alignment, creates uneven paragraph edges, fitting as many words in a paragraph as possible. Justify creates even paragraph edges by inserting additional space between words on all lines except the last line. Distributed is similar to justify, except that space is also inserted between words in the last line of the paragraph.

Widow/orphan control When set to true, the line spacing is adjusted to prevent the following formatting results:
  • A single word ending a paragraph on a new line
  • A single line ending a paragraph on a new page

When set to false, spacing is not adjusted.

Table 10. Row properties
Row properties Description
Row break across pages When set to true, the content of a row that comes at the end of a page is split, if necessary. The content that does not fit on the page carries over onto the next page as a new row.

When set to false, the content of a row that comes at the end of the page is not split. The whole row carries over onto the next page.

Table 11. Styled text properties
Styled text properties Description
Style name If you apply a style to inline elements such as footnotes, text, styled text, or tables, the style is applied to all of the inline elements until the next block element, such as a paragraph. For example, if you add a style to a footnote element and there is a styled text element before it, the style is also applied to the styled text element.
Table 12. Table properties
Table properties Description
Autofit to contents Resizes the table to fit the content each cell contains. When you use this property, also set the Resize to fit contents property to true.
Border width You must specify a border width value between 1 and 30 pixels to create a border in the output.
Border style Use the value single instead of thick, hairline, inset, or outset. The same formatting is applied for all of these values and most closely resembles what you would expect to see for single.
Fixed cell width in column Specify a value in pixels to ensure that all of the cells in a column are the same width.
Resize to fit contents When set to true, lines do not break unless a space is present. When you do not have space, lines do not break and the column width is increased to the width of the text. If autofit to contents is set, you must set resize to fit contents to true.

When set to false, the column width is fixed and the lines break regardless of the spaces used or the length of the text. Also, the table auto fit property is ignored.

Style name If you apply a style to inline elements such as footnotes, text, styled text, or tables, the style is applied to all of the inline elements until the next block element, such as a paragraph. For example, if you add a style to a footnote element and there is a styled text element before it, the style is also applied to the styled text element.
Table auto fit When set to true, the table is resized to fit the width of the page. When resize to fit contents is also set to true, cell widths are ignored and the table is resized to match the content.

You cannot enter fixed column width as a value. Use the fixed cell width property instead.

Width You must specify a value.
Table 13. Table caption properties
Table caption properties Description
Border width N/A
Field code Arabic or Roman numerals display sequentially on each caption.
Table 14. Text properties
Text properties Description
Border width You must specify a border width value between 1 and 30 pixels to create a border in the output.
Style name If you apply a style to inline elements such as footnotes, text, styled text, or tables, the style is applied to all of the inline elements until the next block element, such as a paragraph. For example, if you add a style to a footnote element and there is a styled text element before it, the style is also applied to the styled text element.
Table 15. Total pages number properties
Total pages number properties Description
Border width N/A

Table length

When you are designing templates that are to be generated into Microsoft Word documents, table length might be a factor to consider.

Long tables might need to carry over onto more than one page. When this requirement arises, select a Row element in the table and in the Properties view, set the row break across page property to true. With that property set, your tables can continue across multiple pages.

Tables of contents, figures, and tables in Microsoft Word documents

To add a table of contents to your output, define the table of contents in your template or style sheet. If you define the table of contents in the template, the table is not shown in the Microsoft Word document until you update the document-style report fields. To update the fields, use the Update Fields or Update Table feature in Microsoft Word or use the macros contained in the rpe.dot style sheet. You can find the rpe.dot style sheet in the PUB installation: PUB_install_dir\utils\word\rpe.dot. The same process applies to tables of figures and tables of tables.

Captions in Microsoft Word documents

Figure and table captions are not automatically updated. To update the fields, use the Update Fields feature in Microsoft Word or use the macros contained in the rpe.dot style sheet. You can find the rpe.dot style sheet in the PUB installation: PUB_install_dir\utils\word\rpe.dot.

Include file element

You can create a link to the file or physically embed the file into your output document-style report. However, include file elements are handled differently, depending on the output format and the location you are retrieving the file from.

For Microsoft Word output, when the including type is set to link dynamically, the Word field ({INCLUDETEXT FileName \* MERGEFORMAT}) is added instead of a link.

Heading styles

To use the predefined heading styles for Microsoft Word (Heading 1, Heading 2, ... , Heading 9), use the style name 1, 2, to 9.

PUB styles versus external styles

Use external styles, which are defined in a style sheet, as much as possible. With this approach you can quickly change the appearance of the output document-style report and enforces a uniform look across the company.

Numbered headings for Microsoft Word

Use a style sheet with numbered headings to obtain headings numbered as a hierarchical list.

Unicode data in output

All Unicode data is rendered if the font that is used supports Unicode. For Microsoft Word output, if you used a non-Unicode font, change the font in the output document-style report after document-style report generation.

OLE objects

You can extract embedded objects, such as Object linking and embedding (OLE objects), from attributes in a data source. For Microsoft Word output, you must set the OLEs as static images property in the metadata section of the document specification.
  • If the OLEs as static images property is set to true, OLE objects are included in the output document-style report as static images. When the OLE objects are included in the output document-style report as static images, the document-style report is self-contained.
  • If the OLEs as static images property is set to false, a ref folder is generated in the same location as the Microsoft Word output document. When the OLE objects are not included in the output document-style report as static images, the document-style report is not self-contained because the separate ref folder is required.
The ref folder contains .rtf files for the OLE objects. For each OLE object exported, the Microsoft Word output has one included field pointing to an .rtf file. Because PUB cannot update Microsoft Word fields, the included fields are not visible when the Microsoft Word document is open. To make the fields visible, take one of the following actions:
Table 16. Actions
Action Result
Select the entire document-style report content and use the Update fields function in Microsoft Word. The OLE objects are displayed in the document-style report. The document-style report is not self-contained.
Use the updateFields macro provided by PUB. The OLE objects are displayed in the document-style report. The document-style report is not self-contained.
Use the insertOLEs macro provided by PUB. The OLE objects are displayed in the document-style report. The document-style report is self-contained.
Use the rpe or insertOLEs macros provided by PUB. The OLE objects are displayed in the document-style report. The document-style report is self-contained.
Note: If you move a document-style report that is not self-contained to another computer, you cannot edit the OLE objects. To prevent this problem, run the insertOLEs macro.

Limitation

Consider Microsoft Word limitations while generating Microsoft Word documents with PUB. Microsoft Word 2007 and later versions limit document-style report size to 512 MB while prior Microsoft Word versions limit document-style report size to 32 MB. See Microsoft Word operating parameter limitations for details.