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