4. Implementation specificities

4.1. Page references

4.1.1. RTF/WML/OOXML

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' [start]?

start -> ';start=' Positive_Integer

Description:

  • An empty xfc:label-format attribute 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 start= optional parameter specifies the starting number of the first item in an ordered list. Its default value is 1.

Notice that multi-level numbering (e.g. 1.2.3.) is not supported.

Example:

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format"
         xmlns:xfc="http://www.xmlmind.com/foconverter/xsl/extensions">
  ...  
  <fo:list-block font-family="monospace" margin-left="10pt"
                 provisional-distance-between-starts="1cm"
                 provisional-label-separation="5pt"
                 space-before="2pt"
                 xfc:label-format="&#x2022;%{lower-roman;start=10}">
    <fo:list-item>
      <fo:list-item-label end-indent="label-end()">
        <fo:block>&#x2022;x</fo:block>
      </fo:list-item-label>

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

    <fo:list-item>
      <fo:list-item-label end-indent="label-end()">
        <fo:block>&#x2022;xi</fo:block>
      </fo:list-item-label>

      <fo:list-item-body start-indent="body-start()">
        <fo:block>This is the second item 
        of the list.</fo:block>
      </fo:list-item-body>
    </fo:list-item>
  </fo:list-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"
                xmlns:fo="http://www.w3.org/1999/XSL/Format"
                xmlns:xfc="http://www.xmlmind.com/foconverter/xsl/extensions"
                version='1.0'>
<fo:leader leader-pattern="dots"
           leader-pattern-width="3pt"
           leader-alignment="reference-area"
           xfc:tab-position="-30pt"
           xfc:tab-align="right"
           keep-with-next.within-line="always"/>

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.

Example:

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

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

Element fo:block-container is supported only inside a fo:table-cell, where it may be used to rotate the content of this table cell. Outside 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:table-cell>
  <fo:block-container reference-orientation="90">
    <fo:block>Short Header</fo:block>
  </fo:block-container>
</fo:table-cell>

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[1] 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[2] of the fo:block-container.

Example 2: simple case:

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

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:table-cell>
  <fo:block-container reference-orientation="90"
                      block-progression-dimension="96px">
    <fo:block><fo:external-graphic src="logo96x96.png"/>ACME Corp</fo:block>
  </fo:block-container>
</fo:table-cell>

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

<fo:table-cell>
  <fo:block-container reference-orientation="270"
                      inline-progression-dimension="15em" 
                      block-progression-dimension="5cm">
    <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 
    fo:blocks.)</fo:block>
  </fo:block-container>
</fo:table-cell>

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

Important

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

Note

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. 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.8. Special support for East Asian fonts

Important

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[3] 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.9. 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.10. 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"
                  background-image="url(images/draft.png)"
                  background-position="center"/>
  <fo:region-before display-align="before" extent="0.5cm" />
  <fo:region-after display-align="after" extent="0.5cm" />
</fo:simple-page-master>

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.11. 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] That is, with no word wrap.

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

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