| Prev | Chapter�10.�Engineering Standards | Next |
|---|
+
By claus@arsdigita.com, with additions by Roberto Mello and the OpenACS Community -
+
ArsDigita created a good documentation ground for us to build upon. Some sections of the documentation, however, lack details and examples; others are simply nonexistant. 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 + 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 + The documentation for OpenACS™ is written using DocBook XML. The reasons why we are using DocBook are explained in more details in the Why DocBook? section. I will add the reasons why @@ -28,11 +28,11 @@ SGML, with a couple extra rules. More details in the LDP Author Guide. -
In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the DocBook XML DTD - + 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. @@ -53,15 +53,15 @@ 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
Write all elements and attributes in lowercase
Quote all attributes -
You are going to need the following to work with the OpenACS Docbook XML documentation:
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 @@ -95,11 +95,11 @@ for acs-core-docs, especially the Detailed Design Documentation Template and the System/Application Requirements Template. -
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
@@ -117,31 +117,31 @@
... : ...
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 + 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. -
- - Given that your job starts at the sect1-level, all your documents should open with a - <sect1>-tag and end - with the corresponding </sect1>. +
+ + 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 - sect1's will turn into filenames when the book is parsed into HTML. + + 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 Section�, “Links”). + 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.
- - The other attribute is xreflabel. The value of this is the text that will appear - as the link when referring to this sect1. + + 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="aD DocBook Primer">
@@ -151,31 +151,31 @@
</sect1>
- + 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. + <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. -
- + 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 will use the tag - <computeroutput>. - This takes the place of the HTML-tag <code> + <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 + <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically. -
+ 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 + 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:
+Check out how I link to a subsection of the Developer's Guide:
Put this in your XML: @@ -191,10 +191,10 @@Note that even though this is an empty tag, you have to either:
- Provide the end-tag, </xref>, or + 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, + 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: @@ -206,26 +206,26 @@ And the output is: - Find information about what a package looks like in - the section called “What a Package Looks Like” + Section�, “What a Package Looks Like”
- Note that since I haven't provided an xreflabel for the subsection, - packages-looks, the + 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 a little different - (<ulink>): + (<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: & + entities, which is exactly how you'll make an ampersand: & -
NOTE: Currently this section currently only takes HTML-output into consideration - not a printed version
@@ -234,15 +234,15 @@ do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)
- + To insert a graphic we use the elements - <mediaobject>, - <imageobject>, + <mediaobject>, + <imageobject>, and - <imagedata>. + <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> - + <textobject> - in HTML this will be the ALT text.
<mediaobject>
@@ -259,15 +259,15 @@
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:
- 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> + 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>: + <listitem>:
<itemizedlist> @@ -277,20 +277,20 @@ </itemizedlist>
The ordered list is like the preceding, except that you use - <orderedlist> instead:
+ <orderedlist> instead:<orderedlist> <listitem><para>Stuff goes here</para></listitem> <listitem><para>More stuff goes here</para></listitem> </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>, - <term> and - <listitem>:
+ <variablelist>, + <varlistentry>, + <term> and + <listitem>:<variablelist> <varlistentry> @@ -304,10 +304,10 @@ </varlistentry> </variablelist> -
+ DocBook supports several types of tables, but in most cases, the - <informaltable> + <informaltable> is enough:
<informaltable frame="all">
@@ -339,26 +339,26 @@
With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table:
a1 b1 c1 a2 b2 c2 a3 b3 c3
If you want cells to span more than one row or column, it gets a bit more complicated - check out
- <table>
+ <table>
for an example.
-
+ Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - - <emphasis>. + <emphasis>.
- The <emphasis> tag defaults to italics when parsed. If you're looking for - emphasizing with bold type, use <emphasis role="strong">. -
+ The <emphasis> tag defaults to italics when parsed. If you're looking for + emphasizing with bold type, use <emphasis role="strong">. +
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> + <indexterm>, + <primary> and + <secondary> for this. See these links for an explanation. -
Once you have the Docbook Tools @@ -386,7 +386,7 @@ following command:
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml -