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 -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 20 Aug 2003 16:20:18 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 11 Dec 2003 21:39:49 -0000 1.10 @@ -8,14 +8,12 @@ OpenACS Documentation Guide - By claus@arsdigita.com, with - additions by Roberto + By Claus Rasmussen, with additions by Roberto Mello and the OpenACS Community - Overview of OpenACS &version; Documentation + Overview of OpenACS Documentation ArsDigita created a good documentation ground for us to build upon. Some sections of the documentation, however, lack details @@ -33,23 +31,28 @@ The documentation for OpenACS is written using DocBook XML. The reasons why we are using DocBook are explained in more details in the - section. I will add the reasons why + next section. A few more reasons why we are using Docbook XML instead of Docbook SGML: - - Consistency. We already have a bunch of - .xml files that ArsDigita wrote. Trying to re-write them to + + 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). - - + + 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. - + + + 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. + @@ -68,12 +71,12 @@ 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 + 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 - mailing lists) + mailing lists) and a number of free and commercial - tools are available + tools are available for editing and publishing DocBook documents. @@ -120,33 +123,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. + + 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. + + 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. + @@ -171,7 +182,7 @@ System/Application Requirements Template. - + Document Structure @@ -217,7 +228,7 @@ SectionsHeadlines Given that your job starts at the sect1-level, all your documents should open with a - <sect1>-tag and end + <sect1>-tag and end with the corresponding </sect1>. @@ -244,18 +255,18 @@ - <sect1 id="docbook-primer" xreflabel="aD DocBook Primer"> - <title>aD DocBook Primer</title> +<sect1 id="docbook-primer" xreflabel="aD DocBook Primer"> + <title>aD DocBook Primer</title> - ... +... - </sect1> - +</sect1> + sect2 Inside this container your document will be split up into - <sect2>'s, + <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. @@ -276,13 +287,13 @@ computeroutputcode 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>. + <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 + <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically. @@ -309,21 +320,21 @@ 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>. + +- 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 +. + - - Find information about creating a package in - - - - Note that even though this is an empty tag, you have to either: @@ -345,21 +356,21 @@ 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>. + - - Find information about what a package looks like in - <xref linkend="packages-looks"></xref>. + And the output is: + +- Find information about what a package looks like in +. + - 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 @@ -377,7 +388,7 @@ 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>): @@ -416,29 +427,29 @@ GraphicsImages To insert a graphic we use the elements - <mediaobject>, - <imageobject>, + <mediaobject>, + <imageobject>, and - <imagedata>. + <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> - + <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> - +<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 @@ -462,20 +473,20 @@ 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> + <itemizedlist> and - <listitem>: + <listitem>: - - <itemizedlist> - - <listitem><para>Stuff goes here</para></listitem> - <listitem><para>More stuff goes here</para></listitem> + +<itemizedlist> - </itemizedlist> - + <listitem><para>Stuff goes here</para></listitem> + <listitem><para>More stuff goes here</para></listitem> +</itemizedlist> + + @@ -484,17 +495,17 @@ 2. How to make an <ol> The ordered list is like the preceding, except that you use - <orderedlist> instead: + <orderedlist> instead: - <orderedlist> - - <listitem><para>Stuff goes here</para></listitem> - <listitem><para>More stuff goes here</para></listitem> +<orderedlist> - </orderedlist> - + <listitem><para>Stuff goes here</para></listitem> + <listitem><para>More stuff goes here</para></listitem> +</orderedlist> + + @@ -504,27 +515,27 @@ 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> and + <listitem>: - <variablelist> - - <varlistentry> - <term>Heading (<dt>) goes here</term> - <listitem><para>And stuff (<dd>)goes here</para></listitem> - </varlistentry> +<variablelist> - <varlistentry> - <term>Another heading goes here</term> - <listitem><para>And more stuff goes here</para></listitem> - </varlistentry> + <varlistentry> + <term>Heading (<dt>) goes here</term> + <listitem><para>And stuff (<dd>)goes here</para></listitem> + </varlistentry> - </variablelist> - + <varlistentry> + <term>Another heading goes here</term> + <listitem><para>And more stuff goes here</para></listitem> + </varlistentry> +</variablelist> + + @@ -539,43 +550,42 @@ informaltabletable DocBook supports several types of tables, but in most cases, the - <informaltable> + <informaltable> is enough: - <informaltable frame="all"> - <tgroup cols="3"> - <tbody> +<informaltable frame="all"> + <tgroup cols="3"> + <tbody> <row> - <entry>a1</entry> - <entry>b1</entry> - <entry>c1</entry> + <entry>a1</entry> + <entry>b1</entry> + <entry>c1</entry> </row> <row> - <entry>a2</entry> - <entry>b2</entry> - <entry>c2</entry> + <entry>a2</entry> + <entry>b2</entry> + <entry>c2</entry> </row> <row> - <entry>a3</entry> - <entry>b3</entry> - <entry>c3</entry> + <entry>a3</entry> + <entry>b3</entry> + <entry>c3</entry> </row> - </tbody> - </tgroup> - </informaltable> - + </tbody> + </tgroup> +</informaltable> + With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: -
@@ -601,12 +611,11 @@ -
If you want cells to span more than one row or column, it gets a bit more complicated - check out - <table> + <table> for an example. @@ -619,7 +628,7 @@ emphasisbold, italics Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - - <emphasis>. + <emphasis>. @@ -641,9 +650,9 @@ Use - <indexterm>, - <primary> and - <secondary> + <indexterm>, + <primary> and + <secondary> for this. See these links for an explanation. @@ -652,14 +661,13 @@ Converting to HTML - This section is quoted almost verbatim from the LDP Author Guide. + This section is quoted almost verbatim from the LDP Author Guide. Once you have the - installed, you can convert your xml documents to HTML (or other - formats. Let me know if you are able to convert to other - formats). + installed, you can convert your xml documents to HTML or other + formats. @@ -669,22 +677,27 @@ 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 - + + + 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. + @@ -695,25 +708,31 @@ bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml - + + + You could also look at the acs-core-docs Makefile + for examples of how these documents are generated.` + + Further Reading + 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 + David Lutterkort wrote an intro to the PSGML Mode in Emacs @@ -743,7 +762,7 @@ 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 + Brandoch Calef has made a Perl script that gets you most of the way.