Merge pull request #208 from mvincerx/mv-edit-cross

Mv edit cross

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:
 
@@ -81,7 +83,8 @@ This creates a link to the :ref:`label-of-target` using the text of the
 heading.
 
 This creates a link to the :ref:`target <label-of-target>` using the word
-'target' instead of the heading.
+'target' instead of the heading. We use the term 'target' here similar to 
+the way'anchor' is used in HTML. 
 
 .. note::
 
@@ -92,7 +95,7 @@ This creates a link to the :ref:`target <label-of-target>` using the word
 External References
 *******************
 
-External references or hyperlinks can be added easily with ReST. Only
+External references or hyperlinks can be added easily with reST. Only
 hyperlinks with a separated target definition are allowed.
 
 Do not use explicit hyperlinks consisting entire URLs. For example, links
@@ -119,6 +122,32 @@ 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 a file.  
+
+.. code-block:: console
+
+   .. include:: rest.rst
+      :start-after: incl-restructured-text-overview:
+      :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`. 
+
+Use of the ``.. inclusion::`` for :ref:`rest` is shown below. 
+
+.. 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,12 +3,19 @@
 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
 `Sphinx documentation`_ for the complete list of available markup and use
 as much markup as possible.
 
+.. _Sphinx documentation: http://www.sphinx-doc.org/en/stable/markup/index.html
+
 Remember: **Changing incorrect markup is easier than adding markup from
 scratch.**
 
@@ -27,6 +34,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
 
@@ -38,6 +47,3 @@ templates supplied.
    code
    contents
 
-
-.. _Sphinx documentation:
-   http://sphinx-doc.org/contents.html