adds a thorough example of how the case sensitivity works

doc/docs/reference/core_fields.md

@@ -1,4 +1,4 @@
-# opal.core.fields
+  # opal.core.fields
 
 The `opal.core.fields` module contains helper functions for working
 with fields, as well as custom Opal field definitions.
@@ -35,3 +35,31 @@ or as the value in a CharField.
 
 By default this is case insensitive, pass in `case_sensitive=True` to make
 it case sensitive when matching against lookup lists or synonyms.
+
+e.g.
+```python
+class Duck(object):
+  name = ForeignKeyOrFreeText(Name)
+  show = ForiegnKeyOrFreeText(Show, case_sensitive=True)
+
+Name.objects.create(name="Scrooge")
+Show.objects.create(name="Duck Tales")
+
+scrooge = Duck()
+
+# by default we are case insensitive, so this will be saved
+# as a foreign key to a Name object
+scrooge.name = "scrooge"
+# ie now
+scrooge.name == "Scrooge"
+scrooge.name_fk == Name.objects.get(name="Scrooge")
+
+
+# this is not a case sensitive field so will be stored on the model as free
+# text
+scrooge.show = "duck tales"
+
+# ie
+scrooge.show_ft == "duck tales"
+
+```