Last documentation edits for 0.20 release.

Review and small corrections to HISTORY and RELEASE-NOTES.

Add comment with rationale for future cvs-table changes.

git-svn-id: https://svn.code.sf.net/p/docutils/code/trunk/docutils@9362 929543f6-e4f2-0310-98a6-ba3bd3dd1d04

1 files changed, 16 insertions, 3 deletions

diff --git a/docutils/parsers/rst/directives/tables.py b/docutils/parsers/rst/directives/tables.py
index 328554da1..446034828 100644
--- a/docutils/parsers/rst/directives/tables.py
+++ b/docutils/parsers/rst/directives/tables.py
@@ -234,12 +234,25 @@ class CSVTable(Table):
             super().__init__()
 
     class HeaderDialect(csv.Dialect):
-
-        """CSV dialect used for the "header" option data.
+        """
+        CSV dialect used for the "header" option data.
 
         Deprecated. Will be removed in Docutils 0.22.
         """
-
+        # The separate HeaderDialect was introduced in revision 2294
+        # (2004-06-17) in the sandbox before the "csv-table" directive moved
+        # to the trunk in r2309. Discussion in docutils-devel around this time
+        # did not mention a rationale (part of the discussion was in private
+        # mail).
+        # This is in conflict with the documentation, which always said:
+        # ""
+        # and did not change in this aspect.
+        #
+        # Maybe it was intended to have similar escape rules for rST and CSV,
+        # however with the current implementation this means we need
+        # `\\` for rST markup and ``\\\\`` for a literal backslash
+        # in the "option" header but ``\`` and ``\\`` in the header-lines and
+        # table cells of the main CSV data.
         delimiter = ','
         quotechar = '"'
         escapechar = '\\'