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.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 13 Jan 2005 13:55:17 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 17 Jul 2006 05:38:37 -0000 1.13 @@ -1,15 +1,14 @@ - %myvars; ]> OpenACS Documentation Guide - By Claus Rasmussen, with additions by Roberto - Mello and the OpenACS Community + By Claus Rasmussen, with additions by Roberto Mello, Vinod Kurup, and the OpenACS Community @@ -119,7 +118,7 @@ OpenACS forum discussions on documentation requirements and strategies are summarized in the following sections. Production - phases are mainly organized and fulfilled by Joel Aufrecht. + phases are mainly organized and fulfilled by a designated documentation maintainer. Hopefully the following sections will help spur greater direct participation by the OpenACS community. @@ -780,13 +779,19 @@ OpenACS Documentation Strategy: Why DocBook? - All OpenACS documentation will be marked up to conform to the + OpenACS documentation is taking a dual approach to publishing. + Documentation that is subject to rapid change and participation by + the OpenACS community is managed through the OpenACS + xowiki Documentation Project + Formal documents that tend to remain static and require more + expressive publishing tools 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 + DTD. The remaining discussion is about publishing using + Docbook. + + +DocBookDTD is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook: @@ -846,13 +851,13 @@ at that time. - In 2004, Docbook released version 4.2, which complies with all + In 2004, Docbook released version 4.4, 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 + point where referenced. DocBook 4.4 allows for this with bibliocoverage, bibliorelation, and bibliosource. 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 + needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically @@ -933,11 +937,12 @@ - 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 and nXML + modes. The LDP Author + Guide and DocBook + Wiki list some alternates. @@ -950,7 +955,7 @@ 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 + you are 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. @@ -1036,8 +1041,8 @@ -<sect1 id="docbook-primer" xreflabel="aD DocBook Primer"> - <title>aD DocBook Primer</title> +<sect1 id="docbook-primer" xreflabel="DocBook Primer"> + <title>DocBook Primer</title> ... @@ -1067,17 +1072,30 @@ 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> + a sentence, we use + <computeroutput> + and <code> + tags. + These replace the HTML-tag <code> tag, + depending on whether the tag is describing computer output or + computer 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 expressing user interaction via a terminal window, we wrap + the <screen> + tag around text that has been wrapped by combinations of <computeroutput> + and <userinput> + @@ -1180,8 +1198,11 @@ ....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 hyperlinks. These are reserved for + referencing entities. + To create an ampersand, use the entity &amp; @@ -1194,14 +1215,10 @@ Graphics - 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 ;) + Note: The graphics guidelines + are not written in stone. Use another valid approach if it works better + for you. @@ -1210,12 +1227,12 @@ 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. + <imagedata>, + and + <textobject>. + Two versions of all graphics are required. One for the Web + (usually a JPEG or GIF), and a brief text description. The + description becomes the ALT text. You can also supply a version for print (EPS). @@ -1424,9 +1441,8 @@ 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. + Words that are marked as index-words are referenced in an index + in the final, parsed document. @@ -1458,16 +1474,14 @@ 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 - + +bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml + @@ -1487,9 +1501,9 @@ following command: - -bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml - + +bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml + You could also look at the acs-core-docs Makefile @@ -1514,22 +1528,25 @@ for tools. - + + James Clark + wrote nXML Mode, an alternative + to PSGML Mode. nXML Mode can validate a file as it is edited. + + 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) + James Clark's free Java parser + XP. Note that + this does not validate XML, only parses it. + 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 + Converts docbook documents to a number of formats. 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. @@ -1547,67 +1564,16 @@ HTML tidy can be a handy tool to make your HTML "regexp'able". Brandoch Calef has made a - Perl script + Perl + script with directions (now via archive.org) that gets you most of the way. - - Revision History - - - - - - 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.1 - Creation - 12/2000 - Claus Rasmussen - - - - - - - -