By Claus Rasmussen, with additions by Roberto Mello, Vinod -Kurup, and the OpenACS Community
By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.
OpenACS documentation should meet the following requirements. No significance has been given to the order presented, topic breadth @@ -132,7 +136,7 @@ be in 1 area, using a common layout of perhaps summary, introduction and discussion requiring increasing expertise, complexity or specificity.
-Consistency in link descriptions -When link urls refer to whole +
Consistency in link descriptions -When link URLs refer to whole documents, make the link (anchor wrapped title) that points to a document with the same title and/or heading of the document.
Consider OpenACS documentation as a set of books (an encyclopedic set organized like an atlas) that contains volumes @@ -167,7 +171,7 @@
By the OpenACS Community. This section is a collection of +End-users
By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.
OpenACS end-user documentation should meet the following requirements. No significance has been given to the order @@ -208,7 +212,7 @@ of technological obsolescence), reliability, repairability, style of use, design (strategy in design, specifications, integrated, well-matched systems etc).
differentiate "service" by highlighting software -availability (licensing and completeness from mature to early +availability (licensing and completeness from mature too early adopters or development versions), community incident support, project collaborative opportunities, and contractor support availability
differentiate price (economic considerations of opensource and @@ -264,7 +268,7 @@
By the OpenACS Community. This section is a collection of +and Administrators
By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.
OpenACS administrators' documentation should meet the following requirements. No significance has been given to the order @@ -280,7 +284,7 @@ active processes.
Create a list of administrative tools that are useful to administrating OpenACS, including developer support, schema-browser and API browser. Link to AOLserver's config file -documentation.
Resources on high level subjects such as web services, security +documentation.
Resources on high-level subjects such as web services, security guidelines
Describe typical skill sets (and perhaps mapped to standardized job titles) for administrating an OpenACS system (human-resources style). For a subsite admin/moderator attributes might include @@ -307,7 +311,7 @@
By the OpenACS Community. This section is a collection of +Requirements
By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.
OpenACS installation documentation should meet the following requirements. No significance has been given to the order @@ -331,7 +335,7 @@
By the OpenACS Community. This section is a collection of +Documentation Requirements
By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.
OpenACS developer tutorial documentation should meet the following requirements. No significance has been given to the order @@ -347,7 +351,7 @@ 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
Show how to construct basic SQL queries using the db API,
The life of an http request to a dynamic, templated page
General rules to follow for stability, scalability
Show the step by step customizing of an existing package that +user_id etc
Show how to construct basic SQL queries using the db API,
The life of an HTTP request to a dynamic, templated page
General rules to follow for stability, scalability
Show the step by step customizing of an existing package that meets current recommended coding styles of OpenACS package development, by referring to developer resources.
Use the ArsDigita problem sets and "what Lars produced for ACS Java" as inspiration for a PostgreSQL equivalent tutorial @@ -358,7 +362,7 @@
By the OpenACS Community. This section is a collection of +Requirements
By the OpenACS community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.
OpenACS developer documentation should meet the following requirements. No significance has been given to the order @@ -409,9 +413,10 @@ tools will be marked up to conform to the DocBook XML 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.
The DocBook community mailing lists
A number of free and commercial tools are available for editing and publishing DocBook documents.
It enables us to publish in a variety of formats.
XML separates content from presentation: It relieves each @@ -449,7 +454,7 @@ 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: +you remember to:
- Given that your job starts at the
-sect1-level, all your documents
-should open with a <sect1>-tag
+ 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
+ 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 -
+ 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="DocBook Primer"> @@ -538,8 +545,8 @@ </sect1>
- Inside this container your document will
-be split up into <sect2>'s,
+ 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
@@ -548,9 +555,9 @@
- 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> and <code> tags. These
+ 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> and <code> tags. These
replace the HTML-tag <code> tag,
depending on whether the tag is describing computer output or
computer code.
For bigger chunks of code such as SQL-blocks, the tag <programlisting> is used. Just
@@ -562,16 +569,17 @@
- 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:
@@ -594,10 +602,10 @@
- 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 url="http://www.oracle.com/">Oracle Corporation</ulink>
....will create a hyper-link to Oracle in the HTML-version of
+ 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 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 hyperlinks. These are reserved for referencing @@ -612,8 +620,8 @@ Note: The graphics guidelines are not written in stone. Use another valid approach if it works better for you.
- To insert a graphic we use the elements
-<mediaobject>,
+ To insert
+a graphic we use the elements <mediaobject>,
<imageobject>,
<imagedata>,
and <textobject>.
@@ -637,8 +645,9 @@
- 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 @@ -690,8 +699,8 @@
- DocBook supports several types of tables,
-but in most cases, the <informaltable> is enough:
+ DocBook +supports several types of tables, but in most cases, the<informaltable>is enough:<informaltable frame="all"> <tgroup cols="3"> <tbody> @@ -736,8 +745,9 @@
- Our documentation uses two flavors of
-emphasis - italics and bold type. DocBook uses one - <emphasis>.
The <emphasis> tag
+ 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">.
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 +Tools 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 single file, you call one stylesheet. If you want to generate multiple