Index: openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml,v
diff -u -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml 13 Mar 2001 22:59:26 -0000 1.1
+++ openacs-4/packages/acs-core-docs/www/xml/kernel/tcl-doc.xml 2 Feb 2002 03:47:32 -0000 1.2
@@ -15,7 +15,7 @@
The Big Picture
-In versions of the ACS prior to 3.4, the standard
+In versions of the OpenACS prior to 3.4, the standard
place to document Tcl files (both Tcl pages and Tcl library files) was in
a comment at the top of the file:
@@ -45,14 +45,14 @@
web-based user interface for browsing the documentation:
-ad_page_contract: Every Tcl page
-has a contract that explicitly defines what inputs the page
+ad_page_contract: Every Tcl page
+has a contract that explicitly defines what inputs the page
expects (with more precision than ad_page_variables) and
incorporates metadata about the page (what used to live in the top-of-page
comment). Like ad_page_variables, ad_page_contract
also sets the specified variables in the context of the Tcl page.
-ad_library: To be
+ad_library: To be
called at the top of every library file (i.e., all files in the
/tcl/ directory under the server root and
*-procs.tcl files under /packages/).
@@ -128,56 +128,56 @@
-By convention, ad_page_contract should be preceded
-by a comment line containing the file's path. The comment is on
+By convention, ad_page_contract should be preceded
+by a comment line containing the file's path. The comment is on
line 1, and the contract starts on line 2.
-ad_page_contract's first argument is
+ad_page_contract's first argument is
the list of expected arguments from the HTTP query (version_id,
public_p, kind, and format). Like
ad_page_variables, ad_page_contract sets the
corresponding Tcl variables when the page is executed.
-Arguments can have defaults, specified using the same
+Arguments can have defaults, specified using the same
syntax as in the Tcl proc (a two-element list where the first
element is the parameter name and the second argument is the default value).
-Arguments can have flags, specified by following the
+Arguments can have flags, specified by following the
name of the query argument with a colon and one or more of the following
strings (separated by commas):
-optional: the query argument doesn't
+optional: the query argument doesn't
need to be provided; if it's not, the variable for that argument simply
won't be set. For instance, if I call the script above without a
public_p in the query, then in the page body [info exists
public_p] will return 0.
-integer: the argument must be an integer
+integer: the argument must be an integer
(ad_page_contract will fail and display and error if not). This
flag, like the next, is intended to prevent clients from fudging query
arguments to trick scripts into executing arbitrary SQL.
-sql_identifier: the argument must be a SQL
+sql_identifier: the argument must be a SQL
identifier (i.e., [string is wordchar $the_query_var] must
return true).
-trim: the argument will be [string
+trim: the argument will be [string
trim]'ed.
-multiple: the argument may be specified
+multiple: the argument may be specified
arbitrarily many times in the query string, and the variable will be set to a
list of all those values (or an empty list if it's unspecified). This is
analogous to the -multiple-list flag to
@@ -201,7 +201,7 @@
-array: the argument may be specified
+array: the argument may be specified
arbitrarily many times in the query string, with parameter names with
suffixes like _1, _2, _3, etc. The
variable is set to a list of all those values (or an empty list if none are
@@ -226,8 +226,8 @@
-You can provide structured, HTML-formatted documentation for your
-contract. Note that format is derived heavily from Javadoc: a
+You can provide structured, HTML-formatted documentation for your
+contract. Note that format is derived heavily from Javadoc: a
general description of the script's functionality, followed optionally by
a series of named attributes tagged by at symbols (@). You are
encouraged to provide:
@@ -241,7 +241,7 @@
-A @param tag for each allowable query
+A @param tag for each allowable query
argument. The format is
@@ -257,13 +257,13 @@
-An @author tag for each author. Specify the
+An @author tag for each author. Specify the
author's name, followed his or her email address in parentheses.
-A @creation-date tag indicating when the
+A @creation-date tag indicating when the
script was first created.
-A @cvs-id tag containing the page's CVS
+A @cvs-id tag containing the page's CVS
identification string. Just use $Id: tcl-documentation.html,v 1.2
2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will
substitute an appropriate string when you check the file in.
@@ -328,13 +328,13 @@
-An @author tag for each author. Specify the
+An @author tag for each author. Specify the
author's name, followed his or her email address in parentheses.
-A @creation-date tag indicating when the
+A @creation-date tag indicating when the
script was first created.
-A @cvs-id tag containing the page's CVS
+A @cvs-id tag containing the page's CVS
identification string. Just use $Id: tcl-documentation.html,v 1.2
2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will
substitute an appropriate string when you check the file in.