Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/configuration.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/configuration.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/configuration.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,116 @@ +<sect1 id="configuration" xreflabel="Advanced Configuration"> +<title>Advanced Configuration</title> + +<para> +The ACS 4.0 permissions system is about hierarchies and in particular +hiearchical containment. There are three important hiearchies: +</para> + +<orderedlist> +<listitem><para> +the user hierarchy (users, groups, and parties) +</para></listitem> + +<listitem><para> +the object hierarchy (objects nested in the contexts of others) +</para></listitem> + +<listitem><para> +the privilege hiearchy (privileges can entail other entails). +</para></listitem> +</orderedlist> + +<para> +This complexity of mechanism is designed to allow for +simplicity of use for programmers and administrators. Unfortunately, +interfaces to facilitate this simplicity of use are not here yet. Until then, +sophisticated control and configuration of BBoard necessitates an +understanding of these details. +</para> + +<para>The first hierarchy is straightforward. There are users and groups (or +together parties). Privileges granted to groups inherit to their members.</para> + +<para>Unless explicitly disabled (see below), privileges granted to parties are +inherited down an object hierarchy. The nature of the BBoard hierarchy is as +follows: subsites contain bboard package instances; bboard package instances +contain forums; forums contain both categories and messages. Privileges +granted to parties on the package instance are inherited to all the forums +nested within and so on.</para> + +<para>The third hiearchy is the least clear. Privileges can be nested into other +privileges. This lets us group related privileges like those for reading a +message and reading a forum together to allow us to easily grant "read +access" on a hiearchy of objects to a party even though there are +separate notions of "read a message" and "read a forum". +All the bboard privileges are nested in one of the following system level +"super"-privileges: "read", "write", +"create", "delete", and "admin".</para> + +<para>The full set of self explanatory bboard privileges is listed here:</para> + +<itemizedlist> +<listitem><para>bboard_create_forum</para></listitem> +<listitem><para>bboard_create_category</para></listitem> +<listitem><para>bboard_create_message</para></listitem> +<listitem><para>bboard_write_forum</para></listitem> +<listitem><para>bboard_write_category</para></listitem> +<listitem><para>bboard_write_message</para></listitem> +<listitem><para>bboard_read_forum</para></listitem> +<listitem><para>bboard_read_category</para></listitem> +<listitem><para>bboard_read_message</para></listitem> +<listitem><para>bboard_delete_forum</para></listitem> +<listitem><para>bboard_delete_category</para></listitem> +<listitem><para>bboard_delete_message</para></listitem> +<listitem><para>bboard_moderate_forum</para></listitem> +</itemizedlist> + + +<para> +Permissions on package instances are controlled through the "set +permissions" options on the appropriate folder in the admin site map +(/admin/site-map/). While in principal, the system should allow you to grant +permissions on lower level objects like forums or even individual messages +and categories, right now the UI is limited to granting permissions on the +application instance. SQL*Plus users or even URL hackers can probably figure +out how to do this if they're so inclined. +</para> + +<para>The default set of permissions granted in a bboard system are those +inherited from the main site:</para> + +<itemizedlist> +<listitem><para>Registered Users have bboard_create_message</para></listitem> + +<listitem><para>The Public has bboard_read_category</para></listitem> + +<listitem><para>The Public has bboard_read_forum</para></listitem> + +<listitem><para>The Public has bboard_read_message</para></listitem> + +<listitem><para>The Public has read</para></listitem> + +<listitem><para>[Admin user] admin</para></listitem> +</itemizedlist> + +<para> +Granting additional privileges to parties is fairly straightforward. For +moderated forums, creating a moderators group and granting them +"bboard_moderate_forum" (or "admin" if you're feeling +lucky) will let you delegate more of the discussion culling. +</para> + +<para>For significantly different configurations you might need to revoke +privileges already granted by the defaults. In this case you must configure +the package instance not to inherit permissions from the main site and then +add back any permissions needed. Granting "read" to registered +users and bboard_create_message to "Elite d00ds" will give you a +pseudo-private forum.</para> + +<para>Note: To facilitate usability in the common case, BBoard pages present the +option to post or reply even if the user doesn't have the +bboard_create_message privilege. If you remove posting ability from +registered users, you may wish to alter the templates to appropriately +display options.</para> + +</sect1> \ No newline at end of file Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/design.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/design.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/design.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,352 @@ +<sect1 id="design" xreflabel="Bboard Design Document"> +<title>ACS Messaging & BBoard Design Document</title> + + +<sect2 id="design-essentials"> +<title>Essentials</title> + + +<itemizedlist> +<listitem><para>User directory: <ulink url="/bboard/">/bboard/</ulink></para></listitem> + +<listitem><para><xref linkend="requirements"/></para></listitem> + +<listitem><para>Data model: <ulink url="/doc/sql/display-sql?url=bboard-create.sql&package_key=bboard">bboard-create.sql</ulink> + +<ulink url="/doc/sql/display-sql?url=acs-messaging-create.sql&package_key=acs-messaging"> +acs-messaging-create.sql</ulink></para></listitem> + +<listitem><para><ulink url="acs-messaging-and-bboard-dm.gif">Data-model diagram</ulink></para></listitem> +</itemizedlist> + +</sect2> + +<sect2 id="design-intro"> +<title>Introduction</title> + + +<para><computeroutput>bboard</computeroutput> is an ACS application package built to provide +scalable discussion forums to a community of users. As in older versions, +<computeroutput>bboard</computeroutput> provides:</para> + +<itemizedlist> +<listitem><para>posting, browsing, and reading of messages in discussion forums</para></listitem> + +<listitem><para>tools for moderators to maintain editorial standards</para></listitem> + +<listitem><para>categorization and retrieval for knowledge management</para></listitem> +</itemizedlist> + +<para> +The initial 4.0 implementation adds the following new features: +</para> + +<itemizedlist> +<listitem><para>fully templated presentation layer for easy customization</para></listitem> + +<listitem><para>improved access control on bboard operations to support a wide variety of +publisher policies</para></listitem> + +<listitem><para>support for multiple distinct configurations of the bboard package (e.g. +different forums and options at http://foo.com/bboard/ and +http://foo.com/pittsburgh/bboard/)</para></listitem> +</itemizedlist> + + + + + +<para>The ACS 4.0 version of <computeroutput>bboard</computeroutput> is a re-engineering of the data +model and presentation layer without certain capabilities present in the ACS +3.4 bboard. In future releases we intend to achieve the same level of +maturity as the older <computeroutput>bboard</computeroutput> while building on the flexibility +of the new design.</para> + +<para> +In particular this implementation (9/2000) does not include the following +features found in prior versions: +</para> + +<itemizedlist> +<listitem><para>support for expiring messages</para></listitem> + +<listitem><para>facilities for spamming dynamic classes of bboard users</para></listitem> + +<listitem><para>bboard messages with rich media attachments</para></listitem> + +<listitem><para>email alert functionality</para></listitem> + +<listitem><para>full text messages searching</para></listitem> +</itemizedlist> + +<para><computeroutput>bboard</computeroutput> is <emphasis>not</emphasis> intended to be the ultimate +customizable web based discussion system. It is intended to be a practical +and useful system that supports forums much like the photo.net Q&A forum. +Publishers with special needs are encouraged to implement their solution as a +module, much like bboard, built atop the framework <computeroutput>acs-messaging</computeroutput> +provides.</para> + +<para><computeroutput>acs-messaging</computeroutput> is a general purpose component that provides +threaded messaging services to higher level applications such as +<computeroutput>bboard</computeroutput>. The motivation is to provide a base level data model and +reusable presentation code that enables the rapid customization of messaging +applications. acs-messaging is intended to simplify modules like +<computeroutput>general comments</computeroutput> and <computeroutput>webmail</computeroutput>, as well as +specialized messaging applications such as <ulink url="http://www.scorecard.org/">scorecard</ulink>'s geospatial bboard. Such +a framework keeps custom organizational metadata, pageflow and navigation, +and publishing and moderation policy separate from the basic tools needed for +discussion.</para> + +</sect2> + +<sect2 id="design-history"> +<title>Historical Considerations</title> + +<para> +Over the course of ACS development, <computeroutput>bboard</computeroutput> has grown to +encompass a wide variety of functionality. Much of this functionality was +developed first for <computeroutput>bboard</computeroutput> and only later adapted into more +general mechanisms (e.g. alerts, security, group scoping, etc.,). However +<computeroutput>bboard</computeroutput> wasn't refactored to take advantage of the more +general facilities, and its complexity challenged those in need of custom +features. Furthermore there was a lot of ad hoc mechanism in both the data +model and page flow to support different presentation styles, navigation +schemes, and access control models. Although this <computeroutput>bboard</computeroutput> proved +to be useful, scalable, and reliable, the ability to maintain and extend this +code suffered. +</para> + +<para> +The ACS 4.0 release of bboard mimics the basic functionality of older +<computeroutput>bboard</computeroutput> versions but built atop new ACS 4.0 general mechanisms +(objects, persmissions, templating, acs-messaging, etc.,). +</para> + +</sect2> + +<sect2 id="design-competitors"> +<title>Competitive Analysis</title> + +<para> +An analysis of the bboard feature space should be added here. +</para> + +<itemizedlist> +<listitem><para>USENET a la gnus</para></listitem> + +<listitem><para>slashdot</para></listitem> + +<listitem><para>Userland</para></listitem> + +<listitem><para>????</para></listitem> +</itemizedlist> + +</sect2> + +<sect2 id="design-tradeoffs"> +<title>Design Tradeoffs</title> + + +<para>How does one reconcile all the possible discussion forums mentioned above +into a single module? One does not! <computeroutput>bboard</computeroutput> is precisely one way +to implement a discussion forum and should not be all things. In time, there +should be a toolkit of components (user interface, data model, and +procedural) for developers to assemble their custom.</para> + +<para>Although many of the entities in the data model are implemented as +subtyples of ACS object, we avoid using information from the ACS object table +for anything but auditing purposes. For example, we could store a +message's author in the ACS object creation_user field, however to keep +query performance in line we rather use the author field in acs_messages.</para> + +</sect2> + +<sect2 id="design-api"> +<title>API</title> + + +<para>As of the initial ACS 4.0 release, <computeroutput>acs-messaging</computeroutput> and +<computeroutput>bboard</computeroutput> do not provide well defined programming interfaces.</para> + +<para>Although convenience functions will be provided for basic transactions on +the <computeroutput>acs-messaging</computeroutput> and <computeroutput>bboard</computeroutput> entities, it remains +to be seen what sort of abstraction layer is most appropriate.</para> + +</sect2> + +<sect2 id="design-data-model"> +<title>Data Model Discussion</title> + + +<para><computeroutput>acs-messaging</computeroutput> defines the view <computeroutput>acs_messages_all</computeroutput> +for the storage and access of threaded text messages and assorted information +relevant to their display, access, and creation. Under the covers +<computeroutput>acs-messaging</computeroutput> use the content repository for underlying +storage.</para> + +<para><computeroutput>bboard</computeroutput> uses <computeroutput>acs-messaging</computeroutput> messages, and +organizes them into forums and categories. For the purposed of the ACS +permissions system, forums contain messages, and so any permissions on a +forum will default to being inherited for individual messages.</para> + +<para>A forum may be designated as moderated, in which case explicit approvals +or denials are stored in the <computeroutput>bboard_message_moderation</computeroutput>. Messages +without entries in the moderation table are considered unseen, and will be +displayed or hidden in moderated forums based on policy.</para> + +<para>Each forum may have some number of categories, tags denoting further +specialization within a forum. Messages of a forum may be tagged as being in +any of the categories pertaining to that forum.</para> + +<para><emphasis role="strong">Permissions</emphasis></para> + +<para> +Permissions in ACS 4.0 involve 3 interrelated hierarchies: users & +groups, objects, and privileges. The user and group hiearchy is generally +explained elsewhere. The short explanation: +</para> + +<para>The long explanation: BBoard defines the following permissions:</para> + +<itemizedlist> +<listitem><para>nested under the create permission:</para></listitem> + +<listitem><para>bboard_create_forum</para></listitem> + +<listitem><para>bboard_create_category</para></listitem> + +<listitem><para>bboard_create_message</para></listitem> + +<listitem><para>nested under the write permission:</para></listitem> + +<listitem><para>bboard_write_forum</para></listitem> + +<listitem><para>bboard_write_category</para></listitem> + +<listitem><para>bboard_write_message</para></listitem> + +<listitem><para>nested under the read permission:</para></listitem> + +<listitem><para>bboard_read_forum</para></listitem> + +<listitem><para>bboard_read_category</para></listitem> + +<listitem><para>bboard_read_message</para></listitem> + +<listitem><para>nested under the delete permission:</para></listitem> + +<listitem><para>bboard_delete_forum</para></listitem> + +<listitem><para>bboard_delete_category</para></listitem> + +<listitem><para>bboard_delete_message</para></listitem> + +<listitem><para>nested under the moderate permission:</para></listitem> + +<listitem><para>bboard_moderate_forum</para></listitem> +</itemizedlist> + +</sect2> + +<sect2 id="design-ui"> +<title>User Interface</title> + +<para>...</para> + +</sect2> + +<sect2 id="design-config"> +<title>Configuration/Parameters</title> + +<para>...</para> + +</sect2> + +<sect2 id="design-accept-tests"> +<title>Acceptance Tests</title> + +<para>...</para> + +</sect2> + +<sect2 id="design-future"> +<title>Future Improvements/Areas of Likely Change</title> + + +<para>Much of the functionality of the ACS content repository will eventually +provide tangible benefits to <computeroutput>bboard</computeroutput> and any +<computeroutput>acs-messaging</computeroutput> application. Foremost among these features will be +full text searching and rich media attachments.</para> + +<para>When ACS provides a general mechanism for an installation to send and +receive email, <computeroutput>bboard</computeroutput> can provide email alerts and email based +reply and post.</para> + +</sect2> + +<sect2 id="design-authors"> +<title>Authors</title> + +<para> +<ulink url="mailto:akk@arsdigita.com">Anukul Kapoor</ulink> +</para> + +</sect2> + +<sect2 id="design-rev-history"> +<title>Revision History</title> + +<informaltable> +<tgroup cols="4"> +<thead> +<row> +<entry>Document Revision #</entry> +<entry>Action Taken, Notes</entry> +<entry>When?</entry> +<entry>By Whom?</entry> +</row> +</thead> + +<tbody> + +<row> +<entry>0.2</entry> +<entry>Revision</entry> +<entry>09/19/2000</entry> +<entry>Anukul Kapoor</entry> +</row> + + +<row> +<entry>0.1</entry> +<entry>Creation</entry> +<entry>09/01/2000</entry> +<entry>Anukul Kapoor</entry> +</row> + + +</tbody></tgroup></informaltable> + +<!-- notes for writing + +different organizations of discussion messaging (general comments, webmail, different bboard implementations) -> acs messaging with bboard layer above + +inconsistent 'new' messages behavior -> read-thread-user-map + +inconsistent alert and email behavior -> centralized alerts and email processing + +fully templated for flexible presentation +and simple interface for + +acs-messaging aims to provide: + centralized storage, searching of message threads + generalized integration with email messaging +--> + + + + +</sect2> + +</sect1> + Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/index.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/index.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/index.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,66 @@ +<?xml version='1.0' ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://developer.arsdigita.com/docbook/dtd/4.1.2/docbookx.dtd" [ + +<!-- For Everyone --> +<!ENTITY introduction SYSTEM "intro.xml"> +<!ENTITY support SYSTEM "support.xml"> +<!ENTITY notes SYSTEM "notes.xml"> + +<!-- For Admins --> +<!ENTITY installation SYSTEM "installation.xml"> +<!ENTITY configuration SYSTEM "configuration.xml"> + +<!-- For Developers --> +<!ENTITY design SYSTEM "design.xml"> +<!ENTITY requirements SYSTEM "requirements.xml"> + + +]> + +<book> +<title>Bboard Documentation</title> + + + <chapter id="for-everyone"> + <title>For Everyone</title> + + <sect1> + <title>Overview</title> + <para>Brief introduction, support possibilities and release notes</para> + </sect1> + + &introduction; + &support; +<!-- ¬es; +--> + </chapter> + + + <chapter id="for-admins" xreflabel="For Admins"> + <title>For Admins</title> + + <sect1> + <title>Overview</title> + <para>Installation, maintenance</para> + </sect1> + + &installation; + &configuration; + + </chapter> + + <chapter id="for-developers" xreflabel="For Developers"> + <title>For Developers</title> + + <sect1> + <title>Overview</title> + <para>Requirements, design</para> + </sect1> + + &requirements; + &design; + + </chapter> + +</book> Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/installation.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/installation.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/installation.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,185 @@ +<sect1 id="installation" xreflabel="Installation and Configuration of Bboard"> +<title>Installation and Configuration of Bboard</title> + +<sect2 id="installation-installation"> +<title>Installation</title> + +<para> +Using bboard requires an operating ACS 4.0.1 installation. If you haven't +upgraded, do so first. +</para> + +<para> +Installing and enabling the bboard package should be +relatively painless, just: +</para> + +<orderedlist> +<listitem><para> +go to your server's +<ulink url="/acs-admin/apm/package-load">/acs-admin/apm/package-load</ulink> +page, enter +"www.arsdigita.com/acs-repository/download/apm/bboard-4.0.2.apm" +in the first text box +</para> +</listitem> + +<listitem> +<para> +click the button and follow the instructions +</para> +</listitem> +</orderedlist> + +<para> +If you're reading this on your own server, you've +probably already done this. +</para> + +<para> +Once the package is installed and enabled, a subsite administrator can +<emphasis>mount</emphasis> instances on their subsite. If you're the +lone &uuml;ber-admin +of your site, you can just go to your site's +<ulink url="/admin/site-map/">/admin/site-map/</ulink> page and: +</para> + +<orderedlist> + +<listitem><para> +create a new subfolder under the "/" directory +</para></listitem> + +<listitem><para> +Pick a creative +label for your subfolder like "bboard" or "dgroup" +</para></listitem> + +<listitem><para> +Select +"new application" for that subfolder, and choose BBoard from the +pulldown menu. +</para></listitem> +</orderedlist> + +<para> +It is probably best to label the application instance the same +as your subfolder; do otherwise if it helps you keep your site straight.</para> + +<para>At this point you should have a BBoard instance mounted in the subfolder +directory - for the rest of this document I assume that you've choosen "/bboard". +</para> + +</sect2> + +<sect2 id="installation-config"> +<title>Initial Configuration</title> + +<para> +Before you can start using the Bboard you have to create some forums: +</para> + +<orderedlist> +<listitem><para> +log in as an administrator +</para></listitem> + +<listitem><para> +surf to <computeroutput>/bboard</computeroutput> and click "Create a forum" +</para> +</listitem> +</orderedlist> + +<para> +After you've created one or more forums you can specify the settings for your instance +of Bboard from the <ulink url="/admin/site-map/">Site Map</ulink> +(click <computeroutput>set parameters</computeroutput>). +</para> + +<para> +Most of the setting you see require a "t" (for true) or "f" (for false). +The rest should be self-explanatory. +</para> + +<variablelist> +<varlistentry> +<term><emphasis role="strong"><computeroutput>ThreadingEnabledP</computeroutput></emphasis> + +</term> + +<listitem><para>This enables or disables threading indentation on a single thread basis. +"t" enables threading and "f" (the default) turns it +off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><emphasis role="strong"><computeroutput>MailFriendEnabledP</computeroutput></emphasis> + +</term> + +<listitem><para>This enables the option for users to mail copies of a bboard posting to a +friend (or themselves). Since this functionality can be abused, consider +disabling the functionality.</para></listitem> +</varlistentry> + +<varlistentry> +<term><emphasis role="strong"><computeroutput>UserPostsEditableP</computeroutput></emphasis> + +</term> + +<listitem><para>This grants users privileges to edit their own message. Note: toggling +this parameter will not change the ability of user to edit existing messages. +This parameter only effects whether users are granted rights to edit at the +message's posting time. This must be enabled for attachments to +work.</para></listitem> +</varlistentry> + +<varlistentry> +<term><emphasis role="strong"><computeroutput>UserPostsDeletableP</computeroutput></emphasis> + +</term> + +<listitem><para>This grants users privileges to delete their own +message. Note: This parameter only effects whether users are granted +rights to edit their message's with the +<computeroutput>UserPostsEditableP<computeroutput>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><emphasis role="strong"><computeroutput>AttachmentsEnabledP</computeroutput></emphasis> + +</term> + +<listitem><para>This lets users who have edit capability on a message upload file or +image attachments.</para></listitem> +</varlistentry> + +<varlistentry> +<term> +<emphasis role="strong"><computeroutput>MaxAttachmentSize</computeroutput></emphasis> +</term> + +<listitem><para>This specifies the maximum size in bytes to accept for binary +attachments. The default is 1 megabyte.</para></listitem> +</varlistentry> + +<varlistentry> +<term> +<emphasis role="strong"><computeroutput>DisplayLastNDays</computeroutput></emphasis> +</term> + +<listitem><para>This parameter controls how many days worth of recent messages are +displayed on the forum overview page by default. 0 specifies that all +messages should be displayed.</para></listitem> +</varlistentry> +</variablelist> + +<para> +If you want to learn how to set more advanced parameters of your Bboard instance, +read <xref linkend="configuration"/>. +</para> + +</sect2> + +</sect1> + Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/intro.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/intro.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/intro.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,21 @@ +<sect1 id="introduction" xreflabel="Bboard Introduction"> +<title>Bboard Introduction</title> + +<sect2 id="whatisbboard" xreflabel="What is Bboard?"> +<title>What is Bboard?</title> + +<para> +BBoard is a web based discussion system for the ArsDigita Community +System. Once installed and mounted, bboard instances provide +locations on the site that contain discussion forums +(e.g. http://developer.arsdigita.com/bboard/). Users can post and +read messages within individual forums, which are generally geared +towards specific topics or audiences. This basic functionality is +supplemented with a variety of additional features including image and +file message attachments, email notification, categorization, and +moderation facilities. +</para> + +</sect2> + +</sect1> \ No newline at end of file Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/notes.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/notes.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/notes.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,42 @@ +<sect1 id="misc" xreflabel="Release Notes and Miscellaneous Stuff"> +<title>Release Notes and Miscellaneous Stuff</title> + +<sect2 id="release-notes"> +<title>Release Notes</title> + +<para> +This is the final release of BBoard 4.0.2. This release requires ACS +Core 4.0.1, available from the <ulink +url="http://www.arsdigita.com/acs-repository/">ACS Repository</ulink>. +</para> + +<para>This version offers a working drop script, numerous bugfixes, and some +notable improvements such as:</para> + +<itemizedlist> +<listitem><para>support for binary attachments</para></listitem> + +<listitem><para>letting users email postings to others</para></listitem> + +<listitem><para>more informative displays</para></listitem> + +<listitem><para>performance improvements</para></listitem> +<listitem><para></para></listitem> +<listitem><para></para></listitem> +<listitem><para></para></listitem> +</itemizedlist> + + +</sect2> + +<sect2 id="misc-notes"> +<title>Miscellaneous Notes</title> + +<para> +Text searching requires the maintaince of the content repository +<computeroutput>cr_rev_content_index</computeroutput> index; either by hand or by context. +</para> + +</sect2> + +</sect1> \ No newline at end of file Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/requirements.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/requirements.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/requirements.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,427 @@ +<sect1 id="requirements" xreflabel="Bulletin Board Requirements"> +<title>Bulletin Board Requirements</title> + +<authorblurb><para> +By <ulink url="mailto:akk@arsdigita.com">Anukul Kapoor</ulink>, <ulink url="mailto:psu@arsdigita.com">Pete Su</ulink> and <ulink url="mailto:mthomas@arsdigita.com">Mark Thomas</ulink> +</para></authorblurb> + +<sect2 id="requirements-intro"> +<title>Introduction</title> + + +<para>This document outlines necessary functionality and behavior of the new ACS +4.0 Bulletin Board system (herein referred to as bboard).</para> + +<para>Our intent (as of 8/2000) is to start with a simple implementation that +can accomodate future advanced functionality. As a result, these requirements +may not prescribe functionality present in the ACS 3.4 bboard system. We are +using the uslaw-bboard module as inspiration for a lightweight +implementation.</para> + +<para>Futhermore, this document is conservative in attempting to describe the +ultimate framework for modular web based messaging. We hope such an +architecture may well be born out of iterative process when designing this +system. However, the scope is being primarily limited to functional +requirements.</para> + +<para>The <link linkend="requirements-future">future requirements</link> should inform the design process if +not initially implemented.</para> + +</sect2> + +<sect2 id="requirements-vision"> +<title>Vision Statement</title> + + +<para>An electronic bulletin board system is one of the simplest and most +effective forms of collaboration between people separated in space and time. +Bboards provide a centralized and shared venue for discussion that save +communication costs over ad-hoc mechanisms (like arbitrary email lists). +Since messages are organized by topic as well as temporally, bboard can +provide lightweight interfaces for rapidly navigating to interesting +messages. This low barrier to participation encourages spontaneous +collaboration between disperse parties in the community.</para> + +<para>The bboard system also serves as a useful archive and ad-hoc knowledge +management tool by virtue of its persistence, light weight organizational +structure, and flexible browse and search facilities. This sort of knowledge +base can be easily leveraged to provide long term pedagogical value as well +as aid in future problem solving.</para> + +<para>When integrated with an email system, bboards radically improve email +based collaboration. Email notifications can encourage continuous awareness +of community issues. Email based reply functionality further lowers the +barrier to participation, encouraging more Interaction around the +Transaction™.</para> + +</sect2> + +<sect2 id="requirements-system-overview"> +<title>System/Application Overview</title> + + +<para>The bboard system allows users to browse, read, and post messages +organized into forums. Messages consist of short text messages with optional +attachments such as image files or html documents. Messages are organized +into threads when users reply to each other, maintaining the temporal flow of +a particular discussion.</para> + +<para>Forums are contexts for discussion relating to a particular domain of +interest. Examples include the photo.net Q&A forum, the ArsDigita Web/DB +forum, and the away.com discussion forum. Messages within a particular forum +can optionally be tagged as being in certain categories to assist searching +and navigation. Forums are always created in the context of a subsite.</para> + +</sect2> + +<sect2 id="requirements-use-cases"> +<title>IV. Use-cases and User Scenarios</title> + + +<para><emphasis role="strong">Administrator</emphasis>: Phillis Goodsport is a world famous +lithographer who wants to share her knowledge about lithography and encourage +interaction between a community of lithographers on her new site litho.net. +Although she likes the idea of a broad forum for general lithography +discussion, she wants browsing to be tractable when traffic increases. If +quality goes down, she'd like to dedicate one of her minions to +moderating traffic to maintain her high standards.</para> + +<para><emphasis role="strong">Casual browser and poster</emphasis>: Joe Schmoe goes to photo.net +for the first time and wants to ask what zoom lens to buy. He needs to find +the appropriate category/topic to post his message.</para> + +<para><emphasis role="strong">Compulsive reader and expert poster</emphasis>: Jane Developer is a +web development guru and wants to keep up with as much of the traffic on the +web/db forum as possible. She wants to become aware of posts that might +become relevant to her in the future as well as help out folks who have +problems she knows how to solve. Since Jane is on lots of developer mailing +lists, her preferred form of interaction is via email.</para> + +<para><emphasis role="strong">Moderator</emphasis>: Dave Balderdash is a chatter.net moderator and +wants to delete redundant or useless posts. He's short on time, so he +wants a quick interface for rejecting and approving posts.</para> + +<para><emphasis role="strong">Targeted researcher</emphasis>: Ted Stetson is an ACS developer who +remembers someone mentioning something about his Oracle problem on a bboard. +He wants to find records of similar problems and any related solutions.</para> + +</sect2> + +<sect2 id="requirements-links"> +<title>Related Links</title> + + +<itemizedlist> +<listitem><para><xref linkend="design"/></para></listitem> + +<listitem><para>Test Plan (not available)</para></listitem> + +<listitem><para><ulink url="http://www.arsdigita.com/general-comments/view-one?comment_id=28646&item=BBoard%20module"> +notes on USLaw-BBoard implementation</ulink></para></listitem> + +<listitem><para><ulink url="/doc/subsites-requirements.html">Subcommunities</ulink></para></listitem> + +<listitem><para><ulink url="http://www.arsdigita.com/bboard/q-and-a-fetch-msg?msg_id=0003ye">Karl's +thoughts on bboard redesign</ulink></para></listitem> + +<listitem><para><ulink url="http://www.arsdigita.com/bboard/q-and-a-fetch-msg?msg_id=0007ew">Adam +Farkas's web/db thread on bboard improvements</ulink></para></listitem> +</itemizedlist> + +</sect2> + +<sect2 id="requirements-ui"> +<title>Requirements: User Interface</title> + +<itemizedlist> +<listitem> +<para><emphasis role="strong">10.10 End User Basics</emphasis></para> + +<blockquote> +<para><emphasis role="strong">10.10.10</emphasis> The bboard system must provide mechanism for +users to effectively choose which messages to read within a forum. Bboard +must provide an overview interface to enable users to find messages of +interest or relevant to them. This overview should provide the user with +cursory information to facilitate quick scanning and meaningful evaluation of +message contents.</para> + +<para><emphasis role="strong">10.10.15</emphasis> The full text of bboard messages should be +searchable by user queries.</para> + +<para><emphasis role="strong">10.10.20</emphasis> <emphasis role="strong">[unimplemented]</emphasis> Bboard +should consistently provide a mechanism to limit or sort displayed posts by +categories, posters, and date range as well as to perform a text search.</para> + +<para><emphasis role="strong">10.10.30</emphasis> <emphasis role="strong">[unimplemented]</emphasis> Most +users primarily want to browse and read new posts or replies since their last +visit. The bboard interface must allow users to ignore messages they've +already read.</para> + +<para><emphasis role="strong">10.10.40</emphasis> <emphasis role="strong">[unimplemented]</emphasis> Users +should be able to search within and limit scope to messages they have already +read as well as messages they have not read at all.</para> + +<para><emphasis role="strong">10.10.50</emphasis> Users must be able to easily post new messages +to a bboard, or reply to existing messages they have come across. When +replying, users must be presenting with enough context to assist their +composition.</para> +</blockquote> +</listitem> + +<listitem> +<para><emphasis role="strong">10.20 Email Integration</emphasis></para> + +<blockquote> +<para><emphasis role="strong">10.20.10</emphasis> Users can register for email notification of new +messages in a particular forums.</para> + +<para><emphasis role="strong">10.20.13</emphasis> Users can register for email notifications on a +particular thread.</para> + +<para><emphasis role="strong">10.20.16</emphasis> Users can register for email notifications on a +particular category.</para> + +<para><emphasis role="strong">10.20.20</emphasis> <emphasis role="strong">[unimplemented]</emphasis> +Notifications can be sent as each message arrives or in an organized digest +form over a configurable time period.</para> + +<para><emphasis role="strong">10.20.30</emphasis> Individual messages will have appropriate RFC +822 headers to enable threading in the mail client.</para> + +<para><emphasis role="strong">10.20.40</emphasis> <emphasis role="strong">[unimplemented]</emphasis> Email +from the alert system should be tagged in the header with the site and forum +name to enable easy filtering in mail clients. Well, as easy as the mail +clients make it anyway.</para> + +<para><emphasis role="strong">10.20.50</emphasis> <emphasis role="strong">[unimplemented]</emphasis> If the +user requests it, email generated should use MIME encoding to deliver +attachements and appropriately encode HTML. Otherwise plain text emails +should be augmented with URLs and styling cues in place of rich content.</para> +</blockquote> +</listitem> + +<listitem> +<para><emphasis role="strong">10.30 Administrative Requirements</emphasis></para> + +<blockquote> +<para><emphasis role="strong">10.30.10</emphasis> The bboard system must support a flexible +presentation layer that allows custom layout of bboard content.</para> + +<para><emphasis role="strong">10.30.15</emphasis> Publishers should have the option of displaying +discussions in a flat linear fashion or in an indented threaded view.</para> + +<para><emphasis role="strong">10.30.20</emphasis> Parties with administrative privileges on a +particular subsite can create, delete, and edit forums scoped to that +subsite.</para> + +<para><emphasis role="strong">10.30.30</emphasis> Forums can be designated moderated in which case +parties with sufficient privileges must approve messages before they are +displayed generally.</para> +</blockquote> +</listitem> + +<listitem> +<para><emphasis role="strong">10.40 Access Control Requirements</emphasis></para> + +<blockquote> +<para>Objects must be structured to allow the flexible configuration and assignment +of the following privileges: </para> + +<para><emphasis role="strong">10.40.10</emphasis> Reading forums</para> + +<para><emphasis role="strong">10.40.20</emphasis> Reading messages</para> + +<para><emphasis role="strong">10.40.30</emphasis> Posting new messages</para> + +<para><emphasis role="strong">10.40.50</emphasis> Approving and rejecting posted messages (for +moderated groups)</para> + +<para><emphasis role="strong">10.40.60</emphasis> Managing the forum (editing title and +description, determining moderation and restriction policies, granting +approval privileges to others, banning users)</para> + +<para><emphasis role="strong">10.40.70</emphasis> Managing categories (editing, deleting, +combining categories)</para> +</blockquote> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="requirements-datamodel"> +<title>Requirements: Data-model</title> + +<itemizedlist> +<listitem> +<para><emphasis role="strong">20.10 Messages</emphasis></para> + +<blockquote> +<para><emphasis role="strong">20.10.10</emphasis> Messages are the basic units of the bboard +module. The bboard system will provide a repository to store text +messages.</para> + +<para><emphasis role="strong">20.10.20</emphasis> Messages will be tagged as having HTML, plain +text, or preformatted text in their body.</para> + +<para><emphasis role="strong">20.10.30</emphasis> Messages will have a brief plain text subject +line.</para> + +<para><emphasis role="strong">20.10.40</emphasis> Messages will be related to their creating +user.</para> + +<para><emphasis role="strong">20.10.50</emphasis> Messages may optionally have binary +attachments.</para> + +<para><emphasis role="strong">20.10.60</emphasis> The bboard system must store relations between +messages and their replies to enable threaded views.</para> +</blockquote> +</listitem> + +<listitem> +<para><emphasis role="strong">20.20 Forums</emphasis></para> + +<blockquote> +<para><emphasis role="strong">20.20.10</emphasis> Forums are the main administrative units of the +bboard system. Forums are containers to which messages uniquely belong.</para> + +<para><emphasis role="strong">20.20.20</emphasis> Forums must have a brief text descriptions and +optionally a longer description called a charter.</para> +</blockquote> +</listitem> + +<listitem> +<para><emphasis role="strong">20.30 Categories</emphasis></para> + +<blockquote> +<para><emphasis role="strong">20.30.10</emphasis> There must be a mechanism for intra-forum +categorization to facilitate filter, searching, and tractability.</para> +</blockquote> +</listitem> +</itemizedlist> +</sect2> + +<sect2 id="requirements-api"> +<title>Requirements: API</title> + + +<para><emphasis>No requirements in this section are met by the current +implementation.</emphasis></para> + +<para>Since bboard is primarily an end user application any exposed APIs will +come out of the design rather than nailed down requirements from the start. +Stay tuned.</para> + +</sect2> + +<sect2 id="requirements-future"> +<title>Possible Future Requirements</title> + +<itemizedlist> +<listitem> +<para><emphasis role="strong">40.10 In no particular order</emphasis></para> + +<blockquote> +<para><emphasis role="strong">40.10.10</emphasis> bboard should provide a framework for extending +the generic messaging repository with meta-data and in tandem extending the +user interface to take advantage of this meta-data. This would let developers +properly layer functionality such as geo-spatial messaging and slashdot style +scoring. This is actually provided via ACS messaging and the ACS Object +system.</para> + +<para><emphasis role="strong">40.10.20</emphasis> bboard should support replying to and +initiating threads from email. Administrative email list functionality should +be developed or integrated.</para> + +<para><emphasis role="strong">40.10.30</emphasis> Bboard should let users register interests +(categories, certain users, keywords) for the purpose of filtering and +sorting message displays.</para> + +<para><emphasis role="strong">40.10.40</emphasis> Users should have the option of enabling spell +checking on their posts. A framework for filtering (removing bad words, +promoting text URLs to html links, auto detecting HTML vs. plain text, etc.,) +should exist.</para> + +<para><emphasis role="strong">40.10.50</emphasis> Allow users to configure how big the textareas +editing widgets they get are.</para> + +<para><emphasis role="strong">40.10.60</emphasis> Moderators should be given the <emphasis>option</emphasis> +of making notes on a given discussion that appear prominently in the +discussion display.</para> + +<para><emphasis role="strong">40.10.70</emphasis> Moderators should be able to set posts to +expire at a configurable time in the future.</para> + +<para><emphasis role="strong">40.10.80</emphasis> Mega bonus points: an nntp gateway to bboards +for access from standard news clients.</para> + +<para><emphasis role="strong">40.10.90</emphasis> The bboard system should be able to take +advantage of a caching system that stores the results of database queries for +optimal scalability.</para> + +<para><emphasis role="strong">40.10.100</emphasis> Publishers should have the option of allowing +users to edit various parts of messages after they are posted (e.g. the text +body, the subject, the text presentaiton style etc.,)</para> + +<para><emphasis role="strong">40.10.110</emphasis> A user interface should allow administrators +to easily categorize or recategorize existing messages.</para> + +<para><emphasis role="strong">40.10.120</emphasis> Publishers should be able to classify users +based on their forum contributions and appropriately target them for email, +promotions, etc.,</para> + +<para><emphasis role="strong">40.10.130</emphasis> Explicit permissions for posting new messages +vs. posting replies.</para> + +<para><emphasis role="strong">40.10.140</emphasis> Explicit permissions for posting +attachments.</para> +</blockquote> +</listitem> + +<listitem> +<para><emphasis role="strong">40.20 Performance requirements</emphasis></para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="requirements-rev-history"> +<title>Revision History</title> + + + +<informaltable> +<tgroup cols="4"> + +<thead> +<row role="revisiontop"> +<entry>Document Revision #</entry> +<entry>Action Taken, Notes</entry> +<entry>When?</entry> +<entry>By Whom?</entry> +</row> +</thead> +<tbody> + +<row role="revisionbody"> +<entry>0.2</entry> +<entry>Revision: More standard style, more detailed requirements.</entry> +<entry>08/24/2000</entry> +<entry>Anukul Kapoor</entry> +</row> + + +<row> +<entry>0.1</entry> +<entry>Creation</entry> +<entry>08/23/2000</entry> +<entry>Anukul Kapoor</entry> +</row> + +</tbody> +</tgroup> +</informaltable> + +</sect2> + +</sect1> + Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/support.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/support.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/support.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,57 @@ +<sect1 id="support" xreflabel="Bboard Support"> +<title>Support</title> + +<para> +There's a couple of different places you can turn to if this documentation +comes short of answers to your questions or if you want to give us +feedback: +</para> + +<itemizedlist> +<listitem><para> +<emphasis role="strong"> +If you have a general question about usage of the application +</emphasis></para> + +<para> +Ask on the <ulink url="http://www.arsdigita.com/bboard/q-and-a?topic_id=935&topic=ACS%20Applications"> +applications bboard at arsdigita.com</ulink>. +</para> +</listitem> + +<listitem><para> +<emphasis role="strong"> +If you want to report a bug or keep up-to-date on bug fixes +</emphasis></para> + +<para> +Visit the <ulink url="http://www.arsdigita.com/sdm/all-tickets?module_id=8566&package_id=8157&status=newopen"> +ArsDigita SDM</ulink>. +</para> +</listitem> + +<listitem><para> +<emphasis role="strong"> +If you are interested in the general status of the Bboard application +</emphasis></para> + +<para> +Up to date info on BBoard is available from the <ulink url="http://acs40.arsdigita.com/acs40-project-central/bboard/">BBoard status +page</ulink>. +</para> +</listitem> + +<listitem><para> +<emphasis role="strong"> +If you have questions, comments or suggestions to this documentation +</emphasis></para> + +<para> +Visit the <ulink url="http://developer.arsdigita.com/docbook/">Documentation Central</ulink> +or fire directly at <ulink url="mailto:acs-docs@arsdigita.com">acs-docs@ardigita.com</ulink>. +</para> +</listitem> +</itemizedlist> + + +</sect1> \ No newline at end of file Index: openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/top.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/top.xml,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/contrib/obsolete-packages/bboard/www/doc/xml/top.xml 29 Jun 2001 20:35:39 -0000 1.1 @@ -0,0 +1,66 @@ +<?xml version='1.0' ?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd" [ + +<!-- For Everyone --> +<!ENTITY introduction SYSTEM "intro.xml"> +<!ENTITY support SYSTEM "support.xml"> +<!ENTITY notes SYSTEM "notes.xml"> + +<!-- For Admins --> +<!ENTITY installation SYSTEM "installation.xml"> +<!ENTITY configuration SYSTEM "configuration.xml"> + +<!-- For Developers --> +<!ENTITY design SYSTEM "design.xml"> +<!ENTITY requirements SYSTEM "requirements.xml"> + + +]> + +<book> +<title>Bboard Documentation</title> + + + <chapter id="for-everyone"> + <title>For Everyone</title> + + <sect1> + <title>Overview</title> + <para>Brief introduction, support possibilities and release notes</para> + </sect1> + + &introduction; + &support; + ¬es; + + </chapter> + + + <chapter id="for-admins" xreflabel="For Admins"> + <title>For Admins</title> + + <sect1> + <title>Overview</title> + <para>Installation, maintenance</para> + </sect1> + + &installation; + &configuration; + + </chapter> + + <chapter id="for-developers" xreflabel="For Developers"> + <title>For Developers</title> + + <sect1> + <title>Overview</title> + <para>Requirements, design</para> + </sect1> + + &requirements; + &design; + + </chapter> + +</book>