| Prev | Chapter�14.�Documentation Standards | Next |
|---|
+
By Claus Rasmussen, with additions by Roberto Mello and the OpenACS Community
@@ -238,7 +238,7 @@ is built and the library of tried and tested community building tools that are waiting to be added. It seems that most portals just add another layer of complexity to the - cake. See Slides on OACS + cake. See Slides on OACS features...a set of slides on OACS features that can be used for beginners who want to know OACS is about and what they can do with it. Screen captures that highlight @@ -336,7 +336,8 @@ description information and almost everything about a package for administrators and developers is already described in the package itself through two basic - development document templates: a Requirements Template and Detailed + development document templates: a + Requirements Template and Detailed Design Document.
By the OpenACS Community. This section is a collection of @@ -573,7 +574,7 @@ sufficient. We could even write our own, or just use the OpenACS templating system via the Edit-This-Page package. However, - + is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook:
@@ -637,7 +638,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 @@ -686,7 +687,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
@@ -710,20 +711,20 @@
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.
@@ -738,7 +739,7 @@ </sect1>
- + Inside this container your document will be split up into <sect2>'s, each with the same requirements - id and xreflabel @@ -747,7 +748,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.
- + 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>. @@ -757,12 +758,12 @@ <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:
+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:
@@ -786,7 +787,7 @@ 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 @@ -807,7 +808,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>, @@ -833,7 +834,7 @@ 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 @@ -878,7 +879,7 @@ </variablelist>
- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -915,7 +916,7 @@ <table> for an example.
- + Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.
@@ -993,4 +994,4 @@