Skip to main content

The PreTeXt Guide

Subsection 4.5.6 Lists

Roughly, you can target a list item for a cross-reference, but not the list itself, since it is a container. See Subsection 4.11.4 for precise details about using list content as the target of a cross-reference. Note also, that an entire named list may be the target of a cross-reference, see Section 4.20. Here we concentrate on the text of the cross-reference itself.
First, note that if you cross-reference a list item of an anonymous list, there is a very real possibility that the number will be ambiguous, and there is no option for @text will save you, and never can be. See the middle column of Table 4.5.6.5 for the demonstration. We assiduously try to make it impossible to ever create ambiguous text for cross-references, especially in consideration of print output. Use the feature carefully.

Best Practice 4.5.6.4. Take Care Referencing Anonymous Lists.

Cross-references to list items of anonymous lists can easily be ambiguous and then useless for readers of print. Keep such a cross-reference close to its target, ideally within the same list, and/or perhaps using additional, unambiguous clues about location (which you expect will survive later editing):
  1. See Item 2 of this list.
  2. See Item 1 in the list appearing in Best Practice 4.5.6.4.
The local option, discussed generally above, behaves differently for a cross-reference to a list item of an ordered list that is contained in a named list. As seen in the table just below, the local portion of the number is the part that comes from the list item, without the part that comes from the location of the <list> block.
Table 4.5.6.5. Cross-references to list items, visual text styles
@text Named List Anonymous List With Content
type-local Item B.c Item 2.III Extra B.c
type-global Item 4.11.7.4:B.c Item 2.III Extra 4.11.7.4:B.c
type-hybrid Item 4.11.7.4:B.c Item 2.III Extra 4.11.7.4:B.c
local B.c 2.III Extra B.c
global 4.11.7.4:B.c 2.III Extra 4.11.7.4:B.c
hybrid 4.11.7.4:B.c 2.III Extra 4.11.7.4:B.c
phrase-global Item B.c of List 4.11.7.4 Warning Warning
phrase-hybrid Item B.c of List 4.11.7.4 Warning Warning
title A Test Title Exquisite Fish Warning
custom Extra
The hybrid options employ a different definition of when the distance between a cross-reference and its target is close enough that the number can be shortened, without becoming ambiguous. When an <xref> and its target are part of the same <list>, then the common part of the number derived from the <list> is not needed. To illustrate we need to make a small <list> with cross-references contained within.
List 4.5.6.6. Small test
  1. (type-global) Flowers are not Item 4.5.6.6:6.
  2. (type-hybrid) Fish are not Item 6.
  3. (hybrid) Bacteria are not 6.
  4. (phrase-global) Fungi are not Item 6.
  5. (phrase-hybrid) Trees are not Item 6.
  6. Mammals.