| Prev | Chapter 8. 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 @@ -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. @@ -52,16 +52,16 @@ 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: - + 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 + 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,48 +95,48 @@ 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 + book : Docs for one package - templating | - +--chapter : One section - for developers + +--chapter : One section - for developers | ---------+------------------------------------------------------ | - +--sect1 : Single document - requirements + +--sect1 : Single document - requirements | - +--sect2 : Sections - functional requirements + +--sect2 : Sections - functional requirements | - +--sect3 : Subsections - Programmer's API + +--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. -
+ 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.
@@ -151,16 +151,16 @@ </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.
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>. @@ -169,13 +169,13 @@ 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. -
+ 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:
+Check out how I link to a subsection of the Developer's Guide:
Put this in your XML: @@ -212,8 +212,8 @@ 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 @@ -222,19 +222,19 @@
<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 +
NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing 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
- Another Note: Also, it's still not a 100 percent sure that this is how we are going to + Another 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 ;)
- + To insert a graphic we use the elements <mediaobject>, <imageobject>, @@ -259,10 +259,10 @@
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> @@ -275,7 +275,7 @@ <listitem><para>More stuff goes here</para></listitem> </itemizedlist> -
+
The ordered list is like the preceding, except that you use <orderedlist> instead:
<orderedlist> @@ -284,7 +284,7 @@ <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>, @@ -304,8 +304,8 @@ </varlistentry> </variablelist> -
+ DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -337,18 +337,18 @@ </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> for an example. -
+ 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">. -
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. @@ -358,7 +358,7 @@ <primary> and <secondary> for this. See these links for an explanation. -
Once you have the Docbook Tools @@ -376,7 +376,7 @@
bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml -
| 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 |