<commit_before>## Mobo Model Development MANUAL
> Read the latest version [online at GitHub](https://github.com/Fannon/mobo/blob/master/examples/init/MANUAL.md).

### Premises
In order to learn mobo, it is mandatory to understand the basic concepts of JSON and JSON Schema first.

It is a very simple and concise standard and it should only take a few hours to learn it. 
There is a great tutorial published by the Space Telescope Science Institute. 
This time is a good investment anyhow, since JSON Schema can be used in other contexts as well.

Basic understanding of MW / SMW and SF is also highly recommended, since this is the target system and its architecture has a huge impact on how models are developed.

If the default templates are changed, an understanding of the Handlebars.js template engine is of advantage.

### Create a new project
To start with the model development, an empty project structure has to be created first. This is done through a mobo command within an empty directory.

```sh
$ mkdir newProject  # Create new dir
$ cd newProject     # Enter new dir
$ mobo --init       # Create bootstrap project
```

Mobo comes with two example projects, which may be a good starting point to learn mobo. They can be copied to the current project directory with the `--example` flag:

```sh
$ mobo --example shapes
```

### How to write the mobo-model (JSON vs YAML)
It is possible to write the model in either the [JSON](http://json.org/) or the [YAML](http://yaml.org/) notation. 
It is even possible to mix both, though this might get confusing.
In either case, the structure of JSON / mobo Schema must be adhered to.

It is a matter of personal taste which notation might be prefered. JSON is barebone, explicit and very strict. 
This is so, because it is a data-serialization format by design. JSON does not even support comments for example.
YAML is a bit more concise and more implicit (and therefore more forgiving). It is arguably easier to read and write by humans.

The mobo examples are available in both JSON and YAML notation. A comparison:

**JSON-Notation:**

```json
{
    "title": "Location",
    "description": "Location where hardware is deployed",
    "properties": [
        { "$extend": "/field/streetAdress" },
        { "$extend": "/field/streetNumber" },
        { "$extend": "/field/town" },
        { "$extend": "/field/country" }
    ],
    "required": ["streetAdress", "streetNumber", "town" ],
    "smw_prefix": {
        "header": 1,
        "wikitext": "Some prefix-description for the location"
    },
    "smw_postfix": {
        "wikitext": "Some postfix-description for the location"
    }
}
```

**YAML-Notation:**

```yaml
title: Location
description: Location where hardware is deployed
properties:
    - $extend: /field/streetAdress
    - $extend: /field/streetNumber
    - $extend: /field/town
    - $extend: /field/country
required:
    - streetAdress
    - streetNumber
    - town
smw_prefix:
    header: 1
    wikitext: Some prefix-description for the location
smw_postfix:
    wikitext: Some postfix-description for the location
```

To convert a project from JSON to YAML notation (or the other way around), the [yamljs](https://www.npmjs.com/package/yamljs) CLI tool is very helpful. 
Conversion should be easy and fast, so the notation format has no lock-in effect.

### The Development Model Structure
#### Overview
The default bootstrap project structure is now created. Please note that it contains many markdown files (.md) that provide more contextual documen-tation. README.md files will give more general information, while SCHEMA.md is an auto generated, more technical documentation of all available attributes.

Please note that subdirectories can be created freely, but they will be flat-tened on the reading step. This allows greater freedom in organizing the model. Moving files does not require to adjust paths in the model.

```sh
├── field
│   ├── README.md
│   └── SCHEMA.md
├── form
│   ├── README.md
│   └── SCHEMA.md
├── model
│   ├── README.md
│   └── SCHEMA.md
├── README.md
├── MANUAL.md
├── settings.json
├── settings.md
├── smw_page
│   └── README.md
├── smw_query<commit_msg>* Docs++<commit_after>## Mobo Model Development MANUAL
> Read the latest version [online at GitHub](https://github.com/Fannon/mobo/blob/master/examples/init/MANUAL.md).

### Premises
In order to learn mobo, it is mandatory to understand the basic concepts of JSON and JSON Schema first.

It is a very simple and concise standard and it should only take a few hours to learn it. 
There is a great tutorial published by the Space Telescope Science Institute. 
This time is a good investment anyhow, since JSON Schema can be used in other contexts as well.

Basic understanding of MW / SMW and SF is also highly recommended, since this is the target system and its architecture has a huge impact on how models are developed.

If the default templates are changed, an understanding of the Handlebars.js template engine is of advantage.

### Create a new project
To start with the model development, an empty project structure has to be created first. This is done through a mobo command within an empty directory.

```sh
$ mkdir newProject  # Create new dir
$ cd newProject     # Enter new dir
$ mobo --init       # Create bootstrap project
```

Mobo comes with two example projects, which may be a good starting point to learn mobo. They can be copied to the current project directory with the `--example` flag:

```sh
$ mobo --example shapes
```

### How to write the mobo-model (JSON vs YAML)
It is possible to write the model in either the [JSON](http://json.org/) or the [YAML](http://yaml.org/) notation. 
It is even possible to mix both, though this might get confusing.
In either case, the structure of JSON / mobo Schema must be adhered to.

It is a matter of personal taste which notation might be prefered. JSON is barebone, explicit and very strict. 
This is so, because it is a data-serialization format by design. JSON does not even support comments for example.
YAML is a bit more concise and more implicit (and therefore more forgiving). It is arguably easier to read and write by humans.

The mobo examples are available in both JSON and YAML notation. A comparison:

**JSON-Notation:**

```json
{
    "title": "Location",
    "description": "Location where hardware is deployed",
    "properties": [
        { "$extend": "/field/streetAdress" },
        { "$extend": "/field/streetNumber" },
        { "$extend": "/field/town" },
        { "$extend": "/field/country" }
    ],
    "required": [
        "streetAdress", 
        "streetNumber", 
        "town" 
    ],
    "smw_prefix": {
        "header": 1,
        "wikitext": "Some prefix-description for the location"
    },
    "smw_postfix": {
        "wikitext": "Some postfix-description for the location"
    }
}
```

**YAML-Notation:**

```yaml
title: Location
description: Location where hardware is deployed
properties:
    - $extend: /field/streetAdress
    - $extend: /field/streetNumber
    - $extend: /field/town
    - $extend: /field/country
required:
    - streetAdress
    - streetNumber
    - town
smw_prefix:
    header: 1
    wikitext: Some prefix-description for the location
smw_postfix:
    wikitext: Some postfix-description for the location
```

To batch-convert a project from JSON to YAML notation (or the other way around), the [yamljs](https://www.npmjs.com/package/yamljs) CLI tool is recommended. 
Conversion should be easy and fast, so the notation format has no lock-in effect.

### The Development Model Structure
#### Overview
The default bootstrap project structure is now created. Please note that it contains many markdown files (.md) that provide more contextual documen-tation. README.md files will give more general information, while SCHEMA.md is an auto generated, more technical documentation of all available attributes.

Please note that subdirectories can be created freely, but they will be flat-tened on the reading step. This allows greater freedom in organizing the model. Moving files does not require to adjust paths in the model.

```sh
├── field
│   ├── README.md
│   └── SCHEMA.md
├── form
│   ├── README.md
│   └── SCHEMA.md
├── model
│   ├── README.md
│   └── SCHEMA.md
├── README.md
├── MANUAL.md
├── settings.json
├── settings.md
├── smw_page
│   └── README.md
├── smw_query
{'fraction_non_alphanumeric': 0.09345124282982792, 'fraction_numerical': 0.0004780114722753346, 'mean_word_length': 3.5832420591456735, 'pattern_counts': {'":': 26, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 4, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5250729', 'n_tokens_mistral': 2387, 'n_tokens_neox': 2325, 'n_words': 1125}