DOC: enhance documentation on how to upgrade

CHANGELOG.md

@@ -9,20 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added ###
 - Identifiable class to represent the information used to identify Records.
-  This is now used by the crawler.
+- Added some StructureElements: BooleanElement, FloatElement, IntegerElement, 
+  ListElement, DictElement
 
 ### Changed ###
+- Some StructureElements changed (see "How to upgrade" in the docs):
+  - Dict, DictElement and DictDictElement were merged into DictElement.
+  - DictTextElement and TextElement were merged into TextElement.
 
-- The DictXYElements are now depricated. For example, instead of
-  DictTextElement you should use simply a TextElement. See READ
-  See The behavior of the following classes changed:
-  - DictElementConverter (old: DictConverter) now can use "match" keywords. If
-    none are in the definition, the behavior is as before.
-  - TextElement used the 'match' keyword before, which was applied to the
-    value. This is will in future be applied to the key instead and is now
-    forbidden to used. Please use 'match_name' or 'match_value'.
 
 ### Deprecated ###
+- The DictXYElements are now depricated and are now synonyms for the
+  XYElements.
 
 ### Removed ###
 

src/doc/how-to-upgrade.md

@@ -2,10 +2,15 @@
 # How to upgrade
 
 ## 0.2.x to 0.3.0
-If you had "match", "match_name" or "match_value" in the definition of a
+DictElementConverter (old: DictConverter) now can use "match" keywords. If
+none are in the definition, the behavior is as before. If you had "match",
+"match_name" or "match_value" in the definition of a
 DictConverter (StructureElement: Dict) before,
 you probably want to remove those. They were ignored before and are now used.
 
-If you used the 'match' keyword in the definition of TextElementConverter
+TextElement used the 'match' keyword before, which was applied to the
+value. This is will in future be applied to the key instead and is now
+forbidden to used. If you used the 'match'
+keyword in the definition of TextElementConverter
 (StructureElement: TextElement) before, you need to change the key from "match"
 to "match_name" in order to preserve the behavior.