Table of Contents
-In order to separate content and presentation, all ACS documentation will be marked up to conform to the -DocBook XML DTD -(Check the XML source of this document to get an idea of what it looks like). + + +
+ ++ By claus@arsdigita.com, with + additions by Roberto + Mello and the OpenACS Community +
++ ArsDigita created a good documentation ground for us to build + upon. Some sections of the documentation however, lack details + and examples, others simply are inexistent.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 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 documentation for OpenACS™ is + written using DocBook XML. The reasons why we are using + DocBook are explained in more details in the + Why DocBook? section. I will add the reasons why + we are using Docbook XML instead of Docbook SGML: +
++ In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the + DocBook XML DTD + + + 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. +
++ Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around + for a while (since early 90's), + it's well-tested, it's complete, it's extremely well-suited for technical documents + and best of all, it's open-source. A growing community surrounds DocBook (has + mailing lists) + and a number of free and commercial + tools are available + for editing and publishing DocBook documents. +
++ This 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 + 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 +
+ Write all elements and attributes in lowercase +
+ Quote all attributes +
+ You are going to need the following to work with the OpenACS + Docbook XML documentation: +
++ After you have the tools mentioned above, you need to define a + title for your document. Then start thinking about the possible + sections and subsections you will have in your document. Make + sure you coordinate with the OpenACS Gatekeepers to make sure + you're not writing something that someone else is already + writing. Also, if you desire to use the OpenACS CVS repository, + please e-mail the gatekeeper in charge of documentation. +
++ You can look at some templates for documents (in Docbook XML) in + 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: + -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. -
-Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around -for a while (since early 90's), -it's well-tested, it's complete, it's extremely well-suited for technical documents -and best of all, it's open-source. A growing community surrounds DocBook (has -mailing lists) -and a number of free and commercial -tools are available -for editing and publishing DocBook documents. -
-This 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 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: - -
-The documentation for each package will make up a little "book" that is structured like this - - examples are emphasized: - - - -
-The actual content is split up into documents that start at a -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 -to get an idea of how they are tied together. -
+ ... : ... + +
+ The actual content is split up into documents that start at a + 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 + 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. +
++ 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="aD DocBook Primer"> + <title>aD DocBook Primer</title> -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 Section 2.5.). -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. -
+ </sect1> +
+ + 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 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>. + This takes the place of the HTML-tag <code> +
++ For bigger chunks of code such as SQL-blocks, the tag + <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:
+-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: -
-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 some abbreviation of the id in the sect1 such as requirements-overview. -
+ And the output is: -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>. -This takes the place of the HTML-tag <code> -
-For bigger chunks of code such as SQL-blocks, the tag -<programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of -automatically. -
+ - Find information about creating a package in + Making a Package -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:
+ Note that even though this is an empty tag, you have to either: +
+++
- +
+ Provide the end-tag, </xref>, or +
- +
+ 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:
+- Put this in your XML: + Put this in your XML: - - Find information about creating a package in - <xref linkend="packages-making-a-package"></xref>. + - 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 creating a package in - Making a Package + - Find information about what a package looks like in + the section called “What a Package Looks Like” -
- Note that even though this is an empty tag, you have to either: -
If the section you link to hasn't a specified xreflabel-attribute, - the link is going to look like this:
+ 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
+- +
+ + ++ + If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just + a little different - Put this in your XML: + (<ulink>): - - Find information about what a package looks like in - <xref linkend="packages-looks"></xref>. +
+<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 hyper links. These are reserved for referencing + entities, which is exactly how you'll make an ampersand: & - And the output is: +
++ +++ NOTE: Currently this section currently only takes HTML-output into consideration - + 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 ;) + +
++ + To insert a graphic we use the elements + <mediaobject>, + <imageobject>, + and + <imagedata>. + The news is that you have to provide two versions of all your graphics - one for the Web (probably a GIF or a JPEG) + and one for print (EPS). Finally you should provide a brief description wrapped in + <textobject> - + in HTML this will be the ALT text. +
++ <mediaobject> + <imageobject> + <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/> + </imageobject> + <imageobject> + <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/> + </imageobject> + <textobject> + <phrase>This is an image of the flow in the Request Processor</phrase> + </textobject> + </mediaobject> +++ 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: +
++
- 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> + + <listitem><para>Stuff goes here</para><listitem> + <listitem><para>More stuff goes here</para><listitem> - - Find information about what a package looks like in - Section 3.4. + </itemizedlist> ++- 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> + <listitem><para>More stuff goes here</para><listitem> -
- 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 documentation, it works almost the same way as HTML - the tag is just - a little different + </orderedlist> + +
+ 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> + <term>Heading (<dt>) goes here</term> + <listitem><para>And stuff (<dd>)goes here</para><listitem> + </varlistentry> - (<ulink>): + <varlistentry> + <term>Another heading goes here</term> + <listitem><para>And more stuff goes here</para><listitem> + </varlistentry> -+
+ </variablelist> +
+ + DocBook supports several types of tables, but in most cases, the + <informaltable> + is enough: +
++ <informaltable frame="all"> + <tgroup cols="3"> + <tbody> - ....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: & + <row> + <entry>a1</entry> + <entry>b1</entry> + <entry>c1</entry> + </row> -
-NOTE: Currently this section currently only takes HTML-output into consideration - -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 ;) - -
+ <row> + <entry>a2</entry> + <entry>b2</entry> + <entry>c2</entry> + </row> -To insert a graphic we use the elements -<mediaobject>, -<imageobject>, -and -<imagedata>. -The news is that you have to provide two versions of all your graphics - one for the Web (probably a GIF or a JPEG) -and one for print (EPS). Finally you should provide a brief description wrapped in -<textobject> - -in HTML this will be the ALT text. -
-Put your graphics in a separate directory ("images") and link to them -only with relative paths. -
+ <row> + <entry>a3</entry> + <entry>b3</entry> + <entry>c3</entry> + </row> -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 - <para>, and that the tags are called - <itemizedlist> - and - <listitem>: -
+ 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 ++ 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>. +
++ The <emphasis> tag defaults to italics when parsed. If you're looking for + emphasizing with bold type, use <emphasis role="strong">. +
++ +++ Marking up index-words may not have any importance for the HTML-output, but in order to make it easier to make + a nice print-version of the documentation, you should mark up words in your documents that you would like to + see show up in an index one day. +
++ Use + <indexterm>, + <primary> and + <secondary> + for this. See these links for an explanation. +
++ ++++Note
+ 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 other + formats. Let me know if you are able to convert to 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 files, you call a different stylesheet. +
++ To generate a single HTML file from your DocBook XML file, + use the command: +
++bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml ++++Note
+ This example uses Daniel Veillard's xsltproc command available + as part of libxslt from http://www.xmlsoft.org/XSLT/. + If you are using other XML processors such as Xalan or Saxon, + you will need to change the command line appropriately. ++ To generate a set of linked HTML pages, with a separate page + for each <chapter>, <sect1> or <appendix> tag, use the + following command: +
++bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml +++ ++
- + 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 +
- +
+ 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. +
- +
+ 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. - </itemizedlist> -
- The ordered list is like the preceding, except that you use - <orderedlist> instead:
- 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>:
- -DocBook supports several types of tables, but in most cases, the -<informaltable> -is enough: -
-With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: -
-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>. -
-The <emphasis> tag defaults to italics when parsed. If you're looking for -emphasizing with bold type, use <emphasis role="strong">. -
-Marking up index-words may not have any importance for the HTML-output, but in order to make it easier to make -a nice print-version of the documentation, you should mark up words in your documents that you would like to -see show up in an index one day. -
-Use -<indexterm>, -<primary> and -<secondary> -for this. See these links for an explanation and the -source of this document -for examples. -
-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)
-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. -
-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. - -
-You shouldn't worry about publishing you documents - that's the idea of separating content from presentation. -
-Exactly how the documentation will be published is not finalized yet. The current idea is to keep -all the documentation in raw XML under CVS and then parse it with what ever style-sheet we choose upon -release. -
| Document Revision # | +Action Taken, Notes | +When? | +By Whom? | +
|---|---|---|---|
| 0.3 | ++ Added OpenACS information, updatet 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 | +