docs(readme): Rework README and fix linter issues

.markdownlint.json

@@ -0,0 +1,5 @@
+{
+	"line-length": {
+		"code_blocks": false
+	}
+}

README.md

@@ -1,95 +1,89 @@
 # iTop DataModel XSD
 
-[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?logo=git&style=flat)](https://github.com/rudnerbjoern/iTop-schema/issues) [![Validate XSD Schema v3.2](https://github.com/rudnerbjoern/iTop-schema/actions/workflows/validate-xml.v3.2.yml/badge.svg)](https://github.com/rudnerbjoern/iTop-schema/actions/workflows/validate-xml.v3.2.yml) [![Combine XSD Schema v3.2](https://github.com/rudnerbjoern/iTop-schema/actions/workflows/combine-schema.v3.2.yml/badge.svg)](https://github.com/rudnerbjoern/iTop-schema/actions/workflows/combine-schema.v3.2.yml)
+[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?logo=git&style=flat)](https://github.com/rudnerbjoern/iTop-schema/issues)
+[![Validate XSD Schema v3.2](https://github.com/rudnerbjoern/iTop-schema/actions/workflows/validate-xml.v3.2.yml/badge.svg)](https://github.com/rudnerbjoern/iTop-schema/actions/workflows/validate-xml.v3.2.yml)
+[![Combine XSD Schema v3.2](https://github.com/rudnerbjoern/iTop-schema/actions/workflows/combine-schema.v3.2.yml/badge.svg)](https://github.com/rudnerbjoern/iTop-schema/actions/workflows/combine-schema.v3.2.yml)
 
-This project provides an **XSD schema** to validate `datamodel.xxx.xml` files used in the [iTop CMDB software](https://www.combodo.com/itop).
+This project provides an **XSD schema** to validate `datamodel.my-module.xml`
+files used in the [iTop CMDB software](https://www.itophub.io).
 
-The goal is to catch **syntax errors** and **inconsistencies** in your iTop data models *before* importing them into iTop.
+The goal is to catch **syntax errors** and **inconsistencies** in your datamodel
+files *before* importing them into iTop.
 
-## Quickstart
+Keep in mind that this schema definition does not guarantee that your datamodel
+file is fully supported by iTop.
+Always use the [iTop toolkit](https://github.com/Combodo/itop-toolkit-community/releases)
+to fully verify your extension and ensure compatibility with iTop.
 
-Change the second line of your `datamodel.xml` to this:
+## Current status
 
-```xml
-<itop_design version="3.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://rudnerbjoern.github.io/iTop-schema/itop_design.xsd">
-```
-
-This definition will always point to the latest stable version of the schema for iTop (currently version 3.2).
-
-Your IDE will (probably) do the rest.
-
-If you are not yet using an IDE you might try [Visual Studio Code](https://code.visualstudio.com/) by Microsoft and the [XML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml) by Red Hat.
-
-Keep in mind that this schema definition does not guarantee that your datamodel file is fully supported by iTop.
-The schema has many optional elements and attributes that might be mandatory in different use cases.
-
-Always use the [iTop toolkit](https://github.com/Combodo/itop-toolkit-community) to fully verify your extension and ensure compatibility with iTop.
-
-## Current Status
+Supported iTop design versions and URL to use to reference the schema:
 
-- Supported iTop design versions:
-  - [Version 3.2](https://www.itophub.io/wiki/page?id=latest:customization:xml_reference#version_32)
-- The project is in an **early stage**:
-  - The XSD is still **incomplete**.
-  - Many **errors and gaps** are expected.
-  - More advanced validations (e.g. for attribute types and relations) are not yet fully implemented.
+- [Latest](https://rudnerbjoern.github.io/iTop-schema/itop_design.xsd):
+  This will always point to the datamodel reference version from the latest
+  release (STS or LTS) of iTop.
+- [Version 3.2](https://rudnerbjoern.github.io/iTop-schema/3.2/itop_design.xsd):
+  This version is released with iTop 3.2 LTS in August 2024, see also the
+  [schema changes](https://www.itophub.io/wiki/page?id=latest:customization:xml_reference#version_32).
 
-## How to Help
+The project is in an **early stage**:
 
-**Contributions are very welcome!**
-
-- If you have experience with iTop data models or XSD, please help us improve this schema.
-- Issues, suggestions, and pull requests are highly appreciated.
-- Testing with real-world `datamodel.xml` files is extremely helpful.
+- The XSD is still **incomplete**.
+- Many **errors and gaps** are [expected](#known-issues).
 
 ## Usage
 
 You can either:
 
-  1. Download the latest `itop_design.xsd` file.
-  2. Validate your `datamodel.xml` with your preferred XML validator.
-
-or directly link it into your datamodel like this:
-
-### Latest Version
+  1. Use the schema [offline](#offline).
+  2. Feed it directly into a [validator tool](#validator-tool).
+  3. Update your [datamodel](#datamodel) to reference the schema.
 
-This will always point to the latest available version of the schema definition:
-
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<itop_design version="3.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://rudnerbjoern.github.io/iTop-schema/itop_design.xsd">
-```
+### Offline
 
-### Specific Version
+  1. Download the latest `itop_design.xsd` file from [dist](dist/) for the
+     version you want to validate against.
+  2. Validate your `datamodel.xml` with your preferred XML validator or directly
+     include it in your project.
 
-There is only one version available at the moment. This might change in the future when newer versions of iTop get released.
+### Validator tool
 
-#### iTop 3.2
+#### xmllint
 
-```xml
-<?xml version="1.0" encoding="UTF-8"?>
-<itop_design version="3.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://rudnerbjoern.github.io/iTop-schema/3.2/itop_design.xsd">
+```bash
+xmllint --noout --schema https://rudnerbjoern.github.io/iTop-schema/itop_design.xsd datamodel.my-module.xml
 ```
 
-### WARNING
+### Datamodel
 
-When using the `xml-model` declaration the datamodel will not be processed by the iTop installer!
+Change the top of your `datamodel.my-module.xml` to this:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<?xml-model href="https://rudnerbjoern.github.io/iTop-schema/3.2/itop_design.xsd"?>
-<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.2">
+<itop_design version="3.2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:noNamespaceSchemaLocation="https://rudnerbjoern.github.io/iTop-schema/itop_design.xsd">
 ```
 
-or use a tool like `xmllint`:
+Your IDE will (probably) do the rest.
 
-```bash
-xmllint --noout --schema https://rudnerbjoern.github.io/iTop-schema/itop_design.xsd datamodel.xml
-```
+If you are not yet using an IDE, you might try [Visual Studio Code](https://code.visualstudio.com)
+by Microsoft and the [XML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-xml)
+by Red Hat.
+
+> [!WARNING]
+> When using the `xml-model` declaration, the datamodel will probably not be
+> processed by the iTop installer!
+>
+> ```xml
+> <?xml version="1.0" encoding="UTF-8"?>
+> <?xml-model href="https://rudnerbjoern.github.io/iTop-schema/itop_design.xsd"?>
+> <itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.2">
+> ```
 
-## Extending the Schema for Your Own Definitions
+## Extending the schema for your own definitions
 
-You can extend the provided base schema with your own types by creating a local `itop_design.xsd` file in your project and including the base schema.
+You can extend the provided base schema with your own types by creating a local
+`itop_design.xsd` file in your project and include the base schema.
 
 Here is a minimal example:
 
@@ -118,11 +112,20 @@ Here is a minimal example:
 </xs:schema>
 ```
 
-This technique allows you to create additional schema constraints or custom attributes while still relying on the iTop structure.
+This technique allows you to create additional schema constraints or custom
+attributes while still relying on the iTop structure.
+
+Take a look at [this example](https://github.com/Super-Visions/sv-geolocation/blob/master/doc/itop_design.xsd)
+to see it in action.
+
+## Known issues
 
-Take a look at [this example by @Hipska](https://github.com/Super-Visions/sv-geolocation/blob/master/doc/itop_design.xsd) to see it in action.
+<!-- TOD: Convert these to GitHub Issues -->
 
-## Known Issues
+### Required elements
+
+Some elements are required in different scenario's such as `_define`.
+This is currently not checked against.
 
 ### constants/constant
 
@@ -134,7 +137,10 @@ Take a look at [this example by @Hipska](https://github.com/Super-Visions/sv-geo
 </itop_design>
 ```
 
-has error `cvc-type.3.1.1: Element 'constant' is a simple type, so it cannot have attributes. However, the attribute, 'id' was found.`
+Returns this error:
+
+> **cvc-type.3.1.1**: Element 'constant' is a simple type, so it cannot have
+  attributes. However, the attribute, 'id' was found.
 
 ### module_designs/module_design
 
@@ -146,7 +152,9 @@ has error `cvc-type.3.1.1: Element 'constant' is a simple type, so it cannot hav
 </itop_design>
 ```
 
-has error `cvc-elt.4.2: Cannot resolve 'portal' to a type definition for element 'module_design'.`
+Returns this error:
+
+> **cvc-elt.4.2**: Cannot resolve 'portal' to a type definition for element 'module_design'.
 
 ### module_designs/module_design/bricks/brick
 
@@ -164,7 +172,11 @@ has error `cvc-elt.4.2: Cannot resolve 'portal' to a type definition for element
 </itop_design>
 ```
 
-has error `cvc-attribute.3: The value 'Combodo\iTop\Portal\Brick\ManageBrick' of attribute 'xsi:type' on element 'brick' is not valid with respect to its type, 'QName'.`
+Returns this error:
+
+> **cvc-attribute.3**: The value 'Combodo\iTop\Portal\Brick\ManageBrick' of
+  attribute 'xsi:type' on element 'brick' is not valid with respect to its type,
+  'QName'.
 
 ### branding/themes/theme/imports/import
 
@@ -182,20 +194,31 @@ has error `cvc-attribute.3: The value 'Combodo\iTop\Portal\Brick\ManageBrick' of
 </itop_design>
 ```
 
-has errors
+Returns the following errors:
 
-- `cvc-elt.4.3: Type 'variables' is not validly derived from the type definition of element 'import'.`
-- `cvc-type.3.1.1: Element 'import' is a simple type, so it cannot have attributes. However, the attribute, 'id' was found.`
+> **cvc-elt.4.3**: Type 'variables' is not validly derived from the type
+  definition of element 'import'.
+>
+> **cvc-type.3.1.1**: Element 'import' is a simple type, so it cannot have
+  attributes. However, the attribute, 'id' was found.
 
-## Contributing
+## How to help
+
+**Contributions are very welcome!**
+
+- If you have experience with iTop data models or XSD, please help us improve
+  this schema.
+- Issues, suggestions and pull requests are highly appreciated.
+- Testing with real-world `datamodel.xml` files is extremely helpful.
 
-We welcome contributions of all kinds!
-If you would like to contribute, please check the [issues](https://github.com/rudnerbjoern/iTop-schema/issues) or open a pull request.
+If you would like to contribute, please check the [issues](https://github.com/rudnerbjoern/iTop-schema/issues)
+or open a pull request.
 
 ## Contributors
 
 Thanks to everyone who has contributed to this project!
 
 Special thanks to:
 
-- [@Hipska](https://github.com/Hipska) — for valuable additions, corrections, and improvements to the XSD.
+- [@Hipska](https://github.com/Hipska) — for valuable additions, corrections,
+  and improvements to the XSD.