[Boost-commit] svn:boost r45706 - in branches/CMake/release: . libs/function tools/build/CMake

From: dgregor_at_[hidden]
Date: 2008-05-24 01:16:25

Author: dgregor
Date: 2008-05-24 01:16:24 EDT (Sat, 24 May 2008)
New Revision: 45706
URL: http://svn.boost.org/trac/boost/changeset/45706

Log:
Very, very early stab at getting basic support for building HTML and DocBook from BoostBook
Added:
   branches/CMake/release/tools/build/CMake/BoostDocs.cmake   (contents, props changed)
   branches/CMake/release/tools/build/CMake/catalog.xml.in   (contents, props changed)
Text files modified: 
   branches/CMake/release/CMakeLists.txt                    |     1 +                                       
   branches/CMake/release/libs/function/CMakeLists.txt      |     2 +-                                      
   branches/CMake/release/tools/build/CMake/BoostCore.cmake |     8 +++++++-                                
   3 files changed, 9 insertions(+), 2 deletions(-)

Modified: branches/CMake/release/CMakeLists.txt
==============================================================================
--- branches/CMake/release/CMakeLists.txt	(original)
+++ branches/CMake/release/CMakeLists.txt	2008-05-24 01:16:24 EDT (Sat, 24 May 2008)
@@ -43,6 +43,7 @@
 include(BoostUtils)
 include(BoostConfig)
 include(BoostCore)
+include(BoostDocs)
 include(BoostTesting)
 ##########################################################################
 

Modified: branches/CMake/release/libs/function/CMakeLists.txt
==============================================================================
--- branches/CMake/release/libs/function/CMakeLists.txt	(original)
+++ branches/CMake/release/libs/function/CMakeLists.txt	2008-05-24 01:16:24 EDT (Sat, 24 May 2008)
@@ -1 +1 @@
-boost_library_project(Function TESTDIRS test)
+boost_library_project(Function TESTDIRS test DOCDIRS doc)

Modified: branches/CMake/release/tools/build/CMake/BoostCore.cmake
==============================================================================
--- branches/CMake/release/tools/build/CMake/BoostCore.cmake	(original)
+++ branches/CMake/release/tools/build/CMake/BoostCore.cmake	2008-05-24 01:16:24 EDT (Sat, 24 May 2008)
@@ -72,7 +72,7 @@
 #     )
 macro(boost_library_project LIBNAME)
   parse_arguments(THIS_PROJECT
-    "SRCDIRS;TESTDIRS;DESCRIPTION;AUTHORS;MAINTAINERS"
+    "SRCDIRS;TESTDIRS;DOCDIRS;DESCRIPTION;AUTHORS;MAINTAINERS"
     "MODULAR"
     ${ARGN}
     )
@@ -285,6 +285,12 @@
         endforeach(SUBDIR ${THIS_PROJECT_TESTDIRS})
       endif(${BOOST_TEST_LIB_OPTION})
     endif(BUILD_TESTING AND THIS_PROJECT_TESTDIRS)
+
+    if (BUILD_DOCUMENTATION AND THIS_PROJECT_DOCDIRS)
+      foreach(SUBDIR ${THIS_PROJECT_DOCDIRS})
+        add_subdirectory(${SUBDIR})
+      endforeach(SUBDIR)
+    endif ()
   endif(${BOOST_BUILD_LIB_OPTION} AND THIS_PROJECT_OKAY)
 endmacro(boost_library_project)
 

