From 3f30f6283a0dc0d1b692c8fd2518f67b3bfb1c24 Mon Sep 17 00:00:00 2001
From: Mark Hoeber <hoeber@edx.org>
Date: Thu, 16 Oct 2014 13:35:13 -0400
Subject: [PATCH] Mark Edits

---
 .../annotation.rst                            |  0
 .../conditional_module.rst                    |  0
 .../components/discussion-components.rst      |  4 +-
 .../full_screen_image.rst                     |  0
 .../google_hangout.rst                        |  0
 .../olx/source/components/html-components.rst | 55 ++++++++-----------
 .../lti_component.rst                         |  0
 .../open_response_assessment.rst              |  0
 .../periodic_table.rst                        |  0
 .../{problem-xml => components}/poll.rst      |  0
 .../source/components/video-components.rst    |  4 +-
 .../word_cloud.rst                            |  0
 .../zooming_image.rst                         |  0
 docs/en_us/olx/source/directory-structure.rst | 54 ++++++++----------
 docs/en_us/olx/source/index.rst               |  1 +
 docs/en_us/olx/source/links.rst               |  4 +-
 .../course-structure-overview.rst             | 11 ++--
 .../organizing-course/course-xml-file.rst     |  8 ++-
 docs/en_us/olx/source/pages/pages.rst         | 12 ++--
 docs/en_us/olx/source/problem-xml/index.rst   | 35 +++++++++---
 .../olx/source/problem-xml/vitalsource.rst    |  2 -
 21 files changed, 103 insertions(+), 87 deletions(-)
 rename docs/en_us/olx/source/{advanced-components => components}/annotation.rst (100%)
 rename docs/en_us/olx/source/{problem-xml => components}/conditional_module.rst (100%)
 rename docs/en_us/olx/source/{problem-xml => components}/full_screen_image.rst (100%)
 rename docs/en_us/olx/source/{problem-xml => components}/google_hangout.rst (100%)
 rename docs/en_us/olx/source/{advanced-components => components}/lti_component.rst (100%)
 rename docs/en_us/olx/source/{advanced-components => components}/open_response_assessment.rst (100%)
 rename docs/en_us/olx/source/{problem-xml => components}/periodic_table.rst (100%)
 rename docs/en_us/olx/source/{problem-xml => components}/poll.rst (100%)
 rename docs/en_us/olx/source/{advanced-components => components}/word_cloud.rst (100%)
 rename docs/en_us/olx/source/{problem-xml => components}/zooming_image.rst (100%)
 delete mode 100644 docs/en_us/olx/source/problem-xml/vitalsource.rst

diff --git a/docs/en_us/olx/source/advanced-components/annotation.rst b/docs/en_us/olx/source/components/annotation.rst
similarity index 100%
rename from docs/en_us/olx/source/advanced-components/annotation.rst
rename to docs/en_us/olx/source/components/annotation.rst
diff --git a/docs/en_us/olx/source/problem-xml/conditional_module.rst b/docs/en_us/olx/source/components/conditional_module.rst
similarity index 100%
rename from docs/en_us/olx/source/problem-xml/conditional_module.rst
rename to docs/en_us/olx/source/components/conditional_module.rst
diff --git a/docs/en_us/olx/source/components/discussion-components.rst b/docs/en_us/olx/source/components/discussion-components.rst
index 183d1b2256..e721ccf79a 100644
--- a/docs/en_us/olx/source/components/discussion-components.rst
+++ b/docs/en_us/olx/source/components/discussion-components.rst
@@ -36,7 +36,9 @@ In-line, you can create, if the vertical XML file contains:
        /> 
   </vertical>
 
-If you prefer to split this up, you can also create: 
+If you prefer to create the discussion in its own file, you can create: 
+
+.. code-block:: xml
 
    <vertical display_name="Lesson_1_Unit_1">
       <discussion 
diff --git a/docs/en_us/olx/source/problem-xml/full_screen_image.rst b/docs/en_us/olx/source/components/full_screen_image.rst
similarity index 100%
rename from docs/en_us/olx/source/problem-xml/full_screen_image.rst
rename to docs/en_us/olx/source/components/full_screen_image.rst
diff --git a/docs/en_us/olx/source/problem-xml/google_hangout.rst b/docs/en_us/olx/source/components/google_hangout.rst
similarity index 100%
rename from docs/en_us/olx/source/problem-xml/google_hangout.rst
rename to docs/en_us/olx/source/components/google_hangout.rst
diff --git a/docs/en_us/olx/source/components/html-components.rst b/docs/en_us/olx/source/components/html-components.rst
index 5680cdd3bd..3a11ca3424 100644
--- a/docs/en_us/olx/source/components/html-components.rst
+++ b/docs/en_us/olx/source/components/html-components.rst
@@ -4,25 +4,32 @@
 HTML Components
 #################################
 
