Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml,v
diff -u -N -r1.11 -r1.11.2.1
--- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 26 Jan 2004 15:39:44 -0000 1.11
+++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 17 Nov 2004 20:32:05 -0000 1.11.2.1
@@ -15,77 +15,348 @@
Overview of OpenACS Documentation
- 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
- OpenACS a superb documentation, so that users, developers and
- administrators of OpenACS installations can enjoy the system.
+ 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.
+
- OpenACS is a powerful system, with
- incredible possibilities and applications, but with this power
- comes some complexity and a learning curve that will only be
- atenuated by good documentation. This is what we are after.
+ 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
+ community began meeting the challenge by identifying needs and
+ writing documentation on an as needed basis.
+
- The documentation for OpenACS is
- written using DocBook XML. The reasons why we are using
- DocBook are explained in more details in the
- next section. A few more reasons why
- we are using Docbook XML instead of Docbook SGML:
+ By having documentation dependent on volunteers and code
+ developers, documentation updates lagged behind the evolving
+ system software. As significant development changes were made
+ to the system, existing documentation became dated, and its
+ value significantly reduced. The valiant efforts that were made
+ to keep the documentation current proved too difficult as
+ changes to the system sometimes had far-reaching affects to
+ pages throughout the documentation. System integration and
+ optimization quickly rendered documentation obsolete for
+ developers. The code became the substitute and source for
+ documentation.
-
+
+ With thousands of lines of code and few developers tracking
+ changes, features and advances to the OpenACS system went
+ unnoticed or were not well understood except by the code
+ authors. Work was duplicated as a consequence of developers
+ not realizing the significant work completed by others. New
+ developers had to learn the system through experience with
+ working with it and discussion in the forums. Informal sharing
+ of experiential and tacit knowledge has become the OpenACS
+ community's main method sharing knowledge.
+
+
+ This document attempts to shape ongoing documentation efforts by
+ using principles of continual improvement to re-engineer
+ documentation production.
+
+
+
+
+ Managing OpenACS Documentation
+
+ Documentation production shares many of the challenges of
+ software development, such as managing contributions, revisions
+ and the (editorial) release cycle. This is yet another
+ experiment in improving documentation --this time by using
+ principles of continual improvement to focus the on-going
+ efforts. These processes are outlined as project management
+ phases:
+
+
- Consistency. We started with a collection
- of DcoBook XML files that ArsDigita wrote. Trying to re-write them to
- conform to the SGML DTD would be unnecessary work (I tried).
-
+ Requirements phase is about setting goals and
+ specifications, and includes exploration of scenarios, use cases
+ etc. As an example, see the
+ OpenACS Documentation Requirements Template which focuses on
+ systems requirements for developers.
+
- It 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.
-
+ Strategy phase is about creating an approach
+ to doing work. It sets behavioral guidelines and boundaries
+ that help keep perspective on how efforts are directed.
+ OpenACS developers discuss strategy when coordinating
+ efforts such as code revisioning and new features.
+
- The tool chain has matured. xsltproc and other XML
- based tools have improved to the point where they are about as good as
- the SGML tools and generation of both html and pdf output is straighforward.
-
-
+ Planning phase is about explicitly stating
+ the way to implement the strategy as a set of methods.
+ OpenACS system design requires planning. For example, see
+ OpenACS
+ documentation template planning relating to package
+ design.
+
+
+ Implementation phase is about performing the
+ work according to the plan, where decisions on how to handle
+ unforseen circumstances are guided by the strategy and
+ requirements.
+
+
+ Verification phase measures how well the plan
+ was implemented. Success is measured by A) verifying if the
+ project has met the established goals, and B) reviewing for
+ ongoing problem areas etc. OpenACS follows verification
+ through different means on different projects, but in all
+ cases, the OpenACS community verifies the project as a
+ success through feedback including bug reports, user and
+ administrator comments, and code changes.
+
+
+
+ OpenACS forum discussions on documentation requirements and strategies are
+ summarized in the following sections. Production
+ phases are mainly organized and fulfilled by Joel Aufrecht.
+ Hopefully the following sections will help spur greater
+ direct participation by the OpenACS community.
+
-
-
- Why DocBook?
+
+ OpenACS General Documentation Requirements
- In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the
- DocBook XML DTD
-
- DocBookDTD
- 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.
+ 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 goals. No
+ significance has been given to the order presented, topic breadth or depth here.
+
+
+ clarity in presentation. Life with
+ qmail is a recommended example of "rated high" online
+ documentation.
+
+
+ Avoid requirements that significantly increase the labor
+ required to maintain documentation.
+
+
+
+ Use best practices learned from the print world, web, and
+ other media, about use of gamma, space, writing style etc.
+
+
+
+ Consistency in publishing -Establishing and adhering to publishing standards
+
+
+ Use standardized language -Use international English
+ (without slang or colloquial terms) for ESL (English as
+ a second language) readers (and making translation
+ easier for those interested in translating the
+ documentation for internationalization efforts).
+
+
+ All jargon used in documentation needs to be defined.
+ Use standardized terms when available, avoiding implicit
+ understanding of specific OpenACS terms.
+
+
+ Document titles (for example on html pages) should
+ include whole document title (as in book title):
+ (chapter title) : (section), so that bookmarks etc.
+ indicate location in a manner similar to pages in books
+ (in print publishing world).
+
+
+ Organize document according to the needs of the reader
+ (which may be different than the wishes of the writers).
+
+
+ Do not make informal exclamations about difficulty/ease
+ for users to complete tasks or understand... for
+ example, "Simply...". Readers come from many different
+ backgrounds --remember that the greater audience is
+ likely as varied as the readers on the internet--- If
+ important, state pre-conditions or knowledge
+ requirements etc. if different than the rest of the
+ context of the document. For example, "requires basic
+ competency with a text-based editor such as vi or emacs
+ via telnet"
+
+
+
+
+ Show where to find current information instead of writing
+ about current info that becomes obsolete. If the information
+ is not found elsewhere, then create one place for it, where
+ others can refer to it. This structure of information will
+ significantly reduce obsolescence in writing and labor burden
+ to maintain up-to-date documentation. In other words, state
+ facts in appropriately focused, designated areas only, then
+ refer to them by reference (with links).
+
+
+ Note: Sometimes facts should be stated multiple ways, to
+ accommodate different reading style preferences. The should
+ still 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 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 (books). Each book contains chapters and sections
+ much like how DocBook examples are shown, where each chapter
+ is a web page. This designation could help create an OpenACs
+ book in print, and help new readers visualize how the
+ documentation is organized.
+
+
+ The use licenses between OpenACS and Arsdigita's ACS are not
+ compatible, thereby creating strict limits on how much
+ OpenACS developers should have access to Arsdigita code and
+ resources. The OpenACS documentation has a new legal
+ requirement: to eliminate any dependency on learning about
+ the system from Arsdigita ACS examples to minimize any
+ inference of license noncompliance, while recognizing the
+ important work accomplished by Philip Greenspun, Arsdigita,
+ and the early ACS adopters.
+
+
+ Use a consistent general outline for each book.
+
+
+ Introduction (includes purpose/goal), Glossary of terms,
+ Credits, License, Copyright, Revision History
+
+
+ Table of Contents (TOC)s for each book: the end-users, content and site
+ administrators, marketing, beginning developers, and
+ developers.
+
+
+ Priorities of order and content vary based on each of
+ the different readers mentioned. The developers guide
+ should be organized to be most useful to the priorities
+ of developers, while being consistent with the general
+ documentation requirements including publishing strategy,
+ style etc.
+
+
+ Use generic DocBook syntax to maximize reader familiarity with the documents.
+
+ <part label="Part 1"><etc...>
+ </programlisting>
+ </para></listitem>
+ </itemizedlist>
+ </para></listitem>
+ </itemizedlist>
+ </sect2>
+ <sect2 id="dbprimer-why" xreflabel="Why DocBook?">
+ <title>OpenACS Documentation Strategy: Why DocBook?
- Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around
- for a while (since the early 90's),
- it's well-tested, it's complete, it's designed for technical documentation
- and best of all, it's open-source. A growing community surrounds DocBook (has
+ All OpenACS documentation will be marked up to conform to the
+ DocBook XML
+ DTD. Theoretically, any strict DTD would have been
+ sufficient. We could even write our own, or just use the
+ OpenACS templating system via the Edit-This-Page package.
+ However,
+ DocBookDTD
+ 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)
- and a number of free and commercial
+
+
+ A number of free and commercial
tools are available
- for editing and publishing DocBook documents.
+ for editing and publishing DocBook documents.
+
+
+ It enables us to publish in a variety of formats.
+
+
+ XML separates content from presentation: It relieves each
+ contributor of the burden of presentation, freeing each writer
+ to focus on content and sharing knowledge.
+
+
+ It is well tested technology. It has been in development
+ since the early 1990's).
+
+
+
+ Reasons why we are using Docbook XML instead of Docbook SGML:
-
+
+
+ Consistency and history. We started with a collection
+ of DocBook XML files that ArsDigita wrote. Trying to re-write them to
+ conform to the SGML DTD would be unnecessary work.
+
+
+ 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.
+
+
+ The tool chain has matured. xsltproc and other XML
+ based tools have improved to the point where they are about as good as
+ the SGML tools. Both can output html and pdf formats.
+
+
- This primer walks you through the basics, and should cover the
+ Albeit, the road to using DocBook has had some trials.
+ In 2002, Docbook still was not fully capable of representing
+ online books as practiced by book publishers and expected from
+ readers with regards to usability on the web. That meant
+ DocBook did not entirely meet OpenACS publishing requirements
+ at that time.
+
+
+ In 2004, Docbook released version 4.2, which complies with all
+ the OpenACS publishing requirements.
+ Producing a web friendly book hierarchy arguably remains DocBooks'
+ weakest point. For example, a dynamically built document
+ should be able to extract details of a specific reference from
+ a bibliographic (table) and present a footnote at the
+ point where referenced. DocBook 4.2 allows for this with
+ bibliocoverage,
+ bibliorelation, and
+ bibliosource. DocBook:
+ The Definitive Guide is a good start for learning how
+ to represent paper-based books online.
+
+
+
+ The following DocBook primer walks you through the basics, and should cover the
needs for 95 percent of the documentation we produce. However,
you're always welcome to check out DocBook's
- list of elements and use more exotic features in your
+ 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:
@@ -94,21 +365,21 @@
-
- Always close your tags with corresponding end-tags and to
- not use other tag minimization
-
+
+ Always close your tags with corresponding end-tags and to
+ not use other tag minimization
+
-
- Write all elements and attributes in lowercase
-
+
+ Write all elements and attributes in lowercase
+
- Quote all attributes
-
+ Quote all attributes
+
@@ -123,41 +394,41 @@
-
- Docbook XML
- DTD - The document type definition for XML. You can
- find an RPM or DEB package or you can download a zip file from
- the site linked from here.
-
+
+ Docbook XML
+ DTD - The document type definition for XML. You can
+ find an RPM or DEB package or you can download a zip file from
+ the site linked from here.
+
-
- XSL
- Stylesheets (docbook-xsl) - The stylesheets to convert
- to HTML. We have been using a stylesheet based upon
- NWalsh's chunk.xsl.
-
+
+ XSL
+ Stylesheets (docbook-xsl) - The stylesheets to convert
+ to HTML. We have been using a stylesheet based upon
+ NWalsh's chunk.xsl.
+
-
- xsltproc - The processor that
- will take an XML document and, given a xsl stylesheet, convert
- it to HTML. It needs libxml2 and libxslt (available in RPM and
- DEB formats or from xmlsoft.org.
-
+
+ xsltproc - The processor that
+ will take an XML document and, given a xsl stylesheet, convert
+ it to HTML. It needs libxml2 and libxslt (available in RPM and
+ DEB formats or from xmlsoft.org.
+
-
- Some editing tool. A popular one is Emacs with the psgml
- mode. We have a intro to the PSGML
- Mode in Emacs as part of our documentation. You can
- read about other editing tools in the LDP Author Guide.
-
+
+ Some editing tool. A popular one is Emacs with the psgml
+ mode. We have a intro to the PSGML
+ Mode in Emacs as part of our documentation. You can
+ read about other editing tools in the LDP Author Guide.
+
@@ -312,97 +583,97 @@
- 1. Inside linking, cross-referencing other parts of your book
-
- By having unique id's you can cross-reference any part of your book
- with a simple tag, regardless of where that part is.
-
+ 1. Inside linking, cross-referencing other parts of your book
+
+ By having unique id's you can cross-reference any part of your book
+ with a simple tag, regardless of where that part is.
+
- xreflinkendCheck out how I link to a subsection of the Developer's Guide:
+ xreflinkendCheck out how I link to a subsection of the Developer's Guide:
- Put this in your XML:
+ Put this in your XML:
- Find information about creating a package in
<xref linkend="packages-making-a-package"></xref>.
- And the output is:
+ And the output is:
- Find information about creating a package in
.
-
- Note that even though this is an empty tag, you have to either:
-
+
+ Note that even though this is an empty tag, you have to either:
+
-
-
-
- Provide the end-tag, </xref>, or
-
-
+
+
+
+ Provide the end-tag, </xref>, or
+
+
-
-
- Put a slash before the ending-bracket: <xref linkend="blahblah"/>
-
-
-
+
+
+ Put a slash before the ending-bracket: <xref linkend="blahblah"/>
+
+
+
- If the section you link to hasn't a specified xreflabel-attribute,
- the link is going to look like this:
+ If the section you link to hasn't a specified xreflabel-attribute,
+ the link is going to look like this:
- Put this in your XML:
+ Put this in your XML:
-Find information about what a package looks like in
<xref linkend="packages-looks"></xref>.
- And the output is:
+ And the output is:
- Find information about what a package looks like in
.
-
- 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.
-
+
+ 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.
+
-
+
- 2. Linking outside the documentation
-
- ulink
- If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just
- a little different
+ 2. Linking outside the documentation
+
+ ulink
+ 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>):
-
+
- <ulink url="http://www.oracle.com/">Oracle Corporation</ulink>
+ <ulink url="http://www.oracle.com/">Oracle Corporation</ulink>
-
+
- ....will create a hyper-link to Oracle in the HTML-version of the documentation.
-
+ ....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
- entities, which is exactly how you'll make an ampersand: &
+ NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing
+ entities, which is exactly how you'll make an ampersand: &
-
+
@@ -414,13 +685,13 @@
NOTE: Currently this section currently only takes HTML-output into consideration -
- not a printed version
+ not a printed version
- 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 ;)
+ 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 ;)
@@ -469,14 +740,14 @@
- 1. How to make an <ul>
-
- 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>
- and
- <listitem>:
-
+ 1. How to make an <ul>
+
+ 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>
+ and
+ <listitem>:
+
<itemizedlist>
@@ -487,17 +758,17 @@
</itemizedlist>
-
+
- 2. How to make an <ol>
-
- The ordered list is like the preceding, except that you use
- <orderedlist> instead:
+ 2. How to make an <ol>
+
+ The ordered list is like the preceding, except that you use
+ <orderedlist> instead:
-
+
<orderedlist>
<listitem><para>Stuff goes here</para></listitem>
@@ -506,21 +777,21 @@
</orderedlist>
-
+
- 3. How to make a <dl>
-
- This kind of list is called a variablelist and these are the tags you'll need to
- make it happen:
- <variablelist>,
- <varlistentry>,
- <term> and
- <listitem>:
+ 3. How to make a <dl>
+
+ This kind of list is called a variablelist and these are the tags you'll need to
+ make it happen:
+ <variablelist>,
+ <varlistentry>,
+ <term> and
+ <listitem>:
-
+
<variablelist>
<varlistentry>
@@ -536,7 +807,7 @@
</variablelist>
-
+
@@ -587,29 +858,29 @@
-
-
+
+
-
- a1
- b1
- c1
-
+
+ a1
+ b1
+ c1
+
-
- a2
- b2
- c2
-
+
+ a2
+ b2
+ c2
+
-
- a3
- b3
- c3
-
+
+ a3
+ b3
+ c3
+
-
-
+
+
@@ -678,7 +949,7 @@
-
+
To generate a single HTML file from your DocBook XML file,
use the command:
@@ -711,8 +982,8 @@
- You could also look at the acs-core-docs Makefile
- for examples of how these documents are generated.
+ You could also look at the acs-core-docs Makefile
+ for examples of how these documents are generated.
@@ -725,51 +996,51 @@
Using Xinclude
-
- 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.
-
+
+ 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.
+
- David Lutterkort
- wrote an intro to the PSGML Mode in Emacs
-
+ David Lutterkort
+ wrote an intro to the PSGML Mode in Emacs
+
- For checking if your document is well-formed, James Clark's free Java parser,
- XP, is recommended. (note that
- it is not a validating parser, but as long as you follow the guidelines set forth in this
- document, your XML will validate)
+ For checking if your document is well-formed, James Clark's free Java parser,
+ XP, is recommended. (note that
+ it is not a validating parser, but as long as you follow the guidelines set forth in this
+ document, your XML will validate)
- DocBook Tool for Linux:
- Let's you convert your docbook documents to a number of formats. Sometimes it's nice to see
- how you stuff looks. NOTE: I only got these to
- work with Docbook SGML, NOT with Docbook XML. If you are
- able to make it work with our XML, please let us know.
-
+ DocBook Tool for Linux:
+ Let's you convert your docbook documents to a number of formats. Sometimes it's nice to see
+ how you stuff looks. NOTE: I only got these to
+ work with Docbook SGML, NOT with Docbook XML. If you are
+ able to make it work with our XML, please let us know.
+
- AptConvert from PIXware is a Java editor that will produce
- DocBook documents and let you transform them into HTML and PDF for a local preview before you submit.
-
+ AptConvert from PIXware is a Java editor that will produce
+ DocBook documents and let you transform them into HTML and PDF for a local preview before you submit.
+
-
- In the process of transforming your HTML into XML,
- HTML tidy
- can be a a handy tool to make your HTML "regexp'able".
- Brandoch Calef has made a
- Perl script
- that gets you most of the way.
+
+ In the process of transforming your HTML into XML,
+ HTML tidy
+ can be a handy tool to make your HTML "regexp'able".
+ Brandoch Calef has made a
+ Perl script
+ that gets you most of the way.
-
+
@@ -779,50 +1050,50 @@
-
-
- Document Revision #
- Action Taken, Notes
- When?
- By Whom?
-
-
+
+
+ Document Revision #
+ Action Taken, Notes
+ When?
+ By Whom?
+
+
-
-
-
- 0.4
-
- Fixed some typos.
-
- 8/3/2002
- Vinod Kurup
-
-
-
- 0.3
-
- Added OpenACS information, updated tools, added
- extra links and added info to the Publishing section.
-
- 12/24/2001
- Roberto Mello
-
-
-
- 0.2
- Changed recommendation from <phrase> to <emphasis role="strong">
- 01/19/2000
- Claus Rasmussen
-
+
+
+
+ 0.4
+
+ Fixed some typos.
+
+ 8/3/2002
+ Vinod Kurup
+
+
+
+ 0.3
+
+ Added OpenACS information, updated tools, added
+ extra links and added info to the Publishing section.
+
+ 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
-
-
+
+ 0.1
+ Creation
+ 12/2000
+ Claus Rasmussen
+
+