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.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 24 Dec 2001 19:31:43 -0000 1.2 @@ -1,73 +1,122 @@ - -aD DocBook Primer + + OpenACS Documentation Guide - -By claus@arsdigita.com - + + By claus@arsdigita.com, with + additions by Roberto + Mello, Vinod Kurup, Talli Somekh and the OpenACS + Community + - -Why DocBook? + + Overview of OpenACS 4 Documentation + + 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 + section. I will add the 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 + 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. + + + + + + Why DocBook? - -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). + + 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. + -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. - + + 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. + - -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: + XML guidelines + - -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: -XML guidelines - + + + + Always close your tags with corresponding end-tags and to + not use other tag minimization + + - + + + Write all elements and attributes in lowercase + + - - Always close your tags with corresponding end-tags and to not use other tag minimization - + + Quote all attributes + - - Write all elements and attributes in lowercase - + - - Quote all attributes - + - + + Document Structure - + + The documentation for each package will make up a little "book" that is structured like this + - examples are emphasized: + Document structure + - -Document Structure - - -The documentation for each package will make up a little "book" that is structured like this - - examples are emphasized: - -Document structure - - - - + book : Docs for one package - templating | +--chapter : One section - for developers @@ -81,562 +130,648 @@ +--sect3 : Subsections - Programmer's API | ... : ... - + - -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. + + 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. - + For now you can take a look at the sources of these DocBook documents + to get an idea of how they are tied together. + - + - -Headlines, Sections + + Headlines, Sections - -SectionsHeadlines -Given that your job starts at the sect1-level, all your documents should open with a -<sect1>-tag and end -with the corresponding </sect1>. - + + SectionsHeadlines + Given that your job starts at the sect1-level, all your documents should open with a + <sect1>-tag and end + with the corresponding </sect1>. + - -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 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 + 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 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. + - -xreflabel -The other attribute is xreflabel. The value of this is the text that will appear -as the link when referring to this sect1. - + + xreflabel + 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: - + + 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> + + <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, -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. - + + sect2 + 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. - + + 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. + - + - -Code + + Code - -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>. -This takes the place of the HTML-tag <code> - + + 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>. + 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. - + + 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. + - + - -Links + + Links - -Linking -Linking falls into two different categories: inside the book you're making and outside: - + + Linking + Linking falls into two different categories: inside the book you're making and outside: + - + - - 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>. + - 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: - + + 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>. + - 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 - + - 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: &amp; + NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing + entities, which is exactly how you'll make an ampersand: &amp; - - + + - + - + - -Graphics + + Graphics - -NOTE: Currently this section currently only takes HTML-output into consideration - -not a printed version - + + 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 ;) - - + + + 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 ;) + + - -GraphicsImages -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. - + + GraphicsImages + 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> - + + <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. - + + Put your graphics in a separate directory ("images") and link to them + only with relative paths. + - + - -Lists + + Lists - -lists -Here's how you make the DocBook equivalent of the three usual HTML-lists: - + + lists + 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>: - + + 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> + + <itemizedlist> + + <listitem><para>Stuff goes here</para><listitem> + <listitem><para>More stuff goes here</para><listitem> - </itemizedlist> - + </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> - <listitem><para>More stuff goes here</para><listitem> + + <orderedlist> + + <listitem><para>Stuff goes here</para><listitem> + <listitem><para>More stuff goes here</para><listitem> - </orderedlist> - + </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> - <term>Heading (<dt>) goes here</term> - <listitem><para>And stuff (<dd>)goes here</para><listitem> - </varlistentry> + + <variablelist> + + <varlistentry> + <term>Heading (<dt>) goes here</term> + <listitem><para>And stuff (<dd>)goes here</para><listitem> + </varlistentry> - <varlistentry> - <term>Another heading goes here</term> - <listitem><para>And more stuff goes here</para><listitem> - </varlistentry> + <varlistentry> + <term>Another heading goes here</term> + <listitem><para>And more stuff goes here</para><listitem> + </varlistentry> - </variablelist> - + </variablelist> + - - + + - + - + - -Tables + + Tables - -informaltabletable -DocBook supports several types of tables, but in most cases, the -<informaltable> -is enough: - + + informaltabletable + DocBook supports several types of tables, but in most cases, the + <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> - </row> + <row> + <entry>a1</entry> + <entry>b1</entry> + <entry>c1</entry> + </row> - <row> - <entry>a2</entry> - <entry>b2</entry> - <entry>c2</entry> - </row> + <row> + <entry>a2</entry> + <entry>b2</entry> + <entry>c2</entry> + </row> - <row> - <entry>a3</entry> - <entry>b3</entry> - <entry>c3</entry> - </row> + <row> + <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: - + + With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: + -
- - - +
+ + + - -a1 -b1 -c1 - + + a1 + b1 + c1 + - -a2 -b2 -c2 - + + a2 + b2 + c2 + - -a3 -b3 -c3 - + + 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. - - + + If you want cells to span more than one row or column, it gets a bit more complicated - check out + <table> + for an example. + + - -Emphasis + + Emphasis - -emphasisbold, italics -Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - -<emphasis>. - + + emphasisbold, italics + 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">. - + + The <emphasis> tag defaults to italics when parsed. If you're looking for + emphasizing with bold type, use <emphasis role="strong">. + - + - -Indexing Your DocBook Documents + + Indexing Your DocBook Documents - -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. - + + 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. - + + Use + <indexterm>, + <primary> and + <secondary> + for this. See these links for an explanation and the + source of this document + for examples. + - + + + + Tools + + You are going to need the following to work with the OpenACS XML + documentation: + - -Tools + + + 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. + + + - -David Lutterkort wrote an intro to the PSGML Mode in Emacs - + + Converting to HTML - -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) + + 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). + + + + 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 + - -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. - - + + 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. + - -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. - - + + To generate a set of linked HTML pages, with a separate page + for each <chapter>, <sect1> or <appendix> tag, use the + following command: + - - -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. + +bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml + - - + + + + 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 + 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. - -Publishing + + + + - -You shouldn't worry about publishing you documents - that's the idea of separating content from presentation. - + + Revision History + + + + + + Document Revision # + Action Taken, Notes + When? + By Whom? + + - -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. - + + + + 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 + + + + - -Revision History - - - - - -Document Revision # -Action Taken, Notes -When? -By Whom? - - + - - -0.2 -Changed recommendation from <phrase> to <emphasis role="strong"> -01/19/2000 -Claus Rasmussen - - - - - -0.1 -Creation -12/2000 -Claus Rasmussen - - - - - - - - - +