4. Implementation specificities

4.1. Page references


Page references - i.e. page-number-citation objects - are converted to PageRef fields. The values of these fields are not automatically updated when loading an RTF/WML/OOXML document in MS-Word. The easiest way to update all field values is to force a repagination of the document, for instance by switching to the Page Layout view. This will work fine for fields in the body of the document, but not for those in the header/footer. To update fields in the header or footer of a document, proceed as follows:

  1. Switch to the Page Layout view.

  2. Double-click on an odd page header/footer outline.

  3. Type Ctrl-A (Select all) and F9 (Update fields).

  4. Double-click on an even page header/footer outline and repeat step #3.

  5. If applicable, double-click on the title page header/footer outline and repeat step #3.

4.1.2. OpenDocument

Page references - i.e. page-number-citation objects - are converted to reference fields. The values of these fields are not automatically updated when loading an OpenDocument file in OpenOffice. Select Update->Fields in the Tools menu to update the field values.

4.2. Lists

XFC automatically tries to infer the numbering style from the label of the first list item. Both bulleted and numbered lists are supported. Nested lists are supported.

When the heuristics used by XFC are insufficient to infer the type of a list, it's still possible to explicitly specify this type by adding an xfc:label-format extension attribute to the fo:list-block.

When the heuristics used by XFC are insufficient to infer the type of a list and the xfc:label-format attribute is absent from the fo:list-block, then the list items are output as plain paragraphs. That is, the list items look as expected, but will not behave as proper list items when edited in MS-Word or OpenOffice.org.

4.2.1. The xfc:label-format extension attribute

The xfc:label-format attribute must be specified on a fo:list-block.

The namespace of this attribute is "http://www.xmlmind.com/foconverter/xsl/extensions". A prefix, typically xfc, must be declared for this namespace.

The syntax of the value of this attribute is:

label-format -> [ bullet | number ]?

bullet -> String

number -> [String]? '%{' format '}' [String]

format -> 'decimal'|'lower-alpha'|'upper-alpha'|
          'lower-roman'|'upper-roman' [inherit]? [start]?

inherit -> ';inherit'

start -> ';start=' Positive_Integer


  • An empty xfc:label-format attribute (e.g. xfc:label-format="") is allowed. It instructs XFC not to use any heuristic and to convert the fo:list-block to plain paragraphs.

  • The '%' character must be escaped by doubling it. Example: %%%{decimal}, which corresponds to %1, %2, %3, etc.

  • The format values decimal, lower-alpha, etc, correspond to the values of the CSS list-style-type property.

  • The inherit optional parameter specifies that a numbered fo:list-block “inherits” the numbering of its ancestor numbered fo:list-blocks. In other words, this parameter may be used to implement what is often called multi-level numbering (e.g. 1.A.a.)

    For example, let's suppose topmost fo:list-block is numbered 1-, 2-, 3-, etc. Let's suppose its second list item contains a nested fo:list-block having attribute xfc:label-format="%{upper-alpha;inherit})". Then this nested list will be automatically numbered 2-A), 2-B), 2-C), etc.

  • The start= optional parameter specifies the starting number of the first item in an ordered list. Its default value is 1.

    • Specifying both inherit and start=N is currently not really supported and generally gives unexpected results.

    • Something like start=continue is currently not supported.


<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
  <fo:list-block font-family="monospace" margin-left="10pt"
      <fo:list-item-label end-indent="label-end()">

      <fo:list-item-body start-indent="body-start()">
        <fo:block>This is the first item 
        of the list.</fo:block>

      <fo:list-item-label end-indent="label-end()">

      <fo:list-item-body start-indent="body-start()">
        <fo:block>This is the second item 
        of the list.</fo:block>

The heuristics used by XFC corresponds to the following values of xfc:label-format:

  • -, +, *, &#x2022; (bullet), &#x2013; (endash).

  • %{decimal;start=0}, %{decimal}, %{lower-alpha}, %{upper-alpha}, %{lower-roman}, %{upper-roman}.

  • %{decimal;start=0}., %{decimal}., %{lower-alpha}., %{upper-alpha}., %{lower-roman}., %{upper-roman}..

  • %{decimal;start=0}), %{decimal}), %{lower-alpha}), %{upper-alpha}), %{lower-roman}), %{upper-roman}).

  • (%{decimal;start=0}), (%{decimal}), (%{lower-alpha}), (%{upper-alpha}), (%{lower-roman}), (%{upper-roman}).

  • [%{decimal;start=0}], [%{decimal}], [%{lower-alpha}], [%{upper-alpha}], [%{lower-roman}], [%{upper-roman}].

  • &lt;%{decimal;start=0}>, &lt;%{decimal}>, &lt;%{lower-alpha}>, &lt;%{upper-alpha}>, &lt;%{lower-roman}>, &lt;%{upper-roman}>.

