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 +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
to myfirstpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the requirements and
@@ -21,11 +22,13 @@
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 $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/+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/* .-[$OPENACS_SERVICE_NAME xml]$OpenACS uses DocBook for documentation. DocBook is an XML +[$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
@@ -38,7 +41,8 @@
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+correctly, all you need 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) @@ -54,13 +58,14 @@ Writing admin-guide.html for chapter(admin-guide) Writing bi01.html for bibliography Writing index.html for book -[$OPENACS_SERVICE_NAME xml]$Verify that the documentation was generated and reflects your +[$OPENACS_SERVICE_NAME xml]$ +
Verify that the documentation was generated and reflects your
changes by browsing to http://yoursite:8000/myfirstpackage/doc