| Prev | Chapter 13. Documentation Standards | Next |
|---|
+
By Claus Rasmussen, with additions by Roberto Mello, Vinod Kurup, and the OpenACS Community
OpenACS™ is a powerful system with @@ -421,7 +421,7 @@ installation."
list critical decisions (perhaps as questions) that need to - be made before starting: which OS, which DB, which aolserver + be made before starting: which OS, which DB, which AOLserver version, system name, dependencies et cetera. Maybe summarize options as tables or decision-trees. For example, "As you proceed throughout the installation, you will be acting on @@ -458,7 +458,7 @@ installation documentation
Provide working examples that highlight the various - subsystems, tcl environment, OpenACS protocols, aolserver + subsystems, Tcl environment, OpenACS protocols, AOLserver template and ns_* commands, OpenACS templating, sql queries, db triggers, scheduling protocols, how to use the page contract, how to get the accessing user_id etc @@ -578,17 +578,16 @@ DTD. The remaining discussion is about publishing using Docbook.
- + is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook:
It is open-source.
- A growing community surrounds DocBook (has - mailing lists) + The DocBook community mailing lists
A number of free and commercial - tools are available + tools are available for editing and publishing DocBook documents.
It enables us to publish in a variety of formats. @@ -609,7 +608,7 @@ XML 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. + 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 @@ -641,7 +640,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 @@ -669,8 +668,8 @@ DEB formats or from xmlsoft.org.
Some editing tool. A popular one is Emacs with the psgml and nXML - modes. The LDP Author - Guide and DocBook + modes. The LDP Author + Guide and DocBook Wiki list some alternates.
After you have the tools mentioned above, you need to define a @@ -682,15 +681,15 @@ please e-mail the gatekeeper in charge of documentation.
You can look at some templates for documents (in Docbook XML) in - the sources + the sources 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
@@ -711,23 +710,23 @@
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
+ 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.
@@ -742,7 +741,7 @@ </sect1>
-
+
Inside this container your document will be split up into
<sect2>'s,
each with the same requirements - id and xreflabel
@@ -751,7 +750,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 use
<computeroutput>
@@ -769,12 +768,12 @@
tag around text that has been wrapped by combinations of <computeroutput>
and <userinput>
- + 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:
@@ -798,7 +797,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 @@ -819,7 +818,7 @@ for you.
-
+
To insert a graphic we use the elements
<mediaobject>,
<imageobject>,
@@ -845,7 +844,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
@@ -890,7 +889,7 @@
</variablelist>
-
+
DocBook supports several types of tables, but in most cases, the
<informaltable>
is enough:
@@ -922,12 +921,12 @@
</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>.
@@ -968,10 +967,10 @@
bash$xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml
- You could also look at the acs-core-docs Makefile + You could also look at the acs-core-docs Makefile for examples of how these documents are generated.
- The LDP Author + 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 for tools. @@ -1003,4 +1002,4 @@ script with directions (now via archive.org) that gets you most of the way. -