From 1e96e6d2a2c8457d3dae8a1db5386fa8a68ffbe1 Mon Sep 17 00:00:00 2001
From: Scott Smith <sakoht@cpan.org>
Date: Sun, 26 Feb 2012 14:26:50 -0800
Subject: [PATCH] Added a very simple example, and re-titled to match the goal,
 not the means.

The developer's perspective is "I know what page I want the user to see.
How do I make that happen with couchdb?".  The answer is to organize the
data in a view function, and then write a list function which will do the content-type
specific parts, such as generate HTML.  This page presumed the user already
knew that they needed to transform a view to get content, and was
already thinking from that perspective.  I hope my addition at the top
brings them across, before delving into details.
---
 draft/transforming.html | 45 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 41 insertions(+), 4 deletions(-)

diff --git a/draft/transforming.html b/draft/transforming.html
index d07415b..b72eefc 100644
--- a/draft/transforming.html
+++ b/draft/transforming.html
@@ -1,4 +1,4 @@
-<title>Transforming Views with List Functions</title>
+<title>Rendering Content Based-On Multiple Documents with List Functions</title>
 
 <meta charset="utf-8">
 
@@ -10,16 +10,53 @@
 
 <script src="../script.js"></script>
 
-<h2 id="transforming">Transforming Views with List Functions</h2>
+<h2 id="transforming">Rendering Content Based-On Multiple Documents with List Functions</h2>
 
-<p>Just as show functions convert documents to arbitrary output formats, CouchDB <em>list functions</em> allow you to render the output of view queries in any format. The powerful iterator API allows for flexibility to filter and aggregate rows on the fly, as well as output raw transformations for an easy way to make Atom feeds, HTML lists, CSV files, config files, or even just modified JSON.
+<p>Just as <em>show  functions</em> convert an <strong>individual</strong> document into an arbitrary output format, CouchDB <em>list functions</em> are used to render documents as a <strong>group</strong>. 
+
+<p>A list function is invoked with a URL specifying both the list function name and also the underlying view which will provide and organize the data.
+
+<p>For example, given this simple view, which indexes documents by "user_id":
+<pre>
+http://mysite/mydb/_design/myapp/_view/mydocs-by-user
+</pre>
+<pre>
+function(doc) {
+  if (doc.user_id) {
+    emit(doc.user_id, null);
+  }
+};
+</pre>
+
+
+<p>
+This list function renders the list of users in a simple HTML page:
+<pre>
+http://mysite/mydb/_design/myapp/_list/mylist/mydocs-by-user
+</pre>
+<pre>
+function(doc, req) {   
+    provides("html", function() {
+        html = "&lthtml&gt&ltbody&gt&ltol&gt\n";
+        while (row = getRow()) {
+            html += "&ltli&gt" + row.key + ":" + row.value + "&lt/li&gt\n";
+        }   
+        html += "&lt/ol&gt&lt/body&gt&lt/head&gt";
+        return html;
+    }); 
+}
+</pre>
+
+<p>Note that a list function can be used with a variety of views, or might be tailored to produce an elaborate page from a view designed specifically to organize data for it.
+
+<p>The powerful iterator API allows for flexibility to filter and aggregate rows on the fly, as well as output raw transformations for an easy way to make Atom feeds, HTML lists, CSV files, config files, or even just modified JSON.
 
 <p>List functions are stored under the <code>lists</code> field of a design document. Here’s an example design document that contains two list functions:
 
 <pre>
 {
   "_id" : "_design/foo",
-  "_rev" : "1-67at7bg",
+  "_rev" : "1-67aGt7bg",
   "lists" : {
     "bar" : "function(head, req) { var row; while (row = getRow()) { ... } }",
     "zoom" : "function() { return 'zoom!' }",