4.3. Leaders

For lack of a corresponding element in the output formats, leader objects are implemented by means of tab stops. This is not very convenient given the leader object specification, since there is no way for XFC to derive the tab position from the property values. Though XFC will usually set the tab position to a reasonable value by default, this arbitrary position is unlikely to result in the intended layout.

However, the actual tab position may be specified to XFC by setting an additional property on the leader object. This property is named tab-position and must be defined in the XFC namespace (http://www.xmlmind.com/foconverter/xsl/extensions). The property value is a <length> as defined in section 5.11 of the Recommendation. A positive value specifies the tab position relative to the left margin, whereas a negative value specifies the position relative to the right margin.

An additional property named tab-align specifies how the content following a tab is horizontally aligned. The possible values for this property are: left, center, right and decimal. Using the tab-align property is optional. By default, the content following a tab is left aligned.

The code samples below are excerpts from file xslutil_install_dir/addon/config/docbook/xsl/fo/autotoc.xsl. They illustrate a typical use of the tab-position and tab-align properties in an XSL stylesheet.

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
<fo:leader leader-pattern="dots"

4.4. Other extension attributes

4.4.1. The xfc:outline-level extension attribute

Extension attribute xfc:outline-level may be used to mark a fo:block as a heading having the outline level specified by the value of the attribute. The value of this attribute is an integer between 1 and 9 inclusive. Any other value will cause attribute xfc:outline-level to be ignored.

Specifying outline levels allows to:

  • Use the Document Map and the Outline View in MS-Word. Use the Navigator Window in OpenOffice/LibreOffice.

  • Insert a Table of Contents in a document edited in MS-Word or OpenOffice/LibreOffice.


<fo:block font-size="22pt" space-before="22pt" 
          xfc:outline-level="4" color="#406080">Heading 4</fo:block>

4.4.2. The xfc:render-as-table extension attribute

Extension attribute xfc:outline-level may be used to specify that a fo:block is to be automatically converted to an equivalent fo:table. The value of this attribute is true or false.

This extension attribute is a quick and easy workaround for one of the most annoying limitations of XMLmind XSL-FO Converter: a fo:block having a border and/or background color and containing several other blocks, lists or tables was very poorly rendered in RTF, WML, DOCX and ODT. (Such container fo:blocks are quite commonly used, for example, to represent a complex note, admonition or sidebar.)

The reason of this limitation is due to the fact that the RTF, WML, DOCX and ODT output formats can —to make it simple— only contain a “flat” sequence of styled paragraphs and tables.


<fo:block margin="0.5em 2em" padding="1em 4em"
  border="1px solid #800000" background="#FFF0F0"
  <fo:block space-before="0.5em" space-after="0.5em">First paragraph.</fo:block>
  <fo:block space-before="0.5em" space-after="0.5em">Second paragraph.</fo:block>
  <fo:block space-before="0.5em" space-after="0.5em">Third paragraph.</fo:block>

Note that xfc:render-as-table="true" is ignored when a named style (i.e. xfc:user-style) is used to style the fo:block.


When converting to RTF XSL-FO files making use of extension attribute xfc:outline-level, you'll almost certainly want to pass option -rtf.target=MSWord to fo2rtf.

4.5. Special uses of fo:block-container

4.5.1. Using fo:block-container to temporarily switch the page orientation from portrait to landscape

Element fo:block-container with a reference-orientation attribute equal to 90, 270, -90 or -270 may be used to temporarily switch the page orientation from portrait to landscape. This feature is typically used to help MS-Word or OpenOffice/LibreOffice display a wide table or a wide figure.


<fo:block-container reference-orientation="90">

For this feature to work:

  • The fo:block-container must be directly contained in the fo:flow[1]. Outside a fo:flow and a fo:table-cell (see below), fo:block-container is treated like a fo:block.

  • The value of attribute reference-orientation must be 90, 270, -90 or -270. XFC does not make any difference between these four values to implement this feature.

  • The width of current page layout must be smaller than its height. That is, the current page orientation must not be already landscape.

4.5.2. Using fo:block-container to rotate the content of a table cell

Element fo:block-container also is supported inside a fo:table-cell, where it may be used to rotate the content of this table cell. Outside a fo:flow (see above) and a fo:table-cell, fo:block-container is treated like a fo:block.

In order to rotate the content of a table cell, the fo:table-cell must contain a single fo:block-container with a reference-orientation attribute equal to 90, 270, -90 or -270.

Example 1: simplest, most common, case:

  <fo:block-container reference-orientation="90">
    <fo:block>Short Header</fo:block>

In the above case, there is generally no need to specify attribute inline-progression-dimension (or equivalently attribute width) and/or attribute block-progression-dimension (or equivalently attribute height) for the fo:block-container element:

  • Attribute inline-progression-dimension is automatically given by XFC a value equals to the maximum width[2] of the content of the fo:block-container.

  • Attribute block-progression-dimension is automatically given by XFC a value equals to N * 1.2 * FS, when N is the number of blocks, lists or tables contained the fo:block-container and FS is the font size[3] of the fo:block-container.

Example 2: simple case:

  <fo:block-container reference-orientation="-90">
    <fo:block>Short Header</fo:block>
    <fo:block>One more line!</fo:block>

Given the default values assigned by XFC to attributes inline-progression-dimension and block-progression-dimension, the above example should be also rendered correctly.

Example 3: may require specifying attribute block-progression-dimension (or equivalently attribute height):

  <fo:block-container reference-orientation="90"
    <fo:block><fo:external-graphic src="logo96x96.png"/>ACME Corp</fo:block>

Example 4: requires specifying both attribute inline-progression-dimension (or equivalently attribute width) and attribute block-progression-dimension (or equivalently attribute height):

  <fo:block-container reference-orientation="270"
    <fo:block>Quite long header possibly containing 
    several lines of text. (Note that a fo:block-container 
    is not limited to a single fo:block or even to 
[Note]Word processor bugs related to rotating the content of a table cell
  • OpenOffice/LibreOffice only supports the simplest case, like in above example 1.

  • Microsoft Word 2007/2010/2013, .docx format: if the content of fo:block-container contains an image, then the position of this image is incorrect for a reference-orientation attribute equal to 90 or -270. There is no such issue with the RTF and WordprocessingML file formats and with Microsoft Word 2003+Microsoft Office Compatibility Pack, whatever the file format.

4.6. Adding language information to the documents created by XFC

Without this information, the word processor thinks that the document is entirely written in its default language; which may be very annoying when this is not the case (false errors reported by the spell checker).


For attribute language and, optionally, attribute country (or equivalently, xml:lang) to be considered to generate information for use by the word processor, attribute language (or equivalently, xml:lang) must be specified at least on the fo:root element.

Other limitations:

  • Will not work for right-to-left languages (e.g. ar, he).

  • Attribute script is ignored, as well as xml:lang values including script information (e.g. sr-Latn-RS).

  • Use the two-letter ISO 639-1 code of a language if this code exists (e.g. en, fr, de, es), otherwise use the 3-letter ISO 639-2 code (e.g. fil, tzm, sah).

  • Always use the two-letter ISO 3166 code of a country (e.g. GB, BE, AT, AR).


For East Asian language (e.g. zh, ja, ko) detection by MS-Word to work on a Windows computer having a Western locale,

  • you must select "Region and Language Options" from Windows Control Panel and check "Install files for East Asian languages";

  • you may have to use a font having East Asian glyphs (e.g. "MS Gothic") for the text runs containing East Asian characters.

4.7. Adding metadata to the documents created by XFC

Element xfc:document-information may be used to to add metadata[4] to the documents created by XFC[5]. This element is expected to be a child element of standard XSL-FO element fo:declarations.

  Content: [ xfc:meta ]*

  name = non empty string
  content = string


  <xfc:meta name="xfc:creator" content="Fox Mulder" />
  <xfc:meta name="xfc:created" content="1993-09-10" />
  <xfc:meta name="xfc:keywords" 
            content="extraterrestrial life, abduction, supernatural" />
  <xfc:meta name="is_classified" content="true" />

It's also possible to restrict editing in the documents created by XFC using command-line arguments -meta.name=value .

When both element xfc:document-information and the aforementioned command-line argument are specified, it's the command-line argument which is used. In the case of the above xfc:document-information example, -meta.is_classified=false may be used to replace the is_classified custom metadata.

The attributes of element xfc:meta are:


Required. The name of the metadata. This may be the name of a standard metadata (e.g. xfc:creator) or a custom metadata (e.g. is_classified).


Required. The value of the metadata.

4.7.1. Standard metadata

A standard metadata has a generic name (always starting with "xfc:") which, when supported by the output format, is translated to a “native”, case-sensitive, metadata name. For example, "xfc:creator" is translated to DOCX "dc:creator", WML "Author", RTF "author" and ODT "meta:initial-creator".

Table 5.3. Standard metadata
Generic nameTypeDescription

A categorization of the content of the document.


The status (e.g. "Draft", "Final") of the document.


The date of creation of the document.


The initial author of the document.


An explanation of the content of the document.


An unambiguous reference to the document within a given context (e.g. ISBN, URN).


Comma-separated set of keywords to support searching and indexing.


The code (e.g ISO 639-1) of main language of the document.


The user who performed the last modification.


The date of the last printing.


The date on which the document was changed.

xfc:revisionPositive integer

The revision number (e.g the number of saves).


The topic of the content of the document.


The title of the document.


The version number of the document.


The manager of the author of the document.


The company that employs the author of the document.

xfc:finalBoolean: true or false

If true, the author lets anyone who opens the document know that there aren't going to be any more changes made to it. This also makes the document read-only.

Supported date formats are documented in "W3C Note on Date and Time Formats [W3CDTF]". Examples: 2020, 2020-09, 2020-09-16, 2020-09-16T19:20, 2020-09-16T17:20:30Z, 2020-09-16T19:20:30.45+02:00.

It is of course possible to use the “native” name of a standard metadata rather than its generic name. When both names are specified (e.g. xfc:creator="John Doe" and DOCX dc:creator="Jane Doe"), it is the value specified using the native name which is stored in the generated document (e.g. dc:creator="Jane Doe").

Table 5.4. Standard metadata supported by the DOCX output format
Generic nameNative name (case sensitive)
Table 5.5. Standard metadata supported by the WML output format
Generic nameNative name (case sensitive)
xfc:contentStatusNot a standard metadata.
xfc:languageNot a standard metadata.
xfc:versionVersion (must match regular expression "([0-9]?[0-9].[0-9]{4})|([0-9]?[0-9])")
xfc:final_MarkAsFinal (not supported by MS-Word 2003)
No generic name.AppName, the name of the application that created the document.
Table 5.6. Standard metadata supported by the RTF output format
Generic nameNative name (case sensitive)
xfc:contentStatusNot a standard metadata.
xfc:identifierNot a standard metadata.
xfc:languageNot a standard metadata.
xfc:revisionNot a standard metadata.
xfc:versionNot a standard metadata.
xfc:final_MarkAsFinal (not supported by MS-Word 2003)
No generic name.comment, comments; text is ignored.
No generic name.buptim, the date/time of last backup.
Table 5.7. Standard metadata supported by the ODT output format
Generic nameNative name (case sensitive)
xfc:categoryNot a standard metadata.
xfc:contentStatusNot a standard metadata.
xfc:identifierNot a standard metadata.
xfc:versionNot a standard metadata.
xfc:managerNot a standard metadata.
xfc:companyNot a standard metadata.
xfc:finalEmulated using the read-only restriction. See below.
No generic name.meta:generator, a string that identifies the application or tool that was used to create or last modify the document.
No generic name.meta:printed-by, the name of the last person who printed the document.
No generic name.meta:editing-duration, the total time spent editing the document. Duration format is: "PnYnMnDTnHnMnS".

4.7.2. Custom metadata

A metadata having a non standard native name (e.g. "is_classified") or a standard generic name not supported by the output format (e.g. "xfc:manager" not supported by ODT) is considered to be a custom metadata.

A custom metadata is generally stored as a typed value. Supported types are generally: boolean, number, date and string. So when you want to specify a boolean, make sure to specify true or false and when you want to specify a date, make sure to use one of the formats documented in "W3C Note on Date and Time Formats [W3CDTF]".

4.8. Restricting editing in the documents created by XFC

Element xfc:document-protection may be used to control the type of changes which can be made to the documents created by XFC[6]. This element is expected to be a child element of standard XSL-FO element fo:declarations.

  restrictions = Restrictions
  password = string

Restrictions = [ limited-formatting ]?
  [ read-only|comments-only|tracked-changes-only|fill-forms-only ]?


<xfc:document-protection password="changeit"
 restrictions="tracked-changes-only limited-formatting" />

It's also possible to restrict editing in the documents created by XFC using command-line arguments -protect=restrictions and -unprotectPassword=password .

When both element xfc:document-protection and any of the aforementioned command-line arguments are specified, it's the command-line argument which is used. In the case of the above xfc:document-protection example, -unprotectPassword= may be used to discard the password.

The attributes of element xfc:document-protection are:


Specifies how the generated document is to be restricted in terms of editing and/or formatting.


No changes are permitted; the document is read-only.


No changes are permitted, but comments can be inserted.

ODT output format: comments-only restriction not supported.


No changes are permitted, but data can be entered into forms.

ODT output format: fill-forms-only restriction not supported.


All changes are permitted, but they're automatically tracked.


No direct formatting (e.g. Bold, Italic) and limit formatting to a selection of styles.

RTF, ODT output formats: limited-formatting restriction not supported.


This clear text password lets the user of the word processor remove the restrictions specified by attribute restrictions.

RTF, WML output formats: password not supported. ODT output format: password supported only for restriction tracked-changes-only.

4.9. Special characters

XFC uses a character set encoder — an instance of the java.nio.charset.CharsetEncoder class — to determine if a given character can be represented in the output encoding. Characters that cannot be encoded are then represented using a Unicode control word (RTF output) or an XML character reference (WML, Open XML and OpenDocument output).

4.10. Special support for East Asian fonts


This feature is supported by the ODT, WML and DOCX output formats, but not by the RTF output format.

When using East Asian fonts in a XSL-FO file[7] to render CJK (Chinese Japanese Korean) text, these fonts must be declared to XFC.

This is done using the eastAsiaFontFamilies property. This property is specified using command line option -eastAsiaFontFamilies=map . The value of this property is a font family map having the following syntax:

map -> entry [',' entry]*

entry -> east_asian_family '=' western_family

Note that western_family must be an actual font family (e.g. Arial). Generic font families (e.g. sans-serif) are not supported here.

Example ("MS UI Gothic" is a Japanese font):

<fo:inline font-family="MS UI Gothic">ねこ ‎romaji neko</fo:inline>

Let's suppose the font family map used for the XSL-FO file containing the above example is:

MS UI Gothic=Times New Roman,Meiryo=Calibri

The above font family map has two effects on XFC:

  1. Font families "MS UI Gothic" and "Meiryo" are declared as being East Asian fonts and will be used to render the CJK text segments. In the above example, "ねこ" is rendered using the "MS UI Gothic" font.

  2. When a text run contains a mix of CJK text and Western text, the "Times New Roman" and "Calibri" fonts will be used to render the Western text segments. In the above example, "romaji neko" is rendered using the "Times New Roman" font, even if the fo:inline containing this segment requests "MS UI Gothic".

4.11. Multiple page layouts

XFC supports all conditional-page-master-reference element combinations that can be accommodated by a single RTF section. This means the following page sequence layouts are supported:

  • Single-sided layout.

  • Header page + single-sided layout.

  • Double-sided layout.

  • Header page + double-sided layout.

This applies to all output formats. Also, note that a single RTF section can handle different headers/footers on left/right/first pages, but does not allow page geometry changes, except for switching left and right margins on facing pages. This restriction does not apply to OpenDocument output.

Note: By default RTF, WML and Open XML output documents are given a double-sided page layout regardless of the input document properties. This results in all sections having separate headers/footers for odd and even pages, even though the content of both headers/footers may be identical. It may also result in blank pages being inserted in the document in order for every section to start on an odd page.

4.12. Adding a watermark to the generated document

Adding a watermark to the generated document is done the way which is supported by all the other XSL-FO processors, that is, by setting the background-image property of fo:region-body. Example:

<fo:simple-page-master master-name="center"
                       margin-bottom="1.5cm" margin-left="1.5cm"
                       margin-right="1.5cm" margin-top="1.5cm"
                       page-height="29.7cm" page-width="21cm">
  <fo:region-body border-style="solid" border-width="1pt"
                  margin-bottom="0.5cm" margin-top="0.5cm" padding="7.5pt"
  <fo:region-before display-align="before" extent="0.5cm" />
  <fo:region-after display-align="after" extent="0.5cm" />

Note that only the background-image, background-position-horizontal and background-position-vertical properties (and the corresponding shorthand properties) are supported. Other background image properties such as background-repeat are ignored. Moreover the only supported values for background-position-horizontal are: left, 0%, center, 50%, right, 100% and the supported values for background-position-vertical are: top, 0%, center, 50%, bottom, 100%.

4.13. Expressions

Use of expressions for property values specification is supported, subject to the following restrictions:

  • The proportional-column-width function may not be part of an arithmetic expression, i.e. it must be used as a single primary expression.

  • The system-color, system-font and merge-property-values are not supported.

[1] The fo:block-container may also be contained in a fo:block itself directly contained in the fo:flow.

[2] That is, with no word wrap.

[3] This font is generally inherited from the ancestors of the fo:block-container element.

[4] Data stored in a document about the document, e.g. the usual author, title, date, etc, but also custom metadata.

[5] This is the XFC equivalent of MS-Word "FileInfoProperties, Advanced Properties".

[6] This is the XFC equivalent of MS-Word "FileInfoProtect Document, Restrict Editing".

[7] Either directly in the XSL-FO file or indirectly through the use of named styles.