By Claus Rasmussen, with additions by Roberto Mello, Vinod Kurup, and the OpenACS community
-OpenACS™ is a powerful system -with incredible possibilities and applications, but this power -comes with some complexity and a steep learning curve that is only -attenuated by good documentation. Our goal is to write superb -documentation, so that users, developers and administrators of -OpenACS installations can enjoy the system.
The history of OpenACS documentation: ..began by building on a +OpenACSâ„¢ is +a powerful system with incredible possibilities and applications, +but this power comes with some complexity and a steep learning +curve that is only attenuated by good documentation. Our goal is to +write superb documentation, so that users, developers and +administrators of OpenACS installations can enjoy the system.
The history of OpenACS documentation: ..began by building on a good documentation base from ArsDigita's ACS in the late 1990's. Some sections of the documentation, however, lacked details and examples; others simply did not exist. The OpenACS @@ -159,7 +159,8 @@
Use generic DocBook syntax to maximize reader familiarity with the documents.
<book><title><part label="Part 1"><etc...>
-
+
+
OpenACS documentation development is subject to the constraints of the software project development and release methods and cycles -(the section called “Using CVS with -OpenACS”). Essentially, all phases of work may be active to -accommodate the asynchronous nature of multiple subprojects -evolving by the efforts of a global base of participants with -culturally diverse time references and scheduling -idiosyncrasies.
The documentation strategy is to use project methods to involve +(the section called +“Using CVS with OpenACS”). +Essentially, all phases of work may be active to accommodate the +asynchronous nature of multiple subprojects evolving by the efforts +of a global base of participants with culturally diverse time +references and scheduling idiosyncrasies.
The documentation strategy is to use project methods to involve others by collaborating or obtaining guidance or feedback (peer review) to distribute the workload and increase the overall value of output for the OpenACS project.
@@ -409,7 +410,7 @@ 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 + 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 @@ -449,7 +450,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
+ 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
+ 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
+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
+ 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:
@@ -538,7 +540,7 @@ </sect1>
- Inside this container your document will
+ 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
@@ -548,7 +550,7 @@
- For displaying a snippet of code, a
+ 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,
@@ -562,15 +564,15 @@
- Linking falls into two different + 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 +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>. @@ -588,15 +590,17 @@ <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 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
+ 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
+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 @@ -611,7 +615,7 @@ 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
+ To insert a graphic we use the elements
<mediaobject>,
<imageobject>,
<imagedata>,
@@ -636,7 +640,7 @@
- Here's how you make the DocBook + Here's how you make the DocBook equivalent of the three usual HTML-lists:
- DocBook supports several types of tables,
+ DocBook supports several types of tables,
but in most cases, the <informaltable> is enough:
<informaltable frame="all"> <tgroup cols="3"> @@ -735,7 +739,7 @@
- Our documentation uses two flavors of
+ 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
@@ -795,8 +799,8 @@