You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@click.apache.org by sa...@apache.org on 2009/01/18 20:50:29 UTC
svn commit: r735531 - in /incubator/click/trunk/tools/docbook: README.txt
build.xml
Author: sabob
Date: Sun Jan 18 11:50:29 2009
New Revision: 735531
URL: http://svn.apache.org/viewvc?rev=735531&view=rev
Log:
update docbook build process
Modified:
incubator/click/trunk/tools/docbook/README.txt
incubator/click/trunk/tools/docbook/build.xml
Modified: incubator/click/trunk/tools/docbook/README.txt
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/README.txt?rev=735531&r1=735530&r2=735531&view=diff
==============================================================================
--- incubator/click/trunk/tools/docbook/README.txt (original)
+++ incubator/click/trunk/tools/docbook/README.txt Sun Jan 18 11:50:29 2009
@@ -1,107 +1,135 @@
-BEST PRACTICE
-=============
+Click Docs
+==========
-# Soft page break: Add soft breaks before sections and programlisting descriptions
-e.g.
+Click documentation is written in Docbook format, and makes use of the Velocity
+Docbook Framework (DBF) and Apache FOP (FOP) to generate output formats:PDF,
+HTML and HTML (single).
- <?dbfo-need height="2in" ?>
- <section id="section-hello-world">
-
-This will ensure that the <section> will be forced to the next page if less
-than 2 inches available on the current page. This alleviates the problem where
-the section title is displayed at the bottom of the page but the actual content
-only starts on the next page, which looks awkward.
+Click docs makes use of Ant to build the documentation.
-Another example:
- <?dbfo-need height="2in" ?>
- <para>Next we would have a page template:</para>
- <programlisting>
- ...
- </programlisting>
+Project Layout
+==============
-The snippet above will ensure that the paragraph (together with the programlisting)
-will be forced to the next page if less than 2 inches is available. This removes
-the problem where the program listing description is at the bottom of one page
-and the program listing only starts on the next page by itself.
+The project consists of the folowing:
-CHANGELOG
-=========
+build.xml the project build script
+project.properties the project properties
+src/css/html/ contains the HTML stylesheet and Code Syntax Highlighter
+src/docbook/click/ contains the Click Docbook document
+src/images/ contains all the documentation images
+src/style/html/ contains the Docbook HTML transformation rules
+src/style/pdf/ contains the Docbook PDF transformation rules
---------------------------------------------------------------------------------
-Added a Code Syntax Highlighter to HTML generator.
+HowTo Setup the Project
+=======================
-Changes made to docs/src/styles/html/titlepage.xml
- See the section <!-- CLICK HIGHLIGHTER CHANGES START --> in that file
+This project has the following dependencies:
---------------------------------------------------------------------------------
+Ant version 1.7.1: http://ant.apache.org/
+Velocity Docbook Framework (DBF) version 1.0: http://velocity.apache.org/docbook/
+Apache FOP (at least version 0.95): http://xmlgraphics.apache.org/fop/0.95/index.html
-JAI
+Note DBF also ships with Apache FOP, but its an old version which doesn't support
+'soft pagebreaks' (see below) which Click Docs uses extensively.
-install JAI for pdf image rendering from Sun:
+Download and unzip both the Docbook Framework (DBF) 1.0 and Apache FOP 0.95 somewhere
+on your computer. Once done set the following properties in the file
+project.properties:
-https://jai.dev.java.net/binary-builds.html#Stable_builds_1.1.3
+ dbf.basedir = directory-where-DBF-is-installed
+ fop.basedir = directory-where-FOP-is-installed
---------------------------------------------------------------------------------
-Reduced PDF font-size for examples.
+Build Click Docs
+================
-Changes made to
+Once the project is setup you can build the Click docs by running the build script:
-docs/src/styles/pdf/custom.xls
- See the section <!-- CLICK FONT CHANGES START --> in that file
+ ant all
---------------------------------------------------------------------------------
+This command will generate a 'target' folder consisting of a number of subfolders.
+The PDF, HTML and HTML (single) documentation is available at the following locations:
-# Updated to FOP 0.95. Changes needed to be made to
+ target/click/pdf
+ target/click/html
+ target/click/htmlsingle
-build-docbook.xml
- See the section <!-- CLICK FOP 0.95 CHANGES START --> in that file
-docs/src/styles/pdf/custom.xls
- See the section <!-- CLICK FOP 0.95 CHANGES START --> in that file
-
-added new libs:
- batik-all-1.7.jar
- fop.jar
- commons-io.jar
- commons-logging.jar
- xmlgraphics-commons-1.3.1.jar
---------------------------------------------------------------------------------
+Soft pagebreaks
+===============
The generated PDF has a common problem in that there is no control over page
breaks. For example say you have a description and code listing below, the PDF
generator don't care if the description is at the end of the page and the code listing
on the start of the next. However it will be better if the description and code listing
goes together on the same page. Thus the description should be moved to the top of
-the next together with the code listing. One solution is to add a soft break. Here
-one can add some markup which will force a section to break to the next page. A soft
-page break provides a "hint" to the PDF generator to only break to the next page
-upon a certain condition e.g. only break if less than 2inches are left on the page.
+the next together with the code listing. One solution is to add a soft break.
+
+A soft pagebreak provides a hint to the PDF generator to only break to the next page
+upon a certain condition e.g. only break if less than two inches are left on the page.
-Soft breaks provide some protection against further editing of the document at a later
-stage.
+To add a soft pagebreak we use the following markup:
-For pagebreaking use: <?dbfo-need height="2in" ?>
+ <?dbfo-need height="2in" ?>
The above basically states that there should be at least 2 inches left
at the bottom of the page for the content to be added. If more than 2 inches is left,
render the content. If less than 2 inches is available, the page must break and the
content should be moved to the next page.
-e.g:
- <para>Some text in a paragraph</para>
+For example:
+
+ <?dbfo-need height="2in" ?>
+ <section id="section-hello-world">
+ <para>Some content</para>
+
+This will ensure that the <section> will be forced to the next page if less
+than 2 inches are available on the current page. This alleviates the problem where
+the section title is displayed at the bottom of the page but the actual content
+only starts on the next page, which looks awkward.
+
+Another example:
+
+ <para>Some text</para>
- <!-- We would like to have the description and code listing on the same page,
+ <!-- Below we would like to have the description and code listing on the same page,
so we add a soft page break (2 inches) as shown below -->
<?dbfo-need height="2in" ?>
- <para>The following code snippet illustrates the technique.</para>
+ <para>For example:</para>
+ <programlisting>public class MyPage extends Page {
+ ...
+} </programlisting>
- <programlisting># Some sample code</programlisting>
-For further info see:
+For more info see:
http://www.sagehill.net/docbookxsl/PageBreaking.html
---------------------------------------------------------------------------------
\ No newline at end of file
+
+CHANGELOG
+=========
+
+--------------------------------------------------------------------------------
+
+Added a Code Syntax Highlighter for the HTML generator.
+
+Changes made to src/styles/html/titlepage.xml
+See the section <!-- CLICK HIGHLIGHTER CHANGES START -->
+
+--------------------------------------------------------------------------------
+
+Reduced PDF font-size for examples.
+
+Changes made to src/styles/pdf/custom.xls
+See the section <!-- CLICK FONT CHANGES START -->
+
+--------------------------------------------------------------------------------
+
+Upgraded to FOP 0.95.
+
+Changes made to src/styles/pdf/custom.xls
+ See the section <!-- CLICK FOP 0.95 CHANGES START -->
+
+--------------------------------------------------------------------------------
Modified: incubator/click/trunk/tools/docbook/build.xml
URL: http://svn.apache.org/viewvc/incubator/click/trunk/tools/docbook/build.xml?rev=735531&r1=735530&r2=735531&view=diff
==============================================================================
--- incubator/click/trunk/tools/docbook/build.xml (original)
+++ incubator/click/trunk/tools/docbook/build.xml Sun Jan 18 11:50:29 2009
@@ -103,7 +103,10 @@
<taskdef name="fop"
classname="org.apache.fop.tools.anttasks.Fop">
<classpath>
- <fileset dir="${dbf.basedir}/fop-lib">
+ <fileset dir="${fop.basedir}/build">
+ <include name="*.jar"/>
+ </fileset>
+ <fileset dir="${fop.basedir}/lib">
<include name="*.jar"/>
</fileset>
@@ -111,15 +114,6 @@
</taskdef>
<target name="pdf" description="Generates a single PDF file" depends="prepare">
- <available file="${dbf.basedir}/fop-lib/fop.jar" property="isFop095Avail"/>
- <fail message="The ${dbf.basedir}/fop-lib/fop.lib JAR is not available. To resolve this,
-download the FOP 0.95 distribution and add the new jars to the folder ${dbf.basedir}/fop-lib.">
- <condition>
- <or>
- <isfalse value="${isFop095Avail}"/>
- </or>
- </condition>
- </fail>
<transform type="pdf" target="tmp" title="pdf" xsl="fo" dir="${docbook.dir}" file="${docbook.file}"/>