2 # Copyright (c) 2005 João Abecasis
3 # Copyright (c) 2005 Vladimir Prus
4 # Copyright (c) 2006 Rene Rivera
6 # Distributed under the Boost Software License, Version 1.0. (See
7 # accompanying file LICENSE_1_0.txt or copy at
8 # http://www.boost.org/LICENSE_1_0.txt)
11 # This toolset defines a generator to translate QuickBook to BoostBook. It can
12 # be used to generate nice (!) user documentation in different formats
13 # (pdf/html/...), from a single text file with simple markup.
15 # The toolset defines the QUICKBOOK type (file extension 'qbk') and
16 # a QUICKBOOK to XML (BOOSTBOOK) generator.
19 # ===========================================================================
21 # ===========================================================================
23 # If you don't know what this is all about, some Q & A will hopefully get you
24 # up to speed with QuickBook and this toolset.
29 # QuickBook is a WikiWiki style documentation tool geared towards C++
30 # documentation using simple rules and markup for simple formatting tasks.
31 # QuickBook extends the WikiWiki concept. Like the WikiWiki, QuickBook
32 # documents are simple text files. A single QuickBook document can
33 # generate a fully linked set of nice HTML and PostScript/PDF documents
34 # complete with images and syntax-colorized source code.
37 # Where can I get QuickBook ?
39 # Quickbook can be found in Boost's repository, under the tools/quickbook
40 # directory it was added there on Jan 2005, some time after the release of
41 # Boost v1.32.0 and has been an integral part of the Boost distribution
44 # Here's a link to the SVN repository:
45 # https://svn.boost.org/svn/boost/trunk/tools/quickbook
47 # And to QuickBook's QuickBook-generated docs:
48 # http://www.boost.org/doc/libs/release/tools/quickbook/index.html
51 # How do I use QuickBook and this toolset in my projects ?
53 # The minimal example is:
58 # boostbook my_docs : my_docs_source.qbk ;
60 # where my_docs is a target name and my_docs_source.qbk is a QuickBook
61 # file. The documentation format to be generated is determined by the
62 # boostbook toolset. By default html documentation should be generated,
63 # but you should check BoostBook's docs to be sure.
68 # You should start by setting up the BoostBook toolset. Please refer to
69 # boostbook.jam and the BoostBook documentation for information on how to
72 # A QuickBook executable is also needed. The toolset will generate this
73 # executable if it can find the QuickBook sources. The following
74 # directories will be searched:
76 # BOOST_ROOT/tools/quickbook/
77 # BOOST_BUILD_PATH/../../quickbook/
79 # (BOOST_ROOT and BOOST_BUILD_PATH are environment variables)
81 # If QuickBook sources are not found the toolset will then try to use
82 # the shell command 'quickbook'.
85 # How do I provide a custom QuickBook executable ?
87 # You may put the following in your user-config.jam or site-config.jam:
89 # using quickbook : /path/to/quickbook ;
91 # or, if 'quickbook' can be found in your PATH,
93 # using quickbook : quickbook ;
96 # For convenience three alternatives are tried to get a QuickBook executable:
98 # 1. If the user points us to the a QuickBook executable, that is used.
100 # 2. Otherwise, we search for the QuickBook sources and compile QuickBook
101 # using the default toolset.
103 # 3. As a last resort, we rely on the shell for finding 'quickbook'.
107 import "class" : new ;
115 import build-system ;
120 # The one and only QUICKBOOK type!
121 type.register QUICKBOOK : qbk ;
123 # <quickbook-binary> shell command to run QuickBook
124 # <quickbook-binary-dependencies> targets to build QuickBook from sources.
125 feature.feature <quickbook-binary> : : free ;
126 feature.feature <quickbook-binary-dependencies> : : free dependency ;
127 feature.feature <quickbook-define> : : free ;
128 feature.feature <quickbook-indent> : : free ;
129 feature.feature <quickbook-line-width> : : free ;
130 feature.feature <quickbook-strict-mode> : : free ;
133 # quickbook-binary-generator handles generation of the QuickBook executable, by
134 # marking it as a dependency for QuickBook docs.
136 # If the user supplied the QuickBook command that will be used.
138 # Otherwise we search some sensible places for the QuickBook sources and compile
139 # from scratch using the default toolset.
141 # As a last resort we rely on the shell to find 'quickbook'.
143 class quickbook-binary-generator : generator
145 import modules path targets quickbook ;
147 rule run ( project name ? : property-set : sources * : multiple ? )
149 quickbook.freeze-config ;
150 # QuickBook invocation command and dependencies.
151 local quickbook-binary = [ modules.peek quickbook : .quickbook-binary ] ;
152 local quickbook-binary-dependencies ;
154 if ! $(quickbook-binary)
156 # If the QuickBook source directory was found, mark its main target
157 # as a dependency for the current project. Otherwise, try to find
158 # 'quickbook' in user's PATH
159 local quickbook-dir = [ modules.peek quickbook : .quickbook-dir ] ;
162 # Get the main-target in QuickBook directory.
163 local quickbook-main-target = [ targets.resolve-reference $(quickbook-dir) : $(project) ] ;
165 # The first element are actual targets, the second are
166 # properties found in target-id. We do not care about these
167 # since we have passed the id ourselves.
168 quickbook-main-target =
169 [ $(quickbook-main-target[1]).main-target quickbook ] ;
171 quickbook-binary-dependencies =
172 [ $(quickbook-main-target).generate [ $(property-set).propagated ] ] ;
174 # Ignore usage-requirements returned as first element.
175 quickbook-binary-dependencies = $(quickbook-binary-dependencies[2-]) ;
177 # Some toolsets generate extra targets (e.g. RSP). We must mark
178 # all targets as dependencies for the project, but we will only
179 # use the EXE target for quickbook-to-boostbook translation.
180 for local target in $(quickbook-binary-dependencies)
182 if [ $(target).type ] = EXE
196 # Add $(quickbook-binary-dependencies) as a dependency of the current
197 # project and set it as the <quickbook-binary> feature for the
198 # quickbook-to-boostbook rule, below.
199 property-set = [ $(property-set).add-raw
200 <dependency>$(quickbook-binary-dependencies)
201 <quickbook-binary>$(quickbook-binary)
202 <quickbook-binary-dependencies>$(quickbook-binary-dependencies)
205 return [ generator.run $(project) $(name) : $(property-set) : $(sources) : $(multiple) ] ;
210 # Define a scanner for tracking QBK include dependencies.
212 class qbk-scanner : common-scanner
216 return "\\[[ ]*include[ ]+([^]]+)\\]"
217 "\\[[ ]*include:[a-zA-Z0-9_]+[ ]+([^]]+)\\]"
218 "\\[[ ]*import[ ]+([^]]+)\\]" ;
223 scanner.register qbk-scanner : include ;
225 type.set-scanner QUICKBOOK : qbk-scanner ;
228 # Initialization of toolset.
231 # command ? -> path to QuickBook executable.
233 # When command is not supplied toolset will search for QuickBook directory and
234 # compile the executable from source. If that fails we still search the path for
238 command ? # path to the QuickBook executable.
245 errors.user-error "quickbook: configuration cannot be changed after it has been used." ;
247 .command = $(command) ;
251 rule freeze-config ( )
253 if ! $(.config-frozen)
255 .config-frozen = true ;
257 # QuickBook invocation command and dependencies.
259 .quickbook-binary = $(.command) ;
261 if $(.quickbook-binary)
263 # Use user-supplied command.
264 .quickbook-binary = [ common.get-invocation-command quickbook : quickbook : $(.quickbook-binary) ] ;
268 # Search for QuickBook sources in sensible places, like
269 # $(BOOST_ROOT)/tools/quickbook
270 # $(BOOST_BUILD_PATH)/../../quickbook
272 # And build quickbook executable from sources.
274 local boost-root = [ modules.peek : BOOST_ROOT ] ;
275 local boost-build-path = [ build-system.location ] ;
279 .quickbook-dir += [ path.join $(boost-root) tools ] ;
282 if $(boost-build-path)
284 .quickbook-dir += $(boost-build-path)/../.. ;
287 .quickbook-dir = [ path.glob $(.quickbook-dir) : quickbook ] ;
289 # If the QuickBook source directory was found, mark its main target
290 # as a dependency for the current project. Otherwise, try to find
291 # 'quickbook' in user's PATH
294 .quickbook-dir = [ path.make $(.quickbook-dir[1]) ] ;
298 ECHO "QuickBook warning: The path to the quickbook executable was" ;
299 ECHO " not provided. Additionally, couldn't find QuickBook" ;
300 ECHO " sources searching in" ;
301 ECHO " * BOOST_ROOT/tools/quickbook" ;
302 ECHO " * BOOST_BUILD_PATH/../../quickbook" ;
303 ECHO " Will now try to find a precompiled executable by searching" ;
304 ECHO " the PATH for 'quickbook'." ;
305 ECHO " To disable this warning in the future, or to completely" ;
306 ECHO " avoid compilation of quickbook, you can explicitly set the" ;
307 ECHO " path to a quickbook executable command in user-config.jam" ;
308 ECHO " or site-config.jam with the call" ;
309 ECHO " using quickbook : /path/to/quickbook ;" ;
311 # As a last resort, search for 'quickbook' command in path. Note
312 # that even if the 'quickbook' command is not found,
313 # get-invocation-command will still return 'quickbook' and might
314 # generate an error while generating the virtual-target.
316 .quickbook-binary = [ common.get-invocation-command quickbook : quickbook ] ;
323 generators.register [ new quickbook-binary-generator quickbook.quickbook-to-boostbook : QUICKBOOK : XML ] ;
326 # <quickbook-binary> shell command to run QuickBook
327 # <quickbook-binary-dependencies> targets to build QuickBook from sources.
328 toolset.flags quickbook.quickbook-to-boostbook QB-COMMAND <quickbook-binary> ;
329 toolset.flags quickbook.quickbook-to-boostbook QB-DEPENDENCIES <quickbook-binary-dependencies> ;
330 toolset.flags quickbook.quickbook-to-boostbook INCLUDES <include> ;
331 toolset.flags quickbook.quickbook-to-boostbook QB-DEFINES <quickbook-define> ;
332 toolset.flags quickbook.quickbook-to-boostbook QB-INDENT <quickbook-indent> ;
333 toolset.flags quickbook.quickbook-to-boostbook QB-LINE-WIDTH <quickbook-line-width> ;
334 toolset.flags quickbook.quickbook-to-boostbook QB-OPTIONS <quickbook-strict-mode>on : --strict ;
337 rule quickbook-to-boostbook ( target : source : properties * )
339 # Signal dependency of quickbook sources on <quickbook-binary-dependencies>
340 # upon invocation of quickbook-to-boostbook.
341 DEPENDS $(target) : [ on $(target) return $(QB-DEPENDENCIES) ] ;
345 actions quickbook-to-boostbook
347 "$(QB-COMMAND)" -I"$(INCLUDES)" -D"$(QB-DEFINES)" --indent="$(QB-INDENT)" --linewidth="$(QB-LINE-WIDTH)" $(QB-OPTIONS) --output-file="$(1)" "$(2)"
351 # Declare a main target to convert a quickbook source into a boostbook XML file.
353 rule to-boostbook ( target-name : sources * : requirements * : default-build * )
355 local project = [ project.current ] ;
357 targets.main-target-alternative
358 [ new typed-target $(target-name) : $(project) : XML
359 : [ targets.main-target-sources $(sources) : $(target-name) ]
360 : [ targets.main-target-requirements $(requirements) : $(project) ]
361 : [ targets.main-target-default-build $(default-build) : $(project) ]