16  Lists

Lists are a special kind of block elements. We have three types of lists:

1. Simple lists: bullet lists and ordered lists.
2. Numbered examples lists: these are lists whose items are scattered throughout the papers, but numbered continuously.
3. custom labelled lists: like simple lists but with arbitrary (or no) labels instead of bullets or numbers.

Custom labelled lists are sometimes used to typset things that aren’t really lists: arguments with labelled premises, statements within footnotes.

Custom-labelled lists must also be used if you need to crossreference specific items within a list.

16.1 Simple lists

Simple lists are either bullet lists or ordered lists. Here are examples of each:

* an item
  * a sub-item
  * another sub-item
* an item

1. item
2. item
  a. sub item
  b. sub item
1. another item

Result:

• an item
  • a sub-item
  • another sub-item
• an item

1. item
2. item

1. sub item
2. sub item

1. another item

Separating items by a blank line makes no difference: they will be gathered in a single list.

16.1.0.1 Multiple paragraphs or blocks in a list item

List items can consist of several blocks. The blocks should be indented to be aligned with the first non-space character of the list item:

* This list item contains three blocks.

  The second block is a paragraph---a two-space indentation aligns it wth "This" above.

  > The third block is a blockquote.

* This is the second list item

Result:

• This list item contains three blocks.

  The second block is a paragraph—a two-space indentation aligns it wth “This” above.

  The third block is a blockquote.

• This is the second list item

16.1.0.2 Choosing bullets and types

• With bullet lists, you have no control on the type of bullet used—this is decided by your template.
• With ordered lists, you normally have control over numbering type (1, I, A, i, a) and starting number (3, III, C, iii, c), though your template may override this. You don’t control punctuation, i.e whether the number is followed by a point, single parenthesis or double parenthesis—that is up to your template.

If you need finer control of bullets or numbers, consider custom-labelled lists.

16.1.0.3 First-line indentation after lists

Requires: first-line indent filter.

If you use first-line indents rather than vertical space to separate paragraph, you may want to control whether the paragraph below a list is indented or not. There is no mechanical rule for this: it depends on whether the material following the list should be considered as one paragraph with the material before and the list, or whether we should instead consider that the list ends a paragraph.

In most cases, the list does not end a paragraph and the material below forms a unity with the material before. The paragraph below should then not be indented. That is the default setting of the first-line indent filter, so you do not need to do anything.

If the list does end a paragraph, you can ensure the next paragraph starts with an indentation by adding \indent at its beginning.

16.1.1 What to do if a list has non-standard labels?

Problem: a text has a list with regularly numbered items (1, 2, 3, or a, b, c, …) but uses * or ' labels in some cases.

There are two solutions to this:

• If it’s not too important to single out some items with * or ', then you can re-number the author’s list, using a simple numbered list instead.
• If it is important to preserve the author’s labels, e.g. if it helps comprehension to see item ’2**’ as a revision of item ‘2’, then use custom labelled lists.

16.2 Numbered examples lists

Some papers have examples (or other items) that are scattered throughout the paper but numbered continuously. For example:

Sentence (1) below illustrates the Liar paradox:

1. Sentence (1) is false.

Not all self-referential sentences are paradoxical, however:

2. This sentence contains several words.
3. Sentence (3) is written in English.

You enter those as follows using (@) or (@identifier):

Sentence @liar below illustrates the Liar paradox: 

(@liar) Sentence (@liar) is false.

Not all self-referential sentences are paradoxical, however:

(@) This sentence contains several words.

(@three) Sentence @three contains several words.

(@) is enough to create a numbered example item. You add an identifier as in (@item3) if you need to refer to it later. To refer to it, simply use @identifier, as above, which you can wrap between parentheses if desired.

Warning. References to numbered examples do not generate hyperlinks and cannot be placed within links.

Problem. If a paragraph starts by a reference to a number example that you want to wrap between parentheses, markdown will wrongly think that it’s a new numbered example:

The sentence below illustrates the Liar paradox: 

(@liar) Sentence (@liar) is false.

(@liar) cannot be true, because...

Solution. “Escape” (i.e., put a backslash in front of) the first parenthesis

The sentence below illustrates the Liar paradox: 

(@liar) Sentence (@liar) is false.

\(@liar) cannot be true, because...

16.3 Custom labelled lists

Requires: the labelled-lists filter.

A simple illustration of the custom label syntax:

* [Premise 1]{} This is the first claim.
* [Premise 2]{} This is the second claim.
* [Conclusion]{} This is the conclusion.

This generates the following list (process this file with the filter to see the result):

• Premise 1 This is the first claim.
• Premise 2 This is the second claim.
• Conclusion This is the conclusion.

In general, the filter will turn a bullet list into a custom label list provided that every item starts with a Span element.

