Merge pull request #14 from open223/mas/explanation

_config.yml

@@ -1,7 +1,7 @@
 # https://jupyterbook.org/en/stable/customize/config.html
 
 # Book settings
-title: ASHRAE 223P User Documentation
+title: ASHRAE Standard 223P User Documentation
 author: ""
 copyright: ""
 logo: ""

_toc.yml

@@ -5,6 +5,9 @@
 format: jb-book
 root: intro
 parts:
+- caption: Explanation
+  chapters:
+  - file: explanation/223p.md
 - caption: Tutorials
   chapters:
   - file: tutorials/223-explore.md
@@ -16,16 +19,13 @@ parts:
   - file: guides/how-to-model.md
   - file: guides/how-to-telemetry.md
   - file: guides/how-to-extend.md
-- caption: Explanation
-  chapters:
-  - file: explanation/223p.md
-  - file: explanation/supporting-tech.md
 - caption: Reference
   chapters:
   - file: reference/supporting-links.md
   - file: reference/tools.md
   - file: reference/open-223.md
   - file: reference/example-models.md
+  - file: reference/supporting-tech.md
 - caption: Example Models
   chapters:
   - file: examples/lbnl-example.md

explanation/223p.md

@@ -1,28 +1,28 @@
-# Introduction to ASHRAE 223P 
+# ASHRAE Standard 223P
 
 Standard 223P provides a comprehensive approach to applying semantic formalisms for representing building automation system data and relationships between associated entities such as equipment, physical spaces, and zones. The primary purpose is to enable software applications to automate the discovery and understanding of information related to building systems. This facilitates the development of advanced tools and applications for building analytics and supports the creation of digital twins and optimization of energy usage within building systems. Specific functionalities include automated fault detection, diagnostics, building system commissioning, and interactions with smart grids.
 
-The standard provides a machine-readable representation of building systems, their associated spaces, and key measurement/control points that can be used to construct semantic models for individual buildings or entire capmuses. It rigorously defines the concepts of the standard using validation and inference rules, helping to ensure that models are created correctly and will be interoperable. This is accomplished using various semantic web technologies, further described in the [following section](supporting-tech). The notions of entities, classes, relationships, and graphs are required to understand the standard, and are defined below.
+The standard provides a machine-readable representation of building systems, their associated spaces, and key measurement/control points that can be used to construct semantic models for individual buildings or entire capmuses. It rigorously defines the concepts of the standard using validation and inference rules, helping to ensure that models are created correctly and will be interoperable. This is accomplished using various semantic web technologies, further described in the [reference section](../reference/supporting-tech.md). The notions of entities, classes, relationships, and graphs are required to understand the standard, and are defined below.
 
 Definitions
 
 <!-- borrowed from brick since we use similar terms-->
- - **Entity:** An entity is an abstraction of any physical, logical or virtual item; the actual "things" in a building. Examples are mechanical equipment such as air handling units, luminaires, spatial elements like rooms, or the area of these rooms served by certain mechanical equipment. Virtual and logical entities may represent the various data points in a BAS system, such as sensing and actuation points, as well as basic representations of controls. 
+ - **Entity:** An entity is an abstraction of any physical, logical or virtual item; the actual "things" in a building. Examples are mechanical equipment such as air handling units, luminaires, spatial elements like rooms, or the area of these rooms served by certain mechanical equipment. Virtual and logical entities may represent the various data points in a BAS system, such as sensing and actuation points, as well as basic representations of controls.
 
