[symfony#2651] Moving and expanding on note

weaverryan · weaverryan · commit 29c5f84534fb · 2013-06-30T13:44:31.000-05:00
diff --git a/components/dom_crawler.rst b/components/dom_crawler.rst
@@ -10,10 +10,7 @@ The DomCrawler Component
 .. note::
 
     While possible, the DomCrawler component is not designed for manipulation
-    of the DOM or re-dumping HTML/XML. However the DomCrawler will attempt to
-    automatically fix your HTML to match the official specification. Take note
-    about this behaviour as you could be working with a different DOM after it
-    has been parsed with the DomCrawler.
+    of the DOM or re-dumping HTML/XML.
 
 Installation
 ------------
@@ -55,6 +52,16 @@ Specialized :class:`Symfony\\Component\\DomCrawler\\Link` and
 :class:`Symfony\\Component\\DomCrawler\\Form` classes are useful for
 interacting with html links and forms as you traverse through the HTML tree.
 
+.. note::
+
+    The DomCrawler will attempt to automatically fix your HTML to match the
+    official specification. For example, if you nest a ``<p>`` tag inside
+    another ``<p>`` tag, it will be moved to be a sibling of the parent tag.
+    This is expected and is part of the HTML5 spec. But if you're getting
+    unexpected behavior, this could be a cause. And while the ``DomCrawler``
+    isn't meant to dump content, you can see the "fixed" version if your HTML
+    by :ref:`dumping it<component-dom-crawler-dumping>`.
+
 Node Filtering
 ~~~~~~~~~~~~~~
 
@@ -187,6 +194,8 @@ and :phpclass:`DOMNode` objects:
     $crawler->addNode($node);
     $crawler->add($document);
 
+.. component-dom-crawler-dumping:
+
 .. sidebar:: Manipulating and Dumping a ``Crawler``
 
     These methods on the ``Crawler`` are intended to initially populate your
