- note the 'fieldname => pattern' is deprecated
- more doc improvements