Updated git submodules

[docs.git] / docs / documentation.rst

diff --git a/docs/documentation.rst b/docs/documentation.rst
index 0e0e9a009284dd613eb016a10ad66c1bb9fca9a6..471d6c88f14393b3e6d9f2ba7c72448a0d9e1e06 100644 (file)
--- a/docs/documentation.rst
+++ b/docs/documentation.rst
@@ -233,10 +233,20 @@ the chapter should use::
     ^, for subsubsections
     ", for paragraphs
 
-
 Troubleshooting
 ---------------
 
+Nested formatting doesn't work
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As stated in the reStructuredText_ guide, inline markup for bold,
+italic, and fixed-width can't be nested. Further, it can't be mixed
+with hyperlinks, so you can't have bold text link somewhere.
+
+This is tracked in a `Docutils FAQ question
+<http://docutils.sourceforge.net/FAQ.html#is-nested-inline-markup-possible>`,
+but there is no clear current plan to fix this.
+
 Make sure you've cloned submodules
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -342,14 +352,12 @@ itself and it contains a ``pom.xml`` file saying how to build it, a
 Troubleshooting
 ---------------
 
-See `AsciiDoc Tips
-<https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips>`_
-on the wiki for more information.
+See `AsciiDoc Tips`_ on the wiki for more information.
 
 Common AsciiDoc mistakes
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
-See also [[Documentation/Tools/AsciiDoc Tips|AsciiDoc Tips and Tricks]]
+See also `AsciiDoc Tips`_.
 
 * Lists that get formatted incorrectly because of no blank line above
   the list.
@@ -401,7 +409,7 @@ Image formats change from something like::
 
 To something like::
 
-   .. image:: images/dlux-default.png
+   .. figure:: images/dlux-default.png
 
 A helpful regular expression for automating the replacements is
 something like::
@@ -419,3 +427,4 @@ something like::
 .. _Documentation Group: https://wiki.opendaylight.org/view/Documentation/
 .. _RelEng/Builder: https://wiki.opendaylight.org/view/RelEng/Builder
 .. _Pandoc: http://pandoc.org/
+.. _AsciiDoc Tips: https://wiki.opendaylight.org/view/Documentation/Tools/AsciiDoc_Tips