Search · Index

Weblog

Showing 1 - 10 of 653 Postings (summary)

Proposed project goals

Created by Robert Taylor, last modified by Benjamin Brink 08:14 AM, Saturday

This page remains for legacy discussion.

This is regarding Approach 1. in en:Documentation_Project_Discussion. The milestones are performance based, instead of directly connected to work, which makes them an impractical plan to follow.

Overview: 

Here are a few things we are working to accomplish with XoWiki and the OpenACS website:

 

Milestones:

MILESTONE I:  Tooling Up - Before We Can Accomplish Anything We Must Have a Powerfull Wiki.

- XoWiki is functional for the most part

- a few bugs and feature requests remain, Gustaf and Dave have rocked the OACS boat and created some amazing functionality in a short period of time.  When some of these items are cleared this Milestone will be considered accomplished.
 

MILESTONE II:  Testing Packages after each OACS release.

 

- XoWiki is functional, we can start testing immediately.  Look for a TESTING PROCESS document in the PACKAGES category (if it's not up now, soon).

 
MILESTONE III: Look and Feel vs. Content

- XoWiki is turning out to be very powerfull and easy to use.  We will need to focus on content first, look and feel can be handled later.  UTILITY has a greater priority over LICKABILITY.

 

MILESTONE IV: Fanatical Documenation.

- API documenation will stay as is.

- see en:Documentation_Project

MILESTONE V: New Blood.

- I think we can start attracting new devs as soon as our Documentation allows a new developer easy egress into the toolkit.  Watching Dave, Gustaf and others litterally create new functionality out of thin air over the last week of January 2K6 is clear indication the barrier to entry is not the toolkit, it is with the resources and tools they need to be able to understand and become developers. 

- I think getting a LICKABLE look and feel is something that can be done simultaneously, at a stage after XoWiki has been thoroughly debugged and tested.

toc-test-page

Created by Benjamin Brink, last modified by Benjamin Brink 08:09 AM, Saturday

some text..

some text..

 

Documentation Project Plan (Approach 4)

Created by OpenACS community, last modified by Benjamin Brink 07:51 AM, Saturday

This is Approach 4 of the en:Documentation_Project as defined in Documentation_Project_Discussion.  Users benefit when they can read docs the way the brain likes to work. Contributions to various OpenACS topics that further the plan are welcome.

Background

See Documentation history

Goal

to write superb documentation, so that users, developers and administrators of OpenACS installations can enjoy working with and using the system (with fewer headaches! =)

Scope

OpenACS documentation, a systems view as a collection of subsystems and their parts.

API Documentation: there are no plans to move the API docs to XoWiki. That should remain as is.

DocBook docs at: http://openacs.org/doc/index.html are evolving separately at en:New_Documentation_Process

Requirements

Requirements is about setting specifications and milestones we can verify, and includes exploration of scenarios, use cases etc.

Here are documentation requirements for:

Available resources

  • volunteers dedicated to regularly managing and updating the documentation
  • other volunteers who contribute arguably more valuable documentation less frequently (such as magazine articles ;) (and may need some assistance etc. to have their work fit into docs well.)
  • openacs.org website, including use of xowiki
  • open-source software, text editors, spell checkers, html code validators etc.
  • Approaches in docs management explored. See en:Documentation_Project_Discussion

Strategy

Strategy is about creating an approach to doing work. It guides behavior and tactical decisions on the work effort.

Shape ongoing documentation efforts by using principles of continual improvement and following general requirements to re-engineer documentation production and management.

OpenACS documentation development is subject to constraints of the software project development and release methods and cycles (the section called “Using CVS with OpenACS”). Essentially, all phases of work may be active to accommodate the asynchronous nature of multiple subprojects evolving by the efforts of a global base of participants with culturally diverse time references and scheduling idiosyncrasies.

The documentation strategy is to use methods that inspire collaborating or obtaining guidance or feedback (peer review) to distribute the workload and increase the overall value of output for the OpenACS project.

subdivide by subsystems and how they are used (context). Why?

"..the human mind can only deal with a relatively small number of independent pieces of data at one time, but if data are chunked together in appropriate ways, the mind can perform higher order abstractions, and these in turn can be chunked together, with successive abstractions, until an entire complex situation is encompassed. The systems approach addresses this property of the human mind by providing strategies for the data gathering, chunking, and abstracting process." George G. Lendaris, On Systemness and the Problem Solver: Tutorial comments 1983.

A short video on how the mind manages large amounts of information by "chunking": The Science of Thinking

XoWiki docs can use a systems strategy of multiple perspectives to help identify subsystems and how OpenACS works.

Each XoWiki page discusses a single topic.

These topics are pieced together by any number of other xowiki pages to present an ordered presentation of the topics with a common thread/topic connecting them.

For example, en:openacs-system-install is a page that links together the topics of installing the component software of Openacs. Similarly, each component software, such as en:aolserver, has its own view of some overlapping topics.

XoWiki documents organized by subsystems (and how they are used) are easy to update and maintain since there is only one place to put relevant information for a particular topic.

Pages are not encumbered by a maze of categories that tend to only address one or a few perspectives, since pages link to related pages, and a page that addresses each perspective can link to overlapping topics.

In an ideal world, XoWiki will be able to export a page and all the pages that link to it, to any depth of the linkage tree, to form one document. That way, innumerable documents, each with a valid perspective, can be built for a specific purpose.

Work Breakdown Structure

Or Objectives and Key Results (OKRs) is about explicitly stating the way to implement the strategy as a set of milestones and the methods to use.

Allow document writers to reference package API via api-doc by using package_url, or find the local package_id so a link can be supplied from the local documentation to current, up-to-date API and SQL docs, like: http://openacs.org/api-doc/package-view?version_id=358136 use links like this: /api-doc/index?about_package_key=acs-datetime The feature has been added to cvs head (OpenACS 5.3.x) so will be released soon.[DONE]

Iterate through each topic on each docbook page.

  • Port the docbook pages to xowiki manually, because it allows me to look at each part in details and separate to subsystem/object context. Here is the process:
  • Browse to docbook url (something in this tree: http://openacs.org/doc/)
  • View page source
  • Copy the relevant part of source
  • Paste that source to your favorite text editor (not word processor).
  • Edit the page source, removing DIV tags and TARGET="_blank" attributes. Look for any immediate way to improve the document, make additional edits, check for spelling etc.
  • In a browser, open or create the xowiki page. Choose "Source" to view source html. Be sure to make Name starting with "en:"
  • Paste edited source into the xowiki page, repeat editing if needed
  • Click "ok" to post the xowiki changes.
  • That's it! (repeat)

Example documentation outline in wiki

These pages contain links to other pages where items are discussed in context:

Name for/description
en:docs-end-user documentation for everyone
en:openacs-system end-user about OpenACS system, ties together much of the stuff below.
en:docs-end-user-reqs end-user doc requirements and checklist
en:docs-install installing OpenACS prerequisits
en:openacs-system-install installing OpenACS overview
en:openacs-system-install-redhat installing OpenACS on Redhat
en:docs-install-reqs installation- docs requirements and checklist
en:docs-admin administrators
en:docs-admin-reqs administration - doc requriments and checklist
en:docs-dev-tutorial tutorials for developers
en:docs-dev-tutorial-reqs developer tutorials - requirements and checklist
en:docs-eng developers
en:docs-eng-reqs developing - requirements and checklist

These pages describe various OpenACS subsystems, and link to external documents where possible and appropriate. Note that an "OpenACS system" en:openacs-system page that outlines the system and ties these together is part of the end-user docs.

Name subsystem of OpenACS
en:aolserver AOLserver
en:aolserver-install installing AOLserver
en:aolserver-admin administrating AOLserver
[en:naviserver] naviserver
[en:naviserver-install] installing naviserver
en:oracle Oracle relational database
en:oracle-install installing Oracle
[en:oracle-admin] administrating Oracle
en:postgresql PostgreSQL relational database
en:postgresql-install installing PostgreSQL
en:postgresql-admin administrating PostgreSQL
en:os-nix *nix operating system
en:os-nix-install installing an OS
en:tcl tcl language
en:tcl-install installing tcl
en:openacs-subsystem OpenACS subsystem (layer)
en:openacs-subsystem-install install OpenACS

Auxiliary systems

en:ide-emacs gnu emacs as IDE
[en:ide-emacs-nxml] gnu emacs nXML Mode
[en:ide-emacs-psgml] gnu emacs PSGML Mode
en:ide-vi vi/vim as IDE

Verification

This is where we measure how well this plan was implemented. Success is measured by

  • A) verifying if the project has met the established goals and requirements, and
  • B) reviewing for ongoing problem areas etc.

