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.2.4 -r1.9.2.5 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 29 Nov 2003 16:09:37 -0000 1.9.2.4 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 1 Dec 2003 23:26:14 -0000 1.9.2.5 @@ -31,13 +31,13 @@ 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). @@ -48,6 +48,11 @@ url="http://en.tldp.org/LDP/LDP-Author-Guide/docbookxml.html">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. + @@ -66,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. @@ -177,7 +182,7 @@ System/Application Requirements Template. - + Document Structure @@ -223,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>. @@ -250,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. @@ -282,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. @@ -315,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: @@ -351,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 @@ -383,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>): @@ -422,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 @@ -468,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> + + @@ -490,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> + + @@ -510,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> + + @@ -545,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: -
@@ -607,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. @@ -625,7 +628,7 @@ emphasisbold, italics Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - - <emphasis>. + <emphasis>. @@ -647,9 +650,9 @@ Use - <indexterm>, - <primary> and - <secondary> + <indexterm>, + <primary> and + <secondary> for this. See these links for an explanation. @@ -663,9 +666,8 @@ 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. @@ -675,15 +677,18 @@ 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 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.` + +