From: dgregor_at_[hidden]
Date: 2008-05-26 13:19:00
Author: dgregor
Date: 2008-05-26 13:19:00 EDT (Mon, 26 May 2008)
New Revision: 45777
URL: http://svn.boost.org/trac/boost/changeset/45777
Log:
tools/build/CMake/BoostDocs.cmake:
- Major cleanup to xsl_transform, simplifying the code and making the
interface more explicit
- Fix handling of dependencies when there are multiple XML input files
(e.g., via XInclude) and for XSL output to a directory.
- Add custom comments to XSL transform rules, for nicer output.
- Use all of these nifty new features in boost_documentation.
libs/function/doc/CMakeLists.txt:
- Add all other XML files to the boost_documentation invocation, to
enable proper dependency tracking.
Text files modified:
branches/CMake/release/libs/function/doc/CMakeLists.txt | 3
branches/CMake/release/libs/function/doc/faq.xml | 2
branches/CMake/release/libs/function/doc/function.xml | 4 +
branches/CMake/release/tools/build/CMake/BoostDocs.cmake | 120 +++++++++++++++++++++++----------------
4 files changed, 78 insertions(+), 51 deletions(-)
Modified: branches/CMake/release/libs/function/doc/CMakeLists.txt
==============================================================================
--- branches/CMake/release/libs/function/doc/CMakeLists.txt (original)
+++ branches/CMake/release/libs/function/doc/CMakeLists.txt 2008-05-26 13:19:00 EDT (Mon, 26 May 2008)
@@ -1 +1,2 @@
-boost_add_documentation(function.xml)
\ No newline at end of file
+boost_add_documentation(function.xml
+ faq.xml history.xml misc.xml reference.xml tests.xml tutorial.xml)
Modified: branches/CMake/release/libs/function/doc/faq.xml
==============================================================================
--- branches/CMake/release/libs/function/doc/faq.xml (original)
+++ branches/CMake/release/libs/function/doc/faq.xml 2008-05-26 13:19:00 EDT (Mon, 26 May 2008)
@@ -144,7 +144,7 @@
<question><para>How much overhead does a call through <code><classname>boost::function</classname></code> incur?</para></question>
<answer>
<para>The cost of <code>boost::function</code> can be reasonably
- consistently measured at around 20ns +/- 10 ns on a modern >2GHz
+ consistently measured at around 20ns +/- 10 ns on a modern >2GHz
platform versus directly inlining the code.</para>
<para>However, the performance of your application may benefit
Modified: branches/CMake/release/libs/function/doc/function.xml
==============================================================================
--- branches/CMake/release/libs/function/doc/function.xml (original)
+++ branches/CMake/release/libs/function/doc/function.xml 2008-05-26 13:19:00 EDT (Mon, 26 May 2008)
@@ -16,6 +16,10 @@
<year>2002</year>
<year>2003</year>
<year>2004</year>
+ <year>2005</year>
+ <year>2006</year>
+ <year>2007</year>
+ <year>2008</year>
<holder>Douglas Gregor</holder>
</copyright>
Modified: branches/CMake/release/tools/build/CMake/BoostDocs.cmake
==============================================================================
--- branches/CMake/release/tools/build/CMake/BoostDocs.cmake (original)
+++ branches/CMake/release/tools/build/CMake/BoostDocs.cmake 2008-05-26 13:19:00 EDT (Mon, 26 May 2008)
@@ -13,45 +13,61 @@
# Transforms the source XML file by applying the given XSL stylesheet.
#
-# xsl_transform(output input stylesheet
-# [DEPENDS depend1 depend2 ...]
+# xsl_transform(output input [input2 input3 ...]
+# STYLESHEET stylesheet
# [CATALOG catalog]
-# [DIRECTORY]
+# [DIRECTORY mainfile]
# [PARAMETERS param1=value1 param2=value2 ...]
-# [[MAKE_ALL_TARGET | MAKE_TARGET] target])
+# [[MAKE_ALL_TARGET | MAKE_TARGET] target]
+# [COMMENT comment])
#
# This macro builds a custom command that transforms an XML file
-# (input) via the given XSL stylesheet. The output is assumed to be an
-# XML file, unless the DIRECTORY option is specified, in which case
-# the output is a directory that will be populated with the results of
-# the XSL transformation. The stylesheet must be a valid XSL
-# stylesheet.
+# (input) via the given XSL stylesheet. The output will either be a
+# single file (the default) or a directory (if the DIRECTION argument
+# is specified). The STYLESBEET stylesheet must be a valid XSL
+# stylesheet. Any extra input files will be used as additional
+# dependencies for the target. For example, these extra input files
+# might refer to other XML files that are included by the input file
+# through XInclude.
#
+# When the XSL transform output is going to a directory, the mainfile
+# argument provides the name of a file that will be generated within
+# the output directory. This file will be used for dependency tracking.
+#
# XML catalogs can be used to remap parts of URIs within the
# stylesheet to other (typically local) entities. To provide an XML
# catalog file, specify the name of the XML catalog file via the
# CATALOG argument. It will be provided to the XSL transform.
-#
+#
# The PARAMETERS argument is followed by param=value pairs that set
-# additional parameters to the XSL stylesheet.
-#
+# additional parameters to the XSL stylesheet. The parameter names
+# that can be used correspond to the <xsl:param> elements within the
+# stylesheet.
+#
# To associate a target name with the result of the XSL
# transformation, use the MAKE_TARGET or MAKE_ALL_TARGET option and
# provide the name of the target. The MAKE_ALL_TARGET option only
# differs from MAKE_TARGET in that MAKE_ALL_TARGET will make the
-# resulting target a part of the default build. Note that a target
-# name is required the DIRECTORY option is specified.
-macro(xsl_transform OUTPUT INPUT STYLESHEET)
+# resulting target a part of the default build.
+#
+# If a COMMENT argument is provided, it will be used as the comment
+# CMake provides when running this XSL transformation. Otherwise, the
+# comment will be "Generating "output" via XSL transformation...".
+macro(xsl_transform OUTPUT INPUT)
parse_arguments(THIS_XSL
- "DEPENDS;CATALOG;MAKE_ALL_TARGET;MAKE_TARGET;PARAMETERS"
- "DIRECTORY"
+ "STYLESHEET;CATALOG;MAKE_ALL_TARGET;MAKE_TARGET;PARAMETERS;DIRECTORY;COMMENT"
+ ""
${ARGN}
)
+ # TODO: Is this the best way to handle catalogs? The alternative is
+ # that we could provide explicit remappings to the xsl_transform
+ # macro, and it could generate a temporary XML catalog file.
if (THIS_XSL_CATALOG)
set(THIS_XSL_CATALOG "XML_CATALOG_FILES=${THIS_XSL_CATALOG}")
endif ()
+ # Translate XSL parameters into a form that xsltproc can use.
set(THIS_XSL_EXTRA_FLAGS)
foreach(PARAM ${THIS_XSL_PARAMETERS})
string(REGEX REPLACE "([^=]*)=([^;]*)" "\\1;\\2"
@@ -62,46 +78,50 @@
--stringparam ${XSL_PARAM_NAME} ${XSL_PARAM_VALUE})
endforeach(PARAM)
+ # If the user didn't provide a comment for this transformation,
+ # create a default one.
+ if(NOT THIS_XSL_COMMENT)
+ set(THIS_XSL_COMMENT "Generating ${OUTPUT} via XSL transformation...")
+ endif()
+
+ # Figure out the actual output file that we tell CMake about
+ # (THIS_XSL_OUTPUT_FILE) and the output file or directory that we
+ # tell xsltproc about (THIS_XSL_OUTPUT).
if (THIS_XSL_DIRECTORY)
- # Run the XSLT processor to do an XML transformation with a
- # directory as output.
- if (THIS_XSL_MAKE_ALL_TARGET)
- add_custom_target(${THIS_XSL_MAKE_ALL_TARGET} ALL
- COMMAND ${THIS_XSL_CATALOG} ${XSLTPROC} ${XSLTPROC_FLAGS}
- ${THIS_XSL_EXTRA_FLAGS} -o ${OUTPUT}/ ${STYLESHEET} ${INPUT}
- DEPENDS ${INPUT})
- elseif (THIS_XSL_MAKE_TARGET)
- add_custom_target(${THIS_XSL_MAKE_TARGET}
- COMMAND ${THIS_XSL_CATALOG} ${XSLTPROC} ${XSLTPROC_FLAGS}
- ${THIS_XSL_EXTRA_FLAGS} -o ${OUTPUT}/ ${STYLESHEET} ${INPUT}
- DEPENDS ${INPUT})
- else()
- message(SEND_ERROR
- "xsl_transform macro invoked with a directory but no target name")
- endif()
+ set(THIS_XSL_OUTPUT_FILE ${OUTPUT}/${THIS_XSL_DIRECTORY})
+ set(THIS_XSL_OUTPUT ${OUTPUT}/)
else()
- # Run the XSLT processor to do an XML transformation with a single
- # file as output.
- add_custom_command(OUTPUT ${OUTPUT}
+ set(THIS_XSL_OUTPUT_FILE ${OUTPUT})
+ set(THIS_XSL_OUTPUT ${OUTPUT})
+ endif()
+
+ if(NOT THIS_XSL_STYLESHEET)
+ message(SEND_ERROR
+ "xsl_transform macro invoked without a STYLESHEET argument")
+ else()
+ # Run the XSLT processor to do the XML transformation.
+ add_custom_command(OUTPUT ${THIS_XSL_OUTPUT_FILE}
COMMAND ${THIS_XSL_CATALOG} ${XSLTPROC} ${XSLTPROC_FLAGS}
- ${THIS_XSL_EXTRA_FLAGS} -o ${OUTPUT} ${STYLESHEET} ${INPUT}
- DEPENDS ${INPUT})
+ ${THIS_XSL_EXTRA_FLAGS} -o ${THIS_XSL_OUTPUT}
+ ${THIS_XSL_STYLESHEET} ${INPUT}
+ COMMENT ${THIS_XSL_COMMENT}
+ DEPENDS ${INPUT} ${THIS_XSL_DEFAULT_ARGS})
# Create a custom target to refer to the result of this
# transformation.
if (THIS_XSL_MAKE_ALL_TARGET)
add_custom_target(${THIS_XSL_MAKE_ALL_TARGET} ALL
- DEPENDS ${OUTPUT})
+ DEPENDS ${THIS_XSL_OUTPUT_FILE})
elseif(THIS_XSL_MAKE_TARGET)
add_custom_target(${THIS_XSL_MAKE_TARGET}
- DEPENDS ${OUTPUT})
+ DEPENDS ${THIS_XSL_OUTPUT_FILE})
endif()
endif()
endmacro(xsl_transform)
macro(boost_add_documentation SOURCE)
parse_arguments(THIS_DOC
- "DEPENDS"
+ ""
""
${ARGN})
@@ -121,11 +141,11 @@
# Transform BoostBook XML into DocBook XML
get_filename_component(SOURCE_FILENAME ${SOURCE} NAME_WE)
set(DOCBOOK_FILE ${SOURCE_FILENAME}.docbook)
- xsl_transform(${DOCBOOK_FILE}
- ${THIS_DOC_SOURCE_PATH}
- ${BOOSTBOOK_XSL_DIR}/docbook.xsl
+ xsl_transform(${DOCBOOK_FILE} ${THIS_DOC_SOURCE_PATH}
+ ${THIS_DOC_DEFAULT_ARGS}
+ STYLESHEET ${BOOSTBOOK_XSL_DIR}/docbook.xsl
CATALOG ${CMAKE_BINARY_DIR}/catalog.xml
- DEPENDS ${THIS_DOC_DEPENDS}
+ COMMENT "Generating DocBook documentation for Boost.${PROJECT_NAME}..."
MAKE_TARGET docbook)
# Transform DocBook into other formats
@@ -136,12 +156,13 @@
xsl_transform(
${CMAKE_CURRENT_BINARY_DIR}/html
${THIS_DOC_SOURCE_PATH}
- ${BOOSTBOOK_XSL_DIR}/html.xsl
+ STYLESHEET ${BOOSTBOOK_XSL_DIR}/html.xsl
CATALOG ${CMAKE_BINARY_DIR}/catalog.xml
- DIRECTORY
+ DIRECTORY HTML.manifest
PARAMETERS admon.graphics.path=images
navig.graphics.path=images
boost.image.src=boost.png
+ COMMENT "Generating HTML documentation for Boost.${PROJECT_NAME}..."
MAKE_ALL_TARGET html)
# Install generated documentation
@@ -156,9 +177,10 @@
xsl_transform(
${CMAKE_CURRENT_BINARY_DIR}/man
${THIS_DOC_SOURCE_PATH}
- ${BOOSTBOOK_XSL_DIR}/manpages.xsl
+ STYLESHEET ${BOOSTBOOK_XSL_DIR}/manpages.xsl
CATALOG ${CMAKE_BINARY_DIR}/catalog.xml
- DIRECTORY
+ DIRECTORY man.manifest
+ COMMENT "Generating man pages for Boost.${PROJECT_NAME}..."
MAKE_ALL_TARGET man)
# Install man pages