- - **Class:** A named category with intensional meaning (a definition) used for grouping entities. 
-Classes are organized into a hierarchy, and entities are an instance of a given class. Classes are defined using SHACL shapes ensuring that they are instantiated correctly. 
+ - **Class:** A named category with intensional meaning (a definition) used for grouping entities.
+Classes are organized into a hierarchy, and entities are an instance of a given class. Classes are defined using SHACL shapes ensuring that they are instantiated correctly.
 
  - **Relationship:** Defines the nature of a link between two related entities.
 Examples of relationships are *encapsulation* (one entity is contained within another), *sequence* (one entity takes effect before another in some process) and *instantiation* (one entity's type is given by another entity).
 
  - **Graph:** An abstract organizational data structure representing a set of entities (nodes) and relationships (edges) described in triple-structure. 223P models are represented by a directed, labeled graph. We recommend reading the [Wikipedia page on the abstract graph data structure](https://en.wikipedia.org/wiki/Graph_(abstract_data_type)).
 
 
- - **A 223P model:** A 223P model is a digital representation of a building that utilizes the 223P standard. This means that elements of a particular buidling are represented using instances of the classes defined by the 223P standard and use relationships as defined by the rules present in the standard. 223P leverages the semantic web technologies, allowing easy integration with other types of models that utilize RDF. 
+ - **A 223P model:** A 223P model is a digital representation of a building that utilizes the 223P standard. This means that elements of a particular buidling are represented using instances of the classes defined by the 223P standard and use relationships as defined by the rules present in the standard. 223P leverages the semantic web technologies, allowing easy integration with other types of models that utilize RDF.
 
 ## 223P Top Level Classes
 
-The 223P standard defines several high level concepts, represented as classes, that are subclassed and composed to create 223P models. All entities in a 223P model are an instance of these classes or one of their subclasses. More detail about each of these concepts and their classes can be found on [Open 223 Explorer](https://explore.open223.info/). A [tutorial](223-explore) is provided to help users explore that website if they are unfamiliar with semantic ontologies. Additionally, a [modeling guidance section](how-to-model) provides detailed description of how these concepts can be applied, and [example models](example-models) are avaialable to see how these concepts are used. 
+The 223P standard defines several high level concepts, represented as classes, that are subclassed and composed to create 223P models. All entities in a 223P model are an instance of these classes or one of their subclasses. More detail about each of these concepts and their classes can be found on [Open 223 Explorer](https://explore.open223.info/). A [tutorial](223-explore) is provided to help users explore that website if they are unfamiliar with semantic ontologies. Additionally, a [modeling guidance section](how-to-model) provides detailed description of how these concepts can be applied, and [example models](example-models) are avaialable to see how these concepts are used.
 
  - **Connectable:** An abstract class representing a thing that can be connected via ConnectionPoints and Connections.
 
@@ -36,7 +36,7 @@ The 223P standard defines several high level concepts, represented as classes, t
 
     - **DomainSpace:** A portion or entirety of a PhysicalSpace associated with a Domain. Often a DomainSpace is served by a particular piece of equipment, like a single VAV Box, and thus they can be connected to equipment. Multiple DomainSpaces controlled similarly can be grouped together, forming a Zone.
 
-    - **Equipment:** A modeling construct used to represent a mechanical device designed to accomplish a specific task (e.g. pump, fan, heat exchanger, luminaire, temperature sensor, flow meter). Equipment may contain and connect to other equipment, allowing detailed modeling of mechanical systems. Certain pieces of equipment (i.e. Sensors, Actuators, Controllers) may have unique relationships to properties to define how they act on the properties of other entities. 
+    - **Equipment:** A modeling construct used to represent a mechanical device designed to accomplish a specific task (e.g. pump, fan, heat exchanger, luminaire, temperature sensor, flow meter). Equipment may contain and connect to other equipment, allowing detailed modeling of mechanical systems. Certain pieces of equipment (i.e. Sensors, Actuators, Controllers) may have unique relationships to properties to define how they act on the properties of other entities.
 
     - **Junction:** A Junction is a modeling construct used to represent important branching points within a Connection.
 
@@ -48,6 +48,6 @@ The 223P standard defines several high level concepts, represented as classes, t
 
  - **Properties:** Properties often represent the actuation and measurement points within a buidling. They may be associated with real-time data. They also may define the attributes of other entities (e.g. Equipment, DomainSpaces, Zones). They can be further contextualized using enumerations.
 
- - **Enumerations:** The standard uses enumerations to convey groups of useful values for describing attributes of Properties, Equipment, and other things in the model. For example, the enumeration `Role-Cooling` describes that the equipment in question provides cooling. 
+ - **Enumerations:** The standard uses enumerations to convey groups of useful values for describing attributes of Properties, Equipment, and other things in the model. For example, the enumeration `Role-Cooling` describes that the equipment in question provides cooling.
 
- - **FunctionBlock:** Is used to model transfer and/or transformation of information (e.g. control algorithms). It has relations to input properties and output properties, that represent input and output data. The actual algorithms that perform the transformations are not described in 223P, and can be described using standard 231P. 
+ - **FunctionBlock:** Is used to model transfer and/or transformation of information (e.g. control algorithms). It has relations to input properties and output properties, that represent input and output data. The actual algorithms that perform the transformations are not described in 223P, and can be described using standard 231P.

intro.md

@@ -1,4 +1,4 @@
-# ASHRAE 223P User Documentation [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://open223.github.io/docs.open223.info/)
+# ASHRAE Standard 223P User Documentation [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://open223.github.io/docs.open223.info/)
 
 The purpose of this site is to provide documentation for users of the *proposed* ASHRAE Standard 223, ***Designation and Classification of Semantic Tags for Building Data***.