itemizedlist options

In addition to controlling the spacing as described in the section “List spacing”, you have some control over the bullet character, also known as the mark.

Different bullet symbol

The stylesheets provide opportunities for customizing the character sometimes called a bullet used to mark items in an itemizedlist. The methods are different for HTML and FO outputs.

If you want to change the mark on any given itemizedlist, then set its mark attribute to one of the three names that HTML supports. The stylesheets also accept the value bullet as equivalent to disc, and box for square. You can change an individual listitem's mark by setting its override attribute to one of the names. Unfortunately, HTML does not support the use of arbitrary characters in UL lists.

HTML bullets

In HTML output, the ul element provides the bullet character. When ul lists are nested inside one another, most browsers will change the bullet symbol to indicate nesting. The usual sequence is disc (solid circle), circle (open circle), and square (■ solid square), in that order.

The DocBook HTML stylesheets implement the same sequence for nested lists using the type attribute. The following example shows the output for nested lists:

<div class="itemizedlist">
  <ul type="disc">
    <li>
      <p>Level 1</p>
      <div class="itemizedlist">
        <ul type="circle">
          <li>
            <p>Level 2</p>
            <div class="itemizedlist">
              <ul type="square">
                <li>
                  <p>Level 3</p>
                </li>
              </ul>
            </div>
          </li>
        </ul>
      </div>
    </li>
  </ul>
</div>

Note

The HTML attributes described here that control list styles are output only if the stylesheet parameter css.decoration is set to 1 (the default). If it is set to zero, then none of these attributes are output. You may want to do that to control the list styles using a separate CSS stylesheet.

You can change the order of this nesting sequence by customizing a template in common/common.xsl named next.itemsymbol, which looks like this:

<xsl:template name="next.itemsymbol">
  <xsl:param name="itemsymbol" select="'default'"/>
  <xsl:choose>
    <!-- Change this list if you want to change the order of symbols -->
    <xsl:when test="$itemsymbol = 'disc'">circle</xsl:when>
    <xsl:when test="$itemsymbol = 'circle'">square</xsl:when>
    <xsl:otherwise>disc</xsl:otherwise>
  </xsl:choose>
</xsl:template>

This template selects the next item symbol name based on the current name in the parameter itemsymbol. The list is circular, so more deeply nested lists repeat the sequence.

You can also manually choose the symbol name for a given list by adding a mark attribute to the list:

<itemizedlist mark="square">

That will generate a <ul type="square"> in the HTML output. This will use square bullets for that list, and it will reset the nesting sequence to start on square at that point.

You can also override the bullet style for individual list items by adding an override attribute:

<listitem override="circle">

This will override only that list item, and not change the nesting sequence. The HTML output looks like this:

<li style="list-style-type: circle">

You may prefer to use CSS to style your lists, rather than put attributes in the HTML. You may want to set the stylesheet parameter css.decoration to zero to prevent the hard coded attributes in the HTML. You can use CSS styles as follows:

div.itemizedlist ul {
    /* first level */
    list-style-type: square;
}
div.itemizedlist ul div.itemizedlist ul {
    /* second level */
    list-style-type: circle;
}
div.itemizedlist ul div.itemizedlist ul div.itemizedlist ul {
    /* third level */
    list-style-type: disc;
}

What about selecting your own bullet character? HTML does not provide a means to do that; it provides only the three named types. But CSS can, if the browsers support newer features of CSS. The following example uses a small graphics image as a list bullet:

ul {
    list-style-image: url(bullet.gif);
    list-style-type: disc;
}

The list-style-type property is included for those browsers that don't support the list-style-image property. For a more extensive discussion of CSS and lists, see CSS Design: Taming Lists.

FO bullets

For print output, the bullet character is the solid black disc, and it is used at all list levels by default. That is because other bullet characters rely on the font having the right glyph, and the XSL-FO processor being able to find the font with that glyph. So the default behavior in FO output is to just indent nested lists and use the same bullet character for all of them.

But you can customize the bullet behavior to use any Unicode character, if your font setup supports it. There are two templates that need to be customized: next.itemsymbol and itemizedlist.label.markup.

The next.itemsymbol template determines which symbol name is used at each nested list level. It is described in the section “HTML bullets”. For print output, you can use whatever symbol names you like, as long as they are supported in the second template.

The itemizedlist.label.markup template is what renders each symbol name into FO output. It maps the name to a Unicode character, and if necessary can wrap it in fo:inline to select a font-family or other property. You can copy the original template from fo/lists.xsl to your customization layer and modify it as needed. The following shows what it looks like in version 1.68 of the stylesheets:

<xsl:template name="itemizedlist.label.markup">
  <xsl:param name="itemsymbol" select="'disc'"/>
  <xsl:choose>
    <xsl:when test="$itemsymbol='disc'">&#x2022;</xsl:when>
    <xsl:when test="$itemsymbol='bullet'">&#x2022;</xsl:when>
    <xsl:when test="$itemsymbol='endash'">&#x2013;</xsl:when>
    <xsl:when test="$itemsymbol='emdash'">&#x2014;</xsl:when>
    <!-- Some of these may work in your XSL-FO processor and fonts -->
    <!--
    <xsl:when test="$itemsymbol='square'">&#x25A0;</xsl:when>
    <xsl:when test="$itemsymbol='box'">&#x25A0;</xsl:when>
    <xsl:when test="$itemsymbol='smallblacksquare'">&#x25AA;</xsl:when>
    <xsl:when test="$itemsymbol='circle'">&#x25CB;</xsl:when>
    <xsl:when test="$itemsymbol='opencircle'">&#x25CB;</xsl:when>
    <xsl:when test="$itemsymbol='whitesquare'">&#x25A1;</xsl:when>
    <xsl:when test="$itemsymbol='smallwhitesquare'">&#x25AB;</xsl:when>
    <xsl:when test="$itemsymbol='round'">&#x25CF;</xsl:when>
    <xsl:when test="$itemsymbol='blackcircle'">&#x25CF;</xsl:when>
    <xsl:when test="$itemsymbol='whitebullet'">&#x25E6;</xsl:when>
    <xsl:when test="$itemsymbol='triangle'">&#x2023;</xsl:when>
    <xsl:when test="$itemsymbol='point'">&#x203A;</xsl:when>
    <xsl:when test="$itemsymbol='hand'"><fo:inline
                         font-family="Wingdings 2">A</fo:inline></xsl:when>
    -->
    <xsl:otherwise>&#x2022;</xsl:otherwise>
  </xsl:choose>
</xsl:template>

You will notice that most of the choices are commented out by default, because not all systems support all the characters. After you determine which characters work on your system, you can move them out of the comment. Then you can add the symbol name to the next.itemsymbol template to use it automatically.

The last example within the comment shows a symbol that requires switching fonts. The character at letter position A in that font is a pointing hand symbol.

Once you have enabled a symbol name in itemizedlist.label.markup, you can also use it to set a list style manually using attributes in your document source. The mark attribute is used on an itemizedlist element to change the bullet for all the items in that list. The override attribute is used on a listitem element to change the bullet for one item. Examples of both attributes are given in the section “HTML bullets”.