Describes actual use of include directive with use of targets.

Signed-off-by: Michael Vincerra <michael.vincerra@intel.com>

source/clear-linux/reference/collaboration/documentation/cross.rst

@@ -15,16 +15,18 @@ Internal cross-references
 An internal cross-reference is a reference to a location within the |CLOSIA|
 documentation. Use explicit markup labels and the ``:ref:`` role to create
 cross references to headings, figures, and code examples as needed. Every
-file must have a label before the title identical to the file's name in order
-to be able to add cross-references without having to open the file.
+file must have a label before the title, which is identical to the file's 
+name, in order to be be cross-referenced within the entire documentation.
 
-The labels' naming conventions are:
+Labels' naming conventions:
+
+* Ensure the label is unique throughout the documentation
 
 * Use only full words.
 
 * Use \- to link multiple words.
 
-* Use only as many words as necessary to ensure the label is unique.
+* Use only as many words as necessary.
 
 These are some examples of proper labels:
 
@@ -119,6 +121,33 @@ Use this template to add a hyperlink with a separated definition:
 
 .. code-block:: rst
 
-   The state of `Oregon`_ offers a wide range of recreational activities.
+The state of `Oregon`_ offers a wide range of recreational activities.
 
-   .. _Oregon: http://traveloregon.com/
+The include directive 
+*********************
+
+Clear Linux documentation also uses the ``.. include::`` 
+directive to include a portion of another reST file. 
+
+Use the ``.. include::` directive to show a select portion of :ref:`rest`, as shown below. 
+
+.. code-block:: 
+
+   .. include:: rest.rst
+      :start-after: incl-restructured-text-overview-end:
+      :end-before: incl-restructured-text-overview-end:
+
+In this example, note that you must: 
+
+* Create a `target` that appears directly above a header (ease of inclusion)
+* Ensure that the target is unique, as explained in :ref:`target <internal-cross>`
+* Use a `:` at the end of the value of `start-after` and `end-before`. 
+
+Following is the actual inclusion of the rest.rst file: 
+
+.. include:: rest.rst
+   :start-after: incl-restructured-text-overview:
+   :end-before: incl-restructured-text-overview-end:
+
+
+.. _Oregon: http://traveloregon.com/

source/clear-linux/reference/collaboration/documentation/rest.rst

@@ -3,6 +3,11 @@
 RestructuredText guide
 ######################
 
+.. incl-restructured-text-overview: 
+
+Overview
+********
+
 The |CLOSIA| uses Sphinx and RestructuredText as authoring tools for its
 documentation. This section contains the preferred methods for using the
 :abbr:`ReST (RestructuredText)` markup on your documents. Please refer to the
@@ -27,6 +32,8 @@ templates, or the code-block directive, for multi-lined templates.
 Every use case is explained, examples provided and, lastly,
 templates supplied.
 
+.. incl-restructured-text-overview-end: 
+
 .. toctree::
    :maxdepth: 3