-To add an HTML component to your course, you can either in-line it in
-the parent XML file, or split it up into either 1 or 2 additional
-files. HTML configuration can be broken out into a .xml file in the
-html directory. In addition, HTML content can be broken out into an
-additional .html file in the same directory. Breaking out HTML content
-is especially useful if you are embedding HTML which is not valid XML. 
-
 See:
 
-* `Create the XML File for an HTML Component`_
+* `Create the HTML Component`_
+* `Example of an HTML Component Embedded in a Vertical`_
+* `Example of Separate HTML Files`_
 * `HTML Component XML File Elements`_
 * `html Element Attributes`_
 * `Example HTML Component XML File`_
-* `Create the HTML File for an HTML Component`_
 * `Example HTML Component Content`_
 
-*************************************
-In-line HTML Example
-*************************************
+
+*********************************************
+Create the HTML Component
+*********************************************
+
+To add an HTML component to your course, you can embed the XML for it in the
+parent XML file, or split it up into either 1 or 2 additional files. You can
+break up the HTML configuration into an .xml file in the html directory and an
+additional .html file in the same directory. 
+
+.. caution:: If you are including HTML that is not valid HTML, you must break out HTML content in a separate file.
+
+
+*****************************************************
+Example of an HTML Component Embedded in a Vertical
+*****************************************************
 
 .. code-block:: xml
   
@@ -33,12 +40,14 @@ In-line HTML Example
 
 
 *********************************************
-Fully split HTML file example and explanation
+Example of Separate HTML Files
 *********************************************
 
-You create an XML file in the ``html`` directory for each HTML component in your course.
+You create an XML file in the ``html`` directory for each HTML component in
+your course.
 
-The name of the XML file must match the value of the @url_name attribute of the ``html`` element in the vertical XML file.
+The name of the XML file must match the value of the @url_name attribute of the
+``html`` element in the vertical XML file.
 
 For example, if the vertical XML file contains:
 
@@ -87,22 +96,6 @@ The following example shows an XML file for an HTML component:
   <html filename="Introduction" display_name="Unit Introduction"/>  
 
 
-*********************************************
-Create the HTML File for an HTML Component
-*********************************************
-
-You create an HTML file in the ``html`` directory for each HTML component in your course.
-
-The name of the HTML file must match the value of the @file_name attribute of the ``html`` element in the component's XML file.
-
-For example, if the component's XML file contains:
-
-.. code-block:: xml
-  
-  <html filename="Introduction" display_name="Unit Introduction"/> 
-
-You create the file ``html/Introduction.html`` to define the HTML component content.
-
 *************************************
 Example HTML Component Content
 *************************************
diff --git a/docs/en_us/olx/source/advanced-components/lti_component.rst b/docs/en_us/olx/source/components/lti_component.rst
similarity index 100%
rename from docs/en_us/olx/source/advanced-components/lti_component.rst
rename to docs/en_us/olx/source/components/lti_component.rst
diff --git a/docs/en_us/olx/source/advanced-components/open_response_assessment.rst b/docs/en_us/olx/source/components/open_response_assessment.rst
similarity index 100%
rename from docs/en_us/olx/source/advanced-components/open_response_assessment.rst
rename to docs/en_us/olx/source/components/open_response_assessment.rst
diff --git a/docs/en_us/olx/source/problem-xml/periodic_table.rst b/docs/en_us/olx/source/components/periodic_table.rst
similarity index 100%
rename from docs/en_us/olx/source/problem-xml/periodic_table.rst
rename to docs/en_us/olx/source/components/periodic_table.rst
diff --git a/docs/en_us/olx/source/problem-xml/poll.rst b/docs/en_us/olx/source/components/poll.rst
similarity index 100%
rename from docs/en_us/olx/source/problem-xml/poll.rst
rename to docs/en_us/olx/source/components/poll.rst
diff --git a/docs/en_us/olx/source/components/video-components.rst b/docs/en_us/olx/source/components/video-components.rst
index d6e4c969f5..d21a501c54 100644
--- a/docs/en_us/olx/source/components/video-components.rst
+++ b/docs/en_us/olx/source/components/video-components.rst
@@ -19,7 +19,9 @@ See:
 Create the XML File for a Video Component
 **********************************************
 
