Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

init commit

  • Loading branch information...
commit 8acf615b3c702e9d47b19148776f6c1cc787de2f 0 parents
@cwensel authored
Showing with 3,029 additions and 0 deletions.
  1. BIN  .DS_Store
  2. BIN  DBFUserGuide.pdf
  3. +202 −0 LICENSE
  4. +58 −0 MANIFEST
  5. +12 −0 NOTICE
  6. +12 −0 README.FIRST
  7. +28 −0 TODO
  8. +336 −0 build-docbook.xml
  9. +24 −0 default_imageincludes.txt
  10. +84 −0 docbook.properties
  11. +72 −0 docs/build.xml
  12. +23 −0 docs/project.properties
  13. +275 −0 docs/src/css/html/stylesheet.css
  14. +1,173 −0 docs/src/docbook/dbf/DBFUserGuide.xml
  15. BIN  docs/src/images/logo.png
  16. +58 −0 docs/src/styles/html/custom.xsl
  17. +60 −0 docs/src/styles/html/titlepage.xml
  18. +320 −0 docs/src/styles/pdf/custom.xsl
  19. +97 −0 docs/src/styles/pdf/titlepage.xml
  20. BIN  lib/.DS_Store
  21. BIN  lib/avalon-framework-api-4.3.jar
  22. BIN  lib/avalon-framework-impl-4.3.jar
  23. BIN  lib/batik-all-1.7.jar
  24. BIN  lib/commons-io-1.3.1.jar
  25. BIN  lib/commons-logging-1.0.4.jar
  26. BIN  lib/fop-0.95.jar
  27. BIN  lib/xalan-j-2.7.0/xalan.jar
  28. BIN  lib/xerces-2.9.0/serializer.jar
  29. BIN  lib/xerces-2.9.0/xercesImpl.jar
  30. BIN  lib/xml-apis-1.3.04.jar
  31. BIN  lib/xml-apis-ext-1.3.04.jar
  32. BIN  lib/xml-resolver-1.1.jar
  33. BIN  lib/xmlgraphics-commons-1.3.1.jar
  34. BIN  src/.DS_Store
  35. +23 −0 src/resolver/CatalogManager.properties
  36. +53 −0 src/resolver/xml-catalog.xml
  37. +26 −0 src/styles/custom.xsl
  38. +32 −0 src/styles/html.xsl
  39. +30 −0 src/styles/htmlsingle.xsl
  40. +31 −0 src/styles/pdf.xsl
  41. BIN  src/zip/.DS_Store
  42. BIN  src/zip/docbook-xml-5.0.zip
  43. BIN  src/zip/docbook-xsl-1.74.0.zip
