| Prev | Chapter�10.�Advanced Topics | Next |
|---|
Before you get started you should make yourself familiar with +
Before you get started you should make yourself familiar with the tags that are used to write your documentation. For tips on editing SGML files in emacs, see the section called “OpenACS Documentation Guide”.
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
+ /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml
to
- myfirstpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the
+ myfirstpackage/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
+ 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
+ www/doc directory.
For this tutorial, you should instead install the pre-written documentation files for the tutorial app. Log in as $OPENACS_SERVICE_NAME, create the standard - directories, and copy the prepared documentation:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/ -[$OPENACS_SERVICE_NAME myfirstpackage]$ mkdir -p www/doc/xml -[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www/doc/xml -[$OPENACS_SERVICE_NAME xml]$ cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/myfirstpackage/* . + directories, and copy the prepared documentation:[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/+[$OPENACS_SERVICE_NAME myfirstpackage]$mkdir -p www/doc/xml+[$OPENACS_SERVICE_NAME myfirstpackage]$cd www/doc/xml+[$OPENACS_SERVICE_NAME xml]$cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/myfirstpackage/* .[$OPENACS_SERVICE_NAME 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 + into html for reading.
Open the file
index.xmlin emacs. Examine the file. Find the version history (look for the tag - <revhistory>). Add a +<revhistory>). Add a new record to the document version history. Look for the - <authorgroup> tag and +<authorgroup>tag and add yourself as a second author. Save and exit.Process the xml file to create html documentation. The html documentation, including supporting files such as pictures, - is stored in the www/docs/ + 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:[$OPENACS_SERVICE_NAME xml]$ make + to do is:[$OPENACS_SERVICE_NAME xml]$makecd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml Writing requirements-introduction.html for chapter(requirements-introduction) Writing requirements-overview.html for chapter(requirements-overview) @@ -49,4 +49,4 @@ Writing bi01.html for bibliography Writing index.html for book [$OPENACS_SERVICE_NAME xml]$Verify that the documentation was generated and reflects - your changes by browsing to http://yoursite:8000/myfirstpackage/doc
http://yoursite:8000/myfirstpackage/doc