Boost-Commit :

Date view	Thread view	Subject view	Author view

From: dgregor_at_[hidden]
Date: 2008-05-26 13:19:00

Next message: grafikrobot_at_[hidden]: "[Boost-commit] svn:boost r45778 - trunk/tools/regression/xsl_reports"
Previous message: boost_at_[hidden]: "[Boost-commit] svn:boost r45776 - in sandbox/units: boost/units libs/units/example"

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

Next message: grafikrobot_at_[hidden]: "[Boost-commit] svn:boost r45778 - trunk/tools/regression/xsl_reports"
Previous message: boost_at_[hidden]: "[Boost-commit] svn:boost r45776 - in sandbox/units: boost/units libs/units/example"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk