Index: openacs-4/packages/rss-support/www/doc/index.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/rss-support/www/doc/index.html,v
diff -u -r1.2 -r1.3
--- openacs-4/packages/rss-support/www/doc/index.html	5 Nov 2001 02:53:33 -0000	1.2
+++ openacs-4/packages/rss-support/www/doc/index.html	5 Nov 2001 04:13:17 -0000	1.3
@@ -45,12 +45,12 @@
 
 <li>Publisher wishes to syndicate the Bar Forum in the Foo Bboard package instance.
 
-<li>Luckily, the bboard package implements the summary service contract for
-    context type bboard:forum of which the Bar Forum is an example.
+<li>Luckily, the bboard package implements the summary service
+    contract for individual forums.
 
 <li>Programmer registers the context identifier for the Bar Forum with
-summary service, indicating that the summary should be built no more
-than once per hour.
+the summary service, indicating that the summary should be built no
+more than once per hour.
 
 <li>Summary is available at /some/url/specific/to/bar/forum/summary.xml
 
@@ -66,13 +66,13 @@
 The feed generation service contract is called <code>RssGenerationSubscriber</code> and consists of two operations.
 
 <ol>
-<li><code>Datasource(context_identifier)</code> returns a data
+<li><code>Datasource(summary_context_id)</code> returns a data
 structure that contains all required metadata fields plus
 configuration information such as the RSS version to be used (0.91 or
 1.00 are supported at present).  This data structure contains
 everything needed to run <code>rss_gen</code>.
 
-<li><code>LastUpdated(context_identifier)</code> returns a timestamp
+<li><code>LastUpdated(summary_context_id)</code> returns a timestamp
 that is used to determine if the live summary is out of date.
 </ol>
 
@@ -82,35 +82,46 @@
 
 <p>
 
-Implementation suggestions:
+<em>RSS files.</em>All summaries are static files.  They are served
+from a static directory under the webroot specific by the
+RssGenOutputDirectory, which defaults to <code>rss</code>.  The full
+path to an RSS file is given by
+<blockquote><pre>
+/${RssGenOutputDirectory}/${ImplementationName}/${summary_context_id}/rss.xml
+</pre></blockquote>
 
-<ol>
-<li>All summaries are static files.  We will devise an appropriate file-naming scheme.
+Note: we assume that <code>${ImplementationName}</code> and
+<code>${summary_context_id}</code> contain OS- and URL-friendly
+characters.
 
-<li>A programmer registers a context with the summary service through API functions
-    (we can make it possible through web UI as well if that makes sense).
+<p>
 
-<li>A summary context is a content-containing domain which implements
-    the summary service contract.  A summary context is not identical
-    to a package instance.  For example, a single bboard package
-    instance might contain 3 summary contexts, one for each of the
-    forums in the instance.
+<em>Subscription.</em> A programmer registers a context with the
+summary service through API functions (we can make it possible through
+web UI as well if that makes sense).
 
-<li>A scheduled proc runs through all registered contexts, checking to see if the
-    live summary is stale and also if the minimum "quiet time" has elapsed.
+<p>
 
-<li>If the conditions for rebuild are met for a context, the scheduled
-    proc pulls out the context's summary data via
-    <code>Datasource</code> and uses the information to build a new
-    summary page.  This generic and simple scheme can be used to
-    dispatch different versions of the summary builder as well as to
-    support extensibility via modules. <font color=red>Warning:</font>
-    This design expects the output of <code>Datasource</code> to be
-    reasonably small, as we will have to parse this list-of-lists to
-    generate a summary.
+<em>Summary context.</em> A summary context is a content-containing
+domain which implements the summary service contract.  A summary
+context is not identical to a package instance.  For example, a single
+bboard package instance might contain 3 summary contexts, one for each
+of the forums in the instance.
 
-</ol>
+<p>
 
+<em>Service.</em> A scheduled proc runs through all subscribed
+contexts, checking to see if the live summary is stale and also if the
+minimum "quiet time" has elapsed.  If the conditions for rebuild are
+met for a context, the scheduled proc pulls out the context's summary
+data via <code>Datasource</code> and uses the information to build a
+new summary page.  This generic and simple scheme can be used to
+dispatch different versions of the summary builder as well as to
+support extensibility via modules. <font color=red>Warning:</font>
+This design expects the output of <code>Datasource</code> to be
+reasonably small, as we will have to parse this list-of-lists to
+generate a summary.
+
 <h3>2. Feed Parsing</h3>
 
 (aeg's vague ideas: needs can vary.  I can imagine slurping the content into