Added: branches/CMake/release/tools/build/CMake/BoostDocs.cmake
==============================================================================
--- (empty file)
+++ branches/CMake/release/tools/build/CMake/BoostDocs.cmake	2008-05-24 01:16:24 EDT (Sat, 24 May 2008)
@@ -0,0 +1,222 @@
+##########################################################################
+# Boost Documentation Generation                                         #
+##########################################################################
+# Copyright (C) 2008 Douglas Gregor <doug.gregor_at_[hidden]>              #
+#                                                                        #
+# Distributed under the Boost Software License, Version 1.0.             #
+# See accompanying file LICENSE_1_0.txt or copy at                       #
+#   http://www.boost.org/LICENSE_1_0.txt                                 #
+##########################################################################
+# Important developer macros in this file:                               #
+#                                                                        #
+##########################################################################
+
+# Transforms the source XML file into the target XML file by applying
+# the given XSL stylesheet.
+#
+#   transform_xml(target source stylesheet
+#                 [DEPENDS depend1 depend2 ...]
+#                 [CATALOG catalog]
+#
+# 
+macro(transform_xml TARGET SOURCE STYLESHEET)
+  parse_arguments(THIS_XSL
+    "DEPENDS;CATALOG"
+    ""
+    ${ARGN}
+    )
+  
+  if (THIS_XSL_CATALOG)
+    set(THIS_XSL_CATALOG "XML_CATALOG_FILES=${THIS_XSL_CATALOG}")
+  endif ()
+
+  # Run the XSLT processor.
+  add_custom_command(OUTPUT ${TARGET}
+    COMMAND ${THIS_XSL_CATALOG} ${XSLTPROC} --xinclude -o ${TARGET} ${STYLESHEET} ${SOURCE}
+    DEPENDS ${SOURCE})
+
+  # set_source_files_properties(${TARGET} PROPERTIES GENERATED TRUE)
+endmacro(transform_xml)
+
+macro(boost_add_documentation SOURCE)
+  parse_arguments(THIS_DOC
+    "DEPENDS"
+    ""
+    ${ARGN})
+
+  # If SOURCE does not have a 
+  get_filename_component(THIS_DOC_SOURCE_PATH ${SOURCE} PATH)
+  if(THIS_DOC_SOURCE_PATH STREQUAL "")
+    set(THIS_DOC_SOURCE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/${SOURCE}")
+  else()
+    set(THIS_DOC_SOURCE_PATH ${SOURCE})
+  endif()
+
+  # Figure out the source file extension, which will tell us how to
+  # build the documentation.
+  get_filename_component(THIS_DOC_EXT ${SOURCE} EXT)
+  string(TOUPPER ${THIS_DOC_EXT} THIS_DOC_EXT)
+  if (THIS_DOC_EXT STREQUAL ".XML")
+    # Transform BoostBook XML into DocBook XML
+    get_filename_component(SOURCE_FILENAME ${SOURCE} NAME_WE)
+    set(DOCBOOK_FILE ${SOURCE_FILENAME}.docbook)
+    transform_xml(${DOCBOOK_FILE}
+      ${THIS_DOC_SOURCE_PATH} 
+      ${BOOSTBOOK_XSL_DIR}/docbook.xsl
+      CATALOG ${CMAKE_BINARY_DIR}/catalog.xml
+      DEPENDS ${THIS_DOC_DEPENDS})
+    add_custom_target(docbook 
+      DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/${DOCBOOK_FILE})
+
+    # Transform DocBook into other formats
+    boost_add_documentation(${CMAKE_CURRENT_BINARY_DIR}/${DOCBOOK_FILE})
+  elseif(THIS_DOC_EXT STREQUAL ".DOCBOOK")
+    add_custom_target(html
+      COMMAND "XML_CATALOG_FILES=${CMAKE_BINARY_DIR}/catalog.xml"
+        ${XSLTPROC} --xinclude -o html/ ${BOOSTBOOK_XSL_DIR}/html.xsl
+        ${THIS_DOC_SOURCE_PATH}
+      DEPENDS ${THIS_DOC_SOURCE_PATH} ${THIS_DOC_DEPENDS})
+  else()
+    message(SEND_ERROR "Unknown documentation source kind ${SOURCE}.")
+  endif()
+endmacro(boost_add_documentation)
+            
+
+##########################################################################
+# Documentation tools configuration                                      #
+##########################################################################
+
+# Downloads the DocBook DTD into a place where DOCBOOK_DTD_DIR can
+# find it.
+macro(download_docbook_dtd)
+  if (NOT DOCBOOK_DTD_DIR)
+    set(DOCBOOK_DTD_FILENAME "docbook-xml-${WANT_DOCBOOK_DTD_VERSION}.zip")
+    set(DOCBOOK_DTD_URL 
+      "http://www.oasis-open.org/docbook/xml/${WANT_DOCBOOK_DTD_VERSION}/${DOCBOOK_DTD_FILENAME}")
+    message(STATUS "Downloading DocBook DTD from ${DOCBOOK_DTD_URL}...")
+    file(DOWNLOAD 
+      "${DOCBOOK_DTD_URL}"
+      "${CMAKE_BINARY_DIR}/${DOCBOOK_DTD_FILENAME}"
+      TIMEOUT 60 STATUS DOCBOOK_DTD_STATUS)
+    list(GET DOCBOOK_DTD_STATUS 0 DOCBOOK_DTD_ERROR)
+    if (DOCBOOK_DTD_ERROR EQUAL 0)
+      # Download successful! Extract the DTD ZIP file.
+      message(STATUS "Extracting DocBook DTD...")
+      execute_process(
+        COMMAND ${UNZIP} -d docbook-dtd-${WANT_DOCBOOK_DTD_VERSION} -q "${CMAKE_BINARY_DIR}/${DOCBOOK_DTD_FILENAME}"
+        WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+        RESULT_VARIABLE UNZIP_DTD_RESULT)
+      if (UNZIP_DTD_RESULT EQUAL 0)
+        # Extraction successful. Cleanup the downloaded file.
+        file(REMOVE ${CMAKE_BINARY_DIR}/${DOCBOOK_DTD_FILENAME})
+        set(DOCBOOK_DTD_DIR 
+          ${CMAKE_BINARY_DIR}/docbook-dtd-${WANT_DOCBOOK_DTD_VERSION}
+          CACHE PATH "Path to the DocBook DTD" FORCE)
+      else()
+        # We failed: report the error to the user
+        message(SEND_ERROR "Extraction of DocBook DTD archive ${DOCBOOK_DTD_FILENAME} failed with error \"${UNZIP_DTD_RESULT}\". DocBook DTD and XSL autoconfiguration cannot continue.")
+      endif ()
+    else()
+    list(GET DOCBOOK_DTD_STATUS 1 DOCBOOK_DTD_ERRORMSG)
+      message(SEND_ERROR "Unable to download DocBook DTD from ${DOCBOOK_DTD_URL}. Error was: \"${DOCBOOK_DTD_ERRORMSG}\"")
+    endif()
+  endif()
+endmacro(download_docbook_dtd)
+
+# Downloads the DocBook XSL into a place where DOCBOOK_XSL_DIR can
+# find it.
+macro(download_docbook_xsl)
+  if (NOT DOCBOOK_XSL_DIR)
+    set(DOCBOOK_XSL_FILENAME "docbook-xsl-${WANT_DOCBOOK_XSL_VERSION}.zip")
+    set(DOCBOOK_XSL_URL 
+      "${SOURCEFORGE_MIRROR}/sourceforge/docbook/${DOCBOOK_XSL_FILENAME}")
+    message(STATUS "Downloading DocBook XSL from ${DOCBOOK_XSL_URL}...")
+    file(DOWNLOAD 
+      "${DOCBOOK_XSL_URL}"
+      "${CMAKE_BINARY_DIR}/${DOCBOOK_XSL_FILENAME}"
+      TIMEOUT 60 STATUS DOCBOOK_XSL_STATUS)
+    list(GET DOCBOOK_XSL_STATUS 0 DOCBOOK_XSL_ERROR)
+    if (DOCBOOK_XSL_ERROR EQUAL 0)
+      # Download successful! Extract the XSL ZIP file.
+      message(STATUS "Extracting DocBook XSL stylesheets...")
+      execute_process(
+        COMMAND ${UNZIP} -q "${CMAKE_BINARY_DIR}/${DOCBOOK_XSL_FILENAME}"
+        WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+        RESULT_VARIABLE UNZIP_XSL_RESULT)
+      if (UNZIP_XSL_RESULT EQUAL 0)
+        # Extraction successful. Clean up the downloaded file.
+        file(REMOVE ${CMAKE_BINARY_DIR}/${DOCBOOK_XSL_FILENAME})
+        set(DOCBOOK_XSL_DIR 
+          ${CMAKE_BINARY_DIR}/docbook-xsl-${WANT_DOCBOOK_XSL_VERSION}
+          CACHE PATH "Path to the DocBook XSL stylesheets" FORCE)       
+      else()
+        # We failed: report the error to the user
+        message(SEND_ERROR "Extraction of DocBook XSL archive ${DOCBOOK_XSL_FILENAME} failed with error \"${UNZIP_XSL_RESULT}\". DocBook XSL and XSL autoconfiguration cannot continue.")
+      endif ()
+    else()
+    list(GET DOCBOOK_XSL_STATUS 1 DOCBOOK_XSL_ERRORMSG)
+      message(SEND_ERROR "Unable to download DocBook XSL from ${DOCBOOK_XSL_URL}. Error was: \"${DOCBOOK_XSL_ERRORMSG}\". You might want to try another SourceForge mirror site by changing the advanced configuration variable SOURCEFORGE_MIRROR.")
+    endif()
+  endif()
+endmacro(download_docbook_xsl)
+
+# Preferred versions of DocBook stylesheets and utilities. We don't
+# require these, but we know that they work.
+set(WANT_DOCBOOK_DTD_VERSION 4.2)
+set(WANT_DOCBOOK_XSL_VERSION 1.73.2)
+
+# Find xsltproc to transform XML documents via XSLT
+find_program(XSLTPROC xsltproc DOC "xsltproc transforms XML via XSLT")
+
+# Find the DocBook DTD (version 4.2)
+find_path(DOCBOOK_DTD_DIR docbookx.dtd
+  PATHS "${CMAKE_BINARY_DIR}/docbook-dtd-${WANT_DOCBOOK_DTD_VERSION}"
+  DOC "Path to the DocBook DTD")
+
+# Find the DocBook XSL stylesheets
+find_path(DOCBOOK_XSL_DIR html/html.xsl
+  PATHS "${CMAKE_BINARY_DIR}/docbook-xsl-${WANT_DOCBOOK_XSL_VERSION}"
+  DOC "Path to the DocBook XSL stylesheets")
+
+# Find the BoostBook DTD (it should be in the distribution!)
+find_path(BOOSTBOOK_DTD_DIR boostbook.dtd
+  PATHS ${CMAKE_SOURCE_DIR}/tools/boostbook/dtd
+  DOC "Path to the BoostBook DTD")
+mark_as_advanced(BOOSTBOOK_DTD_DIR)
+
+# Find the BoostBook XSL stylesheets (they should be in the distribution!)
+find_path(BOOSTBOOK_XSL_DIR docbook.xsl
+  PATHS ${CMAKE_SOURCE_DIR}/tools/boostbook/xsl
+  DOC "Path to the BoostBook XSL stylesheets")
+mark_as_advanced(BOOSTBOOK_XSL_DIR)
+
+if (XSLTPROC)
+  if (DOCBOOK_DTD_DIR AND DOCBOOK_XSL_DIR)
+    # We have all we need for documentation generation.
+    option(BUILD_DOCUMENTATION "Whether to build library documentation" ON)
+
+    # Generate an XML catalog file.
+    configure_file(${CMAKE_SOURCE_DIR}/tools/build/CMake/catalog.xml.in
+      ${CMAKE_BINARY_DIR}/catalog.xml 
+      @ONLY)
+  else()
+    # Look for "unzip", because we'll need to to permit downloading
+    # the DocBook DTD and XSL stylesheets.
+    find_program(UNZIP unzip DOC "Used to extract ZIP archives")
+
+    if (UNZIP)
+      option(DOCBOOK_AUTOCONFIG 
+        "Automatically download and configure DocBook DTD and XSL" OFF)
+      set(SOURCEFORGE_MIRROR "http://dl.sourceforge.net"
+        CACHE STRING "SourceForge mirror used to download DocBook XSL during autoconfiguration")
+      mark_as_advanced(SOURCEFORGE_MIRROR)
+      if (DOCBOOK_AUTOCONFIG)
+        message(STATUS "Initiating DocBook DTD and XSL autoconfiguration...")
+        download_docbook_dtd()
+        download_docbook_xsl()
+      endif (DOCBOOK_AUTOCONFIG)
+    endif()
+  endif()
+endif()
+
+

Added: branches/CMake/release/tools/build/CMake/catalog.xml.in
==============================================================================
--- (empty file)
+++ branches/CMake/release/tools/build/CMake/catalog.xml.in	2008-05-24 01:16:24 EDT (Sat, 24 May 2008)
@@ -0,0 +1,9 @@
+<?xml version="1.0"?>
+<!DOCTYPE catalog 
+  PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
+  "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
+<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
+  <rewriteURI uriStartString="http://www.boost.org/tools/boostbook/dtd/" rewritePrefix="file://@BOOSTBOOK_DTD_DIR@/"/>
+  <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="file://@DOCBOOK_XSL_DIR@/"/>
+  <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.2/" rewritePrefix="file://@DOCBOOK_DTD_DIR@/"/>
+</catalog>