started reorganizing the information about low-level formatting parameters.

Define dialects in their own subsection.  Define low-level parameters in a
separate subsection.  Define set_dialect() and get_dialect() module-level
functions.

More to be done, but I have to get to work... ;-)

pep-0305.txt

@@ -61,17 +61,15 @@ Module Interface
 ================
 
 The module supports two basic APIs, one for reading and one for
-writing.  The reading interface is::
+writing.  The basic reading interface is::
 
-    reader(fileobj [, dialect='excel2000']
+    reader(fileobj [, dialect='excel2000'])
-                   [, quotechar='"']
-                   [, delimiter=',']
-                   [, skipinitialspace=False])
 
 A reader object is an iterable which takes a file-like object opened
-for reading as the sole required parameter.  It also accepts four
+for reading as the sole required parameter.  The optional dialect
-optional parameters (discussed below).  Readers are typically used as
+parameter is discussed below.  It also accepts several keyword
-follows::
+parameters which define specific format settings (see the section
+"Formatting Parameters").  Readers are typically used as follows::
 
     csvreader = csv.reader(file("some.csv"))
     for row in csvreader:
@@ -79,32 +77,57 @@ follows::
 
 The writing interface is similar::
 
-    writer(fileobj [, dialect='excel2000']
+    writer(fileobj [, dialect='excel2000'], [, fieldnames=list])
-                   [, quotechar='"']
-                   [, delimiter=',']
-                   [, skipinitialspace=False])
 
 A writer object is a wrapper around a file-like object opened for
-writing.  It accepts the same four optional parameters as the reader
+writing.  It accepts the same keyword parameters as the reader
-constructor.  Writers are typically used as follows::
+constructor.  In addition, it accepts an optional fieldnames
+argument.  This is a list which defines the order of fields in the
+output file.  It allows the write() method to accept mapping objects
+as well as sequence objects.
+
+Writers are typically used as follows::
 
     csvwriter = csv.writer(file("some.csv", "w"))
     for row in someiterable:
         csvwriter.write(row)
 
+To generate a set of field names as the first row of the CSV file, the
+programmer must explicitly write it, e.g.::
 
-Optional Parameters
+    csvwriter = csv.writer(file("some.csv", "w"), fieldnames=names)
--------------------
+    csvwriter.write(names)
+    for row in someiterable:
+        csvwriter.write(row)
 
-Both the reader and writer constructors take four optional keyword
-parameters:
 
-- dialect is an easy way of specifying a complete set of format
+Dialects
-  constraints for a reader or writer.  Most people will know what
+--------
-  application generated a CSV file or what application will process
+
-  the CSV file they are generating, but not the precise settings
+Readers and writers support a dialect argument which is just a
-  necessary.  The only dialect defined initially is "excel2000".  The
+convenient (string) handle on a group of lower level parameters.
-  dialect parameter is interpreted in a case-insensitive manner.
+Dialects will generally be named after applications or organizations
+which define specific sets of format constraints.  The initial dialect
+is "excel2000", which describes the format constraints of Excel 2000's
+CSV format.  Another possible dialect (used here only as an example)
+might be "gnumeric".
+
+Two functions are defined in the API to set and retrieve dialects::
+
+    set_dialect(dialect, pdict)
+    pdict = get_dialect(dialect)
+
+The pdict parameter is a dictionary whose keys are the names the
+formatting parameters defined in the next section.
+
+
+Formatting Parameters
+---------------------
+
+Both the reader and writer constructors take several specific
+formatting parameters, specified as keyword parameters.  The
+parameters are also the keys for the input and output mapping objects
+for the set_dialect() and get_dialect() module functions.
 
 - quotechar specifies a one-character string to use as the quoting
   character.  It defaults to '"'.
@@ -117,6 +140,11 @@ parameters:
   that whitespace immediate following a delimiter is part of the
   following field.
 
+- lineterminator specifies the character sequence which should
+  terminate rows.
+
+... XXX More to come XXX ...
+
 When processing a dialect setting and one or more of the other
 optional parameters, the dialect parameter is processed first, then
 the others are processed.  This makes it easy to choose a dialect,