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.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 26 Jan 2004 15:39:44 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 13 Jan 2005 13:55:17 -0000 1.12 @@ -1,10 +1,10 @@ - %myvars; ]> - + OpenACS Documentation Guide @@ -15,77 +15,858 @@ Overview of OpenACS Documentation - ArsDigita created a good documentation ground for us to build - upon. Some sections of the documentation, however, lack details - and examples; others are simply nonexistant. 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 + this power comes with some complexity and a steep learning curve + that is only attenuated by good documentation. Our goal is to write + 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 history of OpenACS documentation: ..began by + building on a good documentation base from ArsDigita's ACS in the + late 1990's. Some sections of the documentation, however, lacked + details and examples; others simply did not exist. The OpenACS + community began meeting the challenge by identifying needs and + writing documentation on an as needed basis. + - The documentation for OpenACS is - written using DocBook XML. The reasons why we are using - DocBook are explained in more details in the - next section. A few more reasons why - we are using Docbook XML instead of Docbook SGML: + By having documentation dependent on volunteers and code + developers, documentation updates lagged behind the evolving + system software. As significant development changes were made + to the system, existing documentation became dated, and its + value significantly reduced. The valiant efforts that were made + to keep the documentation current proved too difficult as + changes to the system sometimes had far-reaching affects to + pages throughout the documentation. System integration and + optimization quickly rendered documentation obsolete for + developers. The code became the substitute and source for + documentation. + + With thousands of lines of code and few developers tracking + changes, features and advances to the OpenACS system went + unnoticed or were not well understood except by the code + authors. Work was duplicated as a consequence of developers + not realizing the significant work completed by others. New + developers had to learn the system through experience with + working with it and discussion in the forums. Informal sharing + of experiential and tacit knowledge has become the OpenACS + community's main method of sharing knowledge. + + + This document attempts to shape ongoing documentation efforts by + using principles of continual improvement to re-engineer + documentation production. + + + + + Managing OpenACS Documentation + + Documentation production shares many of the challenges of + software development, such as managing contributions, revisions + and the (editorial) release cycle. This is yet another + experiment in improving documentation --this time by using + principles of continual improvement to focus the on-going + efforts. These processes are outlined as project management + phases: + + + + Requirements phase is about setting goals and + specifications, and includes exploration of scenarios, use cases + etc. As an example, see the + OpenACS Documentation Requirements Template which focuses on + systems requirements for developers. + + + Strategy phase is about creating an approach + to doing work. It sets behavioral guidelines and boundaries + that help keep perspective on how efforts are directed. + OpenACS developers discuss strategy when coordinating + efforts such as code revisioning and new features. + + + Planning phase is about explicitly stating + the way to implement the strategy as a set of methods. + OpenACS system design requires planning. For example, see + OpenACS + documentation template planning relating to package + design. + + + Implementation phase is about performing the + work according to the plan, where decisions on how to handle + unforseen circumstances are guided by the strategy and + requirements. + + + Verification phase measures how well the plan + was implemented. Success is measured by A) verifying if the + project has met the established goals, and B) reviewing for + ongoing problem areas etc. OpenACS follows verification + through different means on different projects, but in all + cases, the OpenACS community verifies the project as a + success through feedback including bug reports, user and + administrator comments, and code changes. + + + + OpenACS forum discussions on documentation requirements and strategies are + summarized in the following sections. Production + phases are mainly organized and fulfilled by Joel Aufrecht. + Hopefully the following sections will help spur greater + direct participation by the OpenACS community. + + + + + OpenACS General Documentation Requirements + + By the OpenACS Community. This section is a collection of + documentation requirements that have been expressed in the + OpenACS forums to 4th July 2003. + + + OpenACS documentation should meet the following requirements. No + significance has been given to the order presented, topic breadth or depth here. + - 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). - + clarity in presentation. Life with + qmail is a recommended example of "rated high" online + documentation. + - 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. - + Avoid requirements that significantly increase the labor + required to maintain documentation. + + + + Use best practices learned from the print world, web, and + other media, about use of gamma, space, writing style etc. + + + + Consistency in publishing -Establishing and adhering to publishing standards + + + Use standardized language -Use international English + (without slang or colloquial terms) for ESL (English as + a second language) readers (and making translation + easier for those interested in translating the + documentation for internationalization efforts). + + + All jargon used in documentation needs to be defined. + Use standardized terms when available, avoiding implicit + understanding of specific OpenACS terms. + + + Document titles (for example on html pages) should + include whole document title (as in book title): + (chapter title) : (section), so that bookmarks etc. + indicate location in a manner similar to pages in books + (in print publishing world). + + + Organize document according to the needs of the reader + (which may be different than the wishes of the writers). + + + Do not make informal exclamations about difficulty/ease + for users to complete tasks or understand... for + example, "Simply...". Readers come from many different + backgrounds --remember that the greater audience is + likely as varied as the readers on the internet--- If + important, state pre-conditions or knowledge + requirements etc. if different than the rest of the + context of the document. For example, "requires basic + competency with a text-based editor such as vi or emacs + via telnet" + + + - 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. - + Show where to find current information instead of writing + about current info that becomes obsolete. If the information + is not found elsewhere, then create one place for it, where + others can refer to it. This structure of information will + significantly reduce obsolescence in writing and labor burden + to maintain up-to-date documentation. In other words, state + facts in appropriately focused, designated areas only, then + refer to them by reference (with links). + + + Note: Sometimes facts should be stated multiple ways, to + accommodate different reading style preferences. The should + still be in 1 area, using a common layout of perhaps + summary, introduction and discussion requiring increasing + expertise, complexity or specificity. + + + Consistency in link descriptions -When link urls refer to + whole documents, make the link (anchor wrapped title) that + points to a document with the same title and/or heading of + the document. + + + Consider OpenACS documentation as a set of books (an + encyclopedic set organized like an atlas) that contains + volumes (books). Each book contains chapters and sections + much like how DocBook examples are shown, where each chapter + is a web page. This designation could help create an OpenACs + book in print, and help new readers visualize how the + documentation is organized. + + + The use licenses between OpenACS and Arsdigita's ACS are not + compatible, thereby creating strict limits on how much + OpenACS developers should have access to Arsdigita code and + resources. The OpenACS documentation has a new legal + requirement: to eliminate any dependency on learning about + the system from Arsdigita ACS examples to minimize any + inference of license noncompliance, while recognizing the + important work accomplished by Philip Greenspun, Arsdigita, + and the early ACS adopters. + + + Use a consistent general outline for each book. + + + Introduction (includes purpose/goal), Glossary of terms, + Credits, License, Copyright, Revision History + + + Table of Contents (TOC)s for each book: the end-users, content and site + administrators, marketing, developer tutorial, and + developers. + + + Priorities of order and content vary based on each of + the different readers mentioned. The developers guide + should be organized to be most useful to the priorities + of developers, while being consistent with the general + documentation requirements including publishing strategy, + style etc. + + + Use generic DocBook syntax to maximize reader familiarity with the documents. + + <book><title><part label="Part 1"><etc...> + + + + - - Why DocBook? + + OpenACS Documentation Requirements for End-users + + By the OpenACS Community. This section is a collection of + documentation requirements that have been expressed in the + OpenACS forums to 4th July 2003. + + + OpenACS end-user documentation should meet the following requirements. No + significance has been given to the order presented, topic breadth or depth here. + + + + + End-users should not have to read docs to use the system. + + + + Include how to get help. How and where to find answers, + contact others, what to do if one gets an AOLserver or other + error when using the system. Include types of available + support (open-source, private commercial etc.) including + references. + + + Explain/foster understanding of the overall structure of the + system. This would be an overview of the system components, + how it works, and how to find out more or dig deeper... To + promote the system by presenting the history of the system, + and writing about some tacit knowledge re: OpenACS.org and + the opensource culture. + + + Introduce and inspire readers about the uses, benefits, and + the possibilities this system brings (think customer + solution, customer cost, convenience, value). A + comprehensive community communications system; How this + system is valuable to users; Reasons others use OpenACS + (with quotes in their own words) "...the most important + thing that the ACS does is manage users, i.e. provide a way + to group, view and manipulate members of the web community. + -- Talli Somekh, September 19, 2001" using it to + communicate, cooperate, collaborate... OpenACS offers + directed content functionality with the OpenACS templating + system. ... OpenACS is more than a data collection and + presentation tool. OpenACS has management facilities that + are absent in other portals. ...The beauty of OpenACS is + the simplicity (and scalability) of the platform on which it + is built and the library of tried and tested community + building tools that are waiting to be added. It seems that + most portals just add another layer of complexity to the + cake. See Slides on OACS + features...a set of slides on OACS features that can + be used for beginners who want to know OACS is about and + what they can do with it. Screen captures that highlight + features. Example shows BBoard, calendar, news, file + storage, wimpy point, ticket tracking. An OpenACS tour; an + abbreviated, interactive set of demo pages. + + + From a marketing perspective, + + + differentiate "product" by highlighting features, + performance quality, conformance to standards, + durability (handling of technological obsolescence), + reliability, repairability, style of use, design + (strategy in design, specifications, integrated, + well-matched systems etc). + + + differentiate "service" by highlighting software + availability (licensing and completeness from mature to early + adopters or development versions), community incident + support, project collaborative opportunities, and + contractor support availability + + + differentiate price (economic considerations of + opensource and features) + + + Discussion and details should rely on meeting criteria + of design, completeness of implementation, and related + system strengths and weaknesses. Marketing should not + rely on comparing to other technologies. Competitive + analysis involves mapping out strengths, weaknesses, + opportunities and threats when compared to other systems + for a specific purpose, and thus is inappropriate (and + becomes stale quickly) for general documentation. + + + When identifying subsystems, such as tcl, include links + to their marketing material if available. + + + create an example/template comparison table that shows + versions of OpenACS and other systems (commonly + competing against OpenACS) versus a summary feature list + and how well each meets the feature criteria. Each + system should be marked with a date to indicate time + information was gathered, since information is likely + volatile. + + + + + To build awareness about OpenACS, consider product + differentiation: form, features, performance quality, + conformance quality (to standards and requirements), + durability, reliability, repairability, style, design: the + deliberate planning of these product attributes. + + + Include jargon definitions, glossary, FAQs, site map/index, + including where to find Instructions for using the packages. + FAQ should refer like answers to the same place for + consistency, brevity and maintainability. + + + Explain/tutorial on how the UI works (links do more than go + to places, they are active), Page flow, descriptions of form + elements; browser/interface strengths and limitations (cookies, other) + + + Discuss criteria used to decide which features are + important, and the quality of the implementation from a + users perspective. Each project implementation places a + different emphasis on the various criteria, which is why + providing a framework to help decide is probably more useful + than an actual comparison. + + + + Package documentation requirements have additional requirements. + + + + A list of all packages, their names, their purposes, what + they can and cannot do (strengths, limitations), what + differentiates them from similar packages, minimal + description, current version, implementation status, + author/maintainers, link(s) to more info. Current version + available at the repository. + + + Include dependencies/requirements, known conflicts, and + comments from the real world edited into a longer + description to quickly learn if a package is appropriate for + specific projects. + + + Create a long bulleted list of features. Feature list should + go deeper than high-level feature lists and look at the + quality of the implementations (from the user's perspective, + not the programmer's). Example issues an end-user may have + questions about: Ticket Tracker and Ticket Tracker Lite, why + would I want one of them vs the other? And, before I specify + to download and install it, what credit card gateways are + supported by the current e-commerce module? There are some + packages where the name is clear enough, but what are the + limitations of the standard package? + + + End-user docs should not be duplicative. The package + description information and almost everything about a + package for administrators and developers is already + described in the package itself through two basic + development document templates: a + Requirements Template and Detailed + Design Document. + + + + + OpenACS Documentation Requirements for Site and Administrators - 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. + By the OpenACS Community. This section is a collection of + documentation requirements that have been expressed in the + OpenACS forums to 4th July 2003. + + + OpenACS administrators' documentation should meet the following requirements. No + significance has been given to the order presented, topic breadth or depth here. + + + For each requirement below, include links to developer tutorials + and other documentation for more detail. + + + Describe a structural overview of a working system and how + the components work together. "The Layered Cake view" a + general network view of system; a table showing system + levels versus roles to help with understanding how the + subsystems are interconnected. + + + Provide a comprehensive description of typical + administrative processes for operating an OpenACS system + responsibly, including reading logs and command line views that + describe status of various active processes. + + + Create a list of administrative tools that are useful to + administrating OpenACS, including developer support, + schema-browser and api browser. Link to AOLserver's config + file documentation. + + + Resources on high level subjects such as web services, + security guidelines + + + Describe typical skill sets (and perhaps mapped to + standardized job titles) for administrating an OpenACS + system (human-resources style). For a subsite + admin/moderator attributes might include trustworthy, + sociable, familiarity with the applications and + subsystems, work/group communication skills et cetera + + + Describe how to set up typical site moderation and + administration including parameters, permissions, "Hello + World" page + + + Show directory structure of a typical package, explanation + of the various file types in a package (tcl,adp,xql) and how + those relate to the previously described subsystems, when + they get refreshed etc. + + + Ways to build a "Hello World" page + + + Show examples of how the OpenACS templating system is used, + including portal sections of pages. For example, create a + customised auto-refreshing startpage using lars-blogger, a + photo gallery, and latest posts from a forum. This should + rely heavily on documentation existing elsewhere to keep + current. This would essentially be a heavily annotated list + of links. + + + Show ways of modifying the look and feel across pages of an + OpenACS website. Refer to the skins package tutorial. + + + Describe a methodology for diagnosing problems, finding + error statements and interpreting them --for OpenACS and the + underlying processes. + + + FAQs: Administration tasks commonly discussed on boards: + admin page flow, how to change the looks of a subsite with a + new master.adp, options on "user pages" , a quick + introduction to the functions and processes. info about the + user variables, file locations + + + + + + OpenACS Installation Documentation Requirements - Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around - 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 + By the OpenACS Community. This section is a collection of + documentation requirements that have been expressed in the + OpenACS forums to 4th July 2003. + + + OpenACS installation documentation should meet the following requirements. No + significance has been given to the order presented, topic breadth or depth here. + + + + state installation prerequisites. For example: "You should + read through the installation process to familiarize + yourself with the installation process, before beginning an + installation." + + + list critical decisions (perhaps as questions) that need to + be made before starting: which OS, which DB, which aolserver + version, system name, dependencies et cetera. Maybe summarize + options as tables or decision-trees. For example, "As you + proceed throughout the installation, you will be acting on + decisions that have an impact on how the remaining part of + the system is installed. Here is a list of questions you + should answer before beginning." + + + list pre-installation assumptions + + + Show chronological overview of the process of installing a + system to full working status: Install operating + system with supporting software, configure with preparations + for OpenACS, RDBMS(s) install and configure, Webserver + install and configure, OpenACS install and configure, + post-install work + + + + + + OpenACS Developer Tutorial Documentation Requirements + + By the OpenACS Community. This section is a collection of + documentation requirements that have been expressed in the + OpenACS forums to 4th July 2003. + + + OpenACS developer tutorial documentation should meet the following requirements. No + significance has been given to the order presented, topic breadth or depth here. + + + + + list learning prerequisites to customize, fix, and improve + OACS modules, and create new ones. You are expected to have + read and understand the information [minimum requirements + similar to adept at Using OpenACS Administrating Guide] + before reading this guide. + + + + + Refer to development documentation instead of duplicating here + + + + List suggestions for installing and setting up a development + environment; these can be annotated links to the + installation documentation + + + + Provide working examples that highlight the various + subsystems, tcl environment, OpenACS protocols, aolserver + template and ns_* commands, OpenACS templating, sql queries, + db triggers, scheduling protocols, how to use the page contract, + how to get the accessing user_id etc + + + + Show how to construct basic SQL queries using the db API, + + + + The life of an http request to a dynamic, templated page + + + + General rules to follow for stability, scalability + + + + Show the step by step customizing of an existing package + that meets current recommended coding styles of OpenACS + package development, by referring to developer resources. + + + + Use the ArsDigita problem sets and "what Lars produced for ACS Java" as inspiration for a + PostgreSQL equivalent tutorial about developing a new + OpenACS package including discussion of the significance of + the package documentation templates + + + + Include a summary of important links used by developers + + + + Note any deprecated tools and methods by linking to prior + versions instead of describing them in current docs + + + + + + + OpenACS Developer Documentation Requirements + + By the OpenACS Community. This section is a collection of + documentation requirements that have been expressed in the + OpenACS forums to 4th July 2003. + + + OpenACS developer documentation should meet the following requirements. No + significance has been given to the order presented, topic breadth or depth here. + + + + list documentation assumptions, such as familiarity with + modifying OpenACS packages. All kernel docs are here etc. + + + This documentation should be written for ongoing use by + developers, not as a tutorial. + + + List of practical development and diagnostics tools and + methodologies. + + + List of OpenACS development resources, api-doc, + schema-browser, developer-support package etc. + + + Identify each OpenACS subsystem, explain why it is used + (instead of other choices). In the case of subsystems that + are developed outside of OpenACS such as tcl, include + external references to development and reference areas. + + + Show current engineering standards and indicate where + changes to the standards are in the works. + + + Sections should be dedicated to DotLRN standards as well, if + they are not available elsewhere. + + + Add overview diagrams showing the core parts of the + datamodel including an updated summary of Greenspun's + Chapter 4: Data Models and the Object System + + + package design guidelines and development process templates + including planning, core functions, testing, usability, and + creating case studies + + + Standard package conventions, where to see "model" code, and + guidelines (or where to find them) for: + + + programming tcl/sql + + + using the acs-api + + + ad_form + + + coding permissions + + + OpenACS objects + + + scheduled protocols + + + call backs + + + directory structure + + + user interface + + + widgets + + + package_name and type_extension_table + + + adding optional services, including search, general + comments, attachments, notifications, workflow, CR and + the new CR Tcl API + + + + + Document kernel coding requirements, strategy and guidelines + to help code changers make decisions that meet kernel + designers' criteria + + + + + + OpenACS Documentation Strategy + + OpenACS documentation development is subject to the + constraints of the software project development and release + methods and cycles (). + Essentially, all phases of work may be active to accommodate + the asynchronous nature of multiple subprojects evolving by + the efforts of a global base of participants with culturally + diverse time references and scheduling idiosyncrasies. + + + The documentation strategy is to use project methods to + involve others by collaborating or obtaining guidance or + feedback (peer review) to distribute the workload and increase + the overall value of output for the OpenACS project. + + + + + OpenACS Documentation Strategy: Why DocBook? + + All OpenACS documentation 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 + is a publishing standard based on XML with + similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook: + + + + It is open-source. + + + A growing community surrounds DocBook (has mailing lists) - and a number of free and commercial + + + A number of free and commercial tools are available - for editing and publishing DocBook documents. + for editing and publishing DocBook documents. + + + It enables us to publish in a variety of formats. + + + XML separates content from presentation: It relieves each + contributor of the burden of presentation, freeing each writer + to focus on content and sharing knowledge. + + + It is well tested technology. It has been in development + since the early 1990's). + + + + Reasons why we are using Docbook XML instead of Docbook SGML: - + + + Consistency and history. We started with a collection + of DocBook XML files that ArsDigita wrote. Trying to re-write them to + conform to the SGML DTD would be unnecessary work. + + + XML 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. Both can output html and pdf formats. + + - This primer walks you through the basics, and should cover the + Albeit, the road to using DocBook has had some trials. + In 2002, Docbook still was not fully capable of representing + online books as practiced by book publishers and expected from + readers with regards to usability on the web. That meant + DocBook did not entirely meet OpenACS publishing requirements + at that time. + + + In 2004, Docbook released version 4.2, 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 + bibliocoverage, + bibliorelation, and + bibliosource. DocBook: + The Definitive Guide is a good start for learning how + to represent paper-based books online. + + + + 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 - list of elements and use more exotic features in your + 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: @@ -94,21 +875,21 @@ - - Always close your tags with corresponding end-tags and to - not use other tag minimization - + + Always close your tags with corresponding end-tags and to + not use other tag minimization + - - Write all elements and attributes in lowercase - + + Write all elements and attributes in lowercase + - Quote all attributes - + Quote all attributes + @@ -123,41 +904,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. - + + 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. - + + 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. - + + 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. - + + 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. + @@ -312,97 +1093,97 @@ - 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>. - And the output is: + And the output is: - 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>. - And the output is: + 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 - 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; - + @@ -414,13 +1195,13 @@ NOTE: Currently this section currently only takes HTML-output into consideration - - not a printed version + 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 ;) @@ -469,14 +1250,14 @@ - 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> @@ -487,17 +1268,17 @@ </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> @@ -506,21 +1287,21 @@ </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> @@ -536,7 +1317,7 @@ </variablelist> - + @@ -587,29 +1368,29 @@ - - + + - - a1 - b1 - c1 - + + a1 + b1 + c1 + - - a2 - b2 - c2 - + + a2 + b2 + c2 + - - a3 - b3 - c3 - + + a3 + b3 + c3 + - - + + @@ -665,7 +1446,7 @@ - Once you have the + Once you have the installed, you can convert your xml documents to HTML or other formats. @@ -678,7 +1459,7 @@ - + To generate a single HTML file from your DocBook XML file, use the command: @@ -711,8 +1492,8 @@ - You could also look at the acs-core-docs Makefile - for examples of how these documents are generated. + You could also look at the acs-core-docs Makefile + for examples of how these documents are generated. @@ -725,51 +1506,51 @@ Using Xinclude - - 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. - + + 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 - + 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) + 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. - + 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. - + 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. + + In the process of transforming your HTML into XML, + HTML tidy + can be a handy tool to make your HTML "regexp'able". + Brandoch Calef has made a + Perl script + that gets you most of the way. - + @@ -779,50 +1560,50 @@ - - - Document Revision # - Action Taken, Notes - When? - By Whom? - - + + + 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.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 - - + + 0.1 + Creation + 12/2000 + Claus Rasmussen + +