Index: openacs-4/contrib/packages/portal/sql/postgresql/portal-core-create.sql
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/contrib/packages/portal/sql/postgresql/portal-core-create.sql,v
diff -u -r1.2 -r1.3
--- openacs-4/contrib/packages/portal/sql/postgresql/portal-core-create.sql	25 Sep 2003 02:12:16 -0000	1.2
+++ openacs-4/contrib/packages/portal/sql/postgresql/portal-core-create.sql	3 Jan 2004 01:42:57 -0000	1.3
@@ -48,6 +48,8 @@
 );
 
 comment on table portal_datasources is '
+    a portal datasource is the package of code that generates the content      
+    of a portal element. the foo-portlet packages create datasources.
 ';
 
 create table portal_datasource_parameters (
@@ -101,9 +103,9 @@
 ';
 
 comment on column portal_datasource_parameters.config_required_p is '
-    this parameter requires configuration. if configured_p is true then no
+    This parameter requires configuration. If configured_p is true then no
     action is needed at portal element creation since the portal element
-    can simply use the default value provided. if configured_p is false then
+    can simply use the default value provided. If configured_p is false then
     the portal element must provide a value for this parameter at creation
     time.
 ';
@@ -129,12 +131,18 @@
 );
 
 comment on table portal_layouts is '
+    a portal layout is a template that defines regions for portal 
+    elements to "fill in". Examples of layouts are two column and
+    three column
 ';
 
 comment on column portal_layouts.filename is '
+    the relative path to the layout template from the "portal/www/"
+    directory without the ending ".adp" extension. Example: "layouts/simple2"
 ';
 
 comment on column portal_layouts.resource_dir is '
+    XXX remove me
 ';
 
 create table portal_layout_regions (
@@ -152,13 +160,15 @@
 );
 
 comment on table portal_layout_regions is '
+    this table describes each of the regions in each of the layouts.
+    for example a two column layout would have two entries in this
+    table: region = 1 and region = 2. 
 ';
 
 comment on column portal_layout_regions.region is '
+    an ordering of regions in a layout starting from 1
 ';
 
--- Themes are templates with decoration for PEs, nothing more.
--- At this point they will just be bits of ADPs  in the filesystem
 create table portal_themes (
     theme_id                        integer
                                     constraint p_themes_theme_id_fk
@@ -176,24 +186,29 @@
 );
 
 comment on table portal_themes is '
+    decoration templates for portal elements
 ';
 
 comment on column portal_themes.filename is '
+    the relative path to the theme template from the "portal/www/"
+    directory without the ending ".adp" extension. Example: "themes/deco-theme"
 ';
 
 comment on column portal_themes.resource_dir is '
+    the relative path to the theme''s resource directory from the "portal/www/"
+    directory. The resource directory typically contains graphics files. 
+    Example: "themes/deco-theme"
 ';
 
--- Portals are essentially "containers" for PEs that bind to DSs.
--- Parties have, optionally have portals
--- Restrict to party check?
--- Roles and perms issues?
 create table portals (
     portal_id                       integer
                                     constraint p_portal_id_fk
                                     references acs_objects (object_id)
                                     constraint portals_pk
                                     primary key,
+    party_id                        integer
+                                    constraint p_party_id_fk
+                                    references parties (party_id),
     name                            varchar(200)
                                     default 'Untitled'
                                     constraint p_name_nn
@@ -208,12 +223,20 @@
                                     references portals (portal_id)
 );
 
+create index portals_party_id_idx on portals(party_id);
+
 comment on table portals is '
+    portals are containers of one or more portal pages mapped to a party.
 ';
 
 comment on column portals.template_id is '
+    a portal may have a template (another portal)
 ';
 
+comment on column portals.theme_id is '
+    portals one theme for all its contained pages
+';
+
 create table portal_pages (
     page_id                         integer
                                     constraint p_pages_page_id_fk
@@ -244,20 +267,15 @@
 create index portal_pages_prtl_page_idx on portal_pages (portal_id, page_id);
 
 comment on table portal_pages is '
+    portal pages are containers for portal elements. can be thought of
+    as the "tabs" on a portal
 ';
 
 comment on column portal_pages.sort_key is '
+    an ordering of the pages contained in the same portal starting from
+    0 for the first page and increasing in an gapless integer sequence
 ';
 
--- Support for multi-page portals (think my.yahoo.com)
--- PE are fully owned by one and only one portal. They are not
--- "objects" that live on after their portal is gone. One way to think
--- of them is a map b/w a portal and a DS, with satellite data of a
--- theme, a config, a region, etc.
---
--- No securtiy checks are done here. If you can view and bind to a DS you have
--- a PE for it.
-
 create table portal_elements (
     element_id                      integer
                                     constraint portal_elements_pk
@@ -306,12 +324,18 @@
 );
 
 comment on table portal_elements is '
+    the user-visible "box" on a portal page that displays the content of a datasource
 ';
 
 comment on column portal_elements.sort_key is '
+    an ordering of elements contained in the same region on a page starting from
+    0 for the first element and increasing in an gapless integer sequence
 ';
 
 comment on column portal_elements.state is '
+    one of the set "full" (normal), "shaded" (title bar only), "hidden" (not shown), 
+    or "pinned" (like full, but without state change links). portal themes impliment these
+    different behaviors based on a given elements state
 ';
 
 create table portal_element_parameters (
@@ -345,10 +369,6 @@
 create index p_element_params_element_key_idx on portal_element_parameters (element_id, key);
 
 comment on table portal_element_parameters is '
+    parameters on a per-element basis. the data structure is that of a multiset (aka bag)
+    where multiple entries with the same key (for the same element) are allowed ?? XXXX. 
 ';
-
-comment on column portal_element_parameters.config_required_p is '
-';
-
-comment on column portal_element_parameters.configured_p is '
-';
