[clouchdb-cvs] CVS clouchdb/public_html

[peddy]

Update of /project/clouchdb/cvsroot/clouchdb/public_html
In directory clnet:/tmp/cvs-serv5626

Modified Files:
	index.html 
Log Message:
Field name encoding doc changes


--- /project/clouchdb/cvsroot/clouchdb/public_html/index.html	2007/12/21 20:04:34	1.11
+++ /project/clouchdb/cvsroot/clouchdb/public_html/index.html	2007/12/22 02:11:14	1.12
@@ -562,34 +562,32 @@
   </pre>
 
   <p>
-    As described above, clouchdb recognizes keyword symbols as field
-    names, this helps it distinguish .
+    By giving keyword symbols their special significance as field
+    names identifiers, clouchdb is able to distinguish between field
+    names and field values in certain situations which would otherwise
+    be ambiguous. For example, keyword symbols allow clocuhdb to
+    distinguish between associative lists and lists that contain
+    other, non-associative lists.
   </p>
 
   <p>
     Field names in CouchDb are case sensitive. Field names specified
-    with keyword symbols are normally stored as lower case characters
-    in CouchDb, however it is possible to use mixed case field names
-    as well.
-  </p>
-
-  <p>
-    To create a mixed case field name value you can use the 
+    with keyword symbols are normally converted to or from lower case
+    in communication with the CouchDb server, however it is possible
+    to specify case in field names like so:
   </p>
 
   <pre class="code">
-(create-document '((<b>"FieldName"</b> . "Value")) :id "string-mixed")
-(get-document "string-mixed")
-<b>=></b> ((:_ID . "string-mixed") (:_REV . "3753754378") (<b>:*FIELD-NAME</b> . "Value"))
-
-(create-document '((<b>:*field-name</b> . "Value")) :id "keyword-mixed")
-(get-document "keyword-mixed")
-<b>=></b> ((:_ID . "keyword-mixed") (:_REV . "2016717365") (<b>:*FIELD-NAME</b> . "Value"))
-
-(create-document '((<b>*field-name</b> . "Value")) :id "symbol-mixed")
-(get-document "symbol-mixed")
-<b>=></b> ((:_ID . "symbol-mixed") (:_REV . "4010145031") (<b>:*FIELD-NAME</b> . "Value"))
+;; Create a document with a mixed case field name. This document
+;; will appear in the database as, "fieldName"
+(create-document '((<b>:field-name</b> . "Value")) :id "mixed-case1")
+(get-document "mixed-case1")
+<b>=></b> ((:_ID . "mixed-case1") (:_REV . "2016717365") (<b>:*FIELD-NAME</b> . "Value"))
   </pre>
+  
+  <p>
+    But see <a href="#issues-and-bugs">Issues and Bugs</a>
+  </p>
 
   <p>
     The native document representation in the CouchDb protocol is
@@ -609,21 +607,12 @@
 (create-document '((:string . "String Value")
                    (:number . 42.0)
                    (:list . (milk eggs "green beans"))
-                   (:alist . ((:size . 3)
-                              (:string . "Another String")
+                   (:alist . ((:string . "Another String")
+                              (:size . 3)
                               (:list . ("un" "deux" "trois"))
                               (:another-alist . ((a . "A") (b . "B")))))))
 </pre>
 
-<p>
-  <b>Note:</b> There are issues related to the construction of
-  documents with non-trivial structure and their translation into
-  corresponding Json data, specifically with regard to confusion
-  between associative lists and
-  sequences. See <a href="#issues-and-bugs">Issues and Bugs</a> for
-  more information.
-</p>
-
 </blockquote>
 
 <p>
@@ -681,6 +670,7 @@
 </pre>
 <p>
 See (<a href="#sym-as-field-name-string">as-field-name-string</a>)
+ and <a href="#issues-and-bugs">Issues and Bugs</a>
 </p>
 </blockquote>
 
@@ -712,6 +702,7 @@
 </pre>
 <p>
   See (<a href="#sym-as-keyword-symbol">as-keyword-symbol</a>)
+  and <a href="#issues-and-bugs">Issues and Bugs</a>
 </p>
 </blockquote>
 
@@ -1116,6 +1107,11 @@
     support for attachments is not yet implemented in Clouchdb.
   </li>
 
+  <li><b>Mixed case field name encoding</b> Parenscript, cl-json, and
+  clouchdb don't always agree on how mixed-case field names should be
+  encoded and decoded. This will be addressed in a future release, in
+  the mean time, it's best to avoid this feature if possible.
+  </li>
 </ul>