| Prev | Chapter 12. Documentation Standards | Next |
|---|
+ By Claus Rasmussen, with additions by Roberto Mello, Vinod Kurup, and the OpenACS Community +
+ 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. +
+ 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. +
+ 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. +
+ 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 a designated documentation maintainer. + Hopefully the following sections will help spur greater + direct participation by the OpenACS community. +
+ 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. +
+ clarity in presentation. Life with + qmail is a recommended example of "rated high" online + documentation. +
+ 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" +
+ 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...> +
+
+
+ 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. +
+ 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 +
+ 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 +
+ 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 +
+ 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 development is subject to the + constraints of the software project development and release + methods and cycles (the section called “Using CVS with OpenACS”). + 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 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. The remaining discussion is about publishing using + Docbook. +
+ + 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) +
+ A number of free and commercial + tools are available + 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. +
+ 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.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.4 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. 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 + the same elements are valid in the XML DTD as long as you remember to: + +
+ Always close your tags with corresponding end-tags and to + not use other tag minimization +
+ Write all elements and attributes in lowercase +
+ Quote all attributes +
+ You are going to need the following to work with the OpenACS + Docbook XML documentation: +
+ 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 and nXML + modes. The LDP Author + Guide and DocBook + Wiki list some alternates. +
+ After you have the tools mentioned above, you need to define a + 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 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. +
+ You can look at some templates for documents (in Docbook XML) in + the sources + for acs-core-docs, especially the + Detailed Design Documentation Template and the + System/Application Requirements Template. +
+ The documentation for each package will make up a little "book" that is structured like this + - examples are emphasized: + + + +
+ book : Docs for one package - templating + | + +--chapter : One section - for developers + | +---------+------------------------------------------------------ + | + +--sect1 : Single document - requirements + | + +--sect2 : Sections - functional requirements + | + +--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.
For now you can take a look at the + sources of these DocBook documents + to get an idea of how they are tied together. +
+
+ Given that your job starts at the sect1-level, all your documents should open with a
+ <sect1>-tag and end
+ with the corresponding </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 section called “Links”).
+ 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.
+
+
+ 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:
+
+<sect1 id="docbook-primer" xreflabel="DocBook Primer"> + <title>DocBook Primer</title> + +... + +</sect1> +
+
+ 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.
+
+
+ For displaying a snippet of code, a filename or anything else you just want to appear as a part of
+ 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>
+
+ + Linking falls into two different categories: inside the book you're making and outside: +
+ By having unique id's you can cross-reference any part of your book
+ with a simple tag, regardless of where that part is.
+
Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
+- Find information about creating a package in +<xref linkend="packages-making-a-package"></xref>. +
And the output is:
+- Find information about creating a package in +Making a Package. +
+ Note that even though this is an empty tag, you have to either: +
+ Provide the end-tag, </xref>, or
+
+ 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:
Put this in your XML:
+-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 +the section called “What a Package Looks Like”. +
+ 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.
+
+
+ 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 url="http://www.oracle.com/">Oracle Corporation</ulink>
+ + ....will create a hyper-link to Oracle in the HTML-version of the documentation. +
NOTE: Do NOT use
+ ampersands in your hyperlinks. These are reserved for
+ referencing entities.
+ To create an ampersand, use the entity &
+
+
+ + Note: The graphics guidelines + are not written in stone. Use another valid approach if it works better + for you. + +
+
+ To insert a graphic we use the elements
+ <mediaobject>,
+ <imageobject>,
+ <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).
+
+<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. +
+ + Here's how you make the DocBook equivalent of the three usual HTML-lists: +
+ 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> +
+ 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> +
+ 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> + + <varlistentry> + <term>Another heading goes here</term> + <listitem><para>And more stuff goes here</para></listitem> + </varlistentry> + +</variablelist> +
+
+ DocBook supports several types of tables, but in most cases, the
+ <informaltable>
+ is enough:
+
+<informaltable frame="all"> + <tgroup cols="3"> + <tbody> + + <row> + <entry>a1</entry> + <entry>b1</entry> + <entry>c1</entry> + </row> + + <row> + <entry>a2</entry> + <entry>b2</entry> + <entry>c2</entry> + </row> + + <row> + <entry>a3</entry> + <entry>b3</entry> + <entry>c3</entry> + </row> + + </tbody> + </tgroup> +</informaltable> +
+ With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: +
| a1 | b1 | c1 |
| a2 | b2 | c2 |
| 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.
+
+
+ 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">.
+
+ Words that are marked as index-words are referenced in an index + in the final, parsed document. +
+ Use
+ <indexterm>,
+ <primary> and
+ <secondary>
+ for this. See these links for an explanation.
+
This section is quoted almost verbatim from the LDP Author Guide.
+ Once you have the Docbook Tools + installed, you can convert your xml documents to HTML or 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+
+ 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. +
+ To generate a set of linked HTML pages, with a separate page + for each <chapter>, <sect1> or <appendix> tag, use the + following command: +
+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. +
+ 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. +
+ 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 +
+ James Clark's free Java parser + XP. Note that + this does not validate XML, only parses it. +
+ DocBook Tool for Linux: + 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. +
+ 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 handy tool to make your HTML "regexp'able". + Brandoch Calef has made a + Perl + script with directions (now via archive.org) + that gets you most of the way. + +