Finished detailed documentation

SDT/schema2.0/docs/SDT_Components.md

@@ -9,9 +9,10 @@ In this document an overview about the SDT 2.0 definitions and component hierarc
    [DeviceInfo](#DeviceInfo)  
 [ModuleClass](#ModuleClass)  
    [Action](#Action)  
-   [Data](#Data)  
+   [Data / DataPoint](#Data)  
       [DataType](#DataType)  
-   [Event](#Event) 
+   [Event](#Event)  
+[Doc](#Documentation)  
 
 
 ## SDT Overview
@@ -31,7 +32,7 @@ The syntax used in the diagram to model an XML Schema Definition (XSD) as an UML
 ### Domain
 The *Domain* is the top-level component that defines all modules and devices of a domain. A *Domain* can import definitions of other domains.
 
-A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to provide both.
+A *Domain* can define [Domain](#Domain) or [RootDevices](#RootDevice) only, or may choose to provide both.
 
 ![](images/Domain.png)
 
@@ -40,8 +41,8 @@ A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to pr
 
 #### Elements
 - **Imports** : XML import/include of other XML files. Optional.
-- **Modules** : A list of *Module* components that are global to the whole domain. Optional.
-- **RootDevices** : a List *RootDevice* components. Optional.
+- **Modules** : A list of [Module](#ModuleClass) components that are global to the whole domain. Optional.
+- **RootDevices** : a List [RootDevices](#RootDevice) components. Optional.
 
 #### Example
 
@@ -64,15 +65,15 @@ A *Domain* can define *ModuleClasses* or *RootDevices* only, or may choose to pr
 
 <a name="RootDevice"/></a>
 ### RootDevice
-A *RootDevice* is the description of a (physical) device that may contain optional embedded sub-devices. It represents the idea an appliance that is addressable on a Home Area Network where one or more sub-*Devices* provide certain functionalities. 
+A *RootDevice* is the description of a (physical) device that may contain optional embedded sub-devices. It represents the idea an appliance that is addressable on a Home Area Network where one or more sub-[Devices](#Devices) provide certain functionalities. 
 
 An example is a connected power-strip where each of the sockets can be switched on and off individually. The power-strip itself can provide functions such as "all sockets off" and "overall power consumption".
 
-If the *RootDevice* includes sub-*Devices* then each sub-device may be of the same type or of different types. The functionality (*Actions*) of the *RootDevice* may be different from the functionality of its sub-*Devices*.
+If the *RootDevice* includes sub-[Devices](#Device) then each sub-device may be of the same type or of different types. The functionality ([Actions](#Action)) of the *RootDevice* may be different from the functionality of its sub-[Devices](#Device).
 
 If the *RootDevice* does not include sub-devices then the *RootDevice* is the actual adressable device that provides all the functionality of the connected appliance.
 
-*RootDevices* may define their own *ModuleClasses* or refer to predefined ModulesClasses of its or another *Domain*.
+*RootDevices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of its or another *Domain*.
 
 ![](images/RootDevice.png)
 
@@ -82,9 +83,9 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
 #### Elements
 
 - **Doc** : Documentation for the *RootDevice*. Optional.
-- **Modules** : A list of *Module* components that are local to the *RootDevice*. Optional.
-- **DeviceInfo** : Further meta-data about the *RootDevice*. Optional.
-- **Devices** : A list *Device* components. Optional.
+- **Modules** : A list of [Module](#ModuleClass) components that are local to the *RootDevice*. Optional.
+- **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *RootDevice*. Optional.
+- **Devices** : A list [Device](#Device) components. Optional.
 
 #### Example
 
@@ -104,9 +105,9 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
 ---
 
 ### Device
-*Devices* are optional components of a *RootDevice*. They represent physical sub-devices inside another device (the *RootDevice*).
+*Devices* are optional components of a [RootDevice](#RootDevice). They represent physical sub-devices inside another device (the RootDevice).
 
-*Devices* may define their own *ModuleClasses* or refer to predefined ModulesClasses of its or another *Domain*.
+*Devices* may define their own [ModuleClasses](#ModuleClass) or refer to predefined ModulesClasses of its or another [Domain](#Domain).
 
 ![](images/Device.png)
 
@@ -115,8 +116,8 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
 
 #### Elements
 - **Doc** : Documentation for the *Device*. Optional.
-- **Modules** : A list of *Module* components that are local to the *RootDevice*. Optional.
-- **DeviceInfo** : A list *Device* components. Optional.
+- **Modules** : A list of [Module](#ModuleClass) components that are local to the *Device*. Optional.
+- **[DeviceInfo](#DeviceInfo)** : Further meta-data about the *Device*. Optional.
 
 #### Example
 
@@ -134,7 +135,7 @@ If the *RootDevice* does not include sub-devices then the *RootDevice* is the ac
 
 <a name="DeviceInfo"/></a>
 ### DeviceInfo
-The *DeviceInfo* is an element of *RootDevice* or *Device* where a device vendor can provide metadata for a device that may be presented to an end-user.
+The *DeviceInfo* is an element of [RootDevice](#RootDevice) or [Device](#Device) where a device vendor can provide metadata for a device that may be presented to an end-user.
 
 ![](images/DeviceInfo.png)
 
@@ -162,11 +163,11 @@ None.
 
 <a name="ModuleClass"/></a>
 ### Module, ModuleClass
-The *Module* (or *ModuleClass*) represents the concept of a reusable module that defines the *Actions*, *Data* and *Events* for a single functionality of a device. A connected device may contain or refer to single or multiple *ModuleClasses* to specify its inherent services it exposes for use by applications.
+The *Module* (or *ModuleClass*) represents the concept of a reusable module that defines the [Actions](#Action), [Data](#Data) and [Events](#Event) for a single functionality of a device. A connected device may contain or refer to single or multiple *ModuleClasses* to specify its inherent services it exposes for use by applications.
 
-*ModuleClasses* can be defined by a domain (on the level of the *Domain* component) or in *(Root)Devices*: The former are global to a domain and can be used by all *(Root)Devices* of a *Domain*; the later are local to the *Device*. *ModuleClasses* defined on the *Domain* level can be imported and used by other *Domains*.
+*ModuleClasses* can be defined by a domain (on the level of the [Domain](#Domain) component) or in [RootDevices](#RootDevice)/[Devices](#Device): The former are global to a [Domain](#Domain) and can be used (refered to) by all [RootDevices](#RootDevice)/[Devices](#Device) of a [Domain](#Domain); the later are local to the [RootDevices](#RootDevice)/[Devices](#Device) where it is defined in. *ModuleClasses* defined on the [Domain](#Domain) level can be imported and used by other domains.
 
-New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add new or overriding defined *Actions*, *Data* and *Events*.
+New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add new or overriding defined [Actions](#Action), [Data](#Data) and [Events](#Event).
 
 ![](images/ModuleClass.png)
 
@@ -176,12 +177,12 @@ New *ModuleClasses* can be defined by extending existing *ModuleClasses* to add
 #### Elements
 - **extends** : Reference to a another *ModuleClass* that is extended with this *ModuleClass*. Optional.  
 The element has the following attributes:
-	- **domain** : Identifier / Reference of the *Domain* of the extended *ModuleClass*. Required when *extends* is specified.
-	- **class** : Name of the *ModuleClass* in the *Domain* thet is extended.
+	- **domain** : Identifier / Reference of the [Domain](#Domain) of the extended *ModuleClass*. Required when *extends* is specified.
+	- **class** : Name of the *ModuleClass* in the [Domain](#Domain) thet is extended.
 - **Doc** : Documentation for the *ModuleClass*. Optional.
-- **Actions** : A list of *Action* components, each defining a single action. Optional.
-- **Data** : A list of *Data* components. Optional.
-- **Events** : A list of *Event* components. Optional.
+- **Actions** : A list of [Action](#Action) components, each defining a single action. Optional.
+- **Data** : A list of [Data](#Data) components. Optional.
+- **Events** : A list of [Event](#Event) components. Optional.
 
 #### Example
 
@@ -202,13 +203,13 @@ The element has the following attributes:
 
 <a name="Action"/></a>
 ### Action
-An *Action* is defines a single procedure call for a *ModuleClass*. It is basically for calling a function on a physical device in order to set or request data, or to invoke an action at a *Device*.
+An *Action* is defines a single procedure call for a [ModuleClass](#ModuleClass). It is basically for calling a function on a physical device in order to set or request data, or to invoke an action at a [Device](#Device).
 
 ![](images/Action.png)
 
 #### Attributes
 - **name** : The name of the *Action*. Required.
-- **type** : The return type of the *Action*. It must comply to one of the defined *DataTypes*. Optional. If no *type* is specified the *Action* does not return a value.
+- **type** : The return type of the *Action*. It must comply to one of the defined [DataTypes](#DataType). Optional. If no *type* is specified the *Action* does not return a value.
 
 #### Elements
 - **Doc** : Documentation for the *Action*. Optional.
@@ -216,7 +217,7 @@ An *Action* is defines a single procedure call for a *ModuleClass*. It is basica
 The *Arg* has the following attributes and elements:
 	- **name** : The name of the *Arg*. Attribute. Required.
 	- **type** : The type of the *Arg*. It must comply to one of the defined *DataTypes*. Attribute. Required.
-	- **Doc** : Documentation for the *Arg*. Element. Optional.
+	- **Doc** : Documentation for the *Arg* element. Optional.
 
 #### Example
 The following are two examples for actions implementing a getter and a setter for boolean values.
@@ -240,15 +241,15 @@ The *Data* component represents a list of *DataPoints*.
 
 ![](images/Data.png)
 
-Though *DataPoints* only refer to single data points of a physical device it is possible to describe hierarchies by model the path to the data point in the hierarchy by a path-like structure like to the pathname of a UNIX file system. Here, the root node of the hierarchy is a slash (/ TODO hex value) and the nodes along the path are also separated by slashes. The actual datapoint is the last leaf at the path. 
+Though *DataPoints* only refer to single data points of a physical device it is possible to describe hierarchies by model the path to the data point in the hierarchy by a path-like structure like to the pathname of a UNIX file system. Here, the root node of the hierarchy is a slash (/ 0x2F) and the segments or nodes along the path are also separated by slashes. The actual datapoint is the last leaf at the path. 
 
-In BNF:
+In EBNF:
 
-	name := leaf | '/' path .
-	path : = node '/' path | leaf.
-	node := String . 
-	leaf := String .
-	String := [character string excluding the character '/'] .
+	name          = dataPointName | "/" path ;  
+	path          = segment "/" path | dataPointName ;  
+	segment       = string ;  
+	dataPointName = string ;  
+	string        = (* character string excluding the character "/" *) ;
 
 
 #### Attributes
@@ -262,7 +263,7 @@ A *DataPoint* has the following attributes and elements:
 	- **writable** : Boolean value that indicates whether this *DataPoint* is writable by an application. Attribute. Optional. Default: false.
 	- **readable** : Boolean value that indicates whether this *DataPoint* is readable by an application. Attribute. Optional. Default: false.
 	- **eventable** : Boolean value that indicates whether an internal or external change of this *DataPoint* raises an event. Attribute. Optional. Default: false.
-	- **Doc** : Documentation for the *DataPoint*. Element. Optional.
+	- **Doc** : Documentation for the *DataPoint* element. Optional.
 
 
 #### Example
@@ -277,7 +278,7 @@ A *DataPoint* has the following attributes and elements:
 
 <a name="DataType"/></a>
 ### DataType
-The following *DataTypes* can be used in the SDT's *Actions*, *Args* and *DataTypes* elements and attributes. If not stated otherwise datatypes should comply to the equivalent datatypes defined in [XML Schema Part 2: Datatypes Second Edition](http://www.w3.org/TR/xmlschema-2/#boolean):
+The following *DataTypes* can be used in the SDT's [Action](#Action), *Arg* and [DataPoint](#Data) elements and attributes. If not stated otherwise datatypes should comply to the equivalent datatypes defined in [XML Schema Part 2: Datatypes Second Edition](http://www.w3.org/TR/xmlschema-2/#boolean):
 
 - **boolean** : A boolean value as defined by [http://www.w3.org/TR/xmlschema-2/#boolean](http://www.w3.org/TR/xmlschema-2/#boolean) .
 - **byte** : An integer datatype with the range of [0 - 255] as defined by [http://www.w3.org/TR/xmlschema-2/#unsignedByte](http://www.w3.org/TR/xmlschema-2/#unsignedByte) .
@@ -295,7 +296,7 @@ The following *DataTypes* can be used in the SDT's *Actions*, *Args* and *DataTy
 
 <a name="Event"/></a>
 ### Event
-An *Event* is a component that defines properties for events that are raised as reactions to changes in *DataPoints* of a *device's* data model. These state changes can happen either through a device-internal change or by external means, e.g. a user operates a switch or the temperature in a room rises beyond a certain threshold.
+An *Event* is a component that defines properties for events that are raised as reactions to changes in [DataPoints](#Data) of a [Device](#Device)'s data model. These state changes can happen either through a device-internal change, e.g. a low battery level, or by external means, e.g. a user operates a switch or the temperature in a room rises beyond a certain threshold.
 
 ![](images/Event.png)
 
@@ -303,64 +304,45 @@ An *Event* is a component that defines properties for events that are raised as
 - **name** : The name of the *Event*. Required.
 
 #### Elements
-- **Data** : A list of *Data* components. Optional.
-
-#### Example
-
-TODO continue
-
-
-
+- **Data** : A list of [Data](#Data) components for an event's payload. Optional.
+- **Doc** : Documentation for the *Event* Element. Optional.
 
 
+#### Example
 
-# DOC TBD
-Explain. Describe content elements
+	<Event name="stateChanged">
+		<Data>
+			<DataPoint name="state" type="boolean">
+			</DataPoint>
+		</Data>
+	</Event>
 
-	DocText := [ text | emphasizedText | boldText | monotypeText ] * . 
+---
 
+<a name="Documentation"/></a>
+# Documentation
+The *Doc* documentation element is optionally available in most components of the SDT. Its purpose is to provide a short documentation of the respective element.
 
-	<define name="DocText">
-		<zeroOrMore>
-			<choice>
-				<text/>
-				<element name="em">
-					<text/>
-				</element>
-				<element name="b">
-					<text/>
-				</element>
-				<element name="tt">
-					<text/>
-				</element>
-			</choice>
-		</zeroOrMore>
-	</define>
+The text inside the *Doc* element can be structure using a very limited subset of HTML elements. The possible structuring is defined in EBNF as follows:
 
 
-	<define name="Doc">
-		<optional>
-			<element name="Doc">
-				<choice>
-					<ref name="DocText"/>
-					<zeroOrMore>
-						<choice>
-							<element name="p">
-								<ref name="DocText"/>
-							</element>
-							<element name="img">
-								<attribute name="src"/>
-								<element name="caption">
-									<text/>
-								</element>
-							</element>
-						</choice>
-					</zeroOrMore>
-				</choice>
-			</element>
-		</optional>
-	</define>
+	Doc            = "<Doc>" docContent "</Doc" ;
+	docContent     = docText | { paragraph | image } ;
+	docText        = { text | emphasizedText | boldText | monotypeText } ;
+	emphasizedText = "<em>" text "</em>" ;
+	boldText       = "<b>" text "</b>" ;
+	monotypeText   = "<tt>" text "</tt>" ;
+	paragraph      = "<p>" docText "</p>" ;
+	image          = "<img src=" url ">" "<caption>" text "</caption>" "</img>" ;
+	url            = "\"" (* valid URL *) "\"" ;
+	text           = (* XML text element *) ;
 
 
+The intended use for each element is:
 
+- **emphasizedText** : Emphasize the included text, e.g. printing it in italics font.
+- **boldText** : Print the included text in bold font.
+- **monotypeText** : Print the included text in a monospaced fonttype, e.g. to emphasize source code.
+- **paragraph** : Structure the text in paragraphs.
+- **image** : Include an image in the text. The image is loaded from the specified URL and must include a caption text.