[widgets] APIs and Events ready for pub

Hi All,
I've gone through the API and Events spec and done a general clean up
to ready the doc for publication. Changes:

* Added TOC, changed from definition list structure to headings for
easier access/overview of content
* Fixed a bunch of typos and copy/paste errors
* Added references
* Made terminology consistent with P&C spec
* Made terminology more consistent throughout the spec
* Removed some redundant markup
* Made links back to P&C spec, particularly as to how some values are
derived on Widget object.
* Highlighted a bunch of issues

Kind regards,
Marcos

-- 
Marcos Caceres
http://datadriven.com.au