Observations then help to modify the plan for the next documentation revision.

OpenACS follows verification through different means on different projects, but in all cases, the OpenACS community verifies the project as a success through feedback including bug reports, user and administrator comments, and code changes.

Related links and sources

(none)

TOC includelet test

Created by Torben Brosten, last modified by Benjamin Brink 07:26 AM, Saturday

begin toc 

 end toc
 

New Documentation Process (Approach 3)

Created by Rocael Hernández Rizzardini, last modified by Benjamin Brink 07:14 AM, Saturday

This is Approach 3 of the en:Documentation_Project as defined in en:Documentation_Project_Discussion.

Official documentation will go into openacs.org/test-doc (to be renamed) generate from there the html pages for documentation, therefore the first result is to update the documentation to reflect current tools, version, correct commands, all done within that wiki instance

The process for generating technical documentation is:

  1. Update that documentation wiki instance named doc-head
  2. Once the documentation is ready, freeze it doing a export/import process from /doc/head to a new instance (i.e. /doc/5-5-0)
    • No write permissions for the public will be granted to this frozen instances
    • Use an alternate template to distinguish between /doc/head and the frozen ones
  3. Generate the static html documentation based on the wiki-frozen instance (/doc/5-5-0) 
    • Using as template_file the view-oacs-docs
      • Available here: http://alice.wu-wien.ac.at:8000/xowiki/listing?m=list
      • Have to be placed on www dir of xowiki package
      • Also the parameter top_includelet have to be in blank for the wiki-frozen instance
      • Example on how the doc will be available in the wiki-frozen instance: http://alice.wu-wien.ac.at:8000/test-doc/for-everyone
    • Options for the static content:
      • One large HTML file and/or (book-print prototype)
      • One HTML file per chapter and/or (tutorial-advance prototype)
      • Same granularity as in /doc/head
      • Get the documentation using wget
        • This wget command should get you the html files for the documentation:
        • wget -kpr -R book <root of the documentation's xowiki instance>
      • The html files will not have an extension, this may cause them to not be interpreted as html and returned as plain text on some web servers, to be safe, rename the files to have an extension. Run the following script on the directory containing the static html files.
        • #!/bin/bash

          FILENAMES=`ls . | grep -v "html" | grep -v ".sh"`

          for f in $FILENAMES; do
              if [ ! -d "$f" ] ; then
                  FILE_NAME=`echo $f | awk -F ? '{print $1}'`
                  FILE_PARAMS=`echo $f | awk -F ? '{print $2}'`
                  if [ -z "$FILE_PARAMS" ]; then
                      NEW_FILE_NAME="${f}.html"
                  else
                      NEW_FILE_NAME="${FILE_NAME}.html?${FILE_PARAMS}"
                  fi

                  if [ ! -f "$NEW_FILE_NAME" ]; then
                      mv $f $NEW_FILE_NAME
                  fi
              fi
          done

           
  4. Commit into the CVS, branch and tag appropriately following the branch/tag conventions for the specific release.
  5. Add a link of this new /doc/5-5-0 into online documentation index openacs.org/doc and a map it in the site map to /doc/current

