# -*- coding: UTF-8 -*-

# first some blocks of meta data, there can be several such blocks (the
# definition is part of the format, perhaps we'll allow extensions), and
# they're all well-formed ex-ml

[comment]
    ''' simple text-based tree storage format example document

        the format is inspired by xml and python
        
        xml mostly provided knowledge by its mistakes, though ex-ml certainly
        borrows features, and python for its great indentation features and
        quoting, escaping and namespacing

        the format tries to solve problems where xml has gone wild, most
        notably in the 'easy to read by both machines and men' idea, in the
        following ways:

          * strings must be quoted, like in programming languages, allowing
            proper recursive escaping (which was not possible in CDATA
            sections), quoted binary information, and discarding the idea of
            'ignorable whitespace', which is very hard to deal with properly in
            XML
          
          * it supports namespaces as a proper feature rather than than the
            bolted-on frankenfeature it is in XML - so that means no null
            namespace unless explicitly defined, attributes in the same
            namespace as the element on which they're defined unless explicitly
            defined, an explicit naming scheme (similar to Python variable
            names) and an explicit namespace operator, etc.

          * it uses indentation rather than tags to mark blocks, making
            'pretty-printing' part of the format rather than a hard-to-use
            optional feature
          
        however, by staying relatively close to XML, we can easily
        transform to and from XML, and use XML tools such as RNG/XSD schemas,
        XPath to perform searches and XSLT for transformations, etc.
    '''

# meta data
[meta]
    [author]
        'Guido Wesdorp'

# namespace declarations
[namespaces]
    [default]
        'http://docbook.org/ns/docbook'

# the last is the document block, authors are free to pick any name for the
# element (besides the reserved ones, though using a prefix can obviously
# solve that too)
[document]
    [book]
        [bookinfo]
            [author]
                [firstname]
                    'Guido'
                [surname]
                    'Wesdorp'
            [copyright]
                [year]
                    '2008'
                [holder]
                    'Guido Wesdorp'
        [chapter]
            [title]
                'My first Ex-ML docbook document'
            [para]
                'This document is well-formed Ex-ML, a markup language that '
                'is based on XML, but with some twists, making it easier '
                'to read, easier to write and easier to parse.'
            [sect1]
                [title]
                    'Why Ex-ML?'
                [para]
                    'XML has a number of huge disadvantages. Even though the '
                    'initial idea was to have a simple, generic markup '
                    'language that was both relatively easy to read by '
                    'humans and by computers, they failed in several ways. '
                    'Features such as \'ignorable whitespace\', and the way '
                    'namespaces are bolted on - trying not to break '
                    'compatibility with older XML parsers - make XML a pain '
                    'to write manually, and also make it quite hard to '
                    'write good parsers.'
                [para]
                    'By using ideas taken from the '
                    [ulink url='http://www.python.org/']
                        'Python programming language'
                    ' to create a format that is a bit more formal in dealing '
                    'strings, Ex-ML tries to take away the ambiguity of XML, '
                    'making it perhaps a little bit harder to learn at first, '
                    'but a lot more consistent - and thus easier to read, '
                    'write and execute - once you know the rules.'