-If you wish to place a video in your course, add it to the course XML tree as: 
+To add a video component to your course, add it to the course XML tree as: 
+
+.. code-block:: xml
 
   <video 
     youtube="1.00:o2pLltkrhGM" 
diff --git a/docs/en_us/olx/source/advanced-components/word_cloud.rst b/docs/en_us/olx/source/components/word_cloud.rst
similarity index 100%
rename from docs/en_us/olx/source/advanced-components/word_cloud.rst
rename to docs/en_us/olx/source/components/word_cloud.rst
diff --git a/docs/en_us/olx/source/problem-xml/zooming_image.rst b/docs/en_us/olx/source/components/zooming_image.rst
similarity index 100%
rename from docs/en_us/olx/source/problem-xml/zooming_image.rst
rename to docs/en_us/olx/source/components/zooming_image.rst
diff --git a/docs/en_us/olx/source/directory-structure.rst b/docs/en_us/olx/source/directory-structure.rst
index 39200be3fc..9945c5e02d 100644
--- a/docs/en_us/olx/source/directory-structure.rst
+++ b/docs/en_us/olx/source/directory-structure.rst
@@ -8,14 +8,8 @@ See:
 
 * `OLX and Directory File Structures`_
 * `Top-level Directory`_
-* `about Directory`_
-* `html Directory`_
-* `info Directory`_
-* `policies Directory`_
-* `problem Directory`_
-* `static Directory`_
-* `tabs Directory`_
-* `video Directory`_
+* `XBlock directories`_
+* `edX Platform Directories`_
 
 ****************************************
 OLX and Directory File Structures
@@ -32,15 +26,15 @@ Top-level Directory
 ************************
 
 Starting out, it is easiest to create your courseware structure in a
-single file, the ``course.xml file``. This file may contain your
-entire course, but in most cases, it is convenient to split out large
-chunks of content into individual files. This is typically done either
-at the level of large components, such as either problems or homework
-assignments. 
+single file, the ``course.xml file``. 
 
-Currently, Studio, on export, places each component in its own
-file. MIT ODL and edX have scripts which rechunk the file structure in
-different ways.
+This file can contain your entire course, but in most cases, it is convenient
+to split out large chunks of content into individual files. This is typically
+done either at the level of large components, such as problems or homework
+assignments.
+
+Currently, when Studio exports a course, it places each component in its own
+file. 
 
 For example, the edX Platform contains a directory called
 `manual-testing-complete`_ that contains a course with all component
@@ -54,19 +48,19 @@ content.
  If you are using custom XBlocks, you can have
  additional directories that store the XML for XBlocks of that type.
 
-********************
-XBlock directories (``html``, ``problem``, etc.)
-********************
+*******************
+XBlock directories
+*******************
 
-edX course components may be broken out of the main course.xml file
+edX course components can be broken out of the main ``course.xml`` file
 into individual files. Those files go into directories of the name of
 the component type (XML tag). For example, components of type ``html``
-may be placed as individual files in the ``html`` directory. If your
-course does not contain html files, or if they are all in-lined in
+can be placed as individual files in the ``html`` directory. If your
+course does not contain html files, or if they are all embedded in
 their top-level components, you do not need to create an ``html``
 directory.
 
-For information about several examplars of these directories, see: 
+For information about several examples of these directories, see: 
 
 See :ref:`HTML Components` for more information.
 See :ref:`Problems and Tools` for more information.
@@ -75,15 +69,13 @@ See :ref:`Video Components` for more information.
 As the set of XBlocks grows, so does the set of associated XML tags
 and directories.
 
-********************
+*************************
 edX Platform Directories
-********************
+*************************
 
 In addition to the course hierarchy, which is designed to be generic
-and cross-platform, XML course exports contain a set of JSON and HTML
-files providing edX-specific course metadata (such as course
-information pages specific to a MOOC setting), as well as things which
-have not yet been folded into the above framework.
+and cross-platform, OLX courses contain a set of JSON and HTML
+files that specify course policies and non-courseare content.
 
 ====================
 ``about`` Directory
@@ -112,9 +104,9 @@ The ``info`` directory contains:
 * ``updates.html``, which contains the course updates students see when opening
   a course.
 
-====================
+=======================
 ``policies`` Directory