BIN  .DS_Store
Binary file not shown
BIN  DBFUserGuide.pdf
Binary file not shown
202 LICENSE
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
58 MANIFEST
@@ -0,0 +1,58 @@
+# Copyright 2006 The Apache Software Foundation
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+README.FIRST - Important Information about PDF rendering!
+DBFUserGuide.pdf - DocBook Framework documentation
+
+TODO - Want to help? Start here.
+LICENSE - Apache Software License 2.0
+MANIFEST - This file
+NOTICE - Copyright notices
+
+build-docbook.xml - ant tasks for docbook transformation
+docbook.properties - Default values for all settings.
+
+src/resources/CatalogManager.properties - Configuration file for xml commons resolver
+src/resources/xml-catalog.xml - Catalog file for xml commons resolver
+
+src/styles - User XSLT styles
+src/styles/custom.xsl - Empty default custom file. Do not delete or change!
+src/styles/html.xsl - Stylesheet driver for HTML
+src/styles/htmlsingle.xsl - Stylesheet driver for HTML-Single
+src/styles/pdf.xsl - Stylesheet driver for PDF
+
+src/styles/html - XSLT styles for HTML and HTML-Single
+src/styles/html/custom.xsl - Custom settings for HTML and HTML-Single
+src/styles/html/titlepage.xml - Titlepage definition for HTML and HTML-Single
+
+src/styles/pdf - XSLT styles for PDF
+src/styles/pdf/custom.xsl - Custom settings for PDF
+src/styles/pdf/titlepage.xml - Titlepage definition for PDF
+
+src/css - User CSS files
+src/css/html - CSS files for HTML and HTML-Single
+
+src/zip - Docbook reference files
+src/zip/docbook-xml-4.4.zip - XML definition files from http://www.oasis-open.org/docbook/xml/
+src/zip/docbook-xsl-snapshot.zip - XSL transformation styles from http://docbook.sourceforge.net/snapshots/
+ (Build 6795, 2007-04-26)
+
+docs - Contains the DocBook source for the DocBook Framework
+ documentation.
+
+lib - libraries for XSLT transformation
+
+MANIFEST - This file
+TODO - If you feel like helping out, tackle these tasks.
+LICENSE.txt - The license (ASL 2.0) for this toolset
12 NOTICE
@@ -0,0 +1,12 @@
+Apache Docbook Framework
+
+Copyright (C) 2006-2007 The Apache Software Foundation
+
+This product includes software developed at
+The Apache Software Foundation (http://www.apache.org/).
+
+This product includes software developed by
+M.H.Kay (michael.h.kay@ntlworld.com) and distributed under
+the MOZILLA PUBLIC LICENSE 1.0.
+
+
12 README.FIRST
@@ -0,0 +1,12 @@
+ DocBook Framework (DBF)
+ =======================
+
+------------------------------------------------------------------------
+
+The documentation has been moved to DocBook format and is available
+in the DBUserGuide.pdf file in this directory.
+
+You can rebuild this documentation by running "ant" in the docs
+directory.
+
+------------------------------------------------------------------------
28 TODO
@@ -0,0 +1,28 @@
+* Do testing on non-windows platforms to find out whether the
+ framework actually works on Windows. It should, but all testing was
+ done on Linux.
+
+* Test JDK 1.4.2
+
+* Convert the README into Docbook and render it through the framework
+ (Eat our own dogfood)
+
+* Don't use Saxon directly. Use the <style> ant task and make Saxon
+ configurable (use another processor, e.g. Xalan (eat Apache dog
+ food... ;-) )
+
+* The title pages still have some large gaps. Toy with the style sheets
+ and titlepage.xml files
+
+* Document the customizations in the custom.xsl files better
+
+* Don't blindly add all the images from the docbook XSL distribution to
+ the HTML directories.
+
+* Get better images for admonition and callouts.
+
+* Maybe use SVG for PDF image rendering so the images scale.
+
+* Force the examples (<computeroutput>) to be kept on one page.
+
+* Add an ant task that can create the project specific build.xml file.
336 build-docbook.xml
@@ -0,0 +1,336 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<project name="docbook" default="all" basedir=".">
+
+ <!-- Load our properties -->
+ <property file="${dbf.basedir}/docbook.properties"/>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Set up the classpath for the XSLT conversion == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <path id="dbf.classpath">
+ <fileset dir="${dbf.basedir}/lib">
+ <include name="**/*.jar"/>
+ </fileset>
+ <fileset dir="${dbf.xsl.dir}/extensions">
+ <include name="${xslt-db.jar}"/>
+ </fileset>
+ <pathelement location="${tmp.dir}"/>
+ </path>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Prepare Path elements to be used when filtering the XSL files == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <path id="dbf.xml.path" location="${dbf.xml.dir}"/>
+ <path id="dbf.xsl.path" location="${dbf.xsl.dir}"/>
+ <path id="src.dir.path" location="${src.dir}"/>
+ <path id="tmp.dir.path" location="${tmp.dir}"/>
+ <path id="target.dir.path" location="${target.dir}"/>
+ <pathconvert dirsep="/" property="dbf.xml.path" refid="dbf.xml.path"/>
+ <pathconvert dirsep="/" property="dbf.xsl.path" refid="dbf.xsl.path"/>
+ <pathconvert dirsep="/" property="src.dir.path" refid="src.dir.path"/>
+ <pathconvert dirsep="/" property="tmp.dir.path" refid="tmp.dir.path"/>
+ <pathconvert dirsep="/" property="target.dir.path" refid="target.dir.path"/>
+
+ <condition property="file.prefix" value="file:///">
+ <os family="windows"/>
+ </condition>
+ <condition property="file.prefix" value="file://">
+ <os family="unix"/>
+ </condition>
+
+ <!-- This filterset is used to convert the style sheets to reference
+ the actual locations of the docbook XSLT files -->
+ <filterset id="filterset.dbf.location">
+ <filter token="paper.type" value="${paper.type}"/>
+ <filter token="file.prefix" value="${file.prefix}"/>
+ <filter token="dbf.xml" value="${dbf.xml.path}"/>
+ <filter token="dbf.xsl" value="${dbf.xsl.path}"/>
+ <filter token="src.dir" value="${src.dir.path}"/>
+ <filter token="tmp.dir" value="${tmp.dir.path}"/>
+ <filter token="target.dir" value="${target.dir.path}"/>
+ </filterset>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Xalan Converter macro that uses commons-resolver == -->
+ <!-- == == -->
+ <!-- == input: The file to transform == -->
+ <!-- == output: The transformation result == -->
+ <!-- == style: The Style Sheet used for the transformation == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <macrodef name="xalan">
+ <attribute name="input"/>
+ <attribute name="output"/>
+ <attribute name="style"/>
+ <sequential>
+ <java classname="org.apache.xalan.xslt.Process" fork="true"
+ dir="${basedir}" classpathref="dbf.classpath">
+ <jvmarg
+ value="-Dorg.apache.xerces.xni.parser.XMLParserConfiguration=org.apache.xerces.parsers.XIncludeParserConfiguration"/>
+ <arg line="-URIRESOLVER org.apache.xml.resolver.tools.CatalogResolver"/>
+ <arg line="-ENTITYRESOLVER org.apache.xml.resolver.tools.CatalogResolver"/>
+ <arg value="-OUT"/>
+ <arg value="@{output}"/>
+ <arg value="-IN"/>
+ <arg value="@{input}"/>
+ <arg value="-XSL"/>
+ <arg value="@{style}"/>
+ </java>
+ </sequential>
+ </macrodef>
+
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Transformation Macro that generates output from Docbook == -->
+ <!-- == == -->
+ <!-- == type: Type of transformation (pdf, html, htmlsingle) == -->
+ <!-- == title: Titlepage to use (html and htmlsingle both use html!) == -->
+ <!-- == target: Target directory (pdf needs tmp for FOP transform) == -->
+ <!-- == dir: Subdir where the Docbook XML file is located. Also subdir == -->
+ <!-- == for the output == -->
+ <!-- == file: Name of the file (without ending!) to transform == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <macrodef name="transform">
+ <attribute name="type"/>
+ <attribute name="title"/>
+ <attribute name="target"/>
+ <attribute name="dir"/>
+ <attribute name="file"/>
+ <attribute name="xsl"/>
+ <sequential>
+
+ <property name="@{type}.target.dir" value="${target.dir}/@{dir}/@{target}"/>
+ <property name="@{type}.target.file" value="${@{type}.target.dir}/@{file}"/>
+ <property name="@{type}.tmp.style" value="${tmp.dir}/@{type}.xsl"/>
+ <property name="@{type}.tmp.custom" value="${tmp.dir}/@{type}-style.xsl"/>
+ <property name="@{type}.tmp.titlepage" value="${tmp.dir}/@{type}-titlepage"/>
+ <property name="@{type}.tmp.imageincludes" value="${tmp.dir}/@{type}_imageincludes.txt"/>
+
+ <path id="@{type}.target.path" location="${@{type}.target.dir}"/>
+ <pathconvert dirsep="/" property="@{type}.target.path" refid="@{type}.target.path"/>
+
+ <copy overwrite="true" filtering="on" file="${dbf.style.src.dir}/@{type}.xsl" tofile="${@{type}.tmp.style}">
+ <filterset refid="filterset.dbf.location"/>
+ <filterset>
+ <filter token="@{type}.target.dir" value="${@{type}.target.path}"/>
+ </filterset>
+ </copy>
+
+ <copy overwrite="true" failonerror="false" filtering="on" file="${styles.src.dir}/@{type}/custom.xsl"
+ tofile="${@{type}.tmp.custom}">
+ <filterset refid="filterset.dbf.location"/>
+ <filterset>
+ <filter token="@{type}.target.dir" value="${@{type}.target.path}"/>
+ </filterset>
+ </copy>
+
+ <!-- No custom style file around. Use the vanilla one. -->
+ <copy overwrite="false" failonerror="true" file="${dbf.style.src.dir}/custom.xsl" tofile="${@{type}.tmp.custom}"/>
+
+ <mkdir dir="${@{type}.target.dir}/"/>
+
+ <!-- copy custom title page. If we don't have one, use the custom one. -->
+ <copy file="${styles.src.dir}/@{title}/titlepage.xml" tofile="${@{type}.tmp.titlepage}.xml" overwrite="true"
+ failonerror="false"/>
+ <copy file="${dbf.xsl.dir}/@{xsl}/titlepage.templates.xml" tofile="${@{type}.tmp.titlepage}.xml" overwrite="false"
+ failonerror="true"/>
+
+ <xalan input="${@{type}.tmp.titlepage}.xml"
+ output="${@{type}.tmp.titlepage}.xsl"
+ style="${dbf.xsl.dir}/template/titlepage.xsl"/>
+
+ <!-- copy custom imageincludes. If we don't have one, use the default one. -->
+ <copy file="${docbook.src.dir}/@{dir}/@{file}.@{type}_imageincludes.txt"
+ tofile="${@{type}.tmp.imageincludes}" overwrite="true" failonerror="false"/>
+ <copy file="${dbf.basedir}/default_imageincludes.txt" tofile="${@{type}.tmp.imageincludes}"
+ overwrite="false" failonerror="true"/>
+ <copy todir="${@{type}.target.dir}/images">
+ <fileset dir="${images.src.dir}" includesfile="${@{type}.tmp.imageincludes}"/>
+ </copy>
+
+ <xalan input="${docbook.src.dir}/@{dir}/@{file}.xml"
+ output="${@{type}.target.file}.xml"
+ style="${@{type}.tmp.style}"/>
+
+ </sequential>
+ </macrodef>
+
+ <!-- =========================================================================== -->
+ <!-- == == -->
+ <!-- == prepare temporary directories and unzip the docbook DTD and XSL files == -->
+ <!-- == == -->
+ <!-- =========================================================================== -->
+ <target name="prepare">
+
+ <fail message="You must set docbook.file and docbook.dir!">
+ <condition>
+ <not>
+ <and>
+ <isset property="docbook.dir"/>
+ <isset property="docbook.file"/>
+ </and>
+ </not>
+ </condition>
+ </fail>
+
+ <fail
+ message="You must configure the dbf.basedir from your project.properties. That is usually ${basedir}/docbook!">
+ <condition>
+ <not>
+ <and>
+ <isset property="dbf.basedir"/>
+ </and>
+ </not>
+ </condition>
+ </fail>
+
+ <mkdir dir="${tmp.dir}"/>
+
+ <mkdir dir="${dbf.xml.dir}"/>
+ <unzip src="${dbf.zip.src.dir}/docbook-xml-${dbf.xml.version}.zip" dest="${dbf.xml.dir}"/>
+
+ <mkdir dir="${dbf.xsl.dir}"/>
+ <unzip src="${dbf.zip.src.dir}/docbook-xsl-${dbf.xsl.version}.zip" dest="${target.dir}"/>
+
+ <copy todir="${tmp.dir}" filtering="on" overwrite="true">
+ <fileset dir="${dbf.resolver.src.dir}"/>
+ <filterset refid="filterset.dbf.location"/>
+ </copy>
+
+ </target>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == This is the main target to generate all the docs == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <target name="all" depends="pdf,html,htmlsingle"
+ description="--> Generate and copy reference documentation"/>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Clean up the target directory == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <target name="clean"
+ description="--> Delete temporary and distribution directories for docs">
+
+ <fail
+ message="You must configure the dbf.basedir from your project.properties. That is usually ${basedir}/docbook!">
+ <condition>
+ <not>
+ <and>
+ <isset property="dbf.basedir"/>
+ </and>
+ </not>
+ </condition>
+ </fail>
+
+ <delete quiet="true" dir="${target.dir}"/>
+ </target>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Create the PDF documentation == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <target name="pdf"
+ depends="prepare"
+ description="--> Generate PDF docs">
+
+ <transform type="pdf" target="tmp" title="pdf" xsl="fo" dir="${docbook.dir}" file="${docbook.file}"/>
+
+ <mkdir dir="${target.dir}/${docbook.dir}/pdf"/>
+
+ <java classname="org.apache.fop.cli.Main" fork="true" maxmemory="256m"
+ dir="${basedir}" classpathref="dbf.classpath">
+ <arg value="${pdf.target.file}.xml"/>
+ <arg value="${target.dir}/${docbook.dir}/pdf/${docbook.file}.pdf"/>
+ </java>
+ </target>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Create the HTML documentation, many pages == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <target name="html"
+ depends="prepare"
+ description="--> Generate HTML docs in multiple files">
+
+ <transform type="html" target="html" title="html" xsl="html" dir="${docbook.dir}" file="${docbook.file}"/>
+
+ <!-- transform copied the custom or default imageincludes, so use it -->
+ <copy todir="${html.target.dir}/images">
+ <fileset dir="${dbf.xsl.dir}/images/" includesfile="${tmp.dir}/html_imageincludes.txt"/>
+ </copy>
+
+ <copy todir="${html.target.dir}/css">
+ <fileset dir="${css.src.dir}/html"/>
+ </copy>
+
+ <delete file="${html.target.file}.xml"/>
+
+ <delete quiet="true" file="${html.target.file}.zip"/>
+ <zip basedir="${target.dir}/${docbook.dir}" destfile="${html.target.file}.zip">
+ <include name="html/**"/>
+ </zip>
+ </target>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Create the HTML documentation, one big page == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <target name="htmlsingle"
+ depends="prepare"
+ description="--> Generate HTML docs in a single, big file">
+
+ <transform type="htmlsingle" target="htmlsingle" title="html" xsl="html" dir="${docbook.dir}"
+ file="${docbook.file}"/>
+
+ <!-- transform copied the custom or default imageincludes, so use it -->
+ <copy todir="${htmlsingle.target.dir}/images">
+ <fileset dir="${dbf.xsl.dir}/images/" includesfile="${tmp.dir}/htmlsingle_imageincludes.txt"/>
+ </copy>
+
+ <copy todir="${htmlsingle.target.dir}/css">
+ <fileset dir="${css.src.dir}/html"/>
+ </copy>
+
+ <move file="${htmlsingle.target.file}.xml" tofile="${htmlsingle.target.dir}/index.html"/>
+
+ <delete quiet="true" file="${htmlsingle.target.file}.zip"/>
+ <zip basedir="${target.dir}/${docbook.dir}" destfile="${htmlsingle.target.file}.zip">
+ <include name="htmlsingle/**"/>
+ </zip>
+
+ </target>
+</project>
24 default_imageincludes.txt
@@ -0,0 +1,24 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# #######################################################################
+#
+# Include all images into the project. This is the default.
+#
+# #######################################################################
+
+**/*
84 docbook.properties
@@ -0,0 +1,84 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# #######################################################################
+#
+# The following parameter usually get overwritten by the caller.
+#
+# These are the default values that should work in most cases.
+#
+# #######################################################################
+
+# Where all the sources are located
+src.dir = ${basedir}/src
+
+# Location of custom style files (XSL)
+styles.src.dir = ${src.dir}/styles
+
+# Location of the docbook files
+docbook.src.dir = ${src.dir}/docbook
+
+# Location of the image files
+images.src.dir = ${src.dir}/images
+
+# Location of the CSS files
+css.src.dir = ${src.dir}/css
+
+# Target Directory
+target.dir = ${basedir}/target
+
+# Directory for temporary files
+tmp.dir = ${target.dir}/tmp
+
+# The size of the PDF pages.
+paper.type= Letter
+
+
+# #######################################################################
+#
+# End of default values. Don't change anything below this line.
+#
+# #######################################################################
+
+# The docbook XML and Style sheet versions used.
+# These must match the archives in src/zip!
+dbf.xml.version = 5.0
+
+# SVN 6795, 2007-04-26
+dbf.xsl.version = 1.74.0
+
+# Where all the sources are located
+dbf.src.dir = ${dbf.basedir}/src
+
+# Location of the docbook reference archives
+dbf.zip.src.dir = ${dbf.src.dir}/zip
+
+# Location of the generic style xsl files.
+dbf.style.src.dir = ${dbf.src.dir}/styles
+
+# Location of the generic style xsl files.
+dbf.resolver.src.dir = ${dbf.src.dir}/resolver
+
+# Directories into which the docbook reference archives are expanded
+dbf.xml.dir = ${target.dir}/docbook-xml-${dbf.xml.version}
+dbf.xsl.dir = ${target.dir}/docbook-xsl-${dbf.xsl.version}
+
+# We use SAXON as our XSLT processor and this is the custom jar included with
+# the docbook XML distribution.
+#xslt-db.jar = saxon653.jar
+xslt-db.jar = xalan27.jar
+
72 docs/build.xml
@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<project name="dbf-docbook" default="all" basedir=".">
+
+ <!-- Load our properties -->
+ <property file="project.properties"/>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Build all the Velocity Docbook Documentation == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <target name="all" description="--> Build all documentation">
+
+ <!-- Build the Users Guide -->
+ <ant antfile="${dbf.basedir}/build-docbook.xml" target="all">
+ <property name="docbook.dir" value="dbf"/>
+ <property name="docbook.file" value="DBFUserGuide"/>
+ </ant>
+ </target>
+
+ <!-- ======================================================================== -->
+ <!-- == == -->
+ <!-- == Clean up the target directory == -->
+ <!-- == == -->
+ <!-- ======================================================================== -->
+ <target name="clean"
+ description="--> Delete temporary and distribution directories for docs">
+ <ant antfile="${dbf.basedir}/build-docbook.xml" target="clean"/>
+ </target>
+
+ <target name="pdf">
+ <ant antfile="${dbf.basedir}/build-docbook.xml" target="pdf">
+ <property name="docbook.dir" value="dbf"/>
+ <property name="docbook.file" value="DBFUserGuide"/>
+ </ant>
+ </target>
+
+ <target name="html">
+ <ant antfile="${dbf.basedir}/build-docbook.xml" target="html">
+ <property name="docbook.dir" value="dbf"/>
+ <property name="docbook.file" value="DBFUserGuide"/>
+ </ant>
+ </target>
+
+ <target name="htmlsingle">
+ <ant antfile="${dbf.basedir}/build-docbook.xml" target="htmlsingle">
+ <property name="docbook.dir" value="dbf"/>
+ <property name="docbook.file" value="DBFUserGuide"/>
+ </ant>
+ </target>
+
+</project>
23 docs/project.properties
@@ -0,0 +1,23 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# Basedir for the docbook framework
+dbf.basedir = ..
+
+# The size of the PDF pages.
+paper.type= Letter
+
275 docs/src/css/html/stylesheet.css
@@ -0,0 +1,275 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+<!--
+Copyright
+
+2006
+The Apache Software Foundation.
+
+ Licensed under the Apache License, Version
+
+2.0
+(
+the
+
+"License"
+)
+you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http:
+
+/
+/
+www.apache.org
+
+/
+licenses
+
+/
+LICENSE-2
+
+.0
+
+Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an
+
+"AS IS"
+BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+
+-->
+
+html {
+ padding: 0pt;
+ margin: 0pt;
+}
+
+body {
+ margin-top: 1em;
+ margin-bottom: 1em;
+ margin-left: 10%;
+ margin-right: 10%;
+
+ font-family: Times, Times New Roman, serif;
+}
+
+div {
+ margin: 0pt;
+}
+
+p {
+ text-align: justify;
+ margin-bottom: .6em;
+ line-height: 1.2;
+}
+
+hr {
+ margin-top: .6em;
+ margin-bottom: .6em;
+ margin-left: 0pt;
+ margin-right: 0pt;
+ border: 1px solid gray;
+ background: gray;
+}
+
+h1, h2, h3, h4, h5 {
+ color: #525D76;
+}
+
+a {
+ text-decoration: underline;
+ color: black;
+}
+
+a:hover {
+ text-decoration: underline;
+ color: black;
+}
+
+h1, h2, h3, h4, h5 {
+ line-height: 1.3;
+ margin-top: 1.5em;
+ font-family: Arial, Sans-serif;
+}
+
+h1.title {
+ text-align: left;
+
+ margin-top: 2em;
+ margin-bottom: 2em;
+ margin-left: 0pt;
+ margin-right: 0pt;
+}
+
+h2.subtitle, h3.subtitle {
+ text-align: left;
+ margin-top: 2em;
+ margin-bottom: 2em;
+ text-transform: uppercase;
+}
+
+h3.author, p.othercredit {
+ font-size: 0.9em;
+ font-weight: normal;
+ font-style: oblique;
+ text-align: left;
+ color: #525D76;
+}
+
+div.titlepage {
+}
+
+div.section {
+}
+
+div.authorgroup {
+ text-align: left;
+ margin-bottom: 3em;
+ display: block;
+}
+
+div.toc, div.list-of-examples, div.list-of-figures {
+ font-size: 0.8em;
+ margin-bottom: 3em;
+}
+
+div.itemizedlist {
+ margin-top: 0.5em;
+ margin-bottom: 0.5em;
+}
+
+ol, ul {
+}
+
+li {
+}
+
+pre {
+ margin: .75em 0;
+ line-height: 1.0;
+ color: black;
+}
+
+pre.programlisting {
+ font-size: 9pt;
+ padding: 5pt 2pt;
+ border: 1pt solid black;
+ background: #eeeeee;
+}
+
+div.table {
+ margin: 1em;
+ padding: 0.5em;
+ text-align: center;
+}
+
+div.table table {
+ display: block;
+}
+
+div.table td {
+ padding-right: 5px;
+ padding-left: 5px;
+}
+
+div.table p.title {
+ text-align: center;
+ margin-left: 5%;
+ margin-right: 5%;
+}
+
+p.releaseinfo, .copyright {
+ font-size: 0.7em;
+ text-align: left;
+ margin: 0px;
+ padding: 0px;
+}
+
+div.note, div.important, div.example, div.informalexample, div.tip, div.caution {
+ margin: 1em;
+ padding: 0.5em;
+ border: 1px solid gray;
+ background-color: #f8f8e0;
+}
+
+div.important th, div.note th, div.tip th {
+ text-align: left;
+ border-bottom: solid 1px gray;
+}
+
+div.navheader, div.navheader table {
+ font-family: sans-serif;
+ font-size: 12px;
+}
+
+div.navfooter, div.navfooter table {
+ font-family: sans-serif;
+ font-size: 12px;
+}
+
+div.figure {
+ text-align: center;
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+
+div.figure p.title {
+ text-align: center;
+ margin-left: 15%;
+ margin-right: 15%;
+}
+
+div.example p.title {
+ margin-top: 0em;
+ margin-bottom: 0.6em;
+ text-align: left;
+ padding-bottom: 0.4em;
+ border-bottom: solid 1px gray;
+}
+
+div.figure img {
+ border: 1px solid gray;
+ padding: 0.5em;
+ margin: 0.5em;
+}
+
+div.revhistory {
+ font-size: 0.8em;
+ width: 90%;
+ margin-left: 5%;
+ margin-top: 3em;
+ margin-bottom: 3em;
+}
+
+div.revhistory table {
+ font-family: sans-serif;
+ font-size: 12px;
+ border-collapse: collapse;
+}
+
+div.revhistory table tr {
+ border: solid 1px gray;
+}
+
+div.revhistory table th {
+ border: none;
+}
1,173 docs/src/docbook/dbf/DBFUserGuide.xml
@@ -0,0 +1,1173 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<book lang="en">
+ <title>DocBook Framework (DBF)</title>
+
+ <bookinfo>
+ <copyright>
+ <year>2006-2007</year>
+
+ <holder>The Apache Software Foundation</holder>
+ </copyright>
+
+ <releaseinfo>V 1.1-dev</releaseinfo>
+
+ <productname>DBF</productname>
+
+ <authorgroup>
+ <corpauthor>The Apache Velocity Developers</corpauthor>
+ </authorgroup>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/logo.png"/>
+ </imageobject>
+ </mediaobject>
+ </bookinfo>
+
+ <toc/>
+
+ <chapter id="chapter-preface">
+ <title>Preface</title>
+
+ <section id="section-about-this-project">
+ <title>About this Project</title>
+
+ <para>This project started out as a framework to render documentation
+ for the Apache Velocity project (
+ <uri>http://velocity.apache.org/</uri>) and ended somehow up to be a
+ generic framework to render DocBook documents using Java and driven by
+ Apache ant.
+ </para>
+
+ <para>While DocBook format seems to be ubiquitous these days, to our
+ surprise there were not many generic frameworks around that could render
+ all kinds of formats, are platform independent, do not require lots of
+ infrastructure installed and are easily customizable.
+ </para>
+
+ <para>Projects either use heavily customized and hacked style sheets or
+ a mix of Java and other applications. Adjusting such a rendering
+ framework to the needs of the Apache Velocity project was not easy, so
+ at some point, we decided to redo this (almost) from scratch.
+ </para>
+ </section>
+
+ <section id="section-license">
+ <title>License Information</title>
+
+ <para>Copyright © 2006-2007 The Apache Software Foundation.</para>
+
+ <para>Licensed under the Apache License, Version 2.0 (the "License") you
+ may not use this file except in compliance with the License. You may
+ obtain a copy of the License at
+ <uri>http://www.apache.org/licenses/LICENSE-2.0</uri>
+ </para>
+
+ <para>Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an "AS IS"
+ BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied. See the License for the specific language governing permissions
+ and limitations under the License.
+ </para>
+ </section>
+
+ <section id="section-author-information">
+ <title>Author Information</title>
+
+ <para>This framework and documentation was written by the Apache
+ Velocity Developers. If you have questions, found a bug or have
+ enhancements, please contact us through the Apache Velocity Development
+ Mailing list at
+ <email>dev@velocity.apache.org</email>
+ </para>
+ </section>
+ </chapter>
+
+ <chapter id="chapter-introduction">
+ <title>Introduction</title>
+
+ <section id="section-why-another-framework">
+ <title>Why another framework for rendering docbook?</title>
+
+ <para>The Velocity project used a simple HTML based format called
+ <firstterm>XDOC</firstterm>
+ for its documentation for a very long time.
+ However,
+ <firstterm>XDOC</firstterm>
+ is not really popular outside the
+ Apache world
+ <footnote>
+ <para>And not even in the Apache world...</para>
+ </footnote>
+ , 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.
+ </para>
+
+ <para>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.
+ </para>
+
+ <para>What we wanted to have, was a framework, that...</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>...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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>...separates the render framework and the actual documentation
+ to render. It should be sufficient to install the framework only
+ once and then reference it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>...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.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>...uses current versions of the DocBook reference files, the
+ libraries and supporting tools.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>...render all formats without connecting to the Internet.
+ Using the Apache XML resolver, it should be possible to use the
+ framework completely standalone. See
+ <uri>http://xml.apache.org/commons/components/resolver/resolver-article.html</uri>
+ for an explanation.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>...has some documentation so you understand what happens when
+ a format gets rendered and how.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>...that can be customized easily (if you consider customizing
+ complex XSL style sheets 'easy').
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>...that is platform independent and uses 100% pure Java. No
+ external programs should be needed or called.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>...that is driven by Apache ant and could be easily embedded
+ into larger builds.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <?hard-pagebreak ?>
+
+ <section id="section-what-you-need">
+ <title>What you need</title>
+
+ <itemizedlist>
+ <listitem>
+ <para>A Java Runtime. All testing has been done using the Sun JSDK
+ 1.5.0
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>Apache Ant version 1.6 or better. The build script uses the
+ macrodef task which was introduced in ant 1.6. Any later version
+ should work, too. Get it from
+ <uri>http://ant.apache.org/</uri>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>The Sun JAI libraries. Please see the
+ <literal>README.FIRST</literal>
+ file on how to get and install
+ these.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Everything else needed should be included in this package.</para>
+ </section>
+
+ <section id="section-caveat-emptor">
+ <title>Caveat Emptor!</title>
+
+ <para>This framework has been written for the Velocity documentation and
+ we also tried to do a reasonably good job in documentating it.
+ </para>
+
+ <para>In any case, the last and final word is in the Subversion
+ repository for the DocBook Framework at
+ <uri>
+ http://svn.apache.org/repos/asf/velocity/docbook/trunk/
+ </uri>
+ </para>
+
+ <para>The reference on how to setup and build documentation is the
+ Velocity documentation at
+ <uri>
+ http://svn.apache.org/repos/asf/velocity/docs/
+ </uri>
+ and also the
+ DocBook Framework documentation itself which is located in the
+ <literal>docs/</literal>
+ subfolder of the distribution. If in doubt,
+ please check there on how the framework is used.
+ </para>
+ </section>
+ </chapter>
+
+ <chapter id="chapter-using-the-framework">
+ <title>Using the Framework</title>
+
+ <section id="section-how-to-set-up">
+ <title>How to set up your documentation files</title>
+
+ <para>Writing documentation is not just writing text. Often, an author
+ wants to add images, customize the layout of the pages or use specific
+ style information to format documentation in e.g. HTML format. All the
+ required files must be found by the DocBook Framework for creating
+ output files.
+ </para>
+
+ <figure id="figure-recommended-layout">
+ <title>Recommended layout for a documentation project</title>
+
+ <programlisting>&lt;root&gt;
+ |
+ +---- build.xml
+ <co id="co-build-xml" linkends="ca-build-xml"/>
+ +---- project.properties
+ <co id="co-project-properties"
+ linkends="ca-project-properties"/>
+ |
+ +-- src
+ |
+ +-- docbook
+ <co id="co-docbook-sources" linkends="ca-docbook-sources"/>
+ |
+ +-- styles
+ | |
+ | +-- pdf
+ <co id="co-styles-pdf" linkends="ca-styles-pdf"/>
+ | |
+ | +-- html
+ <co id="co-styles-html" linkends="ca-styles-html"/>
+ |
+ +-- css
+ | |
+ | +-- html
+ <co id="co-css-html" linkends="ca-css-html"/>
+ |
+ +-- images
+ <co id="co-src-images" linkends="ca-src-images"/>
+ </programlisting>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="co-build-xml" id="ca-build-xml">
+ <para>ant build file</para>
+ </callout>
+
+ <callout arearefs="co-project-properties" id="ca-project-properties">
+ <para>custom settings for your build</para>
+ </callout>
+
+ <callout arearefs="co-docbook-sources" id="ca-docbook-sources">
+ <para>Docbook sources</para>
+ </callout>
+
+ <callout arearefs="co-styles-pdf" id="ca-styles-pdf">
+ <para>Custom styles for PDF</para>
+ </callout>
+
+ <callout arearefs="co-styles-html" id="ca-styles-html">
+ <para>Custom styles for HTML</para>
+ </callout>
+
+ <callout arearefs="co-css-html" id="ca-css-html">
+ <para>CSS files for HTML</para>
+ </callout>
+
+ <callout arearefs="co-src-images" id="ca-src-images">
+ <para>Image files for PDF/HTML</para>
+ </callout>
+ </calloutlist>
+
+ <para>It is possible to customize this file layout further to adjust it
+ to existing documentation. If you start a new documentation project,
+ then we recommend that you start with this layout until you are familiar
+ on how the DocBook Framework behaves.
+ </para>
+ </section>
+
+ <?hard-pagebreak ?>
+
+ <section id="section-configuring-your-documentation">
+ <title>Customizing your documentation file layout</title>
+
+ <para>Unless you absolutely want to change the default settings for
+ building your documentation, you only need to put a single property into
+ the
+ <firstterm>project.properties</firstterm>
+ file.
+ </para>
+
+ <figure id="figure-minimum-project-properties">
+ <title>Minimum project.properties file</title>
+
+ <programlisting>dbf.basedir = &lt;path to your DocBook Framework installation&gt;</programlisting>
+ </figure>
+
+ <para>The following additional settings can be changed inside the
+ properties file. Except paper type (see below), these settings normally
+ do not need to be changed:
+ </para>
+
+ <table id="table-docbook-framework-properties">
+ <title>DocBook Framework properties</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>property name</entry>
+
+ <entry>default value</entry>
+
+ <entry>property function</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>
+ <literal>paper.type</literal>
+ </entry>
+
+ <entry>
+ <literal>Letter</literal>
+ </entry>
+
+ <entry>Paper output size for PDF docs</entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>src.dir</literal>
+ </entry>
+
+ <entry>
+ <literal>${basedir}/src</literal>
+ </entry>
+
+ <entry>docbook and related sources dir</entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>style.src.dir</literal>
+ </entry>
+
+ <entry>
+ <literal>${src.dir}/styles</literal>
+ </entry>
+
+ <entry>custom styles directory</entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>docbook.src.dir</literal>
+ </entry>
+
+ <entry>
+ <literal>${src.dir}/docbook</literal>
+ </entry>
+
+ <entry>docbook files directory</entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>images.src.dir</literal>
+ </entry>
+
+ <entry>
+ <literal>${src.dir}/images</literal>
+ </entry>
+
+ <entry>images location</entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>css.src.dir</literal>
+ </entry>
+
+ <entry>
+ <literal>${src.dir}/css</literal>
+ </entry>
+
+ <entry>css files location</entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>target.dir</literal>
+ </entry>
+
+ <entry>
+ <literal>${basedir}/target</literal>
+ </entry>
+
+ <entry>output directory</entry>
+ </row>
+
+ <row>
+ <entry>
+ <literal>tmp.dir</literal>
+ </entry>
+
+ <entry>
+ <literal>${target.dir}/tmp</literal>
+ </entry>
+
+ <entry>temporary files location</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>If you do not want to use an absolute location for the
+ <literal>dbf.basedir</literal>
+ property (e.g. because you want to check
+ the documentation into a version control system and do not want to
+ update the file all the time depending on who checks this file out
+ where), you can put the DocBook Framework in a subdirectory of your
+ documentation.
+ </para>
+
+ <para>If you use Subversion, you can even use the
+ <literal>svn:externals</literal>
+ setting to do this
+ automatically:
+ </para>
+
+ <para>Add the following line to the
+ <literal>svn:externals</literal>
+ property of your documentation root
+ </para>
+
+ <programlisting>docbook http://svn.apache.org/repos/asf/velocity/docbook/trunk</programlisting>
+
+ <para>and use the following
+ <literal>dbf.basedir</literal>
+ setting
+ <footnote>
+ <para>This also ensures that everytime you check out your
+ documentation, you will get the lastest version of the DocBook
+ Framework.
+ </para>
+ </footnote>
+ :
+ </para>
+
+ <programlisting>dbf.basedir = ${basedir}/docbook</programlisting>
+
+ <?hard-pagebreak ?>
+
+ <para>To render your documentation files, you should write a simple ant
+ build file which calls the framework using the
+ <literal>docbook.dir</literal>
+ and<literal>docbook.file
+ properties</literal>. If your docbook file is located in
+ <literal>src/docbook/manual/ToolManual.xml</literal>, your ant build
+ file looks like this:
+ </para>
+
+ <figure id="figure-sample-ant-build-file">
+ <title>Sample ant build file for rendering documentation</title>
+
+ <programlisting>&lt;project name="dbf-docbook" default="all" basedir="."&gt;
+
+ &lt;property file="project.properties"/&gt;
+
+ &lt;target name="all" description="Build documentation"&gt;
+ &lt;ant antfile="${dbf.basedir}/build-docbook.xml" target="all"&gt;
+ &lt;property name="docbook.dir" value="manual"/&gt;
+ &lt;property name="docbook.file" value="ToolManual"/&gt;
+ &lt;/ant&gt;
+ &lt;/target&gt;
+
+ &lt;/project&gt;</programlisting>
+ </figure>
+
+ <para>The resulting documentation file will be located in subdirectories
+ of the<literal>target/manual</literal>directory.
+ </para>
+ </section>
+
+ <section id="section-writing-your-documentation">
+ <title>Writing your documentation</title>
+
+ <para>Your DocBook source files normally reside in subdirectories below
+ the<literal>src/docbook</literal>folder. Each document has its own
+ folder that is referenced through the
+ <literal>docbook.dir</literal>
+ property as shown above.
+ </para>
+
+ <para>In the example above, running
+ <literal>ant all</literal>
+ (or just
+ <literal>ant</literal>) will build all the documentation formats for the
+ ToolManual DocBook file.
+ </para>
+
+ <table id="default-formats-built-in">
+ <title>Default formats built by the DocBook Framework</title>
+
+ <tgroup cols="2">
+ <tbody>
+ <row>
+ <entry>pdf</entry>
+
+ <entry>Adobe PDF format</entry>
+ </row>
+
+ <row>
+ <entry>html</entry>
+
+ <entry>Multiple HTML files, one file for each section</entry>
+ </row>
+
+ <row>
+ <entry>htmlsingle</entry>
+
+ <entry>One big HTML file</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Both of the HTML format directories will also contain a Zip file
+ suitable for distribution, which contains all HTML files, images and
+ optional CSS files.
+ </para>
+ </section>
+
+ <?hard-pagebreak ?>
+
+ <section id="section-notes">
+ <title>Notes</title>
+
+ <section id="section-changing-the-paper-size">
+ <title>Changing the paper size</title>
+
+ <para>The DocBook Framework renders the pages of the PDF output by
+ default in
+ <emphasis>US Letter</emphasis>
+ format (8.5 x 11 inches).
+ This allows printing the resulting PDF in both Letter and A4
+ format.
+ </para>
+
+ <para>If you want to reformat the PDF documentation in A4, you can use
+ the
+ <literal>paper.type</literal>
+ property when invoking ant or by
+ setting it permanently in the
+ <literal>project.properties</literal>
+ file.
+ </para>
+
+ <figure id="figure-rendering-in-a4">
+ <title>Rendering documentation in A4 format</title>
+
+ <programlisting>ant -Dpaper.type=A4 will render the documentation in A4.</programlisting>
+ </figure>
+ </section>
+
+ <section id="section-referencing-images">
+ <title>Referencing images</title>
+
+ <para>While the docbook files are located in their respective
+ subdirectories below<literal>src/docbook</literal>, your
+ image files should be put into the
+ <literal>src/images</literal>
+ directory.
+ </para>
+
+ <para>When writing documentation, images are referenced as
+ <literal>images/&lt;your image file name here&gt;</literal>
+ because
+ this is where they will end up when rendering your
+ documentation.
+ </para>
+
+ <warning>
+ <para>If your DocBook writing tool does not allow you to specify
+ image locations, it might not be able to locate the images from
+ <literal>src/images</literal>
+ and just display a broken image
+ symbol. If this concerns you, you can create a symbolic link inside
+ the source directory where your DocBook files reside to the
+ <literal>src/images</literal>
+ directory.
+ </para>
+ </warning>
+ </section>
+
+ <section id="selecting-images-for-inclusion">
+ <title>Selecting images for inclusion</title>
+ <para>By
+ default, all docbook images are included along with the images
+ in the
+ <literal>src/images</literal>
+ directory.
+ </para>
+ <para>To explicitly select images for inclusion, you can
+ create a file which contains inclusion patters for an ant
+ fileset
+ <footnote>
+ <para>see
+ <uri>http://ant.apache.org/manual/CoreTypes/fileset.html</uri>
+ </para>
+ </footnote>
+ . This
+ file must be called
+ <literal>&lt;projectname&gt;.&lt;output-type&gt;_imageincludes.txt</literal>
+ (for example, the html version of the
+ <literal>foo</literal>
+ project would reference
+ <literal>src/docbook/foo/foo.html_imageincludes.txt</literal>)
+ and it must be located in the
+ <literal>src/docbook/&lt;projectname&gt;</literal>
+ directory. This file consists of line delineated file patterns
+ that will be used to match the images to include.
+ </para>
+
+ </section>
+
+ <?hard-pagebreak ?>
+
+ <section id="section-adding-a-new-docbook-file">
+ <title>Adding a new DocBook file to your documentation build</title>
+
+ <para>Create a new subdirectory inside<literal>src/docbook</literal>.
+ This is where your new DocBook document will reside.
+ </para>
+
+ <para>In your documentation ant build file, you must then add a
+ reference to render your new document. To add a DocBook document
+ called
+ <emphasis>NewGuide.xml</emphasis>
+ which has been located in the
+ <literal>guide</literal>
+ subdirectory, see the following
+ example:
+ </para>
+
+ <figure id="figure-adding-new-document">
+ <title>Adding a new DocBook document</title>
+
+ <programlisting>&lt;ant antfile="build-docbook.xml" target="all"&gt;
+ &lt;property name="docbook.dir" value="guide"/&gt;
+ <co id="co-docbook-dir"
+ linkends="ca-docbook-dir"/>
+ &lt;property name="docbook.file" value="NewGuide"/&gt;
+ <co
+ id="co-docbook-file" linkends="ca-docbook-file"/>
+ &lt;/ant&gt;
+ </programlisting>
+ </figure>
+
+ <calloutlist>
+ <callout arearefs="co-docbook-dir" id="ca-docbook-dir">
+ <para>The new DocBook file is located in
+ <literal>src/docbook/guide</literal>.
+ </para>
+ </callout>
+
+ <callout arearefs="co-docbook-file" id="ca-docbook-file">
+ <para>This is the name of the main docbook file
+ <emphasis>WITHOUT</emphasis>
+ the ending. The framework will add
+ <literal>.xml</literal>
+ when opening the DocBook file
+ automatically.
+ </para>
+ </callout>
+ </calloutlist>
+
+ <para>When you add a new document to the framework, you should make
+ sure that it references DocBook DTD files which can be resolved
+ locally. Included are the DTD files for DocBook 4.5, so your document
+ declaration should be
+ </para>
+
+ <figure id="figure-recommended-dtd">
+ <title>Recommended DTD for DocBook documents.</title>
+
+ <programlisting>&lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
+ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"&gt;</programlisting>
+ </figure>
+
+ <para>If you use a different doctype definition, the DocBook Framework
+ will still render your documents, but it will have to connect to the
+ Internet to retrieve the definition files every time you run the build
+ process.
+ </para>
+ </section>
+ </section>
+ </chapter>
+
+ <chapter id="section-how-it-works">
+ <title>Developer information</title>
+
+ <important>
+ <para>First take a look at the
+ <literal>MANIFEST</literal>
+ file in the
+ root directory to get an idea what is in this package and what the
+ various files are supposed to do.
+ </para>
+ </important>
+
+ <section id="section-ant-files">
+ <title>ant files</title>
+
+ <para>The
+ <literal>build.xml</literal>
+ file in your documentation
+ directory contains only the driver targets for rendering the
+ documentation. The actual work is done through targets defined in the
+ <literal>build-docbook.xml</literal>
+ ant file in the DocBook
+ Framework.
+ </para>
+
+ <para>This file normally should not be changed! If you have to, please
+ let us know, so we can incorporate your changes and/or bug fixes into
+ the main distribution.
+ </para>
+
+ <para>
+ <literal>build-docbook.xml</literal>
+ contains three main targets:
+ <literal>pdf</literal>,
+ <literal>html</literal>
+ and
+ <literal>htmlsingle</literal>. Each is responsible for rendering a
+ format. If you want to add another format, please style your new target
+ similar to these.
+ </para>
+
+ <para>All default settings are kept in the
+ <literal>docbook.properties</literal>
+ file in the root directory. There
+ should be no need to change these properties, they can be customized in
+ your project directory by using a
+ <literal>project.properties</literal>
+ file.
+ </para>
+ </section>
+
+ <section id="section-docbook-reference-files">
+ <title>DocBook reference files</title>
+
+ <para>We use the DocBook XML and XSL distribution archives without any
+ changes to them. The reference files are located in the
+ <literal>src/zip</literal>
+ folder and are expanded into the
+ <literal>target/</literal>
+ directory before the rendering
+ process.
+ </para>
+
+ <para>The file names must be reflected in the
+ <literal>docbook.xml.version</literal>
+ and
+ <literal>docbook.xsl.version</literal>
+ properties in the
+ <literal>docbook.properties</literal>
+ file. If you want to use e.g. a
+ newer XSL version, you can put it into
+ <literal>src/zip</literal>
+ and
+ update the
+ <literal>docbook.properties</literal>
+ to reflect this change.
+ Let us know how it works out for you.
+ </para>
+ </section>
+
+ <section id="section-xml-resolver">
+ <title>XML Resolver</title>
+
+ <para>The framework uses the Apache XML commons resolver to avoid
+ accessing the Internet for Catalog files. The resolver is configured
+ through the
+ <literal>CatalogManager.properties</literal>
+ and
+ <literal>xml-catalog.xml</literal>
+ files in the
+ <literal>src/resolver</literal>
+ directory of the distribution.
+ </para>
+
+ <para>If you update e.g. the Docbook XML version, you must also update
+ the catalog file to match the new version. Else the rendering process
+ will have no knowledge of your changes and access the Internet to
+ download the required DTD files.
+ </para>
+ </section>
+
+ <section id="section-docbook-source-files">
+ <title>Docbook Source files</title>
+
+ <para>The sources for each DocBook document to render should be in
+ subdirectories of<literal>src/docbook</literal>. Each document has its
+ own subdirectory and gets rendered separately. Adding a new document is
+ described in the
+ <emphasis>Adding a new DocBook file to your
+ Documentation build
+ </emphasis>
+ note above.
+ </para>
+ </section>
+
+ <section id="section-stylesheets-and-driver-files">
+ <title>Stylesheets and Driver files</title>
+
+ <para>For each of the formats used by the framework, a stylesheet driver
+ file exists in the DocBook Framework in<literal>src/styles</literal>.
+ These files are<literal>pdf.xsl</literal>,
+ <literal>html.xsl</literal>
+ and<literal>htmlsingle.xsl</literal>.
+ </para>
+
+ <para>The driver files are intended to reference the actual style sheet
+ customization and to add some framework specific elements through
+ filtering. This two step process has been chosen because
+ <emphasis>html</emphasis>
+ and
+ <emphasis>htmlsingle</emphasis>
+ are very
+ similar and it makes no sense to maintain two sets of stylesheet
+ customizations that are virtually identical.
+ </para>
+
+ <para>Before usage, these files are copied to
+ <literal>target/tmp</literal>
+ using an ant filter set. This allows you
+ to use the following replacements in the driver files:
+ </para>
+
+ <table id="ant-filter-tokens">
+ <title>ant filter tokens in the stylesheet customization files</title>
+
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Filter token</entry>
+
+ <entry>Default Value</entry>
+
+ <entry>Token function</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>@file.prefix@</entry>
+
+ <entrytbl cols="1">
+ <tbody>
+ <row>
+ <entry>file:// (Unix)</entry>
+ </row>
+
+ <row>
+ <entry>file:/// (Windows)</entry>
+ </row>
+ </tbody>
+ </entrytbl>
+
+ <entry>Prefix for loading a file through the XSL
+ processor.
+ </entry>
+ </row>
+
+ <row>
+ <entry>@docbook.xml@</entry>
+
+ <entry>(computed at runtime)</entry>
+
+ <entry>Location of the DocBook XML files</entry>
+ </row>
+
+ <row>
+ <entry>@docbook.xsl@</entry>
+
+ <entry>(computed at runtime)</entry>
+
+ <entry>Location of the DocBook XSL style sheets</entry>
+ </row>
+
+ <row>
+ <entry>@src.dir@</entry>
+
+ <entry>${basedir}/src</entry>
+
+ <entry>Location of the source files (DocBook, Images
+ etc.)
+ </entry>
+ </row>
+
+ <row>
+ <entry>@tmp.dir@</entry>
+
+ <entry>${basedir}/target/tmp</entry>
+
+ <entry>Directory for temporary (scratch) files</entry>
+ </row>
+
+ <row>
+ <entry>@&lt;type&gt;.target.dir@ (type is pdf for PDF, html for
+ multi-page HTML and htmlsingle for single-page HTML)
+ </entry>
+
+ <entry>(computed at runtime)</entry>
+
+ <entry>Points to the target directory into which the document is
+ rendered
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>Please refer to the provided driver files in
+ <literal>src/styles</literal>
+ in the DocBook Framework on how to use the
+ filter set.
+ </para>
+ </section>
+
+ <section id="section-stylesheet-customizations">
+ <title>StyleSheet customizations</title>
+
+ <para>You can customize the stylesheets used to render the documentation
+ by adding style files to your project.
+ </para>
+
+ <para>The
+ <emphasis>html</emphasis>
+ and
+ <emphasis>htmlsingle</emphasis>
+ render process uses the same set of customizations, so there are only
+ two possible locations, one for PDF and one for HTML.
+ </para>
+
+ <para>The files are located in your project under
+ <literal>src/styles/pdf</literal>
+ and
+ <literal>src/styles/html</literal>
+ respectively. The DocBook Framework only loads a file named
+ <literal>custom.xsl</literal>
+ file from the directory, which in turn can
+ load additional files.
+ </para>
+ </section>
+
+ <section id="section-pdf-stylesheet">
+ <title>PDF StyleSheet information</title>
+
+ <para>In the footer, the
+ <literal>&lt;releaseinfo&gt;</literal>
+ and
+ <literal>&lt;productname&gt;</literal>
+ elements of the DocBook document
+ are displayed. Each document should have these fields defined.
+ </para>
+ </section>
+
+ <section id="section-titlepages">
+ <title>Titlepages</title>
+
+ <para>Similar to the style sheet customizations, the DocBook Framework
+ can use custom title pages when rendering PDF and HTML output.
+ </para>
+
+ <para>The title page format files are also be kept in the
+ <literal>src/styles/html</literal>
+ and
+ <literal>src/styles/pdf</literal>
+ sub-directories of your documentation project. If no custom page is
+ given, a default title page is used.
+ </para>
+ </section>
+ </chapter>
+
+ <chapter id="section-acknowledgements">
+ <title>Acknowledgements</title>
+
+ <para>DocBook is a fairly complex format and using and customizing the XSL
+ style sheets available is not really straightforward. So by googling left
+ and right and looking at other DocBook rendering frameworks that are in
+ the open source, we tried to model similarities and sometimes just copied
+ some of the ideas.
+ </para>
+
+ <para>This DocBook Framework is literally standing on the shoulders of
+ other projects, in particular:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>The DocBook Format</emphasis>
+ by Norman Walsh; (C)
+ 1999-2006 by Norman Walsh, OASIS and O'Reilly, especially all the
+ documentation that is available from
+ <uri>http://www.docbook.org/</uri>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>The DocBook FAQ</emphasis>
+ maintained by Dave Pawson
+ and available from<uri>http://www.dpawson.co.uk/docbook/</uri>. We
+ wouldn't have survived without it.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>DocBook XSL: The Complete Guide</emphasis>
+ by Bob
+ Stayton. This is an invaluable reference to the DocBook style sheets.
+ Find it online at
+ <uri>http://sagehill.net/</uri>
+ or buy the
+ E-book.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>The DocBook Project</emphasis>
+ located at
+ <uri>http://docbook.sourceforge.net/</uri>. They maintain the XSL
+ style sheets used to transform DocBook into other formats and also
+ link to the docbook mailing list archives.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>The Apache XML commons resolver</emphasis>
+ available
+ from
+ <uri>http://xml.apache.org/commons/components/resolver/</uri>
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>The XMLmind XML Editor</emphasis>
+ from XMLMind,
+ available through
+ <uri>http://www.xmlmind.com/xmleditor/</uri>
+ This
+ cross-platform, pure Java editor not only runs well on Linux, Windows
+ and MacOS but also offers DocBook WYSIWYG support and has a free
+ version! And if you pay for it, you get the source code for it
+ too.
+ </para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Ideas on how to render elements, to arrange things and how to do
+ more obscure things like title pages or use CSS to render HTML, we've
+ taken (sometimes literally by cut and paste) from the following
+ projects:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>The Spring Framework documentation</emphasis>. It
+ hooked us on the idea that Velocity should have DocBook documentation,
+ too. Their DocBook framework is really nice, however it proved to be
+ 'not exactly what we were looking for' (see above). Spring is an
+ example on how good documentation makes all the difference between a
+ successful and popular project and 'the others'. Thanks a lot, Spring
+ guys! Download Spring Framework from
+ <uri>http://www.springframework.org/</uri>.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>The "ant and docbook" styler suite</emphasis>
+ by Dawid
+ Weiss, available from
+ <uri>http://www.cs.put.poznan.pl/dweiss/xml/projects/ant-docbook-styler/index.xml</uri>
+ . We stole his CSS style sheet almost verbatim. Thanks a lot,
+ Dawid!
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <emphasis>The Maven sdocbook plugin</emphasis>
+ by Siegfried
+ Goeschl, Per Olesen and Carlos Sanchez, available at the SourceForge
+ Maven plugin page at
+ <uri>http://maven-plugins.sourceforge.net/maven-sdocbook-plugin/</uri>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </chapter>
+</book>
BIN  docs/src/images/logo.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
58 docs/src/styles/html/custom.xsl
@@ -0,0 +1,58 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ version='1.0'>
+
+ <!-- Activate Graphics -->
+ <xsl:param name="admon.graphics" select="1"/>
+ <xsl:param name="admon.graphics.path">images/</xsl:param>
+ <xsl:param name="admon.graphics.extension">.gif</xsl:param>
+ <xsl:param name="callout.graphics" select="1"/>
+ <xsl:param name="callout.graphics.path">images/callouts/</xsl:param>
+ <xsl:param name="callout.graphics.extension">.gif</xsl:param>
+
+ <xsl:param name="table.borders.with.css" select="1"/>
+ <xsl:param name="html.stylesheet">css/stylesheet.css</xsl:param>
+ <xsl:param name="html.stylesheet.type">text/css</xsl:param>
+ <xsl:param name="generate.toc">book toc,title</xsl:param>
+
+ <xsl:param name="admonition.title.properties">text-align: left</xsl:param>
+
+ <!-- Label Chapters and Sections (numbering) -->
+ <xsl:param name="chapter.autolabel" select="1"/>
+ <xsl:param name="section.autolabel" select="1"/>
+ <xsl:param name="section.autolabel.max.depth" select="1"/>
+
+ <xsl:param name="section.label.includes.component.label" select="1"/>
+ <xsl:param name="table.footnote.number.format" select="'1'"/>
+
+ <!-- Remove "Chapter" from the Chapter titles... -->
+ <xsl:param name="local.l10n.xml" select="document('')"/>
+ <l:i18n xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0">
+ <l:l10n language="en">
+ <l:context name="title-numbered">
+ <l:template name="chapter" text="%n.&#160;%t"/>
+ <l:template name="section" text="%n&#160;%t"/>
+ </l:context>
+ </l:l10n>
+ </l:i18n>
+</xsl:stylesheet>
60 docs/src/styles/html/titlepage.xml
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
+ xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+ <!-- ==================================================================== -->
+
+ <t:titlepage t:element="book" t:wrapper="div" class="titlepage">