| Prev | Chapter�12.�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 +27,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 +52,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 +94,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 +
+ 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,70 +116,70 @@
... : ...
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">
+ <sect1 id="docbook-primer" xreflabel="aD DocBook Primer">
<title>aD DocBook Primer</title>
...
</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: - Find information about creating a package in - <xref linkend="packages-making-a-package"></xref>. + <xref linkend="packages-making-a-package"></xref>. And the output is: @@ -191,41 +190,41 @@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: - Find information about what a package looks like in - <xref linkend="packages-looks"></xref>. + <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” + 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>
+
<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,40 +233,40 @@ 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>
<imageobject>
- <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
+ <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
</imageobject>
<imageobject>
- <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/>
+ <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 + 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 +276,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,14 +303,14 @@ </varlistentry> </variablelist> -
+ DocBook supports several types of tables, but in most cases, the - <informaltable> + <informaltable> is enough:
- <informaltable frame="all">
- <tgroup cols="3">
+ <informaltable frame="all">
+ <tgroup cols="3">
<tbody>
<row>
@@ -339,26 +338,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,10 +385,10 @@ following command:
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml -
In the process of transforming your HTML into XML, HTML tidy - can be a a handy tool to make your HTML "regexp'able". + 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. -
| Document Revision # | Action Taken, Notes | When? | By Whom? | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 0.4 |
+
| 12/24/2001 | Roberto Mello | ||||||||||||||||||||
| 0.2 | Changed recommendation from <phrase> to <emphasis role="strong"> | 01/19/2000 | Claus Rasmussen | ||||||||||||||||||||
| 0.1 | Creation | 12/2000 | Claus Rasmussen |