reformat documentation

some links are broken because scaladoc cannot reference `val's or `def's
as links
[ci skip]
more efficient way to construct a string

a string is no more the concatenation of documents representing
characters but the concatenation of documents representing lines
single implicit conversion for options

we can spare a lot of code by using the `T <% Doc' type bound which means that
there exist some implicit conversion in scope from `T' to `Doc'
more doc in README
a lot of new test cases
new tests for document constructors