diff --git a/xdoc/xdocs/reference/xdocs.xml b/xdoc/xdocs/reference/xdocs.xml
index ee9b8a3f..2eb4baac 100644
--- a/xdoc/xdocs/reference/xdocs.xml
+++ b/xdoc/xdocs/reference/xdocs.xml
@@ -197,6 +197,23 @@
         </p>
       </subsection>
 
+      <subsection name="Dont put &lt;source&gt; inside paragraphs">
+        <p>Wrong:</p>
+        <source><![CDATA[<p>
+  The following command executes the program:
+  <source>java -jar CoolApp.jar</source>
+</p>]]></source>
+        <p>Correct:</p>
+        <source><![CDATA[<p>
+  The following command executes the program:
+</p>
+<source>java -jar CoolApp.jar</source>]]></source>
+        <p>
+          However, you may put <code>&lt;source&gt;</code> elements inside
+          list items or table rows.
+        </p>
+      </subsection>
+
     </section>
 
     <navbar prev="navfile.html" home="../index.html" next="i18n.html"/>