adding README and moving graphics

buildingSMART · Aug 19, 2024 · c399ee7 · c399ee7
1 parent faed87a
commit c399ee7
Show file tree

Hide file tree

Showing 14 changed files with 27 additions and 6,580 deletions.
diff --git a/Documentation/ImplementersDocumentation/developer-guide.md b/Documentation/ImplementersDocumentation/developer-guide.md
@@ -54,7 +54,7 @@ XSD also includes a **Total Digits** and a **Fraction Digits** restriction. Thes
 
 ### Optionality
 
-Specifications can be set to **Required**, **Optional**, or **Prohibited** depending on the required match of their `applicability` on the model. 
+Specifications can be set to **Required**, **Optional**, or **Prohibited** depending on the required match of their `applicability` on the model.
 This is represented using XSD's `minOccurs` and `maxOccurs` functionality. They are represented by the following states:
 
 | Optionality | minOccurs | maxOccurs |
@@ -67,12 +67,10 @@ Other configurations of `minOccurs` and `maxOccurs` are currently not allowed.
 
 ## Available developer libraries
 
-To help you get started with development, there is a [directory of IDS libraries](https://technical.buildingsmart.org/resources/software-implementations/) that you may use in your application. 
+To help you get started with development, there is a [directory of IDS libraries](https://technical.buildingsmart.org/resources/software-implementations/) that you may use in your application.
 
 Please feel free to [submit your library](https://technical.buildingsmart.org/resources/software-implementations/) (you need to login).
 
-
-
 ## More reading
 
 - [Add your implementation to the software vendors directory](https://technical.buildingsmart.org/resources/software-implementations/)

diff --git a/Documentation/README.md b/Documentation/README.md
@@ -0,0 +1,4 @@
+# Documentation of the IDS
+
+- [UserManual](UserManual/) contains explanation of the IDS content and how to use it. Start with the [README](UserManual/README.md) file.
+- [ImplementersDocumentation](ImplementersDocumentation/) contains additional explanations of the technicalities for software developers, such as how software should handle numeric value [tolerance](ImplementersDocumentation/tolerance.md). The folder also contains a suite of over 250 test file pairs (.ids and .ifc) for verifying the correctness of the software implementation reading and checking capabilities: [TestCases](ImplementersDocumentation/TestCases/).
diff --git a/Documentation/UserManual/Graphics/IDS-logo-with-letters.png b/Documentation/UserManual/Graphics/IDS-logo-with-letters.png
diff --git a/...ual/Graphics/buildingSMART_RGB_IDS_v4.svg → ...entation/UserManual/Graphics/IDS-logo.svg b/...ual/Graphics/buildingSMART_RGB_IDS_v4.svg → ...entation/UserManual/Graphics/IDS-logo.svg
diff --git a/Documentation/UserManual/Graphics/IDS_logo.ai b/Documentation/UserManual/Graphics/IDS_logo.ai
diff --git a/Documentation/UserManual/Graphics/buildingSMART_RGB_IDS_v4.png b/Documentation/UserManual/Graphics/buildingSMART_RGB_IDS_v4.png
diff --git a/Documentation/UserManual/Graphics/ids-favicon.png b/Documentation/UserManual/Graphics/ids-favicon.png
diff --git a/Documentation/UserManual/Graphics/ids-favicon.svg b/Documentation/UserManual/Graphics/ids-favicon.svg
diff --git a/Documentation/UserManual/Graphics/ids-logo_with-letters.png b/Documentation/UserManual/Graphics/ids-logo_with-letters.png
diff --git a/Documentation/UserManual/README.md b/Documentation/UserManual/README.md
@@ -1,14 +1,14 @@
 # Information Delivery Specification
 
-![IDS Logo](ids-logo.png)
+<img src="Graphics/IDS-logo-with-letters.png" alt="IDS Logo" width="300"/>
 
 **Information Delivery Specification (IDS)** is a buildingSMART standard for specifying and checking simple information requirements from IFC models. It is designed as a free, lightweight, standardised approach to model checking.
 
 ## Introduction
 
 An IDS is a file format ending in `.ids` containing a list of information **Specifications**. For example, a single **Specification** might say that "_all walls must have a fire rating property_". Model authors receiving an IDS file can use it to ensure all required information is provided for each **Specification**. Model recipients may use the IDS file to check whether the IFC model meets all of the **Specifications**. Reports may also be generated to list the results of **Specification** compliance checks.
 
-![IDS Diagram](ids-diagram.png)
+![IDS Diagram](Graphics/ids-diagram.png)
 
 IDS file creation tools and model checking tools are provided by many [software vendors](https://technical.buildingsmart.org/resources/software-implementations/). You can write your own customised IDS **Specifications** from scratch or start from a [public IDS template](todo). Any IFC model produced from any software can be checked by an IDS file.
 

diff --git a/Documentation/UserManual/entity-facet.md b/Documentation/UserManual/entity-facet.md
@@ -44,9 +44,9 @@ One of the most important aspects of writing a specification is to ensure that i
 
 ## Special cases in IFC2X3
 
-Some occurrence entities in IFC2X3 are further specified by their type object. 
+Some occurrence entities in IFC2X3 are further specified by their type object.
 An example is the definition of an air terminal, which is encoded in IFC2X3 by an occurrence instance of IfcFlowTerminal and a type instance of IfcAirTerminalType.
 The entity facet does not have a parameter to further specify the type entity name.
 In this case, the IDS follows the convention introduced in IFC4, which also makes the IDS-based check more schema-agnostic.
-In the given example, the **name** of the entity to be checked should be IfcAirTerminal (without type) and must be resolved by a given mapping table. 
-A full list is given in this [table](./Documentation/ifc2x3-occurrence-type-mapping-table.md)    
+In the given example, the **name** of the entity to be checked should be IfcAirTerminal (without type) and must be resolved by a given mapping table.
+A full list is given in this [table](./Documentation/ImplementersDocumentation/ifc2x3-occurrence-type-mapping-table.md).
diff --git a/Documentation/UserManual/partof-facet.md b/Documentation/UserManual/partof-facet.md
@@ -13,7 +13,7 @@ While objects in IFC can have multiple relationships to other objects. IDS part-
 
 When the `relation` parameter is not specified, then all 6 are to be considered (recursively) to identify containing entities, otherwise only the specified relation type should be considered (also recursively).
 
-![Example of part of identification](graphics/partof-Relations.png)
+![Example of part of identification](Graphics/partof-Relations.png)
 
 ## Parameters
 

diff --git a/Documentation/UserManual/specifications.md b/Documentation/UserManual/specifications.md
@@ -1,35 +1,35 @@
 # How do specifications work?
 
 A **Specification** is designed to be easy for humans to understand.
-However, **Specifications** are also highly structured so that computer software may automatically and accurately check information requirements with no ambiguity. 
+However, **Specifications** are also highly structured so that computer software may automatically and accurately check information requirements with no ambiguity.
 Every **Specification** has three main parts:
 
 1. **Description**: a description of the rationale for the **Specification** and instructions of how to achieve it.
   This part is designed for humans to read and understand why information is being requested.
 
   This field is also used to describe the rationale for the various applicability facets, and how they serve to identify the relevant data contracts on an asset as a whole, rather than individually. Conversely, the `description` data on each requirement facet should help the user understand the purpose of the individual piece of information required.
 
-2. **Applicability**: Identifies the subset of the model that we are intending to specify.
+1. **Applicability**: Identifies the subset of the model that we are intending to specify.
   There are many different types of objects in IFC models, but each **Specification** only applies to a subset.
   The subset can be identified via the available facets like entity (e.g. walls, windows), classification (e.g. Uniclass EF_25_10_25  External walls), and others.
-3. **Requirements**: what information is required for subset identified in the applicability, such as required properties or materials.
+1. **Requirements**: what information is required for subset identified in the applicability, such as required properties or materials.
 
 For example, the **Specification** of "_all walls must have a fire rating property_" is structured like so:
 
  1. **Description**: wall fire ratings are critical for building code compliance
- 2. **Applicability**: this specification applies to all wall objects
- 3. **Requirements**: the aforementioned wall objects must have a fire rating property
+ 1. **Applicability**: this specification applies to all wall objects
+ 1. **Requirements**: the aforementioned wall objects must have a fire rating property
 
 ## How specifications can describe information
 
-**Applicability** and **Requirements** are described using a collection **Facets**. A **Facet** describes information that a single entity (e.g. wall, door, etc) in your model may have. 
+**Applicability** and **Requirements** are described using a collection **Facets**. A **Facet** describes information that a single entity (e.g. wall, door, etc) in your model may have.
 A **Facet** describes its information precisely using fixed **Facet Parameters** so that computers can understand exactly what information you are after.
 
 When a **Facet** is used in the **Applicability** section, it describes the information that we use to identify the relevant parts of the model.
 
 When a **Facet** is used in the **Requirements** section, it describes the information constraints that the model parts must fulfill to comply with the **Specification**.
 
-![IDS Structure](ids-structure.png)
+![IDS Structure](Graphics/ids-structure.png)
 
 There are six different **Facets** of information:
 

diff --git a/README.md b/README.md
@@ -1,6 +1,10 @@
 # Information Delivery Specification standard
 
-Computer interpretable XML based standard to define IFC based Information Delivery Specifications.
-The repo is collecting use-cases, developing and publishing the XSD including XML examples.
+<img src="Documentation/UserManual/Graphics/IDS-logo-with-letters.png" alt="IDS Logo" width="300"/>
 
-Latest info to be found in the /documentation folder
+Computer interpretable XML based standard from buildingSMART to define IFC based Information Delivery Specifications. The repository is collecting use-cases, developing and publishing the XSD including XML examples.
+
+Here are the locations of the latest:
+- schema file: [Schema/ids.xsd](/Schema/ids.xsd)
+- user manual: [Documentation/User manual](/Documentation/UserManual/README.md)
+- implementers documentation: [/Documentation/ImplementersDocumentation/](/Documentation/ImplementersDocumentation/)