Index: openacs-4/packages/acs-templating/tcl/parse-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/parse-procs.tcl,v
diff -u -r1.32 -r1.33
--- openacs-4/packages/acs-templating/tcl/parse-procs.tcl	25 May 2004 15:19:16 -0000	1.32
+++ openacs-4/packages/acs-templating/tcl/parse-procs.tcl	26 Jul 2004 12:32:31 -0000	1.33
@@ -1,27 +1,78 @@
-# ADP to Tcl Compiler for the ArsDigita Templating System
+ad_library {
+  ADP to Tcl Compiler for the ArsDigita Templating System,
+  Based on the original ADP to Tcl compiler by Jon Salz (jsalz@mit.edu)
 
-# Copyright (C) 1999-2000 ArsDigita Corporation
-# Authors: Karl Goldstein    (karlg@arsdigita.com)
-#          Stanislav Freidin (sfreidin@arsdigita.com)
-# Based on the original ADP to Tcl compiler by Jon Salz (jsalz@mit.edu)
+  Copyright (C) 1999-2000 ArsDigita Corporation
 
-# $Id$
+  This is free software distributed under the terms of the GNU Public
+  License.  Full text of the license is available from the GNU Project:
+  http://www.fsf.org/copyleft/gpl.html
 
-# This is free software distributed under the terms of the GNU Public
-# License.  Full text of the license is available from the GNU Project:
-# http://www.fsf.org/copyleft/gpl.html
+  @author Karl Goldstein
+  @author Stanislav Freidin
 
+  @cvs-id $Id$
+}
+
 namespace eval template {}
 
+ad_proc -public template::adp_include {
+  {-uplevel 1}
+  src
+  varlist
+} {
+  return a the output of a tcl/adp pair as a string.  adp_level is
+  set to the calling procedure so that pass by reference works.
+  and example of using this is in the search indexer for various content
+  types:
+  <pre>
+    bookshelf::book::get -book_id $book_id -array bookdata
+    set body [template::adp_include /packages/bookshelf/lib/one-book \ 
+                  [list &book "bookdata" base $base style feed]]
+  </pre>
+
+  The [list &book "bookdata" ...] tells adp_include to pass the book array by reference to the adp include, where it is
+  refered to via @book.field@.
+
+  @param uplevel how far up the stack should the adp_level be set to
+                 (default is the calling procedures level)
+  @param src should be the path to the tcl/adp pair relative to the server root, as
+             with the src attribute to the include tag.
+  @param varlist a list of {key value key value ... } varlist can also be &var foo
+             for things passed by reference (arrays and multirows)
+
+  @return the string generated by the tcl/adp pair.
+
+  @author Jeff Davis davis@xarg.net
+  @creation-date 2004-06-02
+
+  @see template::adp_parse
+} {
+  # set the stack frame at which the template is being parsed so that
+  # other procedures can reference variables cleanly
+  variable parse_level
+  lappend parse_level [expr [info level] - $uplevel]
+
+  set __adp_out [template::adp_parse [template::util::url_to_file $src] $varlist]
+
+  # pop off parse level
+  template::util::lpop parse_level
+
+  return $__adp_out
+}
+
 ad_proc -private template::adp_parse { __adp_stub __args } {
     Execute procedures to prepare data sources and then to output
-    template.
+    template.  Assumes adp_level is set on entry.  in general the 
+    public version template::adp_include should be used for generating 
+    strings from adp files.
 
     @param __adp_stub   The root (without the file extension) of the
                         absolute path to the template and associated code.
     @param __args       One list containing any number of key-value pairs 
                         passed to an included template from its container.  
                         All data sources may be passed by reference.
+  @see template::adp_include
 } {
   # declare any variables passed in to an include or master
   # TODO: call adp_set_vars instead.
Index: openacs-4/packages/acs-templating/tcl/util-procs.tcl
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/tcl/util-procs.tcl,v
diff -u -r1.18 -r1.19
--- openacs-4/packages/acs-templating/tcl/util-procs.tcl	20 Apr 2004 21:13:08 -0000	1.18
+++ openacs-4/packages/acs-templating/tcl/util-procs.tcl	26 Jul 2004 12:32:31 -0000	1.19
@@ -621,9 +621,11 @@
 }
 
 
-ad_proc -public template::util::multirow_foreach { name code_text } {
-    runs a block of code foreach row in a multirow 
+ad_proc -deprecated -public template::util::multirow_foreach { name code_text } {
+    runs a block of code foreach row in a multirow.
 
+    Using "template::multirow foreach" is recommended over this routine.
+
     @param name the name of the multirow over which the block of 
                 code is iterated
 
@@ -633,13 +635,14 @@
                      "fake_multirow" containing columns named "spanky" 
                      and "foobar",to set the column spanky to the value 
                      of column foobar use:<br> 
-                     <code>set fake_multirow.spanky 
-                           @fake_multirow.foobar@</code>
+                     <code>set fake_multirow.spanky @fake_multirow.foobar@</code>
                      <p>
                      note: this block of code is evaluated in the same 
                      scope as the .tcl page that uses this procedure
 
     @author simon
+
+    @see template::multirow
 } {
 
   upvar $name:rowcount rowcount $name:columns columns i i