Read YAML file with configuration and pointers to example data.

    Args:
        file_name (str): Name of the file, where the configuration is stored.

    Returns:
        dict: Parsed and processed data (see :func:`_process_config_item`).

    Example YAML file::
        html: simple_xml.xml
        first:
            data: i wan't this
            required: true
            notfoundmsg: Can't find variable $name.
        second:
            data: and this
        ---
        html: simple_xml2.xml
        first:
            data: something wanted
            required: true
            notfoundmsg: Can't find variable $name.
        second:
            data: another wanted thing

def read_config(file_name):
    """
    Read YAML file with configuration and pointers to example data.

    Args:
        file_name (str): Name of the file, where the configuration is stored.

    Returns:
        dict: Parsed and processed data (see :func:`_process_config_item`).

    Example YAML file::
        html: simple_xml.xml
        first:
            data: i wan't this
            required: true
            notfoundmsg: Can't find variable $name.
        second:
            data: and this
        ---
        html: simple_xml2.xml
        first:
            data: something wanted
            required: true
            notfoundmsg: Can't find variable $name.
        second:
            data: another wanted thing
    """
    dirname = os.path.dirname(
        os.path.abspath(file_name)
    )
    dirname = os.path.relpath(dirname)

    # create utf-8 strings, not unicode
    def custom_str_constructor(loader, node):
        return loader.construct_scalar(node).encode('utf-8')
    yaml.add_constructor(u'tag:yaml.org,2002:str', custom_str_constructor)

    config = []
    with open(file_name) as f:
        for item in yaml.load_all(f.read()):
            config.append(
                _process_config_item(item, dirname)
            )

    return config