Document a limitation of COPY's new CSV mode. Doc patch from Andrew

Dunstan, editorializing by Neil Conway.

diff --git a/doc/src/sgml/ref/copy.sgml b/doc/src/sgml/ref/copy.sgml
index 5d7de053e76c2781ed3f41ad539494578883fca6..8ba5409fd7f27f5959c25ea00ada0cf67caab996 100644 (file)
--- a/doc/src/sgml/ref/copy.sgml
+++ b/doc/src/sgml/ref/copy.sgml
@@ -1,5 +1,5 @@
 
 
@@ -433,13 +433,13 @@ COPY tablename [ ( 
    
 
    
-    It is strongly recommended that applications generating COPY data convert
+    It is strongly recommended that applications generating COPY data convert
     data newlines and carriage returns to the \n and
     \r sequences respectively.  At present it is
     possible to represent a data carriage return by a backslash and carriage
     return, and to represent a data newline by a backslash and newline.  
     However, these representations might not be accepted in future releases.
-    They are also highly vulnerable to corruption if the COPY file is
+    They are also highly vulnerable to corruption if the COPY file is
     transferred across different machines (for example, from Unix to Windows
     or vice versa).
    
@@ -484,15 +484,16 @@ COPY tablename [ ( 
 
     
     In general, the CSV format has no way to distinguish a
-    NULL from an empty string.
-    PostgreSQL's COPY handles this by
-    quoting. A NULL is output as the NULL string 
-    and is not quoted, while a data value matching the NULL string 
-    is quoted. Therefore, using the default settings, a NULL is
-    written as an unquoted empty string, while an empty string is
-    written with double quotes (""). Reading values follows 
-    similar rules. You can use FORCE NOT NULL to prevent NULL
-    input comparisons for specific columns.
+    NULL value from an empty string.
+    PostgreSQL's COPY handles this by
+    quoting. A NULL is output as the NULL
+    string and is not quoted, while a data value matching the
+    NULL string is quoted. Therefore, using the default
+    settings, a NULL is written as an unquoted empty
+    string, while an empty string is written with double quotes
+    (""). Reading values follows similar rules. You can
+    use FORCE NOT NULL to prevent NULL input
+    comparisons for specific columns.
    
 
    
@@ -500,7 +501,12 @@ COPY tablename [ ( 
      CSV mode will both recognize and produce CSV files with quoted
      values containing embedded carriage returns and line feeds. Thus
      the files are not strictly one line per table row like text-mode
-     files.
+     files. However, PostgreSQL will reject
+     COPY input if any fields contain embedded line
+     end character sequences that do not match the line ending
+     convention used in the CSV file itself. It is generally safer to
+     import data containing embedded line end characters using the
+     text or binary formats rather than CSV.