| <html><head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
| <title>2. Introduction</title><link rel="stylesheet" href="css/stylesheet.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.70.0"><link rel="start" href="index.html" title="DocBook Framework (DBF)"><link rel="up" href="index.html" title="DocBook Framework (DBF)"><link rel="prev" href="ch01s03.html" title="1.3 Author Information"><link rel="next" href="ch02s02.html" title="2.2 What you need"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">2. Introduction</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01s03.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ch02s02.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="chapter-introduction"></a>2. Introduction</h2></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="section-why-another-framework"></a>2.1 Why another framework for rendering docbook?</h2></div></div></div><p>The Velocity project used a simple HTML based format called | |
| <em class="firstterm">XDOC</em> for its documentation for a very long time. | |
| However, <em class="firstterm">XDOC</em> is not really popular outside the | |
| Apache world<sup>[<a name="d0e69" href="#ftn.d0e69">1</a>]</sup>, it renders somehow into HTML but no other formats (unless | |
| you consider a set of alpha and beta-level plugins for maven-1 and | |
| maven-2) and tool support for this format is not really there.</p><p>When an XML based format for documentation is considered, DocBook | |
| seems to be a natural choice. So we decided to take a stab at rendering | |
| the existing Velocity Docs that are end-user specific (Users Guide, | |
| Developers Guide, Reference and the likes) through DocBook.</p><p>What we wanted to have, was a framework, that...</p><div class="itemizedlist"><ul type="disc"><li><p>...renders multiple documents into multiple formats with an | |
| uniform look without having to copy a large number of stylesheets, | |
| images and other supporting files around.</p></li><li><p>...separates the render framework and the actual documentation | |
| to render. It should be sufficient to install the framework only | |
| once and then reference it.</p></li><li><p>...uses the standard DocBook XML and XSL zip files available | |
| for download. Many of the open source DocBook frameworks use heavily | |
| hacked versions and we want to be able to keep up with releases | |
| without having to patch the released files every time.</p></li><li><p>...uses current versions of the DocBook reference files, the | |
| libraries and supporting tools.</p></li><li><p>...render all formats without connecting to the Internet. | |
| Using the Apache XML resolver, it should be possible to use the | |
| framework completely standalone. See | |
| <code class="uri">http://xml.apache.org/commons/components/resolver/resolver-article.html</code> | |
| for an explanation.</p></li><li><p>...has some documentation so you understand what happens when | |
| a format gets rendered and how.</p></li><li><p>...that can be customized easily (if you consider customizing | |
| complex XSL style sheets 'easy').</p></li><li><p>...that is platform independent and uses 100% pure Java. No | |
| external programs should be needed or called.</p></li><li><p>...that is driven by Apache ant and could be easily embedded | |
| into larger builds.</p></li></ul></div></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.d0e69" href="#d0e69">1</a>] </sup>And not even in the Apache world...</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s03.html">Prev</a> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ch02s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.3 Author Information </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 2.2 What you need</td></tr></table></div></body></html> |