# # Copyright (c) 2005 Joćo Abecasis # Copyright (c) 2005 Vladimir Prus # Copyright (c) 2006 Rene Rivera # # 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) # # This toolset defines a generator to translate QuickBook to BoostBook. It can # be used to generate nice (!) user documentation in different formats # (pdf/html/...), from a single text file with simple markup. # # The toolset defines the QUICKBOOK type (file extension 'qbk') and # a QUICKBOOK to XML (BOOSTBOOK) generator. # # # =========================================================================== # Q & A # =========================================================================== # # If you don't know what this is all about, some Q & A will hopefully get you # up to speed with QuickBook and this toolset. # # # What is QuickBook ? # # QuickBook is a WikiWiki style documentation tool geared towards C++ # documentation using simple rules and markup for simple formatting tasks. # QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook # documents are simple text files. A single QuickBook document can # generate a fully linked set of nice HTML and PostScript/PDF documents # complete with images and syntax-colorized source code. # # # Where can I get QuickBook ? # # Quickbook can be found in Boost's repository, under the tools/quickbook # directory it was added there on Jan 2005, some time after the release of # Boost v1.32.0 and has been an integral part of the Boost distribution # since v1.33. # # Here's a link to the SVN repository: # https://svn.boost.org/svn/boost/trunk/tools/quickbook # # And to QuickBook's QuickBook-generated docs: # http://www.boost.org/doc/libs/release/tools/quickbook/index.html # # # How do I use QuickBook and this toolset in my projects ? # # The minimal example is: # # using boostbook ; # import quickbook ; # # boostbook my_docs : my_docs_source.qbk ; # # where my_docs is a target name and my_docs_source.qbk is a QuickBook # file. The documentation format to be generated is determined by the # boostbook toolset. By default html documentation should be generated, # but you should check BoostBook's docs to be sure. # # # What do I need ? # # You should start by setting up the BoostBook toolset. Please refer to # boostbook.jam and the BoostBook documentation for information on how to # do this. # # A QuickBook executable is also needed. The toolset will generate this # executable if it can find the QuickBook sources. The following # directories will be searched: # # BOOST_ROOT/tools/quickbook/ # BOOST_BUILD_PATH/../../quickbook/ # # (BOOST_ROOT and BOOST_BUILD_PATH are environment variables) # # If QuickBook sources are not found the toolset will then try to use # the shell command 'quickbook'. # # # How do I provide a custom QuickBook executable ? # # You may put the following in your user-config.jam or site-config.jam: # # using quickbook : /path/to/quickbook ; # # or, if 'quickbook' can be found in your PATH, # # using quickbook : quickbook ; # # # For convenience three alternatives are tried to get a QuickBook executable: # # 1. If the user points us to the a QuickBook executable, that is used. # # 2. Otherwise, we search for the QuickBook sources and compile QuickBook # using the default toolset. # # 3. As a last resort, we rely on the shell for finding 'quickbook'. # import boostbook ; import "class" : new ; import feature ; import generators ; import toolset ; import type ; import scanner ; import project ; import targets ; import build-system ; import path ; import common ; import errors ; # The one and only QUICKBOOK type! type.register QUICKBOOK : qbk ; # shell command to run QuickBook # targets to build QuickBook from sources. feature.feature : : free ; feature.feature : : free dependency ; feature.feature : : free ; feature.feature : : free ; feature.feature : : free ; # quickbook-binary-generator handles generation of the QuickBook executable, by # marking it as a dependency for QuickBook docs. # # If the user supplied the QuickBook command that will be used. # # Otherwise we search some sensible places for the QuickBook sources and compile # from scratch using the default toolset. # # As a last resort we rely on the shell to find 'quickbook'. # class quickbook-binary-generator : generator { import modules path targets quickbook ; rule run ( project name ? : property-set : sources * : multiple ? ) { quickbook.freeze-config ; # QuickBook invocation command and dependencies. local quickbook-binary = [ modules.peek quickbook : .quickbook-binary ] ; local quickbook-binary-dependencies ; if ! $(quickbook-binary) { # If the QuickBook source directory was found, mark its main target # as a dependency for the current project. Otherwise, try to find # 'quickbook' in user's PATH local quickbook-dir = [ modules.peek quickbook : .quickbook-dir ] ; if $(quickbook-dir) { # Get the main-target in QuickBook directory. local quickbook-main-target = [ targets.resolve-reference $(quickbook-dir) : $(project) ] ; # The first element are actual targets, the second are # properties found in target-id. We do not care about these # since we have passed the id ourselves. quickbook-main-target = [ $(quickbook-main-target[1]).main-target quickbook ] ; quickbook-binary-dependencies = [ $(quickbook-main-target).generate [ $(property-set).propagated ] ] ; # Ignore usage-requirements returned as first element. quickbook-binary-dependencies = $(quickbook-binary-dependencies[2-]) ; # Some toolsets generate extra targets (e.g. RSP). We must mark # all targets as dependencies for the project, but we will only # use the EXE target for quickbook-to-boostbook translation. for local target in $(quickbook-binary-dependencies) { if [ $(target).type ] = EXE { quickbook-binary = [ path.native [ path.join [ $(target).path ] [ $(target).name ] ] ] ; } } } } # Add $(quickbook-binary-dependencies) as a dependency of the current # project and set it as the feature for the # quickbook-to-boostbook rule, below. property-set = [ $(property-set).add-raw $(quickbook-binary-dependencies) $(quickbook-binary) $(quickbook-binary-dependencies) ] ; return [ generator.run $(project) $(name) : $(property-set) : $(sources) : $(multiple) ] ; } } # Define a scanner for tracking QBK include dependencies. # class qbk-scanner : common-scanner { rule pattern ( ) { return "\\[[ ]*include[ ]+([^]]+)\\]" "\\[[ ]*include:[a-zA-Z0-9_]+[ ]+([^]]+)\\]" "\\[[ ]*import[ ]+([^]]+)\\]" ; } } scanner.register qbk-scanner : include ; type.set-scanner QUICKBOOK : qbk-scanner ; # Initialization of toolset. # # Parameters: # command ? -> path to QuickBook executable. # # When command is not supplied toolset will search for QuickBook directory and # compile the executable from source. If that fails we still search the path for # 'quickbook'. # rule init ( command ? # path to the QuickBook executable. ) { if $(command) { if $(.config-frozen) { errors.user-error "quickbook: configuration cannot be changed after it has been used." ; } .command = $(command) ; } } rule freeze-config ( ) { if ! $(.config-frozen) { .config-frozen = true ; # QuickBook invocation command and dependencies. .quickbook-binary = $(.command) ; if $(.quickbook-binary) { # Use user-supplied command. .quickbook-binary = [ common.get-invocation-command quickbook : quickbook : $(.quickbook-binary) ] ; } else { # Search for QuickBook sources in sensible places, like # $(BOOST_ROOT)/tools/quickbook # $(BOOST_BUILD_PATH)/../../quickbook # And build quickbook executable from sources. local boost-root = [ modules.peek : BOOST_ROOT ] ; local boost-build-path = [ build-system.location ] ; if $(boost-root) { .quickbook-dir += [ path.join $(boost-root) tools ] ; } if $(boost-build-path) { .quickbook-dir += $(boost-build-path)/../.. ; } .quickbook-dir = [ path.glob $(.quickbook-dir) : quickbook ] ; # If the QuickBook source directory was found, mark its main target # as a dependency for the current project. Otherwise, try to find # 'quickbook' in user's PATH if $(.quickbook-dir) { .quickbook-dir = [ path.make $(.quickbook-dir[1]) ] ; } else { ECHO "QuickBook warning: The path to the quickbook executable was" ; ECHO " not provided. Additionally, couldn't find QuickBook" ; ECHO " sources searching in" ; ECHO " * BOOST_ROOT/tools/quickbook" ; ECHO " * BOOST_BUILD_PATH/../../quickbook" ; ECHO " Will now try to find a precompiled executable by searching" ; ECHO " the PATH for 'quickbook'." ; ECHO " To disable this warning in the future, or to completely" ; ECHO " avoid compilation of quickbook, you can explicitly set the" ; ECHO " path to a quickbook executable command in user-config.jam" ; ECHO " or site-config.jam with the call" ; ECHO " using quickbook : /path/to/quickbook ;" ; # As a last resort, search for 'quickbook' command in path. Note # that even if the 'quickbook' command is not found, # get-invocation-command will still return 'quickbook' and might # generate an error while generating the virtual-target. .quickbook-binary = [ common.get-invocation-command quickbook : quickbook ] ; } } } } generators.register [ new quickbook-binary-generator quickbook.quickbook-to-boostbook : QUICKBOOK : XML ] ; # shell command to run QuickBook # targets to build QuickBook from sources. toolset.flags quickbook.quickbook-to-boostbook QB-COMMAND ; toolset.flags quickbook.quickbook-to-boostbook QB-DEPENDENCIES ; toolset.flags quickbook.quickbook-to-boostbook INCLUDES ; toolset.flags quickbook.quickbook-to-boostbook QB-DEFINES ; toolset.flags quickbook.quickbook-to-boostbook QB-INDENT ; toolset.flags quickbook.quickbook-to-boostbook QB-LINE-WIDTH ; rule quickbook-to-boostbook ( target : source : properties * ) { # Signal dependency of quickbook sources on # upon invocation of quickbook-to-boostbook. DEPENDS $(target) : [ on $(target) return $(QB-DEPENDENCIES) ] ; } actions quickbook-to-boostbook { "$(QB-COMMAND)" -I"$(INCLUDES)" -D"$(QB-DEFINES)" --indent="$(QB-INDENT)" --linewidth="$(QB-LINE-WIDTH)" --output-file="$(1)" "$(2)" } # Declare a main target to convert a quickbook source into a boostbook XML file. # rule to-boostbook ( target-name : sources * : requirements * : default-build * ) { local project = [ project.current ] ; targets.main-target-alternative [ new typed-target $(target-name) : $(project) : XML : [ targets.main-target-sources $(sources) : $(target-name) ] : [ targets.main-target-requirements $(requirements) : $(project) ] : [ targets.main-target-default-build $(default-build) : $(project) ] ] ; }