User/DSL/Common-File-Syntax.md

+All domain-specific languages (DSLs) have a common syntax and base concepts. The syntax specifies a correct file and will be explained in the following.
+
+# Fundamentals
+We must first discuss modules and imports to understand the fundamental file structure. For EvoAl, each DSL file corresponds to a module. A module has a unique name allowing referencing it from other modules. The following example declares the module ```com.example```. Everything present between the following curly braces belongs to this module. In this example, the defined function ```helloWold``` belongs to the module ```com.example```.
+Furthermore, it is necessary to ```import``` a module to use its contents. The example imports everything from a definition language file containing the module ```com.example.foo```. Since it is an example, we do not use the contents of the imported module.
+
+
+```
+import "definitions" from com.example.foo;
+
+module com.example {
+  def void helloWorld();
+}
+```
+
+<details>
+<summary>Why do we need modules?</summary>
+When a computer parses a file, it has to assign a meaning to every character sequence it reads. This is done by having a large table giving sense to every name the computer has read. Not seldomly, we---as human beings---use names more than once but mean different things depending on the context. This ambiguity is problematic for computers since they are terrible at guessing the proper context. Therefore, modules add a context to a name, allowing the computer to distinguish between two things with the same name as long as they are from different contexts. For the computer, the function <tt>helloWorld</tt> is part of the module <tt>com.example</tt> and its official and unique name is <tt>com.example.helloWorld</tt>.
+</details> 
+
+# Names, names, everywhere, names
+We already used the term names. In a DSL file, everything needs a name so EvoAl can give the file's contents meaning. A name can start with a lower or upper-case letter or an underscore. Afterwards, it can continue with any of the already-mentioned characters or figures. The corresponding regular expression looks like ```[a-zA-Z_][a-zA-Z0-9_]*```. Since you may want more expressive names, EvoAl allows you to use any character sequence as long as you quote it with single quotes. Therefore, ```'my special name'``` is valid in EvoAl files.
+
+
+# File layout
+There is a rule you have to follow when you are creating modules. EvoAl derives the file location from a module's name. Therefore, EvoAl expects the example module to be stored in the location ```com/example.dl```. As you can see, for EvoAl, a module name corresponds to a path specification. Nota bene, the ```"definition"``` part of the example determines the file ending that is appended when looking up the corresponding file. 
+
+<details>
+  <summary>Imports and file endings</summary>
+  Currently, the following import categories exist and map to the following file endings:
+
+  | Category     | File Ending |
+  | ------------ | ----------- |
+  | data         | .ddl        |
+  | definitions  | .dl         |
+  | optimisation | .ol         |
+</details>
+
+# Search Path
+EvoAl uses a search path to find modules. First of all, it searches in the plugins of EvoAl itself (at the time of writing this is not true for the Eclipse plugins). The search path of additional modules, such as your data description and optimisation module can be configured using an additional EvoAl parameter `-Bcore:search-path=...`. You can specify multiple paths by using your OS-specific path-separator.
+
+
+# Comments and Documentation
+All DSLs offer single- and multi-line comments. Single-line comments start with `//`, and everything until the end of the line is reached will be ignored while parsing the file. Multi-line comments begin with the character sequence `/*` and end with the character sequence `*/`.
+