Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 30 Mar 2003 20:31:48 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 7 Apr 2003 16:45:17 -0000 1.3 @@ -12,18 +12,10 @@ 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: - - - How to use the APM to start a new package - How to write documentation, including self-documenting code - How to set up the database tables and procedures. - - How to write web pages. - - How to add automated regression testing to your packages - How to debug your package - + minimum steps to create a useful package, including writing + documentation, setting up database tables and procedures, + writing web pages, debugging, and automatic regression testing. + @@ -65,12 +57,17 @@ - - Use the APM to start a new package - Tee ACS Package Manager initializes new packages. This sets - up the initial directories, meta-information files, and - database entries for a new package. + Use the APM to initialize a new package + We use the ACS Package Manager (APM) to add, remove, and + upgrade packages. It handles package meta-data, such as lists of + files that belong in the package. Each package is uniquely + identified by a package key. To start developing a new + package, use the APM to create an empty package with our new + package key, samplenote. This will create + the initial directories, meta-information files, and database + entries for a new package. (More info on APM) @@ -89,11 +86,11 @@ Package Name: - Notes (Sample Application) + Notes Package Plural: - Notes (Sample Applications) + Notes Initial Version: 0.1d @@ -102,72 +99,84 @@ This is my first package. - At the bottom, click - Create Package. + At the bottom, click + Create Package. + This creates a package rooted at + /web/service0/packages/samplenote. + This is the "home directory" of our new package, and all + files in the package will be within this directory. Mount the package in the site map 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. + You do this by mounting the package in the Site Map. This + creates a link between the incoming URL and an + instance of the package. (More on Site Maps and nodes) + You can have + multiple instances of a package on one site, each with a + different URL and different permissions, all sharing the same + code and tables. This requires that a package be developed + package-aware. You'll see how to do that + in this tutorial. Browse to -http://yourserver:8000/admin/site-map/. +http://yourserver.test:8000/admin/site-map/. Click the new sub - folder link on the Main Site - line. + folder link on the top row in the + Site Map table. - Type samplenote + Type note and click New. - Click the new -application link on the samplenote line. - Type Sample Note -where it says + This creates a new row called +note. In the new row, click the new +application link + Type Sample Note where +it says untitled, choose -Notes (Sample Application) from the -drop-down list, and click -New. +Notes from the drop-down list, and +click New. By mounting the package, we've caused all requests to - http://yourserver.test/samplenote + http://yourserver.test:8000/note to be satisfied from the files at /web/service0/packages/samplenote/www. Write the Requirements and Design Specs - It's time to document. For a new package you should - start by copying the documentation template from + It's time to document. For the tutorial we'll use + pre-written documentation. When creating a package + from scratch, 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 + yourpackage/www/docs/xml/index.xml. + You then edit that file with emacs to write the + requirements and design sections, generate the html, and start + coding. Store any supporting files, like page maps or schema + diagrams, in the www/doc/xml + directory, and store png or jpg versions of supporting files in the + www/doc directory. + For this tutorial, you should instead install the + pre-written documentation files for the tutorial app. 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]$ +[service0@anthrax samplenote]$ cd www/doc/xml +[service0@anthrax xml]$ cp /web/service0/packages/acs-core-docs/www/files/samplenote/* . +[service0@anthrax xml]$ 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. + appearance. The style sheet will determine appearance. You + will edit the text in an xml file, and then process the file + into html for reading. Open the file index.xml in emacs. Examine the file. Find the version history (look for the tag <revhistory>). Add a @@ -182,14 +191,12 @@ 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 + [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) @@ -202,14 +209,16 @@ 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 + your changes by browsing to http://yoursite:8000/samplenote/doc Add the new package to CVS 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. + traverse the directory tree manually and add as you go. (More on + CVS) [service0@yourserver xml]$ cd .. [service0@yourserver doc]$ cd .. [service0@yourserver www]$ cd ..