# docopt(-icon) Syntax
This document explains the syntax for the docopt language dialect used by this project. The main reason
for having a slightly different syntax is to allow for a stricter and more robust definition of parts
of the syntax. The original documentation is (maybe intentionally) quite general.

All arguments are required by default (note: this may be reversed in the future if it is more usable).

## Sections

### Usage
```
Usage:
    {program_name} [optional-arguments] (this option | that option)
    {program_name} <repeating-argument>...
    {program_name} THIS IS ANOTHER MUTUTALLY EXCLUSIVE BRANCH
```

### Options
```
Options:
    -h, --help      Help.
    --version       Version.
```

## Individual elements

### program\_name
Just the name of the program. Part of the [Usage].

A program's name is **not** allowed to contain any upper-case, but all alphanumeric,
plus '-' and '\_' are allowed.

```
i_am_a_program-name
```

### <argument> ARGUMENT
Any positional argument is either all UPPER-case or starts with left angle bracket '<' and ends
with right angle bracket '>'. All arguments must be alphanumeric. They may also contain '-' or '\_'
but are not allowed to start with any of them.

```
<arguments-can-be-CAPS-here-too> == ARUMENTS-CAN-NOT-BE-LOWER_CASE-HERE
```

### -o --option
An element that starts with a '-' or '--' are short and long options respectively.

#### The dashes
Special cases exist for single dash "-" and double dash "--" which are not part of an option.

The single dash "-" signifies (by convention) that a program should read input from **stdin** instead of from the command-line arguments. This thus, interrupts any further argument parsing and instead
switches the program to read from stdin, instead, hence, the single dash "-" should be specified last on the command-line if any preceeding arguments whiches to be parsed.

The double dash "--" on the other hand is used as a separator (by convention again) to indicate that
every following argument is to be considered a series of arguments and not something that should be
attempted to be parsed as either subcommands or options.

### subcommand
Anything that is neither an *argument* or *option* is a subcommand which may have its own arguments or
options. Subcommands can have their own definitions of arguments or options that already exist somewhere
else, so for example if a subcommand wants its own "--help" option from the one overall to not have the
help message be as noisy that is possible.

A subcommand can essentially be regarded as its own small little program when it comes to definitions.

### [optional --elements]
Anything enclosed within square brackets is marked as optional. Elements may be enclosed
individually or in groups, it does not matter.

```
[optional --group --of --elements]
is the same as
[optional] [--group] [--of] [--elements]
```

### this\_element | another\_element
The pipe '|' in-between elements symbolizes that either one of the (group of) elements are valid.

### (required --elements)
Parenthesis "()" are used for grouping either mutually exclusive elements or grouping elements
that have to be specified together.

### ...
The triple-dot or elipsis ... is used to indicate an element can be repeated any number of times. This
can be used to repeat groups of elements as well.

### Descriptions