Minor doc improvements

Author: amykyta3

docs/cross-references.rst

@@ -1,29 +1,15 @@
 Cross-references
 ================
 
-.. role:: code-rst(code)
-   :language: reStructuredText
-
-.. rst:directive:: .. rdl:relative-to:: path
-
-    It can be cumbersome to always specify the full register hierarchy in your docs.
-    This directive lets you temporarily set a more localized scope to a hierarchy
-    to make following references in the same document easier to manage.
-
-    .. code-block:: rst
-
-        Annoying! :rdl:ref:`very.long.path.to.my_block.my_register`
-
-        .. rdl:relative-to:: very.long.path.to
-
-        Much better! :rdl:ref:`my_block.my_register`
-
-
-    Cross-references will first search relative to the path specified, then
-    fall back to searching the absolute path.
+PeakRDL cross-references allow you to insert links into your documentation that
+point to specific register model nodes. These are very useful in programming
+guides, or more long-form prose in documentation.
 
+Cross-references can link to inline register reference content, or dynamic HTML content.
 
 
+.. role:: code-rst(code)
+   :language: reStructuredText
 
 
 .. rst:role:: rdl:ref
@@ -46,7 +32,27 @@ Cross-references
     Same as the :rst:role:`rdl:ref` role, except this will prefer linking to
     PeakRDL-HTML reference, regardless of the :confval:`peakrdl_default_link_to` setting.
 
+
 .. rst:role:: rdl:doc-ref
 
     Same as the :rst:role:`rdl:ref` role, except this will prefer linking to
     an inline :rst:dir:`docnode`, regardless of the :confval:`peakrdl_default_link_to` setting.
+
+
+.. rst:directive:: .. rdl:relative-to:: path
+
+    It can be cumbersome to always specify the full register hierarchy in your docs.
+    This directive lets you temporarily set a more localized scope to a hierarchy
+    to make following references in the same document easier to manage.
+
+    .. code-block:: rst
+
+        Annoying! :rdl:ref:`very.long.path.to.my_block.my_register`
+
+        .. rdl:relative-to:: very.long.path.to
+
+        Much better! :rdl:ref:`my_block.my_register`
+
+
+    Cross-references will first search relative to the path specified, then
+    fall back to searching the absolute path.

docs/index.rst

@@ -53,7 +53,7 @@ Start cross-referencing!
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Cross-reference your documentation to automatically-generated PeakRDL-HTML pages.
 
-This really useful when writing software guides or other reference pages. For example:
+This is really useful when writing software guides or other reference pages. For example:
 
 .. code-block:: rst
 

docs/inline-documentation.rst

@@ -1,6 +1,13 @@
 Inline Documentation
 ====================
 
+Register reference can be inserted inline into any reStructuredText document
+using the directives described in this page.
+Inline register reference is useful if you do not want to rely on the dynamic
+HTML-generated register reference, and instead want to have all the register
+reference be included within the Sphinx-doc project. This is especially useful
+if the desired output is PDF.
+
 .. rst:directive:: .. rdl:docnode:: path
 
     Inserts the full documentation for the register model node referenced by ``path``.
@@ -15,7 +22,9 @@ Inline Documentation
 
     .. rst:directive:option:: no-wrap-section:
 
-        If set, suppresses creation of a section heading.
+        If set, suppresses creation of a section heading. This is useful if you
+        want to provide your own section heading fot this docnode.
+
         If this option is not specified, behavior is determined by the
         :confval:`peakrdl_doc_wrap_section` setting.