Part 2 Ordered Lists

asciidoctor-html provides some additional features for ordered lists, including automatic generation of reference text.

Basic List

The default ordered list looks like Example 2.1.

Example 2.1Basic list with 4 levels

1.

A level 1 list item, marked with an arabic numeral followed by a dot.
2.
Another level 1 list item.
1. (a)
  A level 2 list item, marked with a bracketed lowercase letter.
  1. i.
    
    A level 3 list item, marked with a lowercase roman numeral followed by a dot.
    
    (A)
    
    A level 4 list item, marked with a bracketed uppercase letter.
    
    (B)
    
    Another level 4 list item.
  2. ii.
    
    Another level 3 list item.
2. (b)
  
  Another level 2 list item.

If you put an anchor at the start of a list item, then you will be able to refer to that list item elsewhere in the text. This is already possible with Asciidoctor but requires explicit specification of reference text. By contrast, asciidoctor-html will automatically substitute appropriate default reference text when it is unspecified. For example, putting the anchor [[li-level2]] at the start of the first level 2 list item in Example 2.1 will generate the reference link 2(a) with <<li-level2>>. In a similar way, you can generate the link 2(a)i(B) to the second level 4 list item.

Continue Attribute

If you want to define a list that is a continuation of a list defined elsewhere (usually appearing before it), you should use the continue attribute, set to the ID of the other list.

Example 2.2Continuing a list

1.

A level 1 list item of a list with ID lst-first.
2.
Another level 1 list item.
1. (a)
  A level 2 list item.
  1. i.
    
    A level 3 list item.
  2. ii.
    
    Another level 3 list item.
2. (b)
  
  Another level 2 list item.

The list below is a continuation of the above list, achieved with [continue=lst-first].

3.

This is the next level 1 item of the list with ID lst-first.
4.

Another level 1 item.

Lists in AsciiDoc also accept a start attribute, with which you can start the list at any desired number. There is almost never a good reason to do this. In most cases you will want to use the continue attribute instead. It is always best to leave the numbering to the system rather than trying to maintain it yourself.

Markers Attribute

You can change the type of marker used at any list level with the markers attribute. This attribute accepts a format string of the form $left-delimiter$numeral$right-delimiter where $numeral must be a single character from the string 1iIaA. These characters represent arabic numerals, lower or uppercase roman numerals, and lower or uppercase letters. The left and right delimiters may be arbitrary characters (and may be left blank).

For example, setting [markers=#1] on the first level, [markers=(I)] on the second level, and [markers=i)] on the third, gives Example 2.3.

Example 2.3List with custom markers

#1

A level 1 list item, marked with a number preceded by a hash.
#2
Another level 1 list item.
1. (I)
  A level 2 list item, marked with an uppercase roman numeral enclosed in brackets.
  1. i)
    
    A level 3 list item, marked with a lowercase roman numeral followed by a bracket.
  2. ii)
    
    Another level 3 list item.
2. (II)
  
  Another level 2 list item.

Again, reference text gets resolved properly. E.g., #2(II).

Pseudocode Style

You can make all levels of a list share the same counter (and marker) by declaring the pseudocode style on the top level. The markers will all be aligned as in Example 2.4.

Example 2.4Pseudocode list

1

A level 1 item of a pseudocode list.
2
Another level 1 list item.
1. 3
  A level 2 item will be indented.
  1. 4
    
    And a level 3 item will be indented more.
2. 5
  
  Another level 2 list item.

The pseudocode list below is a continuation of the above, achieved with the continue attribute.

6
Continuing the pseudocode list.
1. 7
  
  Yet another level 2 list item.

Bibiliography Style

Setting a list’s style to bibliography will render the markers as arabic numerals in square brackets. When clicking on a generated reference link to a bibliography item, such as [2], the citation will appear in a popover. If you specify reference text in a bibliography citation, it will appear next to the generated number as in [2, p.10].

Example 2.5Bibliography list

[1]

Cormen, T.H. et al. (2022) Introduction to Algorithms. Cambridge, MA: The Mit Press.
[2]

Roughgarden, T. (2022) Algorithms Illuminated: Omnibus Edition. Cambridge: CUP.

Since citations appear in popovers, you may wish not to show the bibliography on the page. You can hide any block by giving it the hidden role.

Real Example

In this section, we reproduce an exercise from [1, p.46]. It demonstrates all the list features introduced thus far in the context of a “real” example.

Algorithm 2.6BubbleSort$(A,n)$

This procedure sorts array $A[1:n]$.

1
for $i=1$ to $n-1$
1. 2
  for $j=n$ downto $i+1$
  1. 3
    
    if $A[j] < A[j-1]$
    
    4
    
    swap $A[j]$ with $A[j-1]$

In the following exercise, the correctness of Algorithm 2.6 is proved.

Exercise 2.7Correctness of BubbleSort

Bubblesort is a popular, but inefficient, sorting algorithm. It works by repeatedly swapping adjacent elements that are out of order.

(a)

Let $A'$ denote the array $A$ after BubbleSort$(A,n)$ is executed. To prove that BubbleSort is correct, you need to prove that it terminates and that

\[A'[1] \leq A'[2] \leq \dots \leq A'[n]\]

(2.1)

In order to show that BubbleSort actually sorts, what else do you need to prove?

The next two parts prove inequality (2.1).

(b)

State precisely a loop invariant for the for loop in lines 2-4, and prove that this loop invariant holds. Your proof should use the structure of the loop-invariant proof presented in [1, ch.2].
(c)

Using the termination condition of the loop invariant proved in part (b), state a loop invariant for the for loop in lines 1-4 that allows you to prove inequality (2.1). Your proof should use the structure of the loop-invariant proof presented in [1, ch.2].
(d)

What is the worst-case running time of BubbleSort? How does it compare with the running time of InsertionSort?

Use the roomy option if you want some extra space between list items.

List of Figures

One often wants to display two images as subfigures of one figure with automatic label numbers. You can do this easily by declaring the figlist style on an ordered list, and putting an inline image in each list item. The list title will get rendered as an overall caption, and each image’s title attribute will get rendered as a subcaption.

(a)Posterior distribution of first Poisson parameter $\theta_1$.
(b)Posterior distribution of second Poisson parameter $\theta_2$ after change point.

Figure 2.1Marginal posteriors of Poisson parameters in change point detection of UK coal mining disasters. Computed by Gibbs algorithm with $B = G = 1000$.

Again, reference text is properly resolved. Just look at (b).

« Part 1 Part 3 »