Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp 25 Apr 2018 08:38:27 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp 3 Sep 2024 15:37:32 -0000 1.5 @@ -1,7 +1,11 @@ -{/doc/acs-core-docs {ACS Core Documentation}} {ACS File Naming and Formatting Standards} +{/doc/acs-core-docs/ {ACS Core Documentation}} {ACS File Naming and Formatting Standards} ACS File Naming and Formatting Standards +

ACS -File Naming and Formatting Standards

<authorblurb>

By Michael Yoon and Aurelius -Prochazka

</authorblurb>

To ensure consistency (and its collateral benefit, +File Naming and Formatting Standards

+

By Michael Yoon and Aurelius Prochazka

+OpenACS docs are written by the named authors, and may be edited by +OpenACS documentation staff.

To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas:

File -Nomenclature

Usually we organize our files so that they mainly serve one of +Nomenclature

Usually, we organize our files so that they mainly serve one of the following three purposes:

  • displaying objects and their properties

  • manipulating or acting on objects in some way (by creating, editing, linking, etc)

  • housing procedures, packages, data models and other prerequisite @@ -101,7 +107,7 @@ <p> Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp </p> -

    This can be at the top or bottom of the file.

    Using ad_page_contract

    For non-library Tcl files (those not in the private Tcl +

    This can be at the top or bottom of the file.

    Using ad_page_contract

    For non-library Tcl files (those not in the private Tcl directory), use ad_page_contract after the file path comment (this supersedes set_the_usual_form_variables and ad_return_complaint). Here is an example of using ad_page_contract, @@ -148,7 +154,7 @@ does not generate QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete.

    • -

Using ad_library

For shared Tcl library files, use ad_library after the file path comment. +

Using ad_library

For shared Tcl library files, use ad_library after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like ad_page_contract. Don't forget to put the \@cvs-id in there. Here is an example of @@ -161,7 +167,7 @@ \@author John Doe (jdoe\@example.com) \@cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp } -

Non-Tcl Files

For SQL and other non-Tcl source files, the following file +

Non-Tcl Files

For SQL and other non-Tcl source files, the following file header structure is recommended:

 -- path relative to the ACS root directory
 --
@@ -200,7 +206,7 @@
 [ad_footer]"
 
 doc_return 200 text/html $page_content
-

The old convention was to call ReturnHeaders and then ns_write for each distinct chunk of the +

The old convention was to call util_return_headers and then ns_write for each distinct chunk of the page. This approach has the disadvantage of tying up a scarce and valuable resource (namely, a database handle) for an unpredictable amount of time while sending packets back to the browser, and so it @@ -214,8 +220,8 @@

Tcl Library Files

Further standards for Tcl library files are under discussion; we -plan to include naming conventions for procs.

($‌Id: filenaming.xml,v 1.8 2017/08/07 -23:47:54 gustafn Exp $)

+plan to include naming conventions for procs.

($‌Id: filenaming.xml,v 1.8.2.2 2021/09/02 +16:56:02 gustafn Exp $)