OpenACS Documentation Guide
By claus@arsdigita.com, with
additions by Roberto
Mello and the OpenACS Community
Overview of OpenACS &version; Documentation
ArsDigita created a good documentation ground for us to build
upon. Some sections of the documentation however, lack details
and examples, others simply are inexistent.Our goal is to give
OpenACS a superb documentation, so that users, developers and
administrators of OpenACS installations can enjoy the system.
OpenACS is a powerful system, with
incredible possibilities and applications, but with this power
comes some complexity and a learning curve that will only be
atenuated by good documentation. This is what we are after.
The documentation for OpenACS is
written using DocBook XML. The reasons why we are using
DocBook are explained in more details in the
section. I will add the reasons why
we are using Docbook XML instead of Docbook SGML:
Consistency. We already have a bunch of
.xml files that ArsDigita wrote. Trying to re-write them to
conform to the SGML DTD would be unnecessary work (I tried).
It does not require extra
effort. Writing in XML is almost identical to
SGML, with a couple extra rules. More details in the
LDP
Author Guide.
Why DocBook?
In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the
DocBook XML DTDDocBookDTD
This enables us to publish in a variety
of formats and relieves each contributor of the burden of presentation, freeing him to focus
on content and sharing knowledge.
Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around
for a while (since early 90's),
it's well-tested, it's complete, it's extremely well-suited for technical documents
and best of all, it's open-source. A growing community surrounds DocBook (has
mailing lists)
and a number of free and commercial
tools are available
for editing and publishing DocBook documents.
This primer walks you through the basics, and should cover the
needs for 95 percent of the documentation we produce. However,
you're always welcome to check out 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:
XML guidelines
Always close your tags with corresponding end-tags and to
not use other tag minimization
Write all elements and attributes in lowercase
Quote all attributes
Tools
You are going to need the following to work with the OpenACS
Docbook XML documentation:
Docbook XML
DTD - The document type definition for XML. You can
find an RPM or DEB package or you can download a zip file from
the site linked from here.
XSL
Stylesheets (docbook-xsl) - The stylesheets to convert
to HTML. We have been using a stylesheet based upon
NWalsh's chunk.xsl.
xsltproc - The processor that
will take an XML document and, given a xsl stylesheet, convert
it to HTML. It needs libxml2 and libxslt (available in RPM and
DEB formats or from xmlsoft.org.
Some editing tool. A popular one is Emacs with the psgml
mode. We have a intro to the PSGML
Mode in Emacs as part of our documentation. You can
read about other editing tools in the LDP Author Guide.
Writing New Docs
After you have the tools mentioned above, you need to define a
title for your document. Then start thinking about the possible
sections and subsections you will have in your document. Make
sure you coordinate with the OpenACS Gatekeepers to make sure
you're not writing something that someone else is already
writing. Also, if you desire to use the OpenACS CVS repository,
please e-mail the gatekeeper in charge of documentation.
You can look at some templates for documents (in Docbook XML) in
the sources
for acs-core-docs, especially the
Detailed Design Documentation Template and the
System/Application Requirements Template.
Document Structure
The documentation for each package will make up a little "book" that is structured like this
- examples are emphasized:
Document structure
book : Docs for one package - templating
|
+--chapter : One section - for developers
|
---------+------------------------------------------------------
|
+--sect1 : Single document - requirements
|
+--sect2 : Sections - functional requirements
|
+--sect3 : Subsections - Programmer's API
|
... : ...
The actual content is split up into documents that start at a
sect1-level. These are then tied together in a top-level document that
contains all the information above the line. This will be explained in more detail in a later document,
and we will provide a set of templates for documenting an entire package. For now you can take a look at the
sources of these DocBook documents
to get an idea of how they are tied together.
Headlines, SectionsSectionsHeadlines
Given that your job starts at the sect1-level, all your documents should open with a
<sect1>-tag and end
with the corresponding </sect1>.
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 value of id has to be unique
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.
xreflabel
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
reading right now looks like this:
<sect1 id="docbook-primer" xreflabel="aD DocBook Primer">
<title>aD DocBook Primer</title>
...
</sect1>
sect2
Inside this container your document will be split up into
<sect2>'s,
each with the same requirements - id and xreflabel
attributes, and a <title>-tag inside. Actually, the xreflabel is never required in sections, but it makes linking to that section a lot easier.
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.
Codecomputeroutputcode
For displaying a snippet of code, a filename or anything else you just want to appear as a part of
a sentence, we will use the tag
<computeroutput>.
This takes the place of the HTML-tag <code>
For bigger chunks of code such as SQL-blocks, the tag
<programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of
automatically.
LinksLinking
Linking falls into two different categories: inside the book you're making and outside:
1. Inside linking, cross-referencing other parts of your book
By having unique id's you can cross-reference any part of your book
with a simple tag, regardless of where that part is.
xreflinkendCheck 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:
- Find information about creating a package in
Note that even though this is an empty tag, you have to either:
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,
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
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.
2. Linking outside the documentationulink
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>):
<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>
....will create a hyper-link to Oracle in the HTML-version of the documentation.
NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing
entities, which is exactly how you'll make an ampersand: &GraphicsNOTE: Currently this section currently only takes HTML-output into consideration -
not a printed versionAnother Note: Also, it's still not a 100 percent sure that this is how we are going to
do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)
GraphicsImages
To insert a graphic we use the elements
<mediaobject>,
<imageobject>,
and
<imagedata>.
The news is that you have to provide two versions of all your graphics - one for the Web (probably a GIF or a JPEG)
and one for print (EPS). Finally you should provide a brief description wrapped in
<textobject> -
in HTML this will be the ALT text.
<mediaobject>
<imageobject>
<imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
</imageobject>
<imageobject>
<imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/>
</imageobject>
<textobject>
<phrase>This is an image of the flow in the Request Processor</phrase>
</textobject>
</mediaobject>
Put your graphics in a separate directory ("images") and link to them
only with relative paths.
Listslists
Here's how you make the DocBook equivalent of the three usual HTML-lists:
1. How to make an <ul>
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
<itemizedlist>
and
<listitem>:
<itemizedlist>
<listitem><para>Stuff goes here</para><listitem>
<listitem><para>More stuff goes here</para><listitem>
</itemizedlist>
2. How to make an <ol>
The ordered list is like the preceding, except that you use
<orderedlist> instead:
<orderedlist>
<listitem><para>Stuff goes here</para><listitem>
<listitem><para>More stuff goes here</para><listitem>
</orderedlist>
3. How to make a <dl>
This kind of list is called a variablelist and these are the tags you'll need to
make it happen:
<variablelist>,
<varlistentry>,
<term> and
<listitem>:
<variablelist>
<varlistentry>
<term>Heading (<dt>) goes here</term>
<listitem><para>And stuff (<dd>)goes here</para><listitem>
</varlistentry>
<varlistentry>
<term>Another heading goes here</term>
<listitem><para>And more stuff goes here</para><listitem>
</varlistentry>
</variablelist>
Tablesinformaltabletable
DocBook supports several types of tables, but in most cases, the
<informaltable>
is enough:
<informaltable frame="all">
<tgroup cols="3">
<tbody>
<row>
<entry>a1</entry>
<entry>b1</entry>
<entry>c1</entry>
</row>
<row>
<entry>a2</entry>
<entry>b2</entry>
<entry>c2</entry>
</row>
<row>
<entry>a3</entry>
<entry>b3</entry>
<entry>c3</entry>
</row>
</tbody>
</tgroup>
</informaltable>
With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table:
a1b1c1a2b2c2a3b3c3
If you want cells to span more than one row or column, it gets a bit more complicated - check out
<table>
for an example.
Emphasisemphasisbold, italics
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
emphasizing with bold type, use <emphasis role="strong">.
Indexing Your DocBook Documents
Marking up index-words may not have any importance for the HTML-output, but in order to make it easier to make
a nice print-version of the documentation, you should mark up words in your documents that you would like to
see show up in an index one day.
Use
<indexterm>,
<primary> and
<secondary>
for this. See these links for an explanation.
Converting to HTML
This section is quoted almost verbatim from the LDP Author Guide.
Once you have the
installed, you can convert your xml documents to HTML (or other
formats. Let me know if you are able to convert to other
formats).
With the DocBook XSL stylesheets, generation of multiple files
is controlled by the stylesheet. If you want to generate a
single file, you call one stylesheet. If you want to generate
multiple files, you call a different stylesheet.
To generate a single HTML file from your DocBook XML file,
use the command:
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
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.
To generate a set of linked HTML pages, with a separate page
for each <chapter>, <sect1> or <appendix> tag, use the
following command:
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml
Further Reading
The LDP Author
Guide has a lot of good information, a table of
docbook elements and their "look" in HTML and lots of good links
for tools.
David
Lutterkort
wrote an intro to the PSGML Mode in Emacs
For checking if your document is well-formed, James Clark's free Java parser,
XP, is recommended. (note that
it is not a validating parser, but as long as you follow the guidelines set forth in this
document, your XML will validate)DocBook Tool for Linux:
Let's you convert your docbook documents to a number of formats. Sometimes it's nice to see
how you stuff looks. NOTE: I only got these to
work with Docbook SGML, NOT with Docbook XML. If you are
able to make it work with our XML, please let us know.
AptConvert from PIXware is a Java editor that will produce
DocBook documents and let you transform them into HTML and PDF for a local preview before you submit.
In the process of transforming your HTML into XML,
HTML tidy
can be a a handy tool to make your HTML "regexp'able".
Brandoch Calef has made a
Perl script
that gets you most of the way.
Revision HistoryDocument Revision #Action Taken, NotesWhen?By Whom?0.3
Added OpenACS information, updated tools, added
extra links and added info to the Publishing section.
12/24/2001Roberto Mello0.2Changed recommendation from <phrase> to <emphasis role="strong">01/19/2000Claus Rasmussen0.1Creation12/2000Claus Rasmussen