To start developing new code in OpenACS, we build a new package. A package is a a discrete collection of web pages, tcl code, and database tables and procedures. A package can be installed, upgraded, and removed. It communicates with other packages through an API. This chapter walks you through the minimum steps to create a useful package, including:

You will need:

Tee ACS Package Manager initializes new packages. This sets up the initial directories, meta-information files, and database entries for a new package.

In order to see your work in progress, you must create a map between the URL space of incoming requests and the package. You do this by mounting the package in the Site Map.

By mounting the package, we've caused all requests to http://yourserver.test/samplenote to be satisfied from the files at /web/service0/packages/samplenote/www.

It's time to document. For a new package you should start by copying the documentation template from /web/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml to yourpackage/www/docs/xml/package-documentation.xml.

You then open that file with emacs, write the requirements and design section, generate html, and start coding. For this tutorial, you should instead install the pre-written documentation files for the tutorial app, examine them, generate html, read it, and then proceed to build the package. Store any diagrams in native format in the www/doc/xml directory, and store png or jpg versions of the diagrams in the www/doc direcory.

Pre-written documentation is available for this tutorial, so we'll copy that documentation and edit it. Log in as service0, create the standard directories, and copy the prepared documentation:

[service0@anthrax service0]$ cd /web/service0/packages/samplenote/
[service0@anthrax samplenote]$ mkdir -p www/doc/xml
[service0@anthrax samplenote]$ cp /web/service0/packages/acs-core-docs/www/files/samplenote/* www/doc/xml/
[service0@anthrax samplenote]$ mv www/doc/xml/*.dia www/doc/
[service0@anthrax samplenote]$ mv www/doc/xml/*.png www/doc/
[service0@anthrax samplenote]$

OpenACS uses DocBook for documentation. DocBook is an XML standard for semantic markup of documentation. That means that the tags you use indicate meaning, not intended appearance. The style sheet will determine appearance.

Open the file index.xml in emacs. Examine the file. Find the version history (look for the tag <revhistory>). Add a new record to the document version history. Look for the <authorgroup> tag and add yourself as a second author. Save and exit. For tips on editing SGML files in emacs, see OpenACS Documentation Guide

Process the xml file to create html documentation. The html documentation, including supporting files such as pictures, is stored in the www/docs/ directory. A Makefile is provided to generate html from the xml, and copy all of the supporting files. If Docbook is set up correctly, all you need to do is:

[service0@anthrax samplenote]$ cd www/doc/xml
[service0@anthrax xml]$ make
cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml
Writing requirements-introduction.html for sect1(requirements-introduction)
Writing requirements-overview.html for sect1(requirements-overview)
Writing requirements-cases.html for sect1(requirements-cases)
Writing sample-data.html for sect1(sample-data)
Writing sample-data.html for sect1(sample-data)
Writing requirements.html for chapter(requirements)
Writing design-data-model.html for sect1(design-data-model)
Writing design-ui.html for sect1(design-ui)
Writing design-config.html for sect1(design-config)
Writing design-future.html for sect1(design-future)
Writing filename.html for chapter(filename)
Writing user-guide.html for chapter(user-guide)
Writing admin-guide.html for chapter(admin-guide)
Writing bi01.html for bibliography
Writing index.html for book
[service0@yourserver xml]$

Verify that the documentation was generated and reflects your changes in the xml by browsing to http://yoursite:8000/samplenote/doc

Before you do any more work, make sure that your work is protected by putting it all into cvs. The cvs add command is not recursive, so you'll have to traverse the directory tree manually and add as you go.

[service0@yourserver xml]$ cd ..
[service0@yourserver doc]$ cd ..
[service0@yourserver www]$ cd ..
[service0@yourserver samplenote]$ cd ..
[service0@yourserver packages]$ cvs add samplenote/
Directory /cvsroot/service0/packages/samplenote added to the repository
[service0@yourserver packages]$ cd samplenote/
[service0@yourserver samplenote]$ cvs add www
Directory /cvsroot/service0/packages/samplenote/www added to the repository
[service0@yourserver samplenote]$ cd www
[service0@yourserver www]$ cvs add doc
Directory /cvsroot/service0/packages/samplenote/www/doc added to the repository
[service0@yourserver www]$ cd doc
[service0@yourserver doc]$ cvs add *
cvs add: cannot add special file `CVS'; skipping
cvs add: scheduling file `admin-guide.html' for addition
cvs add: scheduling file `bi01.html' for addition
cvs add: scheduling file `data-model.dia' for addition
cvs add: scheduling file `data-model.png' for addition
cvs add: scheduling file `design-config.html' for addition
cvs add: scheduling file `design-data-model.html' for addition
cvs add: scheduling file `design-future.html' for addition
cvs add: scheduling file `design-ui.html' for addition
cvs add: scheduling file `filename.html' for addition
cvs add: scheduling file `index.html' for addition
cvs add: scheduling file `page-map.dia' for addition
cvs add: scheduling file `page-map.png' for addition
cvs add: scheduling file `requirements-cases.html' for addition
cvs add: scheduling file `requirements-introduction.html' for addition
cvs add: scheduling file `requirements-overview.html' for addition
cvs add: scheduling file `requirements.html' for addition
cvs add: scheduling file `sample-data.html' for addition
cvs add: scheduling file `sample.png' for addition
cvs add: scheduling file `user-guide.html' for addition
cvs add: scheduling file `user-interface.dia' for addition
cvs add: scheduling file `user-interface.png' for addition
Directory /cvsroot/service0/packages/samplenote/www/doc/xml added to the repository
cvs add: use 'cvs commit' to add these files permanently
[service0@yourserver doc]$ cd xml
[service0@yourserver xml]$ cvs add Makefile index.xml
cvs add: scheduling file `Makefile' for addition
cvs add: scheduling file `index.xml' for addition
cvs add: use 'cvs commit' to add these files permanently
[service0@yourserver xml]$ cd ../../..
[service0@yourserver samplenote]$ cvs commit -m "new package"
cvs commit: Examining .
cvs commit: Examining www
cvs commit: Examining www/doc
cvs commit: Examining www/doc/xml
RCS file: /cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v
done
Checking in www/doc/admin-guide.html;
/cvsroot/service0/packages/samplenote/www/doc/admin-guide.html,v  <--  admin-guide.html
initial revision: 1.1
done
(many lines omitted)
[service0@yourserver samplenote]$