
#############
Documentation
#############

The class ll.url.URL supports many common schemes and one additional
special scheme named root that deserves an explanation.

A root URL is supposed to be an URL that is relative to a "project"
directory instead to a base URL of the document that contains the URL.

Suppose we have the following document with the following base URL:

    >>> from ll import url
    >>> base = url.URL("root:company/it/about/index.html")

Now, if we have the following relative URL in this document:

    >>> url1 = url.URL("images/logos/spam.png")

the combined URL will be:

    >>> base/url1
    URL('root:company/it/about/images/logos/spam.png')

Now it we use this combined URL and interpret it relative to the base
URL we get back our original relative URL:

    >>> (base/url1).relative(base)
    URL('images/logos/spam.png')

Let's try a root URL now:

    >>> url2 = url.URL("root:images/logos/spam.png")

Combining this URL with the base URL gives us the same as url2:

    >>> base/url2
    URL('root:images/logos/spam.png')

But if we interpret this result relative to base, we'll get:

    >>> (base/url2).relative(base)
    URL('../../../images/logos/spam.png')

I.e. this gives us a relative URL that references url2 from base when
both URLs are relative to the same root directory.
