XalanC
  1. XalanC
  2. XALANC-713

Build Xalan-C/C++ API Reference Manal Using Doxygen 1.7 or newer

    Details

    • Type: Task Task
    • Status: Resolved
    • Priority: Major Major
    • Resolution: Fixed
    • Affects Version/s: CurrentCVS, 1.10
    • Fix Version/s: CurrentCVS
    • Component/s: XalanC
    • Labels:
    • Environment:
      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

      1. xalan-api-xdocs.tar.gz
        30 kB
        Steven J. Hathaway

        Activity

          People

          • Assignee:
            Steven J. Hathaway
            Reporter:
            Steven J. Hathaway
          • Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development