Trademark Logo Xalan-C/C++ Version 1.11
Building The Documents
Apache Foundation Xalan Project Xerces Project Web Consortium Oasis Open

Building The Documents

Our HTML web page construction does not use or require any Java installed or the use of JavaScript.

‌

(top)

The Xalan-C/C++ HTML Documentation

The current Xalan-C/C++ HTML documentation pages are available on our website http://xalan.apache.org/xalan-c.

The HTML documentation pages can be built from the Xalan-C source distribution. Let ${XALANC} indicate the top directory of the source distribution.

   ${XALANC}/src/ = the program library source files
   ${XALANC}/xdocs/ = the program documentation source files
   ${XALANC}/build/docs/ = the directory created for documentation builds
   ${XALANC}/build/docs/apiDocs/html/ = apiDocs created here, then moved
   ${XALANC}/build/docs/xalan-c/ =  the HTML documentation tree

UNIX platforms can build the complete documentation package (web pages plus interactive api reference).

Windows platforms an only build the basic web pages.

‌

(top)

Setup UNIX for Building the Documents

  1. Requires the Xalan executable in the ${PATH} environment.
  2. Requires the libxerces-c.so and libxalan-c.so libraries in a path that is accessible to the Xalan executable.
  3. Requires a current installation of the Doxygen package.
  4. The interactive graphics for apiDocs require the GraphViz (dot) package.
‌

(top)

Build the Documentation on UNIX

  1. Connect to the ${XALANC}/xdocs/ directory.
  2. Run the make-apiDocs.sh (full graphics) or make-apiDocs-nograf.sh (no graphics).
  3. The script automatically chains to sources/make-book.sh for building the remainder of the documentation.
  4. You can now relocate and package the documentation at ${XALANC}/build/docs/xalan-c/ to your final destination of choice.
‌

(top)

Setup WINDOWS for Building the Documents

  1. Create a %XALANC%\bin\ directory. Then copy the xalan.exe and the DLL libraries for xerces-c and xalan-c into that directory. This is where the make-xalan.bat file expects to find the xalan.exe executable.
  2. Connect to the %XALANC%\xdocs\sources\ directory.
  3. Run the make-book.bat script to create the %XALANC%\build\docs\xalan-c\ documentation.
  4. You can now relocate and package the documentation at %XALANC%\build\docs\xalan-c\ to your final destination of choice.
note WINDOWS has no Doxygen program for building the apiDocs. Building apiDocs requires a Linux or UNIX platform. You might be able to use WINDOWS JavaDocs to get an interactive apiDocs reference. The JavaDocs program is part of the Java Developer's platform.

Our documentation does not rely on any Java installation.

‌

(top)

About the StyleBook XML Markup

The obsolete Apache Java Stylebook program is no longer being used. The StyleBook XML markup has been slightly modified to accommodate standard XSLT stylesheet transformations.

A standard stylebook.xslt XML transform stylesheet now allows any standard compliant XSLT processor to prepare the basic webpage documents. The resulting documents are in strict XHTML. The source pages have been adjusted so that compliant XML output mode is used and that transitional web browsers are accommodated.

We also include a DTD library so that the markup source pages can be processed with a validating XML parser. The parser used with the stylebook.xslt stylesheet must accommodate top-level string parameters and the ability to process DTD definitions.

Our stylebook processing scripts currently expect to use the Apache Xalan-C/C++ command-line executable program.

‌

(top)

Source Directory Layout

  ${XALAN}/xdocs/style/dtd/*  -- the validation DTD definitions
  ${XALAN}/xdocs/sources/stylebook.xslt -- the XML StyleBook transform
  ${XALAN}/xdocs/sources/xalan/* -- the StyleBook XML page content
  ${XALAN}/xdocs/sources/xalan-graphic/* -- page specific graphics
  ${XALAN}/xdocs/sources/xslt-resources/* -- logos and css stylesheets
  ${XALAN}/xdocs/sources/xalan.xml  -- the book navigation panel
  ${XALAN}/xdocs/sources/entities.ent -- book XML general entity definitions
  ${XALAN}/xdocs/sources/xalan/resources.xml -- general resource links
  ${XALAN}/build/docs/xalan-c/* -- the StyleBook html transformed pages

The resulting document from stylebook.xslt is strict XHTML with markup rules that can also be supported on transitional browsers. To guard against XML element collapse, we use the Unicode zero-width-non-joining character to provide non-empty content. Element collapse prevention is not handled by the "stylebook.xslt" transform. The Apache Xalan or xalan.exe programs do not should guard against unwanted element collapse.

‌

(top)

Document Building Scripts

  ${XALAN}/xdocs/sources/make-xalan.sh {pagename} -- transform a single page
  ${XALAN}/xdocs/sources/make-xalan.bat {pagename} -- transform a single page

  ${XALAN}/xdocs/sources/make-book.sh -- transform an entire book
  ${XALAN}/xdocs/sources/make-book.bat -- transform an entire book

(top)