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.