velocity-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
Subject svn commit: r520955 - in /velocity/docbook/trunk: LICENSE LICENSE.txt MANIFEST NOTICE README TODO lib/LICENSES src/docbook/ src/images/ xml-catalog.xml
Date Wed, 21 Mar 2007 17:35:16 GMT
Author: henning
Date: Wed Mar 21 10:35:14 2007
New Revision: 520955

Remove superflous files and directories. Update docs and MANIFEST.

      - copied unchanged from r520944, velocity/docbook/trunk/LICENSE.txt

Modified: velocity/docbook/trunk/MANIFEST
--- velocity/docbook/trunk/MANIFEST (original)
+++ velocity/docbook/trunk/MANIFEST Wed Mar 21 10:35:14 2007
@@ -14,18 +14,19 @@
 README.FIRST                            - Important Information about PDF rendering!
 README                                  - Documentation Overview
+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
-build.xml                               - frontend build file for the documentation                      - project settings                      - Default values for all settings.               - Configuration file for xml commons resolver
-xml-catalog.xml                         - Catalog file for xml commons resolver
-src/images                              - User images (e.g. Project logo)
-src/docbook                             - Docbook files to transform
+src/resources/ - 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

Modified: velocity/docbook/trunk/NOTICE
--- velocity/docbook/trunk/NOTICE (original)
+++ velocity/docbook/trunk/NOTICE Wed Mar 21 10:35:14 2007
@@ -5,4 +5,8 @@
 This product includes software developed at
 The Apache Software Foundation (
+This product includes software developed by
+M.H.Kay ( and distributed under

Modified: velocity/docbook/trunk/README
--- velocity/docbook/trunk/README (original)
+++ velocity/docbook/trunk/README Wed Mar 21 10:35:14 2007
@@ -3,23 +3,23 @@
 This project started out as a framework to render documentation for
-the Velocity project ( and ended
-somehow up to be a generic framework to render DocBook documents using
-Java and driven by ant.
+the Velocity project ( and ended somehow
+up to be a generic framework to render DocBook documents using Java
+and driven by ant.
 While DocBook format seems to be ubiquitous these days, to my surprise
 there were not many generic frameworks around that could render all
 kinds of formats using Java and be easily customizable. 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 Velocity project wasn't easy, so at some point, we decided
-to redo this (almost) from scratch.
+needs of the Velocity project wasn't easy, so at some point, we
+decided to redo this (almost) from scratch.
 License Information
-Copyright 2006 The Apache Software Foundation.
+Copyright 2006-2007 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.
@@ -37,10 +37,10 @@
 Author information
-This framework and documentation was written by the Jakarta Velocity
+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 Jakarta Velocity Development Mailing
-list at
+please contact us through the Apache Velocity Development Mailing
+list at
 Why another framework for rendering docbook?
@@ -95,19 +95,129 @@
 * Apache Ant version 1.6 or better. The build script uses the macrodef
   task which was introduced in ant 1.6. Get it from
+* The Sun JAI libraries. Please see README.FIRST on how to get and install
+  these.
 Everything else should be included in this package.
-How it is used
+Caveat Emptor
+This framework has been written for the Velocity documentation and we
+also tried to do a reasonably good job in documentating it. However,
+the last and final word is in the Subversion repository at
+and the reference on how to setup and build documentation is the 
+Velocity documentation at 
+If in doubt, please check there on how the framework is used.
+How to set up your documentation repository
+All files that are part of your documentation can be located
+completely separate from the framework.
+This is the recommended layout of your documentation:
+--+---- build.xml          - ant build file
+  +---- - custom settings for your build
+  |
+  +-- src 
+       |
+       +-- docbook         - Docbook sources
+       |
+       +-- styles
+       |     |
+       |     +-- pdf       - Custom styles for PDF
+       |     |
+       |     +-- html      - Custom styles for HTML
+       |
+       +-- css
+       |    |
+       |    +-- html       - CSS files for HTML
+       |
+       +-- images          - Image files for PDF/HTML
+Configuring your documentation repository
+Unless you want to change the default settings for building the
+documentation, you need to add only a single property to the file:
+dbf.basedir = <absolute path to your docbook framework installation>
+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.
+paper.type      | Letter             | Paper output size for PDF docs
+src.dir         | ${basedir}/src     | docbook and related sources dir
+style.src.dir   | ${src.dir}/styles  | custom styles directory
+docbook.src.dir | ${src.dir}/docbook | docbook files directory
+images.src.dir  | ${src.dir}/images  | images location
+css.src.dir     | ${src.dir}/css     | css files location
+target.dir      | ${basedir}/target  | output directory
+tmp.dir         | ${target.dir}/tmp  | temporary files location
+If you do not want to use an absolute location for the dbf.basedir
+(e.g. because you want to check the documentation into a version
+control system and do not want to modify according to the check out
+location), you can put the docbook framework in a subdirectory of your
+documentation. If you use Subversion, you can even use the
+svn:externals setting to do this automatically:
+Add the following line to the svn:externals property of your
+documentation root:
+use the following dbf.basedir setting:
+dbf.basedir = ${basedir}/docbook
+This also ensures that everytime you check out your documentation, you
+will get the lastest version of the docbook framework.
+To render your docs, you must write a simple ant build file which calls the
+framework using the docbook.dir and docbook.file properties. If your
+docbook file is e.g. located in src/docbook/manual/ToolManual.xml, you
+call the docbook framework like this:
+<ant antfile="${dbf.basedir}/build-docbook.xml" target="all">
+  <property name="docbook.dir" value="manual"/>
+  <property name="docbook.file" value="ToolManual"/>
-The documents to render are located in src/docbook. Here you find
-subdirectories and each subdirectory contains one set of docbook files.
+The resulting docs will be located in subdirectories in target/manual.
+Writing your documentation
+The documents to render must be located in src/docbook.
+If you call the docbook framework from ant as shown above, it builds
+for each source file a number of formats:
-If you run ant in the base directory of this distribution, it should
-build a target directory in target/ for each directory in
-src/docbook. In each of the directories, you'll find three
-subdirectories: pdf, html and htmlsingle.
 pdf:		PDF format. 
 html:		Multiple HTML files, one for each section.
@@ -139,7 +249,7 @@
 'images/<yourimage>>' because this is where they will end up during
 the render process.
-In the main build.xml file, you must add a call to the framework for
+In the custom build.xml file, you must add a call to the framework for
 your new document. E.g. this is for the Velocity Users guide:
 <ant antfile="build-docbook.xml" target="all">
@@ -174,17 +284,20 @@
 ant files
-The build.xml file contains only the driver targets for rendering the
-documentation. The actual work is done through targets defined in
-build-docbook.xml. This file normally should not be changed; if you
-have to, please let the developers know, so we can incorporate your
-changes and or bug fixes into the main distribution.
+The build.xml file in your documentation directory contains only the
+driver targets for rendering the documentation. The actual work is
+done through targets defined in build-docbook.xml in the docbook
+This file normally should not be changed; if you have to, please let
+the developers know, so we can incorporate your changes and or bug
+fixes into the main distribution.
 build-docbook.xml contains three main targets: pdf, html and
 htmlsingle. Each is responsible for rendering one format.
-Most settings are done in the file and there should
-be no need to change these properties.
+All default settings are done in the file and there
+should be no need to change these properties.
 DocBook reference files
@@ -224,8 +337,8 @@
 For each of the formats used by the framework, a stylesheet driver
-file exists in src/styles. These files are pdf.xsl, html.xsl and
+file exists in the docbook framework in src/styles. These files are
+pdf.xsl, html.xsl and htmlsingle.xsl.
 The driver files are intended to reference the actual style sheet
 customization and to add some framework specific elements through
@@ -255,20 +368,21 @@
                        to the target directory into which the document
                        is rendered.
-Please note, that *only* the driver file is filtered! If you have path
-adjustments to make, you must do them in the driver file!
-Please look at the provided driver files in src/styles on how to use
-the filter set.
+Please look at the provided driver files in src/styles in the docbook
+framework on how to use the filter set.
 StyleSheet customizations
-These customizations are located in subdirectories in
-src/styles. Currently there are only two: pdf and html (html and
-htmlsingle use the same set of customizations). They are referenced
-from the driver files as src/styles/<subdirectory>/custom.xsl.
+You can customize the stylesheets used to render the documentation by adding
+style files to your project.
+The html and htmlsingle rendering use the same set of customizations,
+so there are only two possible locations, for PDF and HTML. The files
+are located in your project under src/styles/pdf and src/styles/html
+respectively. The docbook framework only loads the custom.xsl file
+from the directory, which in turn could load additional files.
 PDF StyleSheet information
@@ -282,31 +396,13 @@
-PDF and HTML use custom title pages. These are located in the
-respecting src/styles subdirectories as titlepage.xml template
-definitions. The build process renders these files using the DocBook
-XSL template/titlepage.xsl Stylesheet into the target/tmp/ directory
-as <type>-titlepage.xsl (e.g. target/tmp/pdf-titlepage.xsl). This
-style sheet then must be included in the style sheet driver file (see
-the driver files in src/styles, e.g. pdf.xsl).
-The current titlepage reference a project logo which must be located
-as 'logo.png' in the src/images directory. It gets rendered on both
-the HTML and PDF title pages.
-There is support for a CSS file in the html and htmlsingle render
-process. This file is defined in the HTML customization file
-(src/styles/html/custom.xsl) and must be located in the src/css/html
-directory. It is copied into a css subdirectory in the target and must
-be referenced as css/<filename>. See the HTML customization file and
-the build-docbook.xml on how this is done.
+Simlar to the style sheet customizations, the docbook framework can
+also use custom title pages when rendering PDF and HTML.
+These files should also be kept in the src/styles/html and
+src/styles/pdf directories in your documentation source.
-Currently, only a single style sheet is supported for both html and
+If no custom page is given, the default title page is used.
@@ -340,15 +436,15 @@
 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, I've taken
-(sometimes literally by cut'n'paste) from
+obscure things like title pages or use CSS to render HTML, we've taken
+(sometimes literally by cut and paste) from
 * The Spring Framework documentation. This is how we got hooked on the
   idea that Velocity should have DocBook documentation, too. Their
-  DocBook framework is really nice, however for my needs it proved to
-  be 'not exactly what we was looking for' (see above).
+  DocBook framework is really nice, however for our needs it proved to
+  be 'not exactly what we were looking for' (see above).
-  Spring is IMHO an example that good documentation makes all the
+  Spring is an example that good documentation makes all the
   difference between a successful and popular project and 'the
   others'. Thanks a lot, Spring guys!

Modified: velocity/docbook/trunk/TODO
--- velocity/docbook/trunk/TODO (original)
+++ velocity/docbook/trunk/TODO Wed Mar 21 10:35:14 2007
@@ -24,3 +24,5 @@
 * 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.

View raw message