Updated context-providers.txt

* Mark type crack as a preview.
* Added text about check-context-providers.

1 files changed, 70 insertions, 16 deletions

diff --git a/doc/context-providers.txt b/doc/context-providers.txt
index 5b75fd42..2d6c72f5 100644
--- a/doc/context-providers.txt
+++ b/doc/context-providers.txt
@@ -40,8 +40,7 @@ link:schema.html[this XML schema].  A simple example for the
       <doc>
         A exemplary context provider.
       </doc>
-      <key name="Random">
-        <float min="0.0" max="1.0"/>
+      <key name="Random" type="DOUBLE">
         <doc>
  	  A random number between 0 and 1 that changes every now and then.
 	</doc>
@@ -105,6 +104,11 @@ markup.
 Types
 ~~~~~
 
+*NOTE:* This is preview of things that might come, or not.  For now,
+just use a +type+ attribute in your +key+ elements with one of
++"TRUTH"+, +"STRING"+, +"INT"+, or +"DOUBLE"+ as the value.
+
+
 Each +key+ element in the property declaration tree should contain a
 child element that describes the possible values of the property.
 Allowed elements are:
@@ -125,14 +129,15 @@ A arbitrary string.
 A constant.  Constant are useful inside of a +choice+
 element. Attributes +bool+, +int+, +float+, +string+.
 
-+repeat+::
-A list.  The single child element of +repeat+ specifies the possible values
++list+::
+A list.  The single child element of +list+ specifies the possible values
 for all the list elements.
 
-+list+::
-A list.  Each child element of +list+ specifies the possible values
-for the corresponding list element.  The +tag+ attribute of the
-children can be used to give names to the list elements.
++struct+::
+A fixed length list.  Each child element of +struct+ specifies the
+possible values for the corresponding list element.  The +tag+
+attribute of the children can be used to give names to the list
+elements.
 
 +choice+::
 One of a given set of alternative.  Each child element describes one
@@ -145,10 +150,10 @@ For example,
 
 [source,xml]
 ----
-<list>
+<struct>
   <bool tag="landscape"/>
   <bool tag="inverted"/>
-<list>
+<struct>
 ----
 
 describes a pair of booleans.  When showing it, the first boolean is
@@ -175,23 +180,72 @@ coordinates.
 [source,xml]
 ----
 <choice>
-  <list tag="named">
+  <struct tag="named">
     <const int="0"/>
     <string/>
-  </list>
-  <list tag="coords">
+  </struct>
+  <struct tag="coords">
     <const int="1"/>
     <float tag="latitude"/>
     <float tag="longitude"/>
-  </list>
+  </struct>
 </choice>
 ----
 
-
 Guidelines for property providers
 ---------------------------------
 
+TBW.
+
 Providing core properties
 -------------------------
 
-- Using the check/update tool.
+The Context Framework project maintains a list of _core properties_.
+These core properties are intended to cover the needs of most
+applications and be meaningful for many different devices.
+
+When you are implementing a provider for some of the core properties,
+you must of course make sure that you follow the specification of that
+property.  You can not redefine its type or description in your
+property declaration file, obviously.
+
+But you still need to include a complete property declaration file
+with your provider and install it in +/usr/share/context-providers/+.
+At run-time, all properties are equal and there isn't anything special
+about core properties anymore.
+
+To create a property declaration file that includes core properties,
+you should copy the necesarry fragments out of the core declaration
+file into yours.  The core declaration file can be found in the
++contextkit-dev+ package and also link:context.xml[here].
+
+The core properties will not change very often, but there might be
+changes.  When that happens, you need to review the changes and
+maybe--after careful consideration--update your implementation to
+reflect the changes.  You also need to update your property
+declaration file at that time.
+
+The +contextkit-dev+ package contains the +check-core-properties+ tool
+to help with this.  Running it like this
+
+[source,sh]
+----
+check-context-properties properties.xml
+----
+
+will check every core property declared in the file +properties.xml+
+against its current official declarations.  It will output some
+diagnosis and fail if there are any discrepancies.  You should run it
+as part of your test-suite.
+
+You can automatically update your property declaration file from the
+current official declarations by using the +--update+ option:
+
+[source,sh]
+----
+check-context-properties --update properties.xml
+----
+
+This will modify +properties.xml+ in place.  You should run it
+manually when adapting your provider to changes in the official core
+property declarations.