diff --git a/CHANGELOG.org b/CHANGELOG.org
new file mode 100644
--- /dev/null
+++ b/CHANGELOG.org
@@ -0,0 +1,18 @@
+* Series 1
+** 1.2.4.1  -- documentation updates; separate changelog file.
+** 1.2.4.0  -- added brick 0.17 compatibility
+** 1.2.3.0  -- added brick 0.16 compatibility
+** 1.2.2.1  -- added stack.yaml for using itemfield with stack
+** 1.2.2.0  -- added compatibility for GHC7.10
+** 1.2.1.0  -- added compatibility for older distributions
+** 1.2.0.0  -- intermediary state is "Pending"
+** 1.1.0.0  -- add support for 's' and 'f' keys and mouse events
+** 1.0.0.0  -- update from vty-ui to brick
+
+
+* Series 0
+** 0.3.1.0  -- add + key selector to select all successful targets
+** 0.3.0.0  -- rename from StateFieldSelector to ItemField
+** 0.2.0.1  -- more key events: G=toggle group, A=toggle all, !=mrk bad; add helpMsg
+** 0.2.0.0  -- more key events: Shift+Arrow to mark/unmark with move
+** 0.1.0.0  -- initial version
diff --git a/itemfield.cabal b/itemfield.cabal
--- a/itemfield.cabal
+++ b/itemfield.cabal
@@ -1,40 +1,25 @@
 name:                itemfield
-version:             1.2.4.0
+version:             1.2.4.1
 synopsis:            A brick Widget for selectable summary of many elements on a terminal
 description:         
 
-  This module provides a brick Widget that can be used with the
-  brick package to handle situations where there are lots of items
-  to represent to the user along with a corresponding state for each
-  item.  In addition, the user should be able to use the cursor
-  keys and space bar to mark one or more items (presumably so other
-  code can get the list of marked elements and perform a
-  state-changing operation).
-  .
-  * 0.1.0.0  -- initial version
-  .
-  * 0.2.0.0  -- more key events: Shift+Arrow to mark/unmark with move
-  .
-  * 0.2.0.1  -- more key events: G=toggle group, A=toggle all, !=mrk bad; add helpMsg
-  .
-  * 0.3.0.0  -- rename from StateFieldSelector to ItemField
-  .
-  * 0.3.1.0  -- add + key selector to select all successful targets
-  .
-  * 1.0.0.0  -- update from vty-ui to brick
-  .
-  * 1.1.0.0  -- add support for 's' and 'f' keys and mouse events
-  .
-  * 1.2.0.0  -- intermediary state is "Pending"
-  .
-  * 1.2.1.0  -- added compatibility for older distributions
-  .
-  * 1.2.2.0  -- added compatibility for GHC7.10
-  .
-  * 1.2.2.1  -- added stack.yaml for using itemfield with stack
-  .
-  * 1.2.3.0  -- added brick 0.16 compatibility
+  This module provides a brick Widget that can be used with the brick
+  package to handle situations where there are lots of items to
+  represent to the user along with a corresponding state for each
+  item.  One example of where the itemfield would be used is if there
+  are too many elements to reasonably show in a List widget, if those
+  elements are divided into groups, and if some status needs to be
+  shown for each element.
 
+  In addition, the user can use the cursor keys and space bar to mark
+  one or more items (presumably so other code can get the list of
+  marked elements and perform a state-changing operation).
+
+  There are two example programs built when the examples flag is True
+  (the default): bookcase and workreport.  Running these applications
+  should give a better idea of what the itemfield widget is and how it
+  can be used.
+
 license:             BSD3
 license-file:        LICENSE
 author:              Kevin Quick <quick@sparq.org>
@@ -49,6 +34,8 @@
                     compat/brick_016/TextUI/ItemField/BrickHelper.hs
                     compat/base_pre48/Compat.hs
                     compat/base48/Compat.hs
+
+data-files: CHANGELOG.org
 
 library
   hs-source-dirs:    src
diff --git a/src/TextUI/ItemField/Attrs.hs b/src/TextUI/ItemField/Attrs.hs
--- a/src/TextUI/ItemField/Attrs.hs
+++ b/src/TextUI/ItemField/Attrs.hs
@@ -76,7 +76,7 @@
 --
 -- @
 -- App { ...
---     , appAttrMap = const $ applyAttrMappings itemDefaultAttrs def
+--     , appAttrMap = const $ applyAttrMappings itemDefaultAttrs defaultAttrs
 --     ... }
 -- @
 --
@@ -87,8 +87,22 @@
 --     , appAttrMap = const
 --                    $ applyAttrMappings
 --                        [ (itemHeaderAddr, fg cyan), ... ]
---                    $ applyAttrMappings itemDefaultAttrs def
+--                    $ applyAttrMappings itemDefaultAttrs defaultAttrs
 --     ... }
+-- @
+--
+-- where defaultAttrs for Brick < 0.16 is:
+--
+-- @
+-- import Data.Default (def)
+-- defaultAttrs = def
+-- @
+--
+-- and for Brick >= 0.16, defaultAttrs is:
+--
+-- @
+-- import Graphics.Vty.Attrs (defAttrs)
+-- defaultAttrs = attrMap defAttrs []
 -- @
 itemDefaultAttrs :: [ (AttrName, Attr) ]
 itemDefaultAttrs = [ (itemGoodAttr, black `on` green `withStyle` bold)