-====================
+=======================
 
 The ``policies`` directory contains:
 
diff --git a/docs/en_us/olx/source/index.rst b/docs/en_us/olx/source/index.rst
index 1a5a1850e3..51a5d26a4d 100644
--- a/docs/en_us/olx/source/index.rst
+++ b/docs/en_us/olx/source/index.rst
@@ -26,6 +26,7 @@ This document is intended for those developing edX courses through Open Learning
    organizing-course/index
    components/index
    problem-xml/index
+   tools/index
    drafts/index
    demo-course/index
 
diff --git a/docs/en_us/olx/source/links.rst b/docs/en_us/olx/source/links.rst
index 43056eef6a..47bbb3b423 100644
--- a/docs/en_us/olx/source/links.rst
+++ b/docs/en_us/olx/source/links.rst
@@ -3,4 +3,6 @@
 
 .. _Wikipedia XML entry: http://en.wikipedia.org/wiki/XML
 
-.. _manual-testing-complete: https://github.com/edx/edx-platform/tree/master/common/test/data/manual-testing-complete
\ No newline at end of file
+.. _manual-testing-complete: https://github.com/edx/edx-platform/tree/master/common/test/data/manual-testing-complete
+
+.. _LONCAPA XML format: https://s1.lite.msu.edu/adm/help/Authoring_XML_Intro.hlp#Authoring_XML_Intro
\ No newline at end of file
diff --git a/docs/en_us/olx/source/organizing-course/course-structure-overview.rst b/docs/en_us/olx/source/organizing-course/course-structure-overview.rst
index ce3ed33162..692e58e4ce 100644
--- a/docs/en_us/olx/source/organizing-course/course-structure-overview.rst
+++ b/docs/en_us/olx/source/organizing-course/course-structure-overview.rst
@@ -13,15 +13,16 @@ building blocks of an edX course. See:
 Courseware
 **************
 
-Courseware is the main content of your course, namely lessons and assessments.
-The following list describes how courseware is organized in OLX:
+Courseware is the main content of your course and consists mainly of lessons
+and assessments. The following list describes how courseware is organized in
+OLX:
 
 * Course chapters are at the top level of your course and typically
-  represent a time period. In Studio, chapters are called 'sections.'
+  represent a time period. In Studio, chapters are called *sections*.
 
 * A section contains one or more children which correspond to
-  top-level pages in the course. Studio calls these 'subsections' and
-  is currently restricted to ``sequential`` elements at this
+  top-level pages in the course. In Studio, these are called 'subsections' and
+  are currently restricted to ``sequential`` elements at this
   level. OLX supports any XBlock at this level. 
 
 * Courses are composed of structural elements, such as ``sequential``
diff --git a/docs/en_us/olx/source/organizing-course/course-xml-file.rst b/docs/en_us/olx/source/organizing-course/course-xml-file.rst
index 951d31f8ca..8bfc27e937 100644
--- a/docs/en_us/olx/source/organizing-course/course-xml-file.rst
+++ b/docs/en_us/olx/source/organizing-course/course-xml-file.rst
@@ -80,7 +80,13 @@ For example:
 Course Chapters
 *******************************
 
-You create a course chapter with the ``chapter`` element, as a child of the root ``course`` element. Chapter elements are top-level pages in the course. The edX platform renders navigation chrome around them (tab-set on top and accordion on the left). It is possible to disable chrome for specific chapters using the ``chrome`` option. It is possible to associate chapters with different elements of the tabset with the ``default_tab`` option. It is possible to hide them from the navigation using the ``hide_from_toc`` option. 
+You create a course chapter with the ``chapter`` element, as a child of the
+root ``course`` element. Chapter elements are top-level pages in the course.
+The edX platform renders navigation chrome around them (tab-set on top and
+accordion on the left). It is possible to disable chrome for specific chapters
+using the ``chrome`` option. It is possible to associate chapters with
+different elements of the tabset with the ``default_tab`` option. It is
+possible to hide them from the navigation using the ``hide_from_toc`` option.
 
 For example, if the course outline file contains:
 
diff --git a/docs/en_us/olx/source/pages/pages.rst b/docs/en_us/olx/source/pages/pages.rst
index 0858dd6511..dc12fc2755 100644
--- a/docs/en_us/olx/source/pages/pages.rst
+++ b/docs/en_us/olx/source/pages/pages.rst
@@ -1,17 +1,17 @@
-.. _Course Pages:
+.. _Course Tabs:
 
 #################################
