7.6.7.1 Assigning properties to list formats for HTML list styles

For HTML-based output, DITA2Go uses HTML list styles by default; see §30.11.2 Converting list formats to HTML list styles. If you are using CSS, in a formats configuration file you can assign any or all of three list-style properties to a paragraph format that begins a list:

[FormatName]
list style = type image position 

where: 

type

can be one of the following:

 

disc (a filled-in circle; standard bullet)

circle

square

decimal

decimal-leading-zero

upper-alpha (upper-latin)

lower-alpha (lower-latin)

upper-roman

lower-roman

lower-greek

armenian

georgian

none (no number, letter, or symbol)

image

is a URL, such as graphic.gif

position

can be one of the following:

 

outside (default)

inside (within the same indent as the text)

For example:

[Numbered1First]
based = Numbered
list style = decimal
[Bulleted]
list style = circle mybullet.gif

If you specify values for both type and image, but the browser cannot locate the image, the type value is displayed instead. It is a good idea always to include a value for the type property, even if you really want image.

If you omit a list style property, you get the browser defaults for the list type (ol or ul). If you set list style=none, any list keywords you assigned to the format in [HTMLParaStyles] are disabled; see §30.11.2.1 Specifying HTML list styles (deprecated). Use list style=none for continuation paragraphs that should be included in the same <li> element.

Padding and margins

To achieve some degree of cross-browser indentation consistency, you can adjust padding and margins for list elements, by redefining the following predefined formats:

[OrderedListElement]
margin left = 18pt
padding left = 12pt
[UnorderedListElement]
margin left = 18pt
padding left = 12pt

These formats are for the <body> element, not the Body format. They affect all the elements of their CSS selectors regardless of class, thus providing a kind of baseline rule. This rule overrides the built-in CSS rule in a browser.

Indentation

To specify indentation for list formats:

[FormatName]
list level = N

The value N is an integer from 0 to however deep you nest lists. When list level=0, the number or symbol that marks the list item is not indented except for a small amount to keep it within the page margin, and the text of the list item is indented the amount specified for margin left in [OrderedListElement] or in [UnorderedListElement]. For each successive value of list level, the list item is indented a similar (cumulative) amount relative to the page margin.

For example:

[Numbered2]
based = Numbered1
list style = lower-alpha
list level = 2

Indentation using CSS is not just a matter of specifying distance from the left margin. It is more like Petroushka dolls: one element fits inside another. If you do not use lists, you can overlook that, because all the block elements are in the same “box”: the <body> element. With lists, you have an ordered-list <ol> or unordered-list <ul> box inside the <body> box, with list-item <li> boxes inside that; all the list content is in the <li> boxes. This means that for list content, all margins are relative to Numbered or Bulleted in the current list, so most of them will have margin left = 0 to align with the numbered or bulleted text (not the number or bullet).

We find that Bulleted formats need margin left = 0 at all levels; Numbered formats need margin left = 2pt at all levels. The 2pt is needed to make the number align with the item above it; bullets are closer to the text, and do not need the extra indent.

For a detailed explanation of CSS list properties, see Chapter 12 of the O'Reilly book “CSS: The Definitive Guide”, 3rd Edition, by Eric Meyer. For cautionary statements about the pitfalls of using list styles for HTML output, see §30.11 Converting list formats to HTML (deprecated).

Previous Topic:  7.6.7 Configuring list formats

Next Topic:  7.6.7.2 Assigning properties to list formats for DITA2Go list styles

Parent Topic:  7.6.7 Configuring list formats

Sibling Topics:

7.6.7.2 Assigning properties to list formats for DITA2Go list styles

7.6.7.3 Having the best of both worlds