3. Style reference

3. Style reference
	Chapter 6. XSL-FO extension for generating named styles

	About namespaces in the following sections
	In the following sections, all the element names have a `http://www.xmlmind.com/foconverter/xsl/extensions` namespace and all attribute names have no namespace.

3.1. The `styles` element

The stylesheet passed as a parameter to XFC (-styles command-line option) is specified in an XML file conforming to the styles.xsd schema. The recommended extension for these XML files are ".xfc".

<styles>
Content: [ text-style | paragraph-style | numbering ]*
</styles>

Example:

<styles xmlns="http://www.xmlmind.com/foconverter/xsl/extensions"
        xmlns:xfc="http://www.xmlmind.com/foconverter/xsl/extensions">
  ...
</styles>

3.2. The `text-style` element

<text-style
  name = non empty token
  abstract = boolean : false
  base-style = name of another text-style
  Some standard XSL-FO text attributes
  Some standard XSL-FO background attributes
/>

Specifies a text style (also known as a “character style”) which can be applied to a fo:inline element by the means of the xfc:user-style extension attribute. Ignored if applied to any element other than fo:inline.

name: Required. Unique name of this text style.
abstract: If true, this text style is not intended to be directly applied to any fo:inline element. Instead, it is intended to be inherited by other text-style elements by the means of their base-style attributes.
base-style: Specifies another text-style element. This causes this text-style element to inherit all the XSL-FO attributes found in the base text-style element

The standard XSL-FO attributes allowed in a text-style element are:

Note that specifying any other XSL-FO attribute (e.g. text-transform) is reported as a fatal error.

Examples:

<text-style name="Basic" abstract="true" font="10pt sans-serif" />

<text-style name="Red" base-style="Basic" color="red" />

3.3. The `paragraph-style` element

<paragraph-style
  name = non empty token
  abstract = boolean : false
  base-style = name of another paragraph-style
  next-style = name of another paragraph-style
  numbering = name of a numbering
  numbering-level = integer between 1 and 10 inclusive
  outline-level = non empty string
  Some standard XSL-FO text attributes
  Some standard XSL-FO background attributes
  Some standard XSL-FO paragraph attributes
/>

Specifies a paragraph style which can be applied to a fo:block element by the means of the xfc:user-style extension attribute. Ignored if applied to any element other than fo:block.

name: Required. Unique name of this paragraph style.
abstract: If true, this paragraph style is not intended to be directly applied to any fo:block element. Instead, it is intended to be inherited by other paragraph-style elements by the means of their base-style attributes.
base-style: Specifies another paragraph-style element. This causes this paragraph-style element to inherit all the XSL-FO attributes and also the next-style, numbering, numbering-level and outline-level attributes found in the base paragraph-style element
next-style: Specifies the name of a paragraph-style element, this one or another one. A paragraph having next-style style will be automatically created by the word processor if the user presses key Enter inside a paragraph having this style.
numbering: Specifies that paragraphs having this style are to be automatically numbered by the word processor, the numbering scheme to be used being specified by the value of this attribute. See Section 3.4, “The numbering element”.
numbering-level: Required if numbering attribute has also been specified, but not required if this paragraph style is abstract. Specifies the list level of paragraphs having this style. See Section 3.4, “The numbering element”.
outline-level: Same extension attribute, except for the empty namespace, as Section 4.4.1, “The xfc:outline-level extension attribute”.

The standard XSL-FO attributes allowed in a paragraph-style element are:

Note that specifying any other XSL-FO attribute (e.g. padding-after, margin-left, keep-together.within-column, space-before.mininum) is reported as a fatal error.

Examples:

<paragraph-style name="Caption" base-style="Centered"
                 keep-with-previous="always"
                 font-style="oblique" font-size="smaller"
                 start-indent="4em" end-indent="4em" />

<paragraph-style name="Bullet 3" numbering="Bullets" numbering-level="3"
                 start-indent="2*24pt" />

3.4. The `numbering` element

<numbering
  name = non empty token
  show-all-levels = boolean : false
>
Content: [ level ]{1,10}
</numbering>

<level
  format = non empty string
  text-align = non empty string : start
  provisional-distance-between-starts = non empty string : 24pt
  provisional-label-separation = non empty string : 6pt
  Some standard XSL-FO text attributes
  Some standard XSL-FO background attributes
/>

Element numbering specifies a numbering scheme (also known as a “list style”) for use by a paragraph style. For this, the name of the numbering scheme must be referenced in the numbering attribute of element paragraph-style.

Attributes of element numbering:

name

Required. Unique name of this numbering scheme.

show-all-levels

If true, prepend to the number of a list item the numbers of all its “parent” list items. Ignored if this numbering scheme specifies bullets and not numbers.

For example, if list item "d." is “nested” inside list item "3.", itself “nested” inside list item "IV.", then the label found at the beginning of list item "d." will be in fact "IV.3.d.".

A numbering element may contain up to 10 level elements. A level element specifies a number or bullet format for a list item “nested” at the corresponding level. That is, top-level (“non-nested”) list items have a numbering level equal to 1 and their number/bullet formats are specified by the first level child of element numbering; list items “nested” inside top-level list items have a numbering level equal to 2 and their number/bullet formats are specified by the second level child of element numbering; and so on up to 10 “nesting” levels.

Attributes of element level:

