Dashboard > iBATIS DataMapper > Home > Frequently Asked Questions > How do I generate PDF and HTML Help files from the latest documentation XML source files in the source control repository
How do I generate PDF and HTML Help files from the latest documentation XML source files in the source control repository
Added by Clinton Begin, last edited by Ted Husted on Sep 15, 2005  (view change)
Labels: 
(None)


Overview

Our documentation relies on XSLT and XSL-FO with DocBook-based XML source files to generate the PDF, HTML, and HTML Help release files. We use NAnt for executing a build process that takes the XML source files and tranforms them into the various outputs.

NOTE: These are installation instructions for the Windows platform.

TIP: See [How do I get read-only access to the source control repository?] to obtain the latest documentation source files.

Dependencies

To build the iBATIS.NET documentation from the latest SVN XML source files, you will first need to download DocBook-XSL, Apache FOP, xsltproc, and NAnt. Additionally, make sure that the Microsoft HTML Help compiler (

hhc.exe
) is installed and can be found on your path.

DocBook-XSL

DocBook-XSL can be downloaded from http://sourceforge.net/projects/docbook/ . Currently, we are using version 1.65.1 to build our documentation. Extract the files to the

\docs\docbook
directory so that the directory structure looks like the following:

\docs
    \docbook
    \common
    \fo
    \html
    \htmlhelp
    \images
    \lib

More information on DocBook and XSLT can be found at http://www.docbook.org/ and http://www.w3.org/TR/xslt .

Apache FOP

To use Apache FOP, you must have Java installed and on your path. Download the binary distribution of Apache FOP from http://xml.apache.org/fop/ . At this time, we are using version 0.20.5 to build our documentation. Extract the files to the

\docs\fop
directory so that the directory structure looks like the following:

\docs
    \fop
    \build
    \conf
    \docs
    \examples
    \lib

You should find an

fop.bat
file in the fop directory.

More information on XSL-FO can be found at http://www.w3.org/TR/xsl/slice6.html#fo-section .

xsltproc

There are a number of xsltproc-related files to download. Go to http://www.zlatkovic.com/pub/libxml/ or to ftp://xmlsoft.org/win32/ to download the following:

  • iconv-1.9.1.win32.zip
  • libxml2-2.6.15.win32.zip
  • libxslt-1.1.12.win32.zip
  • zlib-1.2.1.win32.zip

You will need to extract certain files from those downloaded archive files so that you end up with an xsltproc directory file structure that looks like the following:

\docs
    \xsltproc
    iconv.dll
    libexslt.dll
    libxml2.dll
    libxslt.dll
    xsltproc.exe
    zlib1.dll

More information on xsltproc can be found at http://xmlsoft.org/XSLT/xsltproc2.html or http://www.zlatkovic.com/libxml.en.html .

NAnt

Download and install the latest version of NAnt from http://nant.sourceforge.net/ . Make sure that the Nant executable (nant.bat) can be found on your path (try

nant -help
on the command line).

HTML Help Workshop

If you are using Visual Studio.NET, you may already have the HTML Help Workshop installed. A typical installation would place it in the

C:\Program Files\HTML Help Workshop
directory.

If you do not have the HTML Help Workshop installed, you can install it from your Visual Studio.NET CDs or see http://msdn.microsoft.com/library/en-us/htmlhelp/html/hworiHTMLHelpStartPage.asp for more information on downloading the HTML Help SDK.

Make sure that the HTML Help compiler (hhc.exe) can be found on your path (try

hhc
on the command line).

Build

If everything is in place, you will be able to start the NAnt build process through the command line by simply navigating to the

\docs
directory and entering
nant
. All PDF, HTML, and HTML Help (.chm) output files will be created in a new
\docs\output
directory.

Since NAnt build files provide for various build targets, you can view these targets using

nant -projecthelp
. For example:

  • To generate all documentation, just enter
    nant
    .
  • To generate all DataMapper-specific documentation, enter
    nant -sqlMapDoc
    .
  • To generate all DataAccess-specific documentation, enter
    nant -daoDoc
    .

Site running on a free Atlassian Confluence Open Source Project License granted to OSS. Evaluate Confluence today.
Powered by Atlassian Confluence, the Enterprise Wiki. (Version: 2.5.5 Build:#811 Jul 25, 2007) - Bug/feature request - Contact Administrators