Click Docs ========== 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). Click docs makes use of Ant to build the documentation. Project Layout ============== The project consists of the folowing: 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 HowTo Setup the Project ======================= 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 # Docbook XLS project version 1.75.0: http://docbook.sourceforge.net/snapshots/ # XSLTHL syntax highlighter version 2.0.1: http://sourceforge.net/projects/xslthl * Note DBF also ships with Apache FOP, but its an old version which does not support 'soft pagebreaks' (see below). * As of this writing, Docbook-XLS 1.75.0 was not yet available. Instead download the latest snapshot release from: http://docbook.sourceforge.net/snapshots/. The reason for using 1.75.0 is it includes a syntax highlighter package. Download and unzip both the Docbook Framework (DBF) 1.0, Apache FOP 0.95 and Docbook XLS 1.75 (or latest snapshot) somewhere on your computer. Once done set the following properties in the file project.properties: dbf.basedir = directory-where-DBF-is-installed fop.basedir = directory-where-FOP-is-installed click.basedir = directory-where-Click-is-located The following changes must be made to DBF: # Replace the existing docbook-xsl version of DBF with 1.75.0. You can do that by copying docbook-xsl-1.75.0.zip to the DBF folder '/src/zip/'. You can leave docbook-xsl-1.70.0.zip in the folder or remove it if you wish. # Now we need to update DBF to the new Docbook XSL version. To do this open the file '/docbook.properties' and search for the property "dbf.xsl.version". Change its value from '1.70.0' to '1.75.0'. If you are using a snapshot release change the value from '1.70.0' to 'snapshot': dbf.xsl.version = snapshot # Lastly copy the XSLTHL jar (xslthl-2.0.1.jar) to the DBF lib folder. This will provide syntax highlighting of all source code snippet. That's it for setting up the project. Build Click Docs ================ Once the project is setup you can build the Click docs by running the build script: 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: target/click/pdf target/click/html target/click/htmlsingle NOTE: All documentation artifacts will also be copied to the Click folder specified by the property 'click.basedir'. The artifacts will be copied to the folder: '/documentation/docs/user-guide/' Linking to resources ==================== The Click documentation output files (PDF and HTML), will be placed in the folder 'user-guide' of the Click distribution: /documentation/docs/user-guide/pdf /documentation/docs/user-guide/html /documentation/docs/user-guide/htmlsingle When linking to other Click documentation such as 'click-api' and other images, use the relative path and '../../'. For example: This framework uses a single servlet, called ClickServlet Notice we link to ClickServlet using the relative path '../../' since that is where the click-api will be located relative to the user-guide. 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. 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. To add a soft pagebreak we use the following markup: 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. For example:
Hello World 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> <!-- Below we would like to have the description and code listing on the same page, so we add a soft page break of 0.8 inches as shown below --> <?dbfo-need height="0.8in" ?> <para>For example:</para> <programlisting>public class MyPage extends Page { ... } </programlisting> Here there must be at least an 8th of an inch available at the bottom of the page, otherwise the paragraph and program listing will be forced to the next page. For more info see: http://www.sagehill.net/docbookxsl/PageBreaking.html CHANGELOG ========= -------------------------------------------------------------------------------- Added custom syntax highlighting for both HTML and PDF: Changes made to src/styles/html/custom.xml Changes made to src/styles/pdf/custom.xml -------------------------------------------------------------------------------- Replaced JavaScript Syntax Highlighter with XSLTHL[1] which handles both HTML and PDF. [1]: http://sourceforge.net/projects/xslthl -------------------------------------------------------------------------------- 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 --> --------------------------------------------------------------------------------