<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Write the Requirements and Design Specs</title><meta name="generator" content="DocBook XSL Stylesheets V1.64.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter�10.�Advanced Topics"><link rel="previous" href="tutorial-advanced.html" title="Chapter�10.�Advanced Topics"><link rel="next" href="tutorial-cvs.html" title="Add the new package to CVS"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" border="0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><th width="60%" align="center">Chapter�10.�Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-specs"></a>Write the Requirements and Design Specs</h2></div></div><div></div></div><p>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 <a href="docbook-primer.html">OpenACS Documentation Guide</a>.</p><p>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
<tt class="computeroutput">/var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml</tt>
to
<tt class="computeroutput">myfirstpackage/www/docs/xml/index.xml</tt>.</p><p>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 <tt class="computeroutput">www/doc/xml</tt>
directory, and store png or jpg versions of supporting files in the
<tt class="computeroutput">www/doc</tt> directory.</p><p>For this tutorial, you should instead install the
pre-written documentation files for the tutorial app. Log in
as <span class="replaceable"><span class="replaceable">service0</span></span>, create the standard
directories, and copy the prepared documentation:</p><pre class="screen">[service0 service0]$ <b class="userinput"><tt>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/myfirstpackage/</tt></b>
[service0 myfirstpackage]$ <b class="userinput"><tt>mkdir -p www/doc/xml</tt></b>
[service0 myfirstpackage]$ <b class="userinput"><tt>cd www/doc/xml</tt></b>
[service0 xml]$ <b class="userinput"><tt>cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/acs-core-docs/www/files/myfirstpackage/* .</tt></b>
[service0 xml]$</pre><p> 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.</p><p>Open the file <tt class="computeroutput">index.xml</tt>
in emacs. Examine the file. Find the version history (look for the tag
<tt class="computeroutput"><revhistory></tt>). Add a
new record to the document version history. Look for the
<tt class="computeroutput"><authorgroup></tt> tag and
add yourself as a second author. Save and exit.</p><p>Process the xml file to create html documentation. The
html documentation, including supporting files such as pictures,
is stored in the <tt class="computeroutput">www/docs/</tt>
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:</p><pre class="screen">[service0 xml]$<b class="userinput"><tt> make</tt></b>
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)
Writing requirements-cases.html for chapter(requirements-cases)
Writing sample-data.html for chapter(sample-data)
Writing requirements.html for chapter(requirements)
Writing design-data-model.html for chapter(design-data-model)
Writing design-ui.html for chapter(design-ui)
Writing design-config.html for chapter(design-config)
Writing design-future.html for chapter(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 xml]$</pre><p>Verify that the documentation was generated and reflects
your changes by browsing to <tt class="computeroutput">http://<span class="replaceable"><span class="replaceable">yoursite</span></span>:8000/myfirstpackage/doc</tt></p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�10.�Advanced Topics </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Add the new package to CVS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/current/tutorial-specs.html#comments">View comments on this page at openacs.org</a></center></body></html>