coursebuilder/docs/quickstart.md

# concept

The concept behind coursebuilder is to store curricula descriptions in `YAML` files that can be versioned in a git repository. Unlike classic databases, an observable and well defined versioning is paramount in these descriptions as they are the legal foundation for study and exam regulations.

The following pieces play together here:

- `schema` files, usually a `schema.yaml`
- `mod` files, usually something along the lines of `mod.coursecode.yaml`
- `book` files describing a whole regulation set and course global details
- some sort of transformation with `coursebuilder` into Markdown that is piped through [pandoc](https://pandoc.org) in order to generate PDF, HTML and other representation from this code

# schema files

Schema files are responsible to describe the used structures in a database. The following datatypes are supported:

- `str` a simple string, can be accompanied with a `template`
- `enum` a classic enum datatype with a fixed set of values
- `num` a numeric datatype
- `multinum` an array type with the possibility to `spec` each value
- `multikey` a key-value type with additional numeric data associated with each key instance

# mod files (modules)

Modules describe a course in detail and implement an instance of the schema file. Especially `strings` and `enums` are translatable One of the plan is to use a validator to find inconsistencies automatically, like workloads that are not following the 30h = 1ECTS rule.


# datatypes

## `str` datatype

```yaml
# this would reside in a schema field on top level
# a field of name 'id'
id: # name of the field
    type: str # sets the datatype to str
    translatable: false # enforces the value is not translatable (default is true)
    label: { # label describes the meaning of the datatype in regards of the schema
        de: "Kürzel",   # translation of the label in German (de)
        en: "code" # translation of the label in English (en)
    }
```