The history of OpenACS documentation: ..began by - building on a good documentation base from ArsDigita's ACS in the + building on a good documentation base from ArsDigita's ACS in the late 1990's. Some sections of the documentation, however, lacked details and examples; others simply did not exist. The OpenACS community began meeting the challenge by identifying needs and @@ -36,7 +36,7 @@ developers had to learn the system through experience with working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge has become the OpenACS - community's main method of sharing knowledge. + community's main method of sharing knowledge.
This document attempts to shape ongoing documentation efforts by using principles of continual improvement to re-engineer @@ -166,7 +166,7 @@ book in print, and help new readers visualize how the documentation is organized.
- The use licenses between OpenACS and Arsdigita's ACS are not + The use licenses between OpenACS and Arsdigita's ACS are not compatible, thereby creating strict limits on how much OpenACS developers should have access to Arsdigita code and resources. The OpenACS documentation has a new legal @@ -323,8 +323,8 @@
Create a long bulleted list of features. Feature list should go deeper than high-level feature lists and look at the - quality of the implementations (from the user's perspective, - not the programmer's). Example issues an end-user may have + quality of the implementations (from the user's perspective, + not the programmer's). Example issues an end-user may have questions about: Ticket Tracker and Ticket Tracker Lite, why would I want one of them vs the other? And, before I specify to download and install it, what credit card gateways are @@ -363,7 +363,7 @@
Create a list of administrative tools that are useful to administrating OpenACS, including developer support, - schema-browser and api browser. Link to AOLserver's config + schema-browser and api browser. Link to AOLserver's config file documentation.
Resources on high level subjects such as web services, @@ -514,7 +514,7 @@ they are not available elsewhere.
Add overview diagrams showing the core parts of the - datamodel including an updated summary of Greenspun's + datamodel including an updated summary of Greenspun's Chapter 4: Data Models and the Object System
package design guidelines and development process templates @@ -578,7 +578,7 @@ DTD. The remaining discussion is about publishing using Docbook.
- + is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook:
@@ -636,12 +636,12 @@ to represent paper-based books online.
The following DocBook primer walks you through the basics, and should cover the - needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's + needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically the same elements are valid in the XML DTD as long as you remember to: - +
Always close your tags with corresponding end-tags and to not use other tag minimization @@ -661,7 +661,7 @@ XSL Stylesheets (docbook-xsl) - The stylesheets to convert to HTML. We have been using a stylesheet based upon - NWalsh's chunk.xsl. + NWalsh's chunk.xsl.
xsltproc - The processor that
will take an XML document and, given a xsl stylesheet, convert
@@ -690,7 +690,7 @@
The documentation for each package will make up a little "book" that is structured like this
- examples are emphasized:
-
+
book : Docs for one package - templating
@@ -703,7 +703,7 @@
|
+--sect2 : Sections - functional requirements
|
- +--sect3 : Subsections - Programmer's API
+ +--sect3 : Subsections - Programmer's API
|
... : ...
@@ -714,25 +714,25 @@ sources of these DocBook documents to get an idea of how they are tied together.
-
+
Given that your job starts at the sect1-level, all your documents should open with a
<sect1>-tag and end
with the corresponding </sect1>.
-
+
You need to feed every <sect1> two attributes. The first attribute,
id, is standard and can be used with all elements. It comes in very
handy when interlinking between documents (more about this when talking about links in the section called “Links”).
The value of id has to be unique
- throughout the book you're making since the id's in your
+ throughout the book you're making since the id's in your
sect1's will turn into filenames when the book is parsed into HTML.
-
+
The other attribute is xreflabel. The value of this is the text that will appear
as the link when referring to this sect1.
Right after the opening tag you put the title of the document - this is usually the same as
- xreflabel-attribute. E.g. the top level of the document you're
+ xreflabel-attribute. E.g. the top level of the document you're
reading right now looks like this:
<sect1 id="docbook-primer" xreflabel="DocBook Primer"> @@ -742,7 +742,7 @@ </sect1>
-
+
Inside this container your document will be split up into
<sect2>'s,
each with the same requirements - id and xreflabel
@@ -751,7 +751,7 @@
When it comes to naming your
sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview.
-
+
For displaying a snippet of code, a filename or anything else you just want to appear as a part of
a sentence, we use
<computeroutput>
@@ -769,12 +769,12 @@
tag around text that has been wrapped by combinations of <computeroutput>
and <userinput>
- - Linking falls into two different categories: inside the book you're making and outside: + + Linking falls into two different categories: inside the book you're making and outside:
By having unique id's you can cross-reference any part of your book
with a simple tag, regardless of where that part is.
-
Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
+Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
- Find information about creating a package in <xref linkend="packages-making-a-package"></xref>.And the output is:
@@ -786,20 +786,20 @@ Provide the end-tag,</xref>, or
Put a slash before the ending-bracket: <xref linkend="blahblah"/>
-
If the section you link to hasn't a specified xreflabel-attribute,
+
If the section you link to hasn't a specified xreflabel-attribute,
the link is going to look like this:
Put this in your XML:
-Find information about what a package looks like in <xref linkend="packages-looks"></xref>.
And the output is:
- Find information about what a package looks like in the section called “What a Package Looks Like”.
- Note that since I haven't provided an xreflabel for the subsection,
+ Note that since I haven't provided an xreflabel for the subsection,
packages-looks, the
parser will try its best to explain where the link takes you.
-
- If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
+
+ If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
a little different
(<ulink>):
@@ -819,7 +819,7 @@
for you.
-
+
To insert a graphic we use the elements
<mediaobject>,
<imageobject>,
@@ -845,8 +845,8 @@
Put your graphics in a separate directory ("images") and link to them
only with relative paths.
- - Here's how you make the DocBook equivalent of the three usual HTML-lists: + + Here's how you make the DocBook equivalent of the three usual HTML-lists:
Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as
<para>, and that the tags are called
@@ -870,7 +870,7 @@
</orderedlist>
- This kind of list is called a variablelist and these are the tags you'll need to
+ This kind of list is called a variablelist and these are the tags you'll need to
make it happen:
<variablelist>,
<varlistentry>,
@@ -890,7 +890,7 @@
</variablelist>
-
+
DocBook supports several types of tables, but in most cases, the
<informaltable>
is enough:
@@ -927,11 +927,11 @@
<table>
for an example.
-
+
Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one -
<emphasis>.
- The <emphasis> tag defaults to italics when parsed. If you're looking for
+ The <emphasis> tag defaults to italics when parsed. If you're looking for
emphasizing with bold type, use <emphasis role="strong">.
Words that are marked as index-words are referenced in an index @@ -957,7 +957,7 @@
bash$xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
- This example uses Daniel Veillard's xsltproc command available + This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately. @@ -983,7 +983,7 @@ David Lutterkort wrote an intro to the PSGML Mode in Emacs
- James Clark's free Java parser + James Clark's free Java parser XP. Note that this does not validate XML, only parses it.
@@ -997,7 +997,7 @@
In the process of transforming your HTML into XML, HTML tidy - can be a handy tool to make your HTML "regexp'able". + can be a handy tool to make your HTML "regexp'able". Brandoch Calef has made a Perl script with directions (now via archive.org)