Then the process can start again for the next documentation release.

To-Do

  • Still missing a way to transform to independent html files with index / navigation within it (right now only produces a one big html). (done by Gustaf)
  • New /doc has to have a link to the various online (xowiki) frozen versions of the documentation.
  • Document the document formatting/markup rules in the wiki instance and the static documentation. 
    • Probably there is already formats for technical documentation available, produced, or at least some guidelines.
  • Openacs.org/doc will be replaced with the wiki-documentation (/test-doc instance renamed to /doc/head)
    • Provide an index to link to all frozen documentation releases.
    • Current /doc can be renamed to /doc-5-1
  • Assign someone to udpate the documentation, follow the process and release documentation.

Following moved to this context, which is using approach discussed by Malte below:

Malte here:

Instead of doing it manually (though this does have some merit), I would go and modify the script Gustaf provided to import the whole documentation in one go into a new XoWIKI instance with the structure (page_order) that has been added in XoWIKI 0.42 taken from the chapters of the documentation so that we do have an exact mirror of the documentation as it stands now.

Once this is achieved we could go on and assign categories to the documentation, allowing for an alternative view on the documents (so you could say "instead of showing the whole documentation only show the documents for a specific category"). Probably this needs some more detailed discussion with Gustaf finding out how this could be achieved in XoWIKI and what would make most sense. Ideally we could provide a different structure based on the target group (e.g. category) but this is probably shooting too far. Getting categorization and page ordering in a decent shape should provide us a lot of possibilities.

 

  • One can use the follwing script to generate the page objects and load it via xowiki/admin/import into an xowiki instance; this can be improved in many places, but gives you the idea
  • # by Gustaf Neumann 
  • # load doc pages into xowiki   -gustaf neumann
    # for tdom
    lappend auto_path /usr/local/aolserver4/lib
    package require tdom
    package require XOTcl; namespace import ::xotcl::*
    package require xotcl::serializer

    set docpath /usr/local/openacs-4/packages/acs-core-docs/www/

    namespace eval ::xowiki {
      Class create Page -parameter { {lang en} {description ""} {text ""}
        {nls_language en_US} {mime_type text/html} name title text }

      set c 0
      foreach docpage [glob $docpath/*.html] {
        set f [open $docpage r]; set data [read $f]; close $f
        dom parse -html $data doc
        $doc documentElement root

        set content ""
        foreach n [$root selectNodes //body/*] { append content [$n asHTML] \n }
     
        set p [Page create page[incr c] -name en:[file tail $docpage] \
               -title [[$root selectNodes //title] asText] \
               -text [list $content text/html]]
        puts [::Serializer deepSerialize $p]
      }
    }

 

Suggestion by Rob Taylor: 

1a. Move all but maybe the first and last 2 items from http://openacs.org/doc/dev-guide.html to http://openacs.org/doc/kernel/dev-guide.html and refer to them in context of the kernel package (or whatever package their code is in). That helps developers see appropriate context. (This will likely require a board discussion and TIP

Documentation Project Discussion

Created by OpenACS community, last modified by Benjamin Brink 06:46 AM, Saturday

Current topic: What approach should we use to upgrade the documentation?

Here are some recent approaches expressed in one form or another for managing the documentation in the context of "the plan":

Approach 0. Why not use docbook, which was the previous way documentation was being handled?

  • docbook is open-source.
  • A growing community surrounds DocBook (has mailing lists)
  • A number of free and commercial tools are available for editing and publishing DocBook documents.
  • docbook enables us to publish in a variety of formats.
  • XML separates content from presentation: It relieves each contributor of the burden of presentation, freeing each writer to focus on content and sharing knowledge.
  • docbook is well tested technology. It has been in development since the early 1990's).

problems: In 2002, Docbook still was not fully capable of representing online books as practiced by book publishers and expected from readers with regards to usability on the web. That meant DocBook did not entirely meet OpenACS publishing requirements at that time.

In 2004, Docbook released version 4.2, which complies with all the OpenACS publishing requirements. Producing a web friendly book hierarchy arguably remains DocBooks' weakest point. For example, a dynamically built document should be able to extract details of a specific reference from a bibliographic (table) and present a footnote at the point where referenced. DocBook 4.2 allows for this with bibliocoverage, bibliorelation, and bibliosource. Yet, OpenACS documentation does not follow a standard book hierarchy since most of the documentation was written before version 4.2, and re-organizing it in docbook source would be challenging.

Other problems with using docbook:

  • Only developers can make changes, which makes it difficult for the rest of the community to coordinate changes and updates, especially when they are seemingly small (such as typos).
  • OpenACS docbook has long documents, which puts extra stress on using consistent style to separate topics on the same page. For example, readers get confused when trying to follow the installation documents. Some instructions get missed, other instructions are done when they shouldn't have been.
  • OpenACS docbook uses multiple tags for the same function and requires only certain tags to be used in certain contexts. The documentation in HTML is convoluted and displays inconsistent.

Based on the other recent suggestions, there seems to be a general consensus to move away from docbook, but perhaps keep the docbook organization.

Approach 1. from en:Proposed_project_goals

Robert writes:

- First: ..attempt to take the rest of Documentation over to XoWiki..
- Secondly: ..try to setup an automated versioning system. We should end up with categories such as 5.2 Documentation, 5.3 Documentation, HEAD Documentation, etc. My current thinking is that we can work on HEAD category of documentation, once 5.3 is release it becomes categorized as such and a copy of the docs gets created and re-categorized as HEAD once again. This should allow versioning and easy upgrades/editing of docs (well easy may not be the right word, docs are a lot of work)

Robert, "Secondly" is how versioning has been accomplished using docbook.  This method seems to work fine, and we can do it with xowiki docs by creating a set of static pages from the xowiki ones. --Torben

Approach 2. from [en:Structure_Ideas]

Robert writes:

Documentation: [move] ..the rest of the documents to XoWiki. The idea would be to have categorized documents. We would start by moving the 5.2 docs over and expanding on them. When 5.3 is release we would do an automated copy/paste of the 5.2 docs, re-categorize as 5.3 and start the editing process. This is just preliminary thinking at this point..

 Robert, everyone seems to have their own way of slicing and dicing docs into categories.  We ought to use the existing documentation requirements to guide how the documents are organized, and then they can be categorized any number of ways since multiple categories can be applied to each page. --Torben

Approach 3 (and previously 5). Refactoring original docbook docs en:New_Documentation_Process

STAGE A: CONVERT DOCUMENTATION TO XOWIKI (note: all api docs remain the same) Step #1. Catalog the current documentation.

(Malte writes) ..modify the script Gustaf provided to import the whole documentation in one go into a new XoWIKI instance with the structure (page_order) that has been added in XoWIKI 0.42 taken from the chapters of the documentation so that we do have an exact mirror of the documentation as it stands now. [Done, see http://openacs.org/test-doc].

Malte, why would we want an exact mirror of something that is not organized well.. too many topics per page and pages inconsistently presented..  requires a new reader to jump around to get familiarized with material. etc etc?  Why not copy the docbook contents into a cleaner outline and work from there (as in approach 3 above)? --Torben

Torben, the /doc section is organized. That you do not like it is obvious and we could rework it later, but until we have the resource to rewrite the whole documentation, it makes much more sense to improve the documentation we have instead of putting it into the graveyard. And we need to come to terms. This discussion does not yield any results at the moment but keep us from doing the actual work: Improving the documentation -- Malte

[Then] ..assign categories to the documentation, allowing for an alternative view on the documents (so you could say "instead of showing the whole documentation only show the documents for a specific category"). Probably this needs some more detailed discussion with Gustaf finding out how this could be achieved in XoWIKI and what would make most sense. Ideally we could provide a different structure based on the target group (e.g. category) but this is probably shooting too far. Getting categorization and page ordering in a decent shape should provide us a lot of possibilities..

Malte, have you seen docs-admin-toc , docs-end-user-toc and docs-eng?  These are outlines of existing pages in xowiki that represent a revised version of the Table of Contents (TOC) in the docbook version.  Feel free to propose new pages there for us to fill in  content. --Torben

Yes I have seen them. Do they resemble a book in any way to you? They are alternative structures, indeed, but you can impose them on a book view as well, any time. A book is what we need, something people can go to and start reading. If the book starts with four different pages, each outlining a different reading path, even the better. But a book it should be nevertheless, because this is how people still learn. If you do not like the book approach, that is fine, then we should open this question up for a TIP. My main goal at the moment is to finally get this done and start working. And I want to get rid of the myriads of confusing advise given at openacs.org. I have someone to work with me on that in the next two months and I want to have a clear way to go forward. So I will just TIP this. -- Malte
 

See also: en:wikidoc-notice

 

Approach 4 Mental Maps en:Documentation_Project_Plan

This approach was originally posted at en:Documentation_Project. It was moved here as the topic expanded.

..port docbook pages to xowiki manually.. look at each part in detail.. separate to subsystems and how they are used (context). Why?

"..the human mind can only deal with a relatively small number of independent pieces of data at one time, but if data are chunked together in appropriate ways, the mind can perform higher order abstractions, and these in turn can be chunked together, with successive abstractions, until an entire complex situation is encompassed. The systems approach addresses this property of the human mind by providing strategies for the data gathering, chunking, and abstracting process." George G. Lendaris, On Systemness and the Problem Solver: Tutorial comments 1983.

A short video on how the mind deal best with large amounts of information by "chunking": The Science of Thinking

This work is in progress, with root documentation page here: en:openacs-handbook

A systems strategy of multiple perspectives has these rules:

  • Each xowiki page discusses a single topic.
  • Topics are linked together by any number of other xowiki pages to present an ordered presentation of the topics with a common thread/topic connecting them. For example, en:openacs-system-install is a page that links together the topics of installing the component software of OpenACS. Similarly, each component software, such as en:aolserver, has its own view of some overlapping topics.

Multiple perspectives meets these significant documentation requirements:

  • helps identify subsystems and how OpenACS works --becomes a natural tutorial without more words.
  • reduces the burden of keeping documentation up to date since there is only one place to put relevant information for a particular topic --no redundancy
  • pages are not organized by a dominant category morphology that tends to address the perspectives of just a few people. Most any perspective can be represented.
  • Readers do not have to filter out a bunch of information that is irrelevant to them or their task at hand.

Move all but maybe the first and last 2 items from http://openacs.org/doc/dev-guide.html to http://openacs.org/doc/acs-kernel/ (and what ever else is relevant to kernel only); and move the first item to http://openacs.org/doc/acs-admin etc. That way the core docs are presented in a consistent context with the other packages. Also, do not migrate these docs around as a package is designated part of the core (or subsequently removed from it). This would help developers see appropriate context (and meets one of the documentation requirements).

Allow documentation to link directly to the api-docs, to reduce redundancy and links go to current, local API docs. In other words, http://openacs.org/api-doc/package-view?version_id=358136 becomes: /api-doc/index?about_package_key=acs-datetime The feature has been added to OpenACS 5.3 so will be released soon.[DONE]

Move Administrator's Guide to the xowiki [in progress, see en:docs-admin and en:docs-admin-toc ], because this section:

  • has the most duplicated work (topics overlap on various pages). For example, more than one page explains how to add a package, how to restart the server, how to start the server etc.
  • needs to be updated most frequently because of changing installation requirements. For example, PostgreSQL requires different instructions for different revisions, external links change sporadically etc.

Incorporate the work already done in the first wiki ( http://openacs.org/wiki ), where volunteers have already added a wealth of new documentation. Note that some of this will already exist in xowiki from previous importing of docs etc. [TO DO]

We need to get rid of the myriads of different installation instructions. First of all they are not kept up to date (all of them). -- Malte 

Documentation History

Created by OpenACS community, last modified by Benjamin Brink 05:19 AM, Saturday

The history of OpenACS documentation: ..began by building on a good documentation base from ArsDigita's ACS in the late 1990's. The ACS documentation was largely written in docbook. Some sections of the documentation, however, lacked details and examples; others simply did not exist. The OpenACS community began meeting the challenge by identifying needs and writing documentation on an as needed basis.

By having documentation dependent on volunteers and code developers, documentation updates lagged behind the evolving system software. As significant development changes were made to the system, existing documentation became dated, and its value significantly reduced. The valiant efforts that were made to keep the documentation current proved too difficult as changes to the system sometimes had far-reaching affects to pages throughout the documentation. System integration and optimization quickly rendered documentation obsolete for developers. The code became the substitute and source for documentation.

There are many thousands of lines of code, and few developers tracking changes and publishing the changes. Subsequently features and advances to the OpenACS system went unnoticed or were not well understood except by the code authors. Work was duplicated as a consequence of developers not realizing the significant work completed by others. New developers had to learn the system through experience with working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge has become the OpenACS community's main method of sharing knowledge.

Around 2006, efforts were made to build a consensus in new ways to overcome existing documentation limitations. Like most any diverse community, a consensus could not be reached. Time has distilled efforts into three approaches that augment OpenACS' primary source of documentation: OpenACS code itself.

Documentation Project

Created by Robert Taylor and Ryan Gallimore, last modified by Benjamin Brink 04:21 AM, Saturday

The managing of OpenACS documentation has evolved a few different ways. Instead of working on a unified consensus in managing the OpenACS documentation, there are primarily three efforts:

Approach 0: Continue updating docbook documentation via CVS (for those with access to CVS).

Approach 3: en:New_Documentation_Process is migrating the original OpenACS docbook docs to an xowiki instance.

Approach 4: en:Documentation_Project_Plan is building new documentation based on how the brain likes to chunk using subsystems. 

See en:Documentation_Project_Discussion for current status.

Installing OpenACS on Mac OS X

Created by OpenACS community, last modified by Gustaf Neumann 08:13 AM, Friday

See one of these:

Should you decide to install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes:

Installing PostgreSQL

OS X conventions

On Mac OS X type sudo su - to become root.

Use curl -L -O instead of wget

If you are running Mac OS X prior to 10.3, you should be able to install and use PostgreSQL 7.3.x. Mac OS X 10.3 requires PostgreSQL 7.4. Note: if you're installing PG on an Intel Mac, you'll need to install 8.x; 7.4.x won't compile because of a lack of "native spinlock support" -- and this is something that the PG maintainers aren't inclined to fix. See this. PG 8.0.x installs fine, as does PG 8.1 or 8.2.

Creating postgres user

Do this instead:

First make sure the gids and uids below are available (change them if they are not). To list taken uids and gids:

nireport / /groups name gid | grep "[0-9][0-9][0-9]"
nireport / /users name uid | grep "[0-9][0-9][0-9]"

Now you can install the users

sudo niutil -create / /groups/web
sudo niutil -createprop / /groups/web gid 201
sudo niutil -create / /users/postgres
sudo niutil -createprop / /users/postgres gid 201
sudo niutil -createprop / /users/postgres uid 502
sudo niutil -createprop / /users/postgres home /usr/local/pgsql
sudo niutil -create / /users/$OPENACS_SERVICE_NAME
sudo niutil -createprop / /users/$OPENACS_SERVICE_NAME gid  201
sudo niutil -createprop / /users/$OPENACS_SERVICE_NAME uid 201
mkdir -p /usr/local/pgsql
chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
chmod 750 /usr/local/pgsql

Compile and install PostgreSQL

If you're using Fink:

Append --with-includes=/sw/include/ --with-libraries=/sw/lib flags to ./configure.

./configure --with-includes=/sw/include/ --with-libraries=/sw/lib

Set PostgreSQL to start on boot

cd /Library/StartupItems/
tar xfz /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-startup-item.tgz

Alternatively, one can use an XML file like the following to start PostgreSQL via launchd (specifying the postgres binary directory and database directory)

For Mac OS X Tiger (10.4.*), use:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>GroupName</key>
	<string>nsadmin</string>
	<key>Label</key>
	<string>org.postgresql.PostgreSQL</string>
	<key>OnDemand</key>
	<false/>
	<key>ProgramArguments</key>
	<array>
		<string>/usr/local/pg820/bin/pg_ctl</string>
		<string>-D</string>
		<string>/usr/local/pg820/data</string>
		<string>-l</string>
		<string>/usr/local/pg820/data/server.log</string>
		<string>start</string>
	</array>
	<key>ServiceDescription</key>
	<string>PostgreSQL Server</string>
	<key>UserName</key>
	<string>postgres</string>
</dict>
</plist>

For Mac OS X Leopard (10.5.*), use:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>Label</key>
	<string>org.postgresql.PostgreSQL</string>
	<key>UserName</key>
	<string>postgres</string>
	<key>GroupName</key>
	<string>nsadmin</string>
	<key>OnDemand</key>
	<false/>
	<key>ProgramArguments</key>
	<array>
		<string>/usr/local/pg820/bin/postmaster</string>
		<string>-D</string>
		<string>/usr/local/pg820/data</string>
		<string>-c</string>
		<string>log_connections=YES</string>
	</array>
</dict>
</plist>

Save the above files as /Library/LaunchDaemons/org.postgresql.PostgreSQL.plist and postgres will be started automatically on the next boot of the system. One can use launchctl to start the service for testing;

 

launchctl % load /Library/LaunchDaemons/org.postgresql.PostgreSQL.plist % start org.postgresql.PostgreSQL % ^D

To get Tcl to build on Leopard or newer

for compiling under Mac OS X Leopard or newer, use the following flags to compile Tcl:

./configure --prefix=/opt/aolserver --enable-threads --disable-corefoundation --enable-symbols

 

To get tDOM to build on tiger

  1. Download and install/update to the latest version of xcode tools (version2.2) from http://developer.apple.com/tools/xcode which updates the gcc compiler.
     
  2. Then make some additional changes to the unix/CONFIG file (after modifying the unix/CONFIG file according to instructions at en:aolserver-install, uncomment:
    'CC=gcc; export CC'
  3. add a new line, somewhere after the first line:
    export CPP="/usr/bin/cpp"

When versions of AOLservers different to AOLserver 4.5 (head, including changes from Mar 22, 2008) are used, AOLserver is likely to segfault on startup due to recent changes in the Mac OS X System libraries. To avoid this, use

ulimit -n 256

in the startup script (don't use unlimited).

Books and publications about OpenACS

Created by Benjamin Brink, last modified by Benjamin Brink 11:29 PM, Thursday

Listed in chronological order, newest first.

Aram, Koch, Neumann. "Long-Term Analysis of the Development of the Open ACS Community Framework: Open Source Solutions for Knowledge Management and Technological Ecosystems" c2017 http://www.igi-global.com/chapter/long-term-analysis-of-the-development-of-the-open-acs-community-framework/168981

Demetriou, Koch, Neumann. "The Development of the OpenACS Community" http://nm.wu-wien.ac.at/research/publications/b608.pdf  A chapter from: Miltiadis Lytra, Ambjorn Naeve (eds): Open Source for Knowledge and Learning Management: Strategies Beyond Tools, Idea Group Publishing, Hershey, PA, 2006.

Andersson, Greenspun, Grumet. "Software Engineering for Internet Applications" c2006 http://philip.greenspun.com/seia/ "A 2002 textbook for MIT students learning how to build things like amazon.com"

Abelson, Greenspun, Sandon. "Tcl for Web Nerds" http://philip.greenspun.com/tcl/ "We hope that a professional programmer or MIT student can breeze through it in one evening. By the end of the evening, that person should have learned Tcl, learned a little something about the Web, and not have been bored."

Philip Greenspun. "SQL for Web Nerds" http://philip.greenspun.com/sql/ "..we keep our readers in the world of Web services. Most often they are working within the data model for online communities.. ..our examples are all drawn from real production Web sites that get close to 1 million requests per day. This should make the examples more interesting.. ..we assume that our readers are bright and accustomed to formal languages. We don't assume any experience with declarative languages, database query languages, or any specific programming language. But once we can assume that the reader has written code, it is possible to use more sophisticated examples and get to the interesting stuff more quickly. ..we hope that ..[its].. a great choice for the MIT student or the working programmer.

Philip Greenspun. "Philip and Alex's Guide to Web Publishing"e; c1998 http://philip.greenspun.com/panda/ A historical classic that introduced some early developers to the components and thinking behind OpenACS

Next Page
Previous Month June 2017
Sun Mon Tue Wed Thu Fri Sat
28 29 30 31 (4) 1 (3) 2 3
4 (1) 5 (3) 6 (9) 7 8 9 10
(2) 11 12 (5) 13 14 (1) 15 (7) 16 (7) 17
(7) 18 19 (3) 20 21 (3) 22 (1) 23 (8) 24
25 26 27 28 29 30 1

Popular tags

17 , 5.9.0 , 5.9.1 , ad_form , ADP , ajax , aolserver , asynchronous , bgdelivery , bootstrap , bugtracker , CentOS , COMET , CSP , CSRF , cvs , debian , emacs , fedora , FreeBSD , host-node-map , hstore , includelets , install , installation , installers , install-ns , javascript , libthread , linux
No registered users in community xowiki
in last 30 minutes
Contributors

OpenACS.org