From f451cbe1696d8c2bd1014c3fa4fb988cf33c6d6c Mon Sep 17 00:00:00 2001
From: Graham Charters <gcc@php.net>
Date: Fri, 29 Jul 2005 16:58:23 +0000
Subject: [PATCH] Tried to de-jargon the introduction...

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@191813 c90b9560-bf6c-de11-be94-00142212c4b1
---
 reference/sdo/reference.xml | 66 +++++++++++++++++++++++--------------
 1 file changed, 41 insertions(+), 25 deletions(-)

diff --git a/reference/sdo/reference.xml b/reference/sdo/reference.xml
index 1acefec9a1..a036960a4c 100644
--- a/reference/sdo/reference.xml
+++ b/reference/sdo/reference.xml
@@ -1,5 +1,5 @@
 <?xml version='1.0' encoding='iso-8859-1'?>
-<!-- $Revision: 1.10 $ -->
+<!-- $Revision: 1.11 $ -->
 <!-- Generated by xml_proto.php v2.1. Found in /scripts directory of phpdoc. -->
 <reference id="ref.sdo">
  <title>SDO Functions</title>
@@ -12,31 +12,20 @@
     <!-- This warns that the extension is experimental -->
     &warn.experimental;
    </para>
+   
    <para>
-    Service Data Objects (SDOs) are designed to simplify working with
-    heterogeneous data whilst also being tailored for service-oriented
-    applications.  Using SDO, developers can uniformly manipulate data for
-    hetergeneous data sources, such as relational databases and XML.
+    Service Data Objects (SDOs) enable PHP applications to work with
+    data from different sources (like a database query, an XML file, 
+    and a spreadsheet) using a single interface.
    </para>
    <para>
-    SDOs are based on the concept of disconnected data graphs.  
-    A data graph is a tree structure of data objects, navigable via their 
-    containment references.  
-    A containment reference is an aggregation relationship.
-    For example, a Company data object might consists of a number of 
-    Department data objects and therefore the Company would have 
-    a containment reference to the Departments.  
-    A data graph also allows non-containment references. 
-    These are references between data objects within the same tree.
-    For example, one Employee data object might reference another
-    to identify a career mentor.
-   </para>
-   <para>
-    The task of connecting an application to a data source is
-    performed by a Data Access Service (DAS).  
-    Applications use a DAS to retrieve an SDO from a data source.  
-    The application can then manipulate the SDO and use a DAS to write 
-    it back to the same, or an alternative, data source.
+    Each different kind of data source requires a Data Access Service 
+    (DAS) to provide access to the data in the data source.
+    In your PHP application, you use a DAS to create an SDO 
+    instance that represents some data in the data source.  You can then 
+    set and get values in the SDO instance using the standard SDO 
+    interface.  Finally, you use a DAS to write the modified data back
+    to a data source (typically the same one).
    </para>
    <para>
     See the
@@ -47,12 +36,39 @@
     (see the section on <link linkend="sdo.class.sdo-das-spis">SDO Data
     Access Services Interface</link> for more details).
    </para>
-   <para>
+    <para>
     This extension is derived from concepts taken from the
     <ulink url='&url.ibm.sdo;'>
     Service Data Objects specification
     </ulink>
    </para>
+
+   <section id="sdo.intro.structure">
+    <title>The Structure of a Service Data Object</title>
+    <para>
+     A Service Data Object instance is made up of a tree of data objects.
+     The tree is defined by containment references between the data objects.
+     For example, a Company data object might consist of a number of 
+     Department data objects and therefore the Company would have 
+     a containment reference to the Departments.  
+     Deleting a data object which has a containment reference to another
+     data object will delete the referenced data object.  For example, 
+     deleting the Company data object will also delete the Departments.
+    </para>
+    <para>
+     An SDO may also have non-containment references between data objects 
+     in the tree.  For example, one Employee data object might reference 
+     another Employee to identify a career mentor.  Deleting a data object
+     which has a non-containment reference to another data object does 
+     not delete the referenced data object.
+    </para>
+    <para>
+     As well as data objects referencing each other, they can also have
+     primitive properties.  For example, the Company data object might
+     have a property called "name" of type string, for holding the name
+     of the company (for example, "Acme").
+    </para>
+   </section>
   </section>
 
   <section id="sdo.requirements">
@@ -544,7 +560,7 @@ sdoxml:propertyType="company:EmployeeType"/> </xsd:complexType>
      <programlisting role="php" id="sdo.examples.xpathquery">
 <![CDATA[
 <?php
-  $ad_tech_mgr = $company["departments[name=\"Advanced Technologoies\"]/employees[manager=\"true\"]"]; 
+  $ad_tech_mgr = $company["departments[name=\"Advanced Technologies\"]/employees[manager=\"true\"]"]; 
 ?>
 ]]>
      </programlisting>