Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v
diff -u -r1.3 -r1.4
--- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 20 Aug 2003 16:20:18 -0000 1.3
+++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 28 Oct 2003 22:07:40 -0000 1.4
@@ -43,6 +43,135 @@
+
+ Write the Requirements and Design Specs
+ 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
+ /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
+ to
+ 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@yourserver service0]$ cd /var/lib/aolserver/service0/packages/samplenote/
+[service0@yourserver samplenote]$ mkdir -p www/doc/xml
+[service0@yourserver samplenote]$ cd www/doc/xml
+[service0@yourserver xml]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/samplenote/* .
+[service0@yourserver 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. 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
+ 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
+ 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@yourserver 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 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 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. (More on
+ CVS)
+ [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]$
+
Delete with confirmation
We need a way to delete records. We'll create a