-Course Pages
+Course Tabs
 #################################
 
-You can add tabs to your course. Each tab appears in your course’s navigation
-bar.
+You can add tabs, or pages, to your course. Each tab appears in your course’s
+navigation bar.
 
 *********************************************
-Create the Page File
+Create the Tab File
 *********************************************
 
-You create an HTML file for each page you want to add to the course in the
+You create an HTML file for each tab you want to add to the course in the
 ``tabs`` directory.
 
 You can add any text and HTML markup to the page. Tabs can also be
diff --git a/docs/en_us/olx/source/problem-xml/index.rst b/docs/en_us/olx/source/problem-xml/index.rst
index c09f8f048b..e63b7e331f 100644
--- a/docs/en_us/olx/source/problem-xml/index.rst
+++ b/docs/en_us/olx/source/problem-xml/index.rst
@@ -4,20 +4,36 @@
 Problems
 #################################
 
-The format for edX problems is based on the LONCAPA XML format (https://s1.lite.msu.edu/adm/help/Authoring_XML_Intro.hlp#Authoring_XML_Intro), although the two are not quite compatible. In the edX variant, problems are composed of four types of tags: 
+The format for edX problems is based on the `LONCAPA XML format`_,
+although the two are not quite compatible. In the edX variant, problems are
+composed of four types of tags:
 
-* inputtypes are similar to XBlocks. They define ways for users to enter input into the problem. 
-* responsetypes are graders. They define how inputs are mapped to grades. 
-* hinters are used to provide feedback to problems. 
+* **inputtypes** are similar to XBlocks. They define ways for users to enter
+  input into the problem.
+* **responsetypes** are graders. They define how inputs are mapped to grades. 
+* **hinters** are used to provide feedback to problems. 
 * Standard HTML tags are used for formatting. 
 
-In abstract, the system is designed to allow mixing-and-matching of inputtypes, responsetypes, and hinters. For example, a numerical grader could match 7+-0.1%. It would be okay to use this with any inputtype which output a number, whether this was a text box, equation input, slider, or multiple choice question. In practice, this doesn't always work. For example, in the former case, a multiple choice question would not give an output in a format a numerical grader could handle. 
+OLX is designed to allow mixing-and-matching of inputtypes,
+responsetypes, and hinters. For example, a numerical grader could match
+7+-0.1%. It would be okay to use this with any inputtype which output a number,
+whether this was a text box, equation input, slider, or multiple choice
+question. In practice, this doesn't always work. For example, in the former
+case, a multiple choice question would not give an output in a format a
+numerical grader could handle.
 
-In addition, in many cases, there is a 1:1 mapping between graders and inputs. For some types of inputs (especially discipline-specific specialized ones), it simply does not make sense to have more than one grader. 
+In addition, in many cases, there is a 1:1 mapping between graders and inputs.
+For some types of inputs (especially discipline-specific specialized ones), it
+simply does not make sense to have more than one grader.
 
-The most general grader is customresponse. This uses a piece of Python code to evaluate the input. By design, this ought to work with any inputtype, although there are bugs mixing this with a small number of the newer inputtypes. 
+The most general grader is ``customresponse``. This uses Python code
+to evaluate the input. By design, this ought to work with any inputtype,
+although there are bugs mixing this with a small number of the newer
+inputtypes.
 
-Like LON-CAPA, OLX allows embedding of code to generate parameterized problems. Unlike LON-CAPA, edX supports Python (and not Perl). Otherwise, the syntax is approximately identical. 
+Like LON-CAPA, OLX allows embedding of code to generate parameterized problems.
+Unlike LON-CAPA, edX supports Python (and not Perl). Otherwise, the syntax is
+approximately identical.
 
 .. toctree::
    :maxdepth: 2
@@ -42,3 +58,6 @@ Like LON-CAPA, OLX allows embedding of code to generate parameterized problems.
    protein_builder
    symbolic_response
    text_input
+
+
+.. include:: ../links.rst
diff --git a/docs/en_us/olx/source/problem-xml/vitalsource.rst b/docs/en_us/olx/source/problem-xml/vitalsource.rst
deleted file mode 100644
index cfbd0617d4..0000000000
--- a/docs/en_us/olx/source/problem-xml/vitalsource.rst
+++ /dev/null
@@ -1,2 +0,0 @@
-.. include:: ../../../shared/exercises_tools/vitalsource.rst
-