Part 3 Numbered Blocks

Ravi Rajani

asciidoctor-html automatically adds a number of the form $chapnum.$blocknum to the block contexts example, image, and table. Each of these has a unique counter. You have already seen numbered example blocks used to typeset Part 2. There, you may have noticed that the list of figures Figure 2.1 is also numbered.

An ordered list with the figlist style shares a counter with the image counter.

The block contexts stem and listing get numbered only when the numbered option is set. They each have a unique counter.

Reference Table

For each numbered block, automatic reference text gets generated. The details are in Table 3.1.

Table 3.1Numbered block contexts, counters and reference text
Context	Numbered	Counter	Reference Text
example	automatic	thm	E.g., “Example 3.1” (default) Depends on block style if set (see Example Blocks)
image	automatic	fig	E.g., “Figure 3.1”
table	automatic	tbl	E.g., “Table 3.1”
olist	when style is `figlist`	fig	E.g., “Figure 3.2”
stem	with `numbered` option	eqn	E.g., “(3.1)”
listing	with `numbered` option	ltg	E.g., “Listing 3.1”

Example Blocks

Example blocks play the role of amsthm LaTeX environments.

Theorems and other mathematical blocks

You can set a custom name and reference text on an example block by setting the block’s style to the desired text (in lowercase). In Definition 3.1 we used [definition].

Definition 3.1UMP test[2, Definition 6.1]

A test $T_\ast$ of size $\alpha$ is a uniformly most powerful (UMP) test if and only if $\beta_{T_\ast}(P)\geq\beta_T(P)$ for all $P\in\mathcal{P}_1$ and $T$ of level $\alpha$.

You can add a title suffix with normal font weight by setting the title-suffix attribute. This is perfect for including citations.

The styles theorem, proposition, lemma, and corollary on example blocks get a blue colour, and the algorithm style gets an orange colour as in Algorithm 2.8.

Lemma 3.2[2, Lemma 6.3]

Suppose that the distribution of $X$ is in a parametric family $\mathcal{P}$ indexed by a real-valued $\theta$ and that $\mathcal{P}$ has monotone likelihood ratio in $Y(X)$. If $\psi$ is a nondecreasing function of $Y$, then $g(\theta) = E\left[\psi(Y)\right]$ is a nondecreasing function of $\theta$.

You can typeset a proof using an open block with the proof style.

Proof

See [2, p.398].

You can make any open block collapsible with the collapsible option. This may be useful for hiding solutions to exercises for instance.

Example Listings

You may find it useful for your listings to share the same counter as examples. To achieve this, nest a listing inside an example block with style listing, and put the listing title on the example as we have done in Listing 3.3.

Listing 3.3Hello World program

def say_hi():
  """Says hello to the world""" ①
  print("Hello World!")

Always include a docstring.

Unnumbered Option

If you wish to have a block styled like one of the numbered blocks, but without a number, use the unnumbered option.

To create a list of figures that omits generated numbers on subcaptions as well as the overall caption, put the figlist style on an unordered list rather than an ordered list.

Below, we have used the unnumbered option on an example block with the algorithm style.

General descent method[1, Algorithm 9.1]

•

given a starting point $x\in\dom f$.
•
repeat
1. 1.
  
  Determine a descent direction $\Delta x$.
2. 2.
  
  Line search. Choose a step size $t > 0$.
3. 3.
  
  Update. $x\gets x + t\Delta x$.
•

until stopping criterion is satisfied.

Above, we added the unmarked option to the top-level list. Use this option if you want to hide the markers in an unordered list.

References

[1]

Boyd, S. and Vandenberghe, L. (2004) Convex Optimization. Cambridge: Cambridge University Press.
[2]

Shao, J. (2007) Mathematical Statistics. 2nd ed. New York, NY: Springer.