• A Span element is inline text (i.e., not block like a paragraph) that optinally has some attributes. The default syntax is [inline text]{attributes}. Inline text will be used as label, placed within round bracket.
• There is no need to specify attributes on the Span. But curly brackets must be present: [label] won’t work, [label]{} will.
• The label can include formatting. [**T1**]{} will generate a label with strong emphasis (bold by default).
• Span elements can also be entered using HTML syntax: <span>inline text </span>. See [Pandoc manual] (https://pandoc.org/MANUAL.html#divs-and-spans) for details.

If an article has many custom labelled lists with empty labels (see Arguments), you may set the delimiters to be empty rather than parentheses by default. See the labelled-lists.lua filter manual.

16.3.1 Commonly used custom labels

See also the section on symbols.

I want	I type
A*, A**, …	A*, A**, …
A′, A″, A‴, A⁗	A′, A″, A‴, A⁗
A1, A2, …	A^1^, A^2^, …
A1, A2, …	A~1~, A~2~, …

16.3.2 Cross-referencing custom-label items

Custom labels can be given internal identifiers. The syntax is [label]{#identifier}. In the list below, A1ref, A2ref and Cref identify the item:

* [**A1**]{#A1ref} This is the first claim.
* [A2]{#A2ref} This is the second claim.
* [*C*]{#Cref} This is the conclusion.

Note that # is not part of the identifier. Identifiers should start with a letter and contain only letters, digits, colons :, dots ., dashes - and underscores _.

Labels with identifiers can be crossreferenced using Pandoc’s citations or internal links.

16.3.3 Cross-referencing with citations

The basic syntax is:

• Reference in text: @A1ref. Outputs the label with its formatting: A1.
• Normal reference: [@A1ref]. Outputs the label with its formatting, in parentheses: (A1). A prefix and suffix can be specified too: [remember @A1ref and the like] will output (remember A1 and the like).
• The suppressed author style, [-@A1ref], will be processed as normal reference

You can crossrefer to several custom labels at a time: [@A1ref; @A2ref]. But mixing references to a custom label with bibliographic ones in a same citation won’t work: if Smith2003 is a key in your bibliography [@A1ref; Smith2003] will only output “((A1ref?); Smith, 2003)”.

Because this syntax overlaps with Pandoc’s citation syntax, conflicts should be avoided:

• Avoid giving the same identifier (e.g. Smith2005) to a custom label item and a bibliographic entry. If that happens, the citation will be interpreted as crossreference to the custom label item. To make sure you you may use identifiers starting with item:: item:A1ref, item:A2ref, or some other prefix.
• The filter should preferably be run before citeproc, and before other filters that use citations (like pandoc-crossref). It may work properly even if it is run after, though citeproc will issue “citations not found” warnings. To ensure that the filter is run before, just place it before in the command line or in your YAML options file’s filters field.

Alternatively, the citation syntax for crossreferencing custom label items can be deactivated. See [Customization] below.

16.3.4 Cross-referencing with internal links

In Pandoc markdown internal links are created with the syntax [link text](#target_identifier). (Note the rounded brackets instead of curly ones for Span element identifiers.) You can use internal links to cross-refer to custom label items that have a identifier. If your link has no text, the label with its formatting will be printed out; otherwise whichever text you give for the link. For instance, given the custom labelled list above, the following:

The claim [](#A1ref) together with [the next claim](#A2ref) 
entail ([](#Cref)).

will output:

The claim A1 together with the next claim entail (C).

where the links point to the corresponding items in the list.

16.3.5 Custom labelled lists within a numbered example list

Requires: labelled-lists.lua, statement.lua.

In some cases we wanted to put a custom labelled list within a numbered example list. This is particularly difficult when we don’t want any content in the numbered example item other than the embedded list itself.

Solution: place the embedded list within a statement. Note that the embedded content must be indented exactly twice (4 spaces). This works:

(@example-Batu) 

    ::: statement

    * []{delimiter=none} Every head of a horse is a head 
     of an animal.
    * [∴]{} Batu is a head of an animal.
  
    ::::

You should reduce the right margin for the LaTeX output. (LaTeX experts: the statement is placed in a minipage whose with is that of the text minus the default list label width; this is typically too large for an embedded list.)

(@Allskunksaremammals) 

    ::: statement

    * []{} All skunks are mammals. `\addtolength{\rightskip}{1em} % fix needed`{=latex}

    * [∴]{} All who fear all who respect all skunks fear all who respect all mammals.
    :::

16.4 Arguments

Requires: the labelled-lists.lua filter.

We format arguments as custom labelled lists. To indicate the the conclusion, the last label is ∴, i.e. the symbol ∴.

* [1]{} No man is wise.
* [2]{} Socrates is a man.
* [C]{} Socrates is not wise.

Here 1, 2, C are custom labels. We can also write an argument without labels, but we should then add the option deliminter=none to the first item in order to avoid empty parentheses:

* []{delimiter=none} No man is wise.
* []{} Socrates is a man.
* [there4;]{} Socrates is not wise.

&there4 is the standard ‘therefore’ sign (three dots).

The delimiter=none option can be set in the document metadata. It will then apply to all custom labelled lists in the document unless specified otherwise in the lists themselves. See custom labelled lists.

As explained in custom labelled lists, crossreference links to premises can be done by giving them identifiers and using the citation syntax:

* [1]{#prem1} No man is wise.
* [2]{#prem2} Socrates is a man.
* [C]{#conc} Socrates is not wise.

Premises @prem1 and @prem2 entail @conc.

Requires: the statement.lua filter.

Arguments can be placed within statements, especially if they have a name.

::: statement
__The ontological argument__

* []{delimiter=none}
* []{}
:::

To place an argument within a numbered example list, see custom-labelled lists within numbered example lists.