Details
-
Task
-
Status: Resolved
-
Major
-
Resolution: Fixed
-
CurrentCVS, 1.10
-
Unix with Doxygen and GraphViz
Description
Building Xalan-C/C++ Interactive API Reference
Extract the "xdocs.tar.gz" file into your source repository snapshot:
(path)/xalan/c/trunk/xdocs
The "xdocs.tar.gz" file contents
xdocs/DoxyfileXalan (The doxygen configuration file)
xdocs/html/apiDocs/
asf_logo_wide.gif (The ASF logo referenced in footer.html)
diagramnotes.html (Unchanged from Xalan-C 1.10)
footer.html (The ASF copyright footer)
header.html (Links to Internet Xalan Web Pages)
header-local.html (Links to local Xalan Web Pages)
These files properly create the Xalan-C/C++ API Reference web pages
for Xalan-C version 1.10 source distribution and 1.11 CurrentSVN
snapshot using current releases of Doxygen and GraphViz.
Make sure you have a current release of Doxygen and GraphViz (dot) programs.
Doxygen is maintained by the software team at http://www.doxygen.org.
GraphViz is maintained by the software team at http://www.graphviz.org.
Debian and RedHat have distribution packages for Doxygen and GraphViz.
The "(path)/xalan/c/trunk/" is actually a relative path commonly used to
hold a private snapshot of the SVN repository. This relative path can
also be that of your previous V.1.10 source code distribution. The API
document construction tools only use directories below this relative
path. The documentation builds do not look into the hidden "*/.svn/"
directories and is therefore safe to use in an SVN repository snapshot.
(See: the INPUT = "path list" in the doxygen configuration file.)
Your source directory structure should look like:
xalan/c/trunk/xdocs/html/apiDocs/
asf_logo_wide.gif (Referenced by: footer.html)
diagramnotes.html (Referenced by: footer.html)
footer.html (See: doxygen HTML_FOOTER parameter)
header.html (See: doxygen HTML_HEADER parameter)
header-local.html (See: doxygen HTML_HEADER parameter)
xalan/c/trunk/xdocs/
DoxyfileXalan (configuration file for doxygen)
xalan/c/trunk/src/xalanc/* (Your source code)
xalan/c/trunk/build/docs/apiDocs/html/
<empty directory>
This is where the API reference manual is created by:
doxygen DoxyfileXalan
xalan/c/trunk/build/docs/html/
This is where the Xalan-C/C++ Web Pages will be created.
These pages are constructed from StyleBook XML markup as a
separate process.
My DoxyfileXalan is configured with doxywizard version 1.7.1 on a
Debian Linux system. Here are some related DoxyfileXalan configuration
file parameters.
The files are actually created to "../build/docs/apiDocs/html/*"
OUTPUT_DIRECTORY = ../build/docs/apiDocs
The program source file directories (See: the DoxyfileXalan for details)
INPUT = ../src/xalanc
The source files used for documentation
FILE_PATTERNS = *.hpp *.h
The HTML Documentation
GENERATE_HTML = YES
The custom HTML header
HTML_HEADER = html/apiDocs/header-local.html
#HTML_HEADER = html/apiDocs/header.html
The custom HTML footer - for ASF copyright
HTML_FOOTER = html/apiDocs/footer.html
Other documentation sets are set to NO, not being generated.
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_XML = NO
Generate graphics with GraphViz (dot) program
HAVE_DOT = YES
Build the Xalan-C/C++ API Reference Manual - Web Pages
$ cd (path)/xalan/c/trunk/xdocs
$ doxygen DoxyfileXalan
Copy the resources used by the footer.html to the doxygen output directory.
$ cp html/apiDocs/asf_logo_wide.gif ../build/docs/apiDocs/html
$ cp html/apiDocs/diagramnotes.html ../build/docs/apiDocs/html
Note: I like to use the following command line to run doxygen, and
then review the error.log for fatal errors. There are lots of warnings.
$ doxygen DoxyfileXalan 2>error.log | tee doxygen.log
Note: The Xalan-C/C++ User Guide and Web Pages are built into
"(path)/xalan/c/trunk/build/docs/html/" <the pages>
Note: The Xalan-C/C++ API Reference manaual HTML pages are built into
"(path)/xalan/c/trunk/build/apiDocs/html/" <the pages>
Note: The Xalan-C/C++ User Guide and Web Pages expect the API located in
"(path)/xalan/c/trunk/build/docs/html/apiDocs/ <the pages>
After creating the Interactive API Reference, move the API web pages
so that they integrate with the Xalan-C/C++ project Web Pages.
$ cd (path)/xalan/c/trunk/build/docs/apiDocs
$ mv html ../html/apiDocs
Now the Xalan-C/C++ project Web Pages can resolve its links using
relative URI addresses of "apiDocs/<name-of-resource>.html".
If the apiDocs are placed elsewhere, then the Xalan-C/C++ project
Web Pages will need to have its links changed.
Note: The "(path)/xalan/c/trunk/build/docs/html" is the root for
the XALANC project web pages. You can work with them locally.
Eventually, the XALANC project will deploy a snapshot of this build
directory to the ASF infrastructure, but only when XALANC version
1.11 is released as a product.
Sincerely,
Steven J. Hathaway