|Syntax and mark-up / Paragraphs|
When a block element is logically subordinate to the one that precedes it, the subordinate block should be nested within the first block. In other words, subordinate blocks should be child nodes, not siblings, of the leading block.
When one block of text leads into a second block of text, the blocks become interdependent. A risk exists that if only one of the paragraphs is re-used, it will read out of context.
For example, you may introduce a code sample with a stem sentence; the stem sentence is in a paragraph (p) block, and the code sample is in a logically subordinate codeblock block.
If the stem sentence paragraph is re-used outside the current topic, the text won't make sense unless the following codeblock travels with it. Alternatively, a conref push may inject another block between the first (p) block and the second (codeblock) block, affecting the meaning of the stem sentence.
As the two blocks are logically connected, the codeblock should be nested within the paragraph. The resultant code is:
|paragraphs within long quotes||
<lq> <p>There was movement at the station...</p> <p>That the colt from Old Regret...</p> </lq>
|long quotes within paragraphs||
<p>Banjo Paterson started the work with: <lq>There was movement at the station</lq> </p>
|tables within paragraphs||
<p>Examples of content structures include: <simpletable> ... </simpletable> </p>
|code blocks within paragraphs||
<p>Client variables are set as in the example: <codeblock>Dim cli as String cli=43 </codeblock> </p>
|lists within paragraphs||
<p>There are two XRW variants: <sl> <li>XRW</li><li>XRW Super</li> </sl> </p>
Some content models may not permit nesting in this way, such as where both the blocks are p elements, but as an objective, this nesting approach should be preferred.