Keeping connected blocks together

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.

<p>The following code example shows how JavaScript 
can be used in a link to print the current page:</p>
<codeblock>
&lt;a href="#" onclick="window.print()"&gt; 
 Print this page 
&lt;/a&gt;
</codeblock>

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:

<p>The following code example shows how JavaScript 
can be used in a link to print the current page:
<codeblock>
&lt;a href="#" onclick="window.print()"&gt; 
 Print this page 
&lt;/a&gt;
</codeblock></p>

<lq>
 <p>There was movement at the station...</p>
 <p>That the colt from Old Regret...</p>
</lq>

<p>Banjo Paterson started the work with:
 <lq>There was movement at the station</lq>
</p>

<p>Examples of content structures include:
 <simpletable>
 ...
 </simpletable>
</p>

<p>Client variables are set as in the example:
 <codeblock>Dim cli as String
  cli=43
 </codeblock>
</p>

<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.