Merge pull request #53 from opendatakit/cherrypick-merge-commcare-1-s…

…quashed

Cherrypicked improvements and corrections from https://dimagi.github.io/xform-spec/

_includes/footer.html

@@ -20,9 +20,3 @@
   </div>
 
 </footer>
-<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
-<script>
-$(document).ready(function(){
-    $(".post-content > ul:first-child").appendTo(".sidenav");
-});
-</script>

_sections/00-Introduction.md

@@ -4,6 +4,6 @@ title: Introduction
 
 The ODK XForm specification is a subset of the far larger [XForm 1.0 specification](http://www.w3.org/TR/xforms/). It contains a few additional features not found in the XForm specification. 
 
-The ODK XForm Specification continues to evolve. On the web you will often see references to _JavaRosa_ and _OpenRosa_ when the spec is discussed. OpenRosa was the name of the [initial specification](https://bitbucket.org/javarosa/javarosa/wiki/xform) that formed the basis of the ODK specification. JavaRosa is the name of a Java library that implements the OpenRosa specification. ODK, JavaRosa, OpenRosa are still often used to refer to the same, but we recommend using this document to build tools that are compliant with the ODK Ecosystem.
+This specification continues to evolve. On the web you will often see references to _JavaRosa_ and _OpenRosa_ when the spec is discussed. OpenRosa was the name of the initial specification that formed the basis of this document. JavaRosa is a library that implements the XForm part of the OpenRosa specification. 
 
 The document assumes at least a fair understanding of XML and XPath. It is also useful to refer to [XForms 1.0](http://www.w3.org/TR/2003/REC-xforms-20031014/) for details about shared features. 

_sections/10-structure.md

@@ -9,16 +9,15 @@ The high-level form definition is structured as follows:
     * bindings
 * body
 
-The model contains the **[instance](#instance)**(s) and the **[bindings](#bindings)**. The first instance is the XML data structure of the _record_ that is captured with the form. A binding describes an individual instance node and includes information such as _datatype, skip logic, calculations, and more_.
+The model contains the **[instance](#instance)**(s) and the **[bindings](#bindings)**. The first instance is the XML data structure of the _record_ that is captured with the form. A binding describes an individual instance node and includes information such as _datatype, skip logic, calculations,_ and more.
 
 The **[body](#body)** contains the information required to _display_ a form. 
 
-Below is an example of a complete and valid ODK XForm:
+Below is an example of a complete and valid XForm:
 
 {% highlight xml %}
 <?xml version="1.0"?>
 <h:html xmlns="http://www.w3.org/2002/xforms" 
-        xmlns:ev="http://www.w3.org/2001/xml-events" 
         xmlns:h="http://www.w3.org/1999/xhtml" 
         xmlns:jr="http://openrosa.org/javarosa" 
         xmlns:orx="http://openrosa.org/xforms" 
@@ -27,18 +26,19 @@ Below is an example of a complete and valid ODK XForm:
         <h:title>My Survey</h:title>
         <model>
             <instance>
-                <data id="mysurvey" version="2014083101">
+                <data id="mysurvey" orx:version="2014083101">
                     <firstname></firstname>
                     <lastname></lastname>
                     <age></age>
-                    <meta>
-                        <instanceID/>
-                    </meta>
+                    <orx:meta>
+                        <orx:instanceID/>
+                    </orx:meta>
                 </data>
             </instance>
-            <bind nodeset="/data/firstname" type="string" required="true()" />
-            <bind nodeset="/data/lastname"  type="string" />
-            <bind nodeset="/data/age" type="integer" />
+            <bind nodeset="/data/firstname" type="xsd:string" required="true()" />
+            <bind nodeset="/data/lastname"  type="xsd:string" />
+            <bind nodeset="/data/age" type="xsd:int" />
+            <bind nodeset="/data/orx:meta/orx:instanceID" preload="uid" type="xsd:string"/>
         </model>
     </h:head>
     <h:body>
@@ -54,3 +54,10 @@ Below is an example of a complete and valid ODK XForm:
     </h:body>
 </h:html>
 {% endhighlight %}
+
+Outside of this simplified structure there are ways to define: 
+
+* form title as the `<title>` element, a child of the `<head>` element,
+* [linkages with external (mobile) applications](#external-applications), 
+* [language dictionaries](#languages). 
+

_sections/20-instance.md

@@ -10,7 +10,7 @@ The primary instance should contain a single childnode. In the example below `<h
 
 {% highlight xml %}
 <instance>
-    <household id="mysurvey" version="2014083101">
+    <household id="mysurvey" orx:version="2014083101">
         <person>
             <firstname/>
             <lastname/>
@@ -23,22 +23,24 @@ The primary instance should contain a single childnode. In the example below `<h
 </instance>
 {% endhighlight %}
 
-Any value inside a primary instance is considered a default value for that question. If that node has a corresponding input element that value will be displayed to the user when the question is parsed.
+Any value inside a primary instance is considered a default value for that question. If that node has a corresponding input element that value will be displayed to the user when the question is rendered.
 
 Nodes inside a primary instance can contain attributes. The client application normally retains the attribute when a record is submitted. There are 3 pre-defined instance attributes:
 
 | attribute     | description
 |---------------|------------
-| `id`          | on the childnode of the primary instance: This is the unique ID at which the form is identified the server that publishes the Form and receives data submissions. For more information see [this Form List Specification](https://bitbucket.org/javarosa/javarosa/wiki/FormListAPI). 
-| `version`     | on the childnode of the primary instance can contain any string value.
-| `jr:template` | on any repeat group node: This serves to define a default template for repeats and is useful if any of the leaf nodes inside a repeat contains a default value. It is not transmitted in the record. For more details, see the [repeats](#repeats) section.
+| `id`          | on the childnode of the primary instance: This is the unique ID at which the form is identified by the server that publishes the Form and receives data submissions. For more information see [this Form List Specification](https://bitbucket.org/javarosa/javarosa/wiki/FormListAPI). \[required\]
+| `orx:version` | on the childnode of the primary instance in the _http://openrosa.org/xforms/_ namespace: Form version which can contain any string value. Like [meta nodes](#metadata) this information is used as a _processing cue_ for the server receiving the submission.
+| `jr:template` | on any repeat group node in the _http://openrosa.org/javarosa namespace_: This serves to define a default template for repeats and is useful if any of the leaf nodes inside a repeat contains a default value. It is not transmitted in the record and only affects the behavior of the form engine. For more details, see the [repeats](#repeats) section.
+
+The primary instance also includes a special type of nodes for metadata inside the `<meta>` block. See the [Metadata](#metadata) section
+
 
-The primary instance also includes a special type of nodes for metadata inside the `<meta>` block. [pending]() - See the [Metadata](#preloaders---metadata) section
 
 
-### Secondary Instances
+### Secondary Instances - Internal
 
-Secondary instances are used to pre-load data inside a form. This data is searchable in XPath. At the moment the only use case is so-called _cascading selections_ where the available options of a multiple-choice question can be filtered based on an earlier answer.
+Secondary instances are used to pre-load read-only data inside a form. This data is searchable in XPath. At the moment the key use case is in designing so-called _cascading selections_ where the available options of a multiple-choice question can be filtered based on an earlier answer.
 
 A secondary instance should get a unique `id` attribute on the `<instance>` node. This allows apps to query the data (which is outside the root, ie. the primary instance, and would normally not be reachable). It uses the the `instance('cities')/root/item[country='nl']` syntax to do this.
 
@@ -108,3 +110,7 @@ A secondary instance should get a unique `id` attribute on the `<instance>` node
     </root>
 </instance>
 {% endhighlight %}
+
+### Secondary Instances - External
+
+[Proposal pending](https://github.com/opendatakit/odk-xform-spec/issues/50).