| Prev | Chapter�9.�Engineering Standards | Next |
|---|
+
By Claus Rasmussen, 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 @@ -16,34 +16,38 @@ 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 + next section. A few more 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 + Consistency. We started with a collection + of DcoBook 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. +
+ The tool chain has matured. xsltproc and other XML + based tools have improved to the point where they are about as good as + the SGML tools and generation of both html and pdf output is straighforward.
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.
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 + for a while (since the early 90's), + it's well-tested, it's complete, it's designed for technical documentation and best of all, it's open-source. A growing community surrounds DocBook (has - mailing lists) + mailing lists) and a number of free and commercial - tools are available + tools are available for editing and publishing DocBook documents.
This primer walks you through the basics, and should cover the @@ -53,7 +57,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 @@ -102,7 +106,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
@@ -126,101 +130,87 @@
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 + <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.
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 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, + <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.
- + 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>. + <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 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: - - - 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 - Making a Package - -
+
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:
+- Find information about creating a package in +Making a Package. +
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 - the section called “What a Package Looks Like” - -
+ 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, 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>
@@ -237,117 +227,117 @@ 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"/> - </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> -
+<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.
- + 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> + <itemizedlist> and - <listitem>: + <listitem>:
- <itemizedlist> - - <listitem><para>Stuff goes here</para></listitem> - <listitem><para>More stuff goes here</para></listitem> +<itemizedlist> - </itemizedlist> -
+ <listitem><para>Stuff goes here</para></listitem> + <listitem><para>More stuff goes here</para></listitem> + +</itemizedlist> +
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> instead:+<orderedlist> - </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 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> + <variablelist>, + <varlistentry>, + <term> and + <listitem>:+<variablelist> - <varlistentry> - <term>Another heading goes here</term> - <listitem><para>And more stuff goes here</para></listitem> - </varlistentry> + <varlistentry> + <term>Heading (<dt>) goes here</term> + <listitem><para>And stuff (<dd>)goes here</para></listitem> + </varlistentry> - </variablelist> -
+ DocBook supports several types of tables, but in most cases, the - <informaltable> + <informaltable> is enough:
- <informaltable frame="all">
- <tgroup cols="3">
- <tbody>
+<informaltable frame="all">
+ <tgroup cols="3">
+ <tbody>
<row>
- <entry>a1</entry>
- <entry>b1</entry>
- <entry>c1</entry>
+ <entry>a1</entry>
+ <entry>b1</entry>
+ <entry>c1</entry>
</row>
<row>
- <entry>a2</entry>
- <entry>b2</entry>
- <entry>c2</entry>
+ <entry>a2</entry>
+ <entry>b2</entry>
+ <entry>c2</entry>
</row>
<row>
- <entry>a3</entry>
- <entry>b3</entry>
- <entry>c3</entry>
+ <entry>a3</entry>
+ <entry>b3</entry>
+ <entry>c3</entry>
</row>
- </tbody>
- </tgroup>
- </informaltable>
- + </tbody> + </tgroup> +</informaltable> +
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
+
| 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">. @@ -357,15 +347,14 @@ 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.
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 - formats). + installed, you can convert your xml documents to HTML or other + formats.
With the DocBook XSL stylesheets, generation of multiple files is controlled by the stylesheet. If you want to generate a @@ -376,7 +365,7 @@ 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, @@ -387,7 +376,10 @@ following command:
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml -
+
+ You could also look at the acs-core-docs Makefile + for examples of how these documents are generated.` +
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 @@ -421,4 +413,4 @@