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 -r1.2
--- openacs-4/packages/acs-templating/www/doc/tagref/include.html	13 Mar 2001 22:59:27 -0000	1.1
+++ openacs-4/packages/acs-templating/www/doc/tagref/include.html	30 Nov 2002 17:25:12 -0000	1.2
@@ -17,6 +17,7 @@
 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.adp" attribute=value ...></pre>
@@ -44,7 +45,28 @@
 	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>