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>
Examples of content structures where nesting of subordinate blocks is common include:
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.

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.