Documentation update

[Rod Widdowson]

You'll have noticed that I've taken time out from the joys of ARIA and
JavaScript to start to flesh out the legacy documentation.

This is beginning to look quite reasonable from the point of view of "It
tells you what you need to know".  From the point of view of "It tells you
what you need to do and how" it sucks of course, but that was never the
design centre for this piece of the documentation.  That documentation needs
to be written by someone who is less close to the code, it will refer to
this stuff, but that will be it.

Thus far I have made significant inroads into Attribute Definitions.  I need
to do a refresh over the ScriptedAttribute definition and also write up the
Transient and CryptoTransient definitions which I'll only do once I
completely understand the use case (which is SAML1 only, right?)

Any comments and/or changes on what is there so far are more than welcome.

I'm now diving in to the Encoders and the Data Connectors which as a result
will be unstable for a week or so longer.  At that stage I'll particularly
be looking for review of the LDAP and RDBMS connectors.

One issue I feel does need some attention are the examples.   I'm always
including an example, but I want these to be relevant and reasonable.  In
particular with the Connectors and Encoders I am struggling to find relevant
& reasonable examples

One particular issue is the "spring native" syntax for the three data
connectors: Do we want to provide examples of this?  It seems to me that
this will be particularly useful for the StoredIdConnector when one really
does want to share the DataSource between the connector and the NameID code.
At least in the short term these examples are going to be the source of a
lot of people's best practice....

Rod