The PreTeXt Guide

An ordered list has items with markers that are naturally ordered (usually numerically or alphabetically). We borrow from HTML, and use the <ol> tag to construct an ordered list. Some commentators suggest an ordered list should only be used when the order of the content is important. So the steps in a recipe would belong in an ordered list, but the shopping list when you go to the store need not be an ordered list.

An unordered list has items with markers that have no inherent order and so are usually symbols like circles, disks, squares, etc. We borrow from HTML, and use the <ul> tag to construct an unordered list.

A description list has items that have short pieces of text as their markers. We borrow from HTML, and use the <dl> tag to construct a description list.

Ordered lists are used as part of <objectives> ([provisional cross-reference: topic-objectives]) and exercises (Section 4.13). Any of the three lists may occur inside the <list> element (below, Section 4.20). Otherwise, a list must occur within a paragraph, <p>. This means that to place a list within a list item of another list, the list item must contain a paragraph.

Do nothing, and your ordered and unordered lists will get sensible default markers. They are consistent in the following sense. If your list has two items, and each of the two items contains a list, then these two lists will use the same type of marker.

For a description list, you author each marker as part of each list item, as discussed below in the discussion of list items.

If you want to change how an ordered list is marked, then you use the @marker attribute on the <ol>, whose value is a format code. This string contains one of five codes (a single character), which may be surrounded by other characters, excluding the five codes. For example marker="(A)" will produce uppercase letters wrapped in parentheses: (A), (B), (C), …. The extra formatting works well in a conversion to LaTeX, but is not possible technically in a conversion to HTML, so it should be considered decorative, and not relied upon for meaning. The formatting does not carry through to the numbers of list items in cross-references.

If you want to change how an unordered list is marked, then you use the @marker attribute on the <ul>, whose value is a format code. This string contains one of three codes in the table below. Then every item of the list will have that symbol as its marker.

Default marker types are assigned to each level of nested lists in the order shown in the table, and cycle back to the top of the table if necessary, though zero-based Arabic numerals will be skipped for ordered lists.

Start with the defaults, and experiment as needed. See the examples below for some extreme (and unwise) customizations of markers.

For a description list, possible markers are more varied than what you can express within an attribute. So the list item must have a <title> element (see below). This should be very short text, and may contain inline mathematics. It is often rendered in bold, so be aware that some markup may get lost. Perhaps for obvious reasons, do not include footnotes, cross-references, or display mathematics. The <dl> element has a @width attribute, with possible values narrow, medium, and wide. The default is narrow. This is a hint about how much text you have in these markers, and in certain presentations may make better use of horizontal space on a page.

So now you have a list all organized as a container. What do you put in it? List items, using the <li> tag, again borrowed from HTML, and independent of the type of list.

A list item could be really simple, maybe just one or two words. Then you can use, and conceptualize, an <li> element as not much different from a <p> element, and the rules about content are not much different. Even several full sentences, with some intermediate displayed mathematics, is fine.

But once you want two paragraphs in a list item, then you need to structure the contents of the item. So a list item might have five paragraphs in it, requiring five <p> elements. Notice that this is how you nest lists. Make a list item, include a paragraph, then put the subsidiary list into the paragraph. Indeed, this is the only way to nest lists. A consequence of this is that the only way to have an unstructured list item is if it is a terminal item, like the leaf of a tree.

Other items may be interspersed among the paragraphs of a list item, such as a chunk of verbatim text delimited by a <pre> tag. But anything with a number, such as a <figure> or <remark> is banned, in part because the consequences for numbering and organization become too complicated. Imagine a remark, and a paragraph of the remark has a list. Fine so far. But if the items of that list can again contain remarks, the possibilities become endless. You should be able to include non-textual items, like an <image>, and work is underway to improve this. You can use a <sidebyside> in a structured list item, which can in turn hold an <image>, <tabular>, or similar. But you cannot place items in such a <sidebyside> that are numbered, so a <figure> or <table> is not possible. A general rule is no numbered components in a list item. Computational components, such as <sage> are also banned from list items due to the difficulty of converting them into electronic computational notebooks with a relatively flat structure.

A list item of a description list must have a <title> element, to provide the text of the marker. Now that the list item has some structure, the remainder must also be structured, typically with some paragraphs, as discussed above. In other words, the earlier option of employing an <li> element just like a <p> element is not available in a description list. Further, given the complexity of presenting a description list, it can only be a top-level list. It can contain the two other types nested within its list items.

For ordered and unordered lists, you may optionally include a <title> when you have structured the <li>. This will be rendered as a heading of sorts for the list item, though the only distinction might be a change to an italic or oblique font. As an example, this might be a good way to author a Frequently Asked Questions (FAQ).

Note that a list item holding only an <m> element will get special treatment. See Subsection 4.9.15.

Note that a list is a container, so it cannot be the target of a cross-reference, and so the three types of lists cannot have an @xml:id attribute. But you may well be able to point at some other structure (e.g., a <remark>) with a paragraph containing a list of interest. If this seems overly restrictive, read below about named lists.

By contrast, a list item, <li>, is not a container, and does contain content. Further, a list item of an ordered list has a marker that is natural text for a cross-reference. So in this situation, the list item can have an @xml:id attribute. But note that the “number” of a list item of an ordered list, which is nested inside a list item of an unordered list, is not defined, so a cross-reference by number can fail.

The “number” of a list item, mostly for the purposes of a cross-reference, is the concatenation of all of the individual markers in the containing lists, outermost first. For example, from the example lists below, the list item with content “Walleye” has number 2.I. These are indivisible, there is no way to get a component, excepting leading subsequences obtained by using an @xml:id on a containing list item. Note that the format codes never become part of the number.

You can control the number of columns used to layout an ordered or unordered list (but not a description list). On the <ol> or <ul> use a @cols attribute with values 2 through 6. (1 is the default.)

We do not yet (2018-03-28) have enough technical confidence to allow an author to specify a row-major order versus a column-major order for the layout. So understand that this is can be an implementation choice for a particular conversion, and can vary across implementations. If this is critical to conveying meaning, and not an aesthetic preference, then maybe consider using a <table> or <tabular> (Section 4.18).

We use the tags for lists in a few situations outside of anonymous lists inside paragraphs and named lists. These include the items within an objectives, subparts of an exercise, and within panels of a side-by-side. See those topics to learn about subtle differences in use.

To illustrate this section, we offer three too-elaborate examples. Take these as compact examples of what is possible, and not best practice in your writing. We also use these to illustrate cross-references to list items, see Subsection 4.5.6.

A named list, only to test cross-references.