xdocs/sources/xalan/builddocs.xml

<?xml version="1.0" standalone="no"?>  
<!--
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the  "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->

<!DOCTYPE s1 SYSTEM "../../style/dtd/document.dtd">
<s1 title="Building The Documents">
<ul>
<li><link anchor="thedocs">The Xalan-C/C++ HTML Documentation</link></li>
<li><link anchor="unixsetup">Setup UNIX for Building the Documents</link></li>
  <ul>
  <li><link anchor="unixdocbld">Build the Documentation on UNIX</link></li>
  </ul>
<li><link anchor="winsetup">Setup WINDOWS for Building the Documents</link></li>
<li><link anchor="aboutstylebook">About the StyleBook XML Markup</link></li>
  <ul>
  <li><link anchor="sb_dirlayout">Source Directory Layout</link></li>
  <li><link anchor="sb_scripts">Document Building Scripts</link></li>
  </ul>
</ul>
<p>Our HTML web page construction does not use or require
any Java installed or the use of JavaScript.</p>
<!-- END OF TOP-PAGE NAVIGAITON -->
<anchor name="thedocs"/>
<s2 title="The Xalan-C/C++ HTML Documentation">
<p>The current Xalan-C/C++ HTML documentation pages are available on our website
   <jump href="http://xalan.apache.org/xalan-c/index.html">
   http://xalan.apache.org/xalan-c</jump>.</p>
<p>The HTML documentation pages can be built from the Xalan-C
source distribution.  Let <code>${XALANC}</code> indicate the top directory
of the source distribution.</p>
<source>
   ${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
</source>
<p>UNIX platforms can build the complete documentation package (web pages plus
interactive api reference).</p>
<p> Windows platforms an only build the basic web pages.</p>
</s2>
<anchor name="unixsetup"/>
<s2 title="Setup UNIX for Building the Documents">
<ol>
<li>Requires the <code><em>Xalan</em></code> executable in the <code>${PATH}</code> environment.</li>
<li>Requires the <code><em>libxerces-c.so</em></code> and 
    <code><em>libxalan-c.so</em></code> libraries in a path
   that is accessible to the <code><em>Xalan</em></code> executable.</li>
<li>Requires a current installation of the 
    <jump href="http://www.doxygen.org">Doxygen</jump> package.</li>
<li>The interactive graphics for apiDocs require the 
    <jump href="http://www.graphviz.org">GraphViz</jump> (dot) package.</li>
</ol>
<anchor name="unixdocbld"/>
<s3 title="Build the Documentation on UNIX">
<ol>
<li>Connect to the <code>${XALANC}/xdocs/</code> directory.</li>
<li>Run the <code><em>make-apiDocs.sh</em></code> (full graphics) or 
    <code><em>make-apiDocs-nograf.sh</em></code> (no graphics).</li>
<li>The script automatically chains to <code><em>sources/make-book.sh</em></code>
   for building the remainder of the documentation.</li>
<li>You can now relocate and package the documentation at
   <code>${XALANC}/build/docs/xalan-c/</code>
   to your final destination of choice.</li>
</ol>
</s3>
</s2>
<anchor name="winsetup"/>
<s2 title="Setup WINDOWS for Building the Documents">
<ol>
<li>Create a <code>%XALANC%\bin\</code> directory. Then copy the 
  <code><em>xalan.exe</em></code> and the DLL
   libraries for xerces-c and xalan-c into that directory.  This is where
   the <code><em>make-xalan.bat</em></code> file expects to find the 
   <code><em>xalan.exe</em></code> executable.</li>

<li>Connect to the <code>%XALANC%\xdocs\sources\</code> directory.</li>

<li>Run the <code><em>make-book.bat</em></code> script to create 
   the <code>%XALANC%\build\docs\xalan-c\</code> documentation.</li>

<li>You can now relocate and package the documentation at
   <code>%XALANC%\build\docs\xalan-c\</code> to your final destination of choice.</li>
</ol>
<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.</note>
<p>Our documentation does not rely on any Java installation.</p>
</s2>
<anchor name="aboutstylebook"/>
<s2 title="About the StyleBook XML Markup">
<p>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.</p>
<p>A standard <code><em>stylebook.xslt</em></code> 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.</p>
<p>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 <code><em>stylebook.xslt</em></code> stylesheet
must accommodate top-level string parameters and the ability to
process DTD definitions.</p>
<p>Our stylebook processing scripts currently expect to use the
Apache Xalan-C/C++ command-line executable program.</p>

<anchor name="sb_dirlayout"/>
<s3 title="Source Directory Layout">
<source>
  ${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
</source>
<p>The resulting document from <code><em>stylebook.xslt</em></code> 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 <code>Xalan</code> or <code>xalan.exe</code> programs do not
should guard against unwanted element collapse.</p>
</s3>
<anchor name="sb_scripts"/>
<s3 title="Document Building Scripts">
<source>
  ${XALAN}/xdocs/sources/make-xalan.sh {pagename} -- transform a single page
  ${XALAN}/xdocs/sources/make-xalan.bat {pagename} -- transform a single page
</source><source>
  ${XALAN}/xdocs/sources/make-book.sh -- transform an entire book
  ${XALAN}/xdocs/sources/make-book.bat -- transform an entire book
</source>
</s3>
</s2>
</s1>