Index: openacs-4/packages/acs-core-docs/www/tutorial-specs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-specs.html,v diff -u -r1.9.2.1 -r1.9.2.2 --- openacs-4/packages/acs-core-docs/www/tutorial-specs.html 10 Jun 2009 22:24:09 -0000 1.9.2.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-specs.html 11 Sep 2009 23:41:28 -0000 1.9.2.2 @@ -1,39 +1,39 @@ - -
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 ???.
It's time to document. For the tutorial we'll use + editing SGML files in emacs, see Section , “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.xml in 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]$ make cd .. ; /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) @@ -50,4 +50,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