[Apache iBATIS Wiki] New: How do I generate PDF and HTML Help files from the latest documentation XML source files in the source control repository?

[ib...@incubator.apache.org]

   Date: 2005-01-15T18:36:01
   Editor: RobertoRabe
   Wiki: Apache iBATIS Wiki
   Page: How do I generate PDF and HTML Help files from the latest documentation XML source files in the source control repository?
   URL: http://wiki.apache.org/ibatis/How do I generate PDF and HTML Help files from the latest documentation XML source files in the source control repository?

   no comment

New Page:

##language:en
= 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 [http://wiki.apache.org/ibatis/How_20do_20I_20get_20read_2donly_20access_20to_20the_20source_20control_20repository_3f "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 {{{\Documentation\docbook}}} directory so that the directory structure looks like the following:

{{{
\Documentation
  \docbook
    \common
    \docbook-dtd
    \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 ==

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 {{{\Documentation\fop}}} directory so that the directory structure looks like the following:

{{{
\Documentation
  \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 
 * libxmlsec-1.2.6.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:

{{{
\Documentation
  \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://www.nant.org/ .  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 {{{\Documentation}}} directory and entering {{{nant}}} .  All PDF, HTML, and HTML Help (.chm) output files will be created in a new {{{\Documenation\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}}} .