Index: openacs-4/packages/acs-core-docs/www/tcl-doc.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.adp,v diff -u -r1.1.2.4 -r1.1.2.5 --- openacs-4/packages/acs-core-docs/www/tcl-doc.adp 28 Sep 2015 07:54:25 -0000 1.1.2.4 +++ openacs-4/packages/acs-core-docs/www/tcl-doc.adp 23 Jun 2016 08:32:46 -0000 1.1.2.5 @@ -22,15 +22,15 @@ # # path from server home/filename # -# Brief description of the file's purpose +# Brief description of the file's purpose # -# author's email address, file creation date +# author's email address, file creation date # -# $‌Id: tcl-doc.xml,v 1.7 2006/07/17 05:38:38 torbenb Exp $ +# $‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 07:44:36 gustafn Exp $ #

In addition, the inputs expected by a Tcl page (i.e., form variables) would be enumerated in a call to ad_page_variables, in effect, documenting -the page's argument list.

The problem with these practices is that the documentation is +the page's argument list.

The problem with these practices is that the documentation is only accessible by reading the source file itself. For this reason, ACS 3.4 introduces a new API for documenting Tcl files and, on top of that, a web-based user interface for browsing the @@ -50,22 +50,23 @@

  • Facilitates automatic generation of human-readable documentation.

  • Promotes security, by introducing a standard and automated way to check inputs to scripts for correctness.

  • Allows graphical designers to determine easily how to customize -sites' UIs, e.g., what properties are available in templates.

  • Allows the request processor to be intelligent: a script can +sites' UIs, e.g., what properties are available in +templates.

  • Allows the request processor to be intelligent: a script can specify in its contract which type of abstract document it returns, and the request processor can transform it automatically into -something useful to a particular user agent. (Don't worry about -this for now - it's not complete for ACS 3.4.)

    • +something useful to a particular user agent. (Don't worry about +this for now - it's not complete for ACS 3.4.)

    ad_page_contract

    Currently ad_page_contract serves mostly as a replacement for ad_page_variables. Eventually, it will be -integrated closely with the documents API so that each script's +integrated closely with the documents API so that each script's contract will document precisely the set of properties available to graphical designers in templates. (Document API integration is -subject to change, so we don't decsribe it here yet; for now, you -can just consider ad_page_contract a newer, better, -documented ad_page_variables.)

    Let's look at an example usage of ad_page_contract:

    +subject to change, so we don't decsribe it here yet; for now,
+you can just consider ad_page_contract a newer, better,
+documented ad_page_variables.)
    Let's look at an example usage of ad_page_contract:
     
 # /packages/acs-kernel/api-doc/www/package-view.tcl
 ad_page_contract {
@@ -85,17 +86,17 @@
 
     \@author Jon Salz (jsalz\@mit.edu)
     \@creation-date 3 Jul 2000
-    \@cvs-id $‌Id$
+    \@cvs-id $‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 07:44:36 gustafn Exp $
 }
 
 
    Note that:
      
 
    • 
 By convention, ad_page_contract should be preceded by a
-comment line containing the file's path. The
+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 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
+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 syntax as in the
@@ -109,10 +110,11 @@
 (separated by commas):
        
 
      • 
 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.
      • 
+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 (ad_page_contract
 will fail and display and error if not). This flag, like the next,
@@ -127,8 +129,10 @@
 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 ad_page_variables, and is useful for
-handling form input generated by <SELECT MULTIPLE> tags and
+list if it's unspecified). This is analogous to the
+-multiple-list flag to
+ad_page_variables, and is
+useful for handling form input generated by <SELECT MULTIPLE> tags and
 checkboxes.
        For instance, if dest_user_id:multiple is specified in the
 contract, and the query string is
         
@@ -157,8 +161,8 @@
 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:
          
+description of the script's functionality, followed optionally
+by a series of named attributes tagged by at symbols (\@). You are encouraged to provide:
            
 
          • A description of the functionality of the page. If the
 description contains more than one sentence, the first sentence
 should be a brief summary.
          • 
@@ -168,10 +172,10 @@
 \@param parameter-namedescription...
 
        
 
      • An \@author tag for each
-author. Specify the author's name, followed his or her email
+author. Specify the author's name, followed his or her email
 address in parentheses.
      • A \@creation-date tag
 indicating when the script was first created.
      • A \@cvs-id tag containing the
-page's CVS identification string. Just use $‌Id: tcl-documentation.html,v 1.2 2000/09/19
+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.
        • 
 
      These \@ tags are optional,
@@ -191,9 +195,9 @@
 #
 # jsalz\@mit.edu, 7 Jun 2000
 #
-# $‌Id: tcl-doc.xml,v 1.7 2006/07/17 05:38:38 torbenb Exp $
+# $‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 07:44:36 gustafn Exp $
 
-

    you'll now write:

    +

    you'll now write:

     
 # /packages/acs-kernel/00-proc-procs.tcl
 ad_library {
@@ -203,23 +207,23 @@
 
     \@creation-date 7 Jun 2000
     \@author Jon Salz (jsalz\@mit.edu)
-    \@cvs-id $‌Id$
+    \@cvs-id $‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 07:44:36 gustafn Exp $
 
 }

    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 (\@). HTML formatting is allowed. You are +description of the script's functionality, followed optionally +by a series of named attributes tagged by at symbols (\@). HTML formatting is allowed. You are encouraged to provide:

    ($‌Id: tcl-doc.xml,v 1.7 2006/07/17 05:38:38 -torbenb Exp $)
    +
    ($‌Id: tcl-doc.html,v 1.49.2.10 2016/06/21 +07:44:36 gustafn Exp $)