Index: openacs-4/packages/acs-templating/www/doc/tagref/include.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/doc/tagref/include.html,v
diff -u -r1.1.1.1.4.1 -r1.1.1.1.4.2
--- openacs-4/packages/acs-templating/www/doc/tagref/include.html	19 Nov 2002 13:23:16 -0000	1.1.1.1.4.1
+++ openacs-4/packages/acs-templating/www/doc/tagref/include.html	20 Nov 2002 00:35:51 -0000	1.1.1.1.4.2
@@ -17,9 +17,10 @@
 as any other dynamic template; the developer may associate data sources and
 other properties to them.</p>
 
+
 <h3>Usage</h3>
 
-<pre>&lt;include src="subtemplate" attribute=value ...></pre>
+<pre>&lt;include src="subtemplate.adp" attribute=value ...></pre>
 
 <h3>Notes</h3>
     <ul>
@@ -31,20 +32,41 @@
 	  subtemplate, specify the variable name surrounded by at signs as
 	  the value:
 
-	<pre>&lt;include src="subtemplate" source_id="@source_id@" ...></pre>
+	<pre>&lt;include src="subtemplate.adp" source_id="@source_id@" ...></pre>
 
 	To pass a datasource, e.g. <code>users</code>, by reference, use
 	this notation:
 
-	<pre>&lt;include src="subtemplate" &persons="users" ...></pre>
+	<pre>&lt;include src="subtemplate.adp" &persons="users" ...></pre>
 
 	This is particularly useful for passing onerow and multirow data
 	sourced.  Note that in this case, if the subtemplate modifies the
 	value this will affect the includer.  When the datasource in the
 	included page has the same name (<code>&users="users"</code>), you
 	can use the shorthand <code>&="users"</code>.
       </li>
+     
+      <li>
+        It is important to note that variables passed through <tt>include</tt>
+	become available to the .tcl and .adp files being include'd, but it 
+	<b>does not</b> make them settable through <tt>ad_page_contract</tt>.
       
+        <p>
+	  So if you'd like to have a template that will return a fragment of a 
+	  page that you'd like to include in other pages, make sure its .tcl 
+	  component does not call <tt>ad_page_contract</tt>. 
+	</p>
+	
+	<p>
+	  If you'd like to include a full page (that is, one which calls 
+	  <tt>ad_page_contract</tt>) then instead of passing a parameter through 
+	  <tt>&lt;include&gt;</tt>, you could use 
+	  <tt><a href="http://openacs.org/api-doc/proc-view?proc=rp%5fform%5fput">rp_form_put</a></tt>
+	  to add the variable to that page's form. For additional 
+	  references, see how message-chunk is used throughout the forums package.
+	</p>
+      </li>
+      
       <li>
 	If the <tt>src</tt> attribute begins with a slash, the path is
 	assumed to be relative to the server root, the parent directory of
@@ -60,6 +82,5 @@
     
     <hr>
 
-    <a href="mailto:templating@arsdigita.com">templating@arsdigita.com</a>
   </body>
 </html>