OpenACS Documentation Guide

- By claus@arsdigita.com, with - additions by Roberto +OpenACS Documentation Guide

Prev	Chapter�9.�Engineering Standards	Next

OpenACS Documentation Guide

+ By Claus Rasmussen, with additions by Roberto Mello and the OpenACS Community -

Overview of OpenACS 5.0.0b1 Documentation

Overview of OpenACS 5.0.0b2 Documentation

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 @@ -19,19 +18,21 @@ DocBook are explained in more details in the Why DocBook? section. I will add the reasons why we are using Docbook XML instead of Docbook SGML: -

Consistency. We already have a bunch of +
- + 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 +
- + 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 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. @@ -52,7 +53,7 @@ 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 @@ -63,24 +64,27 @@

Tools

You are going to need the following to work with the OpenACS Docbook XML documentation: -

Docbook XML +
+ 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 +
+ 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 +
+ 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 @@ -98,7 +102,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
@@ -122,20 +126,20 @@
       sources of these DocBook documents
       to get an idea of how they are tied together.

Headlines, Sections

- + 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.

- + The other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1.

@@ -150,7 +154,7 @@ </sect1>

- + Inside this container your document will be split up into <sect2>'s, each with the same requirements - id and xreflabel @@ -159,7 +163,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.

Code

- + 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>. @@ -169,12 +173,12 @@ <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.

Links

- + 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. -

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:
 
@@ -212,7 +216,7 @@
 	    packages-looks, the
 	    parser will try its best to explain where the link takes you.

2. Linking outside the documentation

- + If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different @@ -233,7 +237,7 @@ 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>, @@ -259,7 +263,7 @@ Put your graphics in a separate directory ("images") and link to them only with relative paths.

Lists

- + 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 @@ -304,7 +308,7 @@ </variablelist>

Tables

- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -341,7 +345,7 @@ <table> for an example.

Emphasis

- + Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.

@@ -357,9 +361,7 @@ <primary> and <secondary> for this. See these links for an explanation. -

Converting to HTML

Note

- This section is quoted almost verbatim from the LDP Author Guide. -

Converting to HTML

Note

This section is quoted almost verbatim from the LDP Author Guide.

Once you have the Docbook Tools installed, you can convert your xml documents to HTML (or other formats. Let me know if you are able to convert to other @@ -374,25 +376,24 @@ use the command:

 bash$  xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
-

Note

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
-