Lists within paragraphs

Whether a list is contained within a paragraph, or whether it occurs as a separate parallel block after the paragraph, depends on the context. If the paragraph contains a lead-in to the list, then that list is bound to the paragraph, and the list should be a child of the paragraph.

DITA permits you to use a structure for a list of items where the list exists within a paragraph element. You can alternatively create a list structure without a surrounding paragraph. In other words, both of the following are valid.

<p>
 <ul>
  <li>Point 1</li>
  <li>Point 2</li>
 </ul>
</p>

and

<ul>
 <li>Point 1</li>
 <li>Point 2</li>
</ul>

The best choice is the structure that is semantically correct, and that will depend upon the context.

In most cases, the second option (a standalone list structure) is correct semantically, because most lists do not logically fall within a paragraph, and cannot be logically be surrounded by a paragraph. Further, if the paragraph has no content other than the list, then it is probably superfluous.

However, in some cases, the list may logically belong within the same idea as the surrounding paragraph. In such cases, there will be text within the paragraph element before and/or after the list element. For example:

<p>The four turbo-charged models are: 
 <sl>
  <sli>XRW</sli>
  <sli>XRW Super</sli>
  <sli>Lumberer XT</sli>
  <sli>Liberty GT.</sli>
 </sl> 
 </p>

A more complex example is:

<p>The four turbo-charged models 
 <sl>
 <sli>XRW</sli>
  <sli>XRW Super</sli>
  <sli>Lumberer XT</sli>
  <sli>Liberty GT</sli>
 </sl> 
 are the most expensive of their makes.</p>

When considering content re-use, the paragraph in the preceding example could be re-used, and would always include the list, as it is part of the same idea. The list could also be re-used without the paragraph text. But the paragraph text could not be re-used without the list.

Some people treat lead-in sentences, or stem sentences, in the same way. If a stem sentence ends with a colon, then it should only be re-used with the list it supports. Therefore, the stem sentence and the list should be in the same semantic element.

Diagram showing the difference between parallel stem sentence and list and list embedded in stem sentence paragraph — Figure 1. Comparison between parallel and embedded lists

Note:

There are some conflicting requirements when the content needs to be localised. Including a block nested inside a paragraph, such as in the preceding examples, will create some problems for translators. This creates a dilemma which may eventually be solved by advancements in software tools. If you are writing for translation, avoid including text after a nested block inside another block element. The guidelines contained in the Best Practice for Leveraging Legacy Translation Memory when Migrating to DITA (Joseph & Raya, 2007) whitepaper produced by the OASIS DITA Translation Subcommittee should be followed when writing for translation.