format: Required. Number or bullet format specified using the syntax documented in Section 4.2.1, “The xfc:label-format extension attribute”.
text-align: Standard XSL-FO attribute text-align. Specifies the horizontal alignment of the number or bullet within the space specified using provisional-distance-between-starts.
provisional-distance-between-starts: Standard XSL-FO attribute provisional-distance-between-starts. If specified as a positive length, this gives a hanging indent to the list item.
provisional-label-separation: Standard XSL-FO attribute provisional-label-separation. Useful when provisional-distance-between-starts is 0 because it allows to separate the number or bullet from the body of the list item.

The other standard XSL-FO attributes allowed in a level element are:

Note that specifying any other XSL-FO attribute is reported as a fatal error.

Examples:

<numbering name="Bullets">
  <level format="&#x2022;" 
         provisional-label-separation="0" />
  <level format="-" 
         provisional-label-separation="0" />
  <level format="&#x25CF;"
         text-align="right" 
         provisional-distance-between-starts="48pt"
         provisional-label-separation="0" />
</numbering>

<numbering name="Numbers" show-all-levels="true">
  <level format="%{decimal}."
         font-family="sans-serif" font-weight="bold" font-size="10pt" 
         color="#800000" />
  <level format="%{lower-alpha}."
         font-family="sans-serif" font-weight="bold" font-size="10pt" 
         color="#008000" />
  <level format="-%{lower-roman}-"
         text-align="center" 
         font-family="sans-serif" font-weight="bold" font-size="10pt" 
         color="#000080" />
</numbering>

3.5. The `xfc:user-style` extension attribute

This extension attribute specifies which named style to use for a fo:inline or fo:block element. Example:

<fo:inline xfc:user-style="Warning">always keep your seat belt 
fastened</fo:inline>

When an ".xfc" file has been passed as a parameter to XFC, for example by the means of the -styles command-line option :

If set on a fo:inline element, attribute xfc:user-style must reference the name of an existing xfc:text-style element, otherwise a fatal error is reported.
If set on a fo:block element, attribute xfc:user-style must reference the name of an existing xfc:paragraph-style element, otherwise a fatal error is reported.
It's a fatal error to specify xfc:user-style on any XSL-FO element other than fo:inline and fo:block.

Attribute xfc:user-style is ignored, whatever its value, if no ".xfc" file has been passed as a parameter to XFC.

Attribute xfc:user-style="" (empty string value) is ignored in all cases.

3.6. The `xfc:restart-numbering` extension attribute

Using this boolean extension attribute is required to reuse the same numbered paragraph styles to create several logical lists.

Attribute xfc:restart-numbering is best explained using a simple example. The numbering element is:

<numbering name="Item Numbers" show-all-levels="true">
  <level format="%{decimal}."
         provisional-distance-between-starts="20pt"
         provisional-label-separation="0"
         font-family="serif" font-size="10pt" color="#004080" />
  <level format="%{upper-alpha}."
         provisional-distance-between-starts="30pt"
         provisional-label-separation="0"
         font-family="serif" font-size="10pt" color="#004080" />
</numbering>

The numbered paragraph styles are:

<paragraph-style name="Numbered Item 1" base-style="Numbered Item"
                 numbering-level="1" start-indent="2em" />

<paragraph-style name="Numbered Item 2" base-style="Numbered Item"
                 numbering-level="2" start-indent="2em + 20pt" />

What follows is meant to specify two “logical lists” separated by a paragraph.

<fo:block xfc:user-style="Numbered Item 1">First item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">First sub-item
  of first item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">Second sub-item
  of first item.</fo:block>
<fo:block xfc:user-style="Numbered Item 1">Second item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">First sub-item
  of second item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">Second sub-item
  of second item.</fo:block>

<fo:block>A paragraph.</fo:block>

<fo:block xfc:user-style="Numbered Item 1">First item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">First sub-item
  of first item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">Second sub-item
  of first item.</fo:block>
<fo:block xfc:user-style="Numbered Item 1">Second item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">First sub-item
  of second item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">Second sub-item
  of second item.</fo:block>

However the above XSL-FO snippet is converted to:

  1.
    1.A
    1.B
  2.
    2.A
    2.B
A paragraph.
  3.
    3.A.
    3.B.
  4.
    4.A.
    4.B

by XFC.

After adding attribute xfc:restart-numbering="true" to the first item of each logical list:

<fo:block xfc:user-style="Numbered Item 1"
  xfc:restart-numbering="true>First item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">First sub-item
  of first item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">Second sub-item
  of first item.</fo:block>
<fo:block xfc:user-style="Numbered Item 1">Second item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">First sub-item
  of second item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">Second sub-item
  of second item.</fo:block>

<fo:block>A paragraph.</fo:block>

<fo:block xfc:user-style="Numbered Item 1"
  xfc:restart-numbering="true>First item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">First sub-item
  of first item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">Second sub-item
  of first item.</fo:block>
<fo:block xfc:user-style="Numbered Item 1">Second item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">First sub-item
  of second item.</fo:block>
  <fo:block xfc:user-style="Numbered Item 2">Second sub-item
  of second item.</fo:block>

This gives the expected result:

  1.
    1.A
    1.B
  2.
    2.A
    2.B
A paragraph.
  1.
    1.A
    1.B
  2.
    2.A
    2.B


	It is not required to add attribute `xfc:restart-numbering="true"` to the first item of the very first “logical list” of the XSL-FO file, however doing so is simpler and is harmless.


2. How it works		4. A comprehensive example