Mark Edits

2014-10-16 13:35:13 -04:00
parent cd9476b545
commit 3f30f6283a
21 changed files with 103 additions and 87 deletions
--- a/docs/en_us/olx/source/advanced-components/annotation.rst
+++ b/docs/en_us/olx/source/advanced-components/annotation.rst
--- a/docs/en_us/olx/source/problem-xml/conditional_module.rst
+++ b/docs/en_us/olx/source/problem-xml/conditional_module.rst
--- 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 
--- a/docs/en_us/olx/source/problem-xml/full_screen_image.rst
+++ b/docs/en_us/olx/source/problem-xml/full_screen_image.rst
--- a/docs/en_us/olx/source/problem-xml/google_hangout.rst
+++ b/docs/en_us/olx/source/problem-xml/google_hangout.rst
--- 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
 *************************************
--- a/docs/en_us/olx/source/advanced-components/lti_component.rst
+++ b/docs/en_us/olx/source/advanced-components/lti_component.rst
--- a/docs/en_us/olx/source/advanced-components/open_response_assessment.rst
+++ b/docs/en_us/olx/source/advanced-components/open_response_assessment.rst
--- a/docs/en_us/olx/source/problem-xml/periodic_table.rst
+++ b/docs/en_us/olx/source/problem-xml/periodic_table.rst
--- a/docs/en_us/olx/source/problem-xml/poll.rst
+++ b/docs/en_us/olx/source/problem-xml/poll.rst
--- 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" 
--- a/docs/en_us/olx/source/advanced-components/word_cloud.rst
+++ b/docs/en_us/olx/source/advanced-components/word_cloud.rst
--- a/docs/en_us/olx/source/problem-xml/zooming_image.rst
+++ b/docs/en_us/olx/source/problem-xml/zooming_image.rst
--- 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:

--- 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

--- 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
+.. _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
--- 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``
--- 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:

--- 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
--- 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
--- a/docs/en_us/olx/source/problem-xml/vitalsource.rst
+++ b/docs/en_us/olx/source/problem-xml/vitalsource.rst
@@ -1,2 +0,0 @@
-.. include:: ../../../shared/exercises_tools/vitalsource.rst
-
				`@@ -1,2 +0,0 @@`
				`.. include:: ../../../shared/exercises_tools/vitalsource.rst`