Added documentation for enhanced cleanupName

README

@@ -141,10 +141,16 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 Change history
 --------------
 
-Version2.17b (08/05/2015)
+Version2.18a (08/13/2015)
 - Fix to regex pattern used to capture "<![CDATA[ ... ]]>".  The old
   pattern was dropping ending characters when the content contained
   HTML/XML markup.  Thanks to Adrian Cook for this fix.
+- Merged use of replacement patterns in cleanupName. With this fix
+  users can specify patterns to look for and replacements strings to
+  be used to clean up special characters and other patterns in
+  names.  There are some notes in the document; search for
+  "cleanup-name" in generateDS.html.  Thanks to Fedor Tyurin for
+  this fix.
 
 Version 2.17a (05/28/2015)
 - Modified setup.py so that process_includes.py is installed where

generateDS.html

@@ -229,7 +229,7 @@ They are used by updateversion.py. -->
 <col class="field-name" />
 <col class="field-body" />
 <tbody valign="top">
-<tr class="field"><th class="field-name">date:</th><td class="field-body">May 21, 2015</td>
+<tr class="field"><th class="field-name">date:</th><td class="field-body">August 13, 2015</td>
 </tr>
 </tbody>
 </table>
@@ -615,6 +615,12 @@ Options:
                                      to XML)
                              Example: &quot;write etree&quot;
                              Default: &quot;write&quot;
+    --preserve-cdata-tags    Preserve CDATA tags.  Default: False
+    --cleanup-name-dict=&lt;replacement-map&gt;
+                             Specifies replacement pairs when cleaning up
+                             names.
+                             Example: &quot;{':': 'colon', '-': 'dash', '.': 'dot'}&quot;
+                             Default: &quot;{':': '_', '-': '_', '.': '_'}&quot;
     -q, --no-questions       Do not ask questions, for example,
                              force overwrite.
     --session=mysession.session
@@ -848,6 +854,16 @@ and use any of lxml's other capabilities.</li>
 <p class="last">For example: <tt class="docutils literal"><span class="pre">--export=&quot;write</span> etree&quot;</tt> and <tt class="docutils literal"><span class="pre">--export=&quot;write&quot;</span></tt>.  The
 default is: <tt class="docutils literal"><span class="pre">--export=&quot;write</span> literal&quot;</tt>.</p>
 </dd>
+<dt>preserve-cdata-tags</dt>
+<dd>Preserve CDATA tags.  Normally, CDATA tags (&quot;&lt;![CDATA[ ... ]]&gt;&quot;)
+are dropped while parsing an XML instance document.  If this
+option is included, the generated code will preserve those tags
+and will write them out during export.  The default is False.</dd>
+<dt>cleanup-name-dict=&lt;replacement-map&gt;</dt>
+<dd>Specifies replacement pairs to be used when cleaning up names.
+Must be a string representation of a Python dictionary.
+Example: <tt class="docutils literal"><span class="pre">{':':</span> 'colon', <span class="pre">'-':</span> 'dash', <span class="pre">'.':</span> 'dot'}</tt>.
+Default when omitted: <tt class="docutils literal"><span class="pre">{':':</span> '_', <span class="pre">'-':</span> '_', <span class="pre">'.':</span> '_'}</tt>.</dd>
 <dt>q, no-questions</dt>
 <dd>Do not ask questions.  For example, if the &quot;-f&quot; command line
 option is omitted and the ouput file exists, then generateDS.py
@@ -3038,7 +3054,7 @@ following among others:</p>
 <div class="footer">
 <hr class="footer" />
 <a class="reference external" href="generateDS.txt">View document source</a>.
-Generated on: 2015-05-21 18:14 UTC.
+Generated on: 2015-08-13 20:46 UTC.
 Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 
 </div>

generateDS.txt

@@ -309,6 +309,12 @@ Here is the usage message displayed by ``generateDS.py``::
                                          to XML)
                                  Example: "write etree"
                                  Default: "write"
+        --preserve-cdata-tags    Preserve CDATA tags.  Default: False
+        --cleanup-name-dict=<replacement-map>
+                                 Specifies replacement pairs when cleaning up
+                                 names.
+                                 Example: "{':': 'colon', '-': 'dash', '.': 'dot'}"
+                                 Default: "{':': '_', '-': '_', '.': '_'}"
         -q, --no-questions       Do not ask questions, for example,
                                  force overwrite.
         --session=mysession.session
@@ -565,6 +571,25 @@ export
     For example: ``--export="write etree"`` and ``--export="write"``.  The
     default is: ``--export="write literal"``.
 
+preserve-cdata-tags
+    Preserve CDATA tags.  Normally, CDATA tags ("<![CDATA[ ... ]]>")
+    are dropped while parsing an XML instance document.  If this
+    option is included, the generated code will preserve those tags
+    and will write them out during export.  The default is False.
+
+cleanup-name-dict=<replacement-map>
+    Specifies replacement pairs to be used when cleaning up names.
+    Must be a string representation of a Python dictionary.  The
+    keys and values in this dictionary must be strings. The
+    intension is to enable us to replace special characters in names
+    that would cause the generation of invalid Python names, for
+    example the names of generated classes.  However, since a simple
+    string replacement is performed, you can replace any single
+    character or sequence of characters by any other single
+    character or sequence of characters.  Example: ``{':': 'colon',
+    '-': 'dash', '.': 'dot'}``.  Default when omitted: ``{':': '_',
+    '-': '_', '.': '_'}``.
+
 q, no-questions
     Do not ask questions.  For example, if the "-f" command line
     option is omitted and the ouput file exists, then generateDS.py
@@ -652,6 +677,17 @@ generateDS.py modifies the name of the attribute by adding "_attr"
 to its name.
 
 
+Cleaning up names with special characters etc.
+................................................
+
+``generateDS.py`` attempts to clean up names that contain special
+characters.  For example, a complexType whose name contains a dash
+would generate a Python class with an invalid name.  But, you can
+use this facility to make other changes to names as well.  See the
+notes on the command line option ``--cleanup-name-dict`` for more on
+this.
+
+
 The graphical user interface -- How to use it
 ==============================================================