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 ;
132 # quickbook-binary-generator handles generation of the QuickBook executable, by
133 # marking it as a dependency for QuickBook docs.
135 # If the user supplied the QuickBook command that will be used.
137 # Otherwise we search some sensible places for the QuickBook sources and compile
138 # from scratch using the default toolset.
140 # As a last resort we rely on the shell to find 'quickbook'.
142 class quickbook-binary-generator : generator
144 import modules path targets quickbook ;
146 rule run ( project name ? : property-set : sources * : multiple ? )
148 quickbook.freeze-config ;
149 # QuickBook invocation command and dependencies.
150 local quickbook-binary = [ modules.peek quickbook : .quickbook-binary ] ;
151 local quickbook-binary-dependencies ;
153 if ! $(quickbook-binary)
155 # If the QuickBook source directory was found, mark its main target
156 # as a dependency for the current project. Otherwise, try to find
157 # 'quickbook' in user's PATH
158 local quickbook-dir = [ modules.peek quickbook : .quickbook-dir ] ;
161 # Get the main-target in QuickBook directory.
162 local quickbook-main-target = [ targets.resolve-reference $(quickbook-dir) : $(project) ] ;
164 # The first element are actual targets, the second are
165 # properties found in target-id. We do not care about these
166 # since we have passed the id ourselves.
167 quickbook-main-target =
168 [ $(quickbook-main-target[1]).main-target quickbook ] ;
170 quickbook-binary-dependencies =
171 [ $(quickbook-main-target).generate [ $(property-set).propagated ] ] ;
173 # Ignore usage-requirements returned as first element.
174 quickbook-binary-dependencies = $(quickbook-binary-dependencies[2-]) ;
176 # Some toolsets generate extra targets (e.g. RSP). We must mark
177 # all targets as dependencies for the project, but we will only
178 # use the EXE target for quickbook-to-boostbook translation.
179 for local target in $(quickbook-binary-dependencies)
181 if [ $(target).type ] = EXE
195 # Add $(quickbook-binary-dependencies) as a dependency of the current
196 # project and set it as the <quickbook-binary> feature for the
197 # quickbook-to-boostbook rule, below.
198 property-set = [ $(property-set).add-raw
199 <dependency>$(quickbook-binary-dependencies)
200 <quickbook-binary>$(quickbook-binary)
201 <quickbook-binary-dependencies>$(quickbook-binary-dependencies)
204 return [ generator.run $(project) $(name) : $(property-set) : $(sources) : $(multiple) ] ;
209 # Define a scanner for tracking QBK include dependencies.
211 class qbk-scanner : common-scanner
215 return "\\[[ ]*include[ ]+([^]]+)\\]"
216 "\\[[ ]*include:[a-zA-Z0-9_]+[ ]+([^]]+)\\]"
217 "\\[[ ]*import[ ]+([^]]+)\\]" ;
222 scanner.register qbk-scanner : include ;
224 type.set-scanner QUICKBOOK : qbk-scanner ;
227 # Initialization of toolset.
230 # command ? -> path to QuickBook executable.
232 # When command is not supplied toolset will search for QuickBook directory and
233 # compile the executable from source. If that fails we still search the path for
237 command ? # path to the QuickBook executable.
244 errors.user-error "quickbook: configuration cannot be changed after it has been used." ;
246 .command = $(command) ;
250 rule freeze-config ( )
252 if ! $(.config-frozen)
254 .config-frozen = true ;
256 # QuickBook invocation command and dependencies.
258 .quickbook-binary = $(.command) ;
260 if $(.quickbook-binary)
262 # Use user-supplied command.
263 .quickbook-binary = [ common.get-invocation-command quickbook : quickbook : $(.quickbook-binary) ] ;
267 # Search for QuickBook sources in sensible places, like
268 # $(BOOST_ROOT)/tools/quickbook
269 # $(BOOST_BUILD_PATH)/../../quickbook
271 # And build quickbook executable from sources.
273 local boost-root = [ modules.peek : BOOST_ROOT ] ;
274 local boost-build-path = [ build-system.location ] ;
278 .quickbook-dir += [ path.join $(boost-root) tools ] ;
281 if $(boost-build-path)
283 .quickbook-dir += $(boost-build-path)/../.. ;
286 .quickbook-dir = [ path.glob $(.quickbook-dir) : quickbook ] ;
288 # If the QuickBook source directory was found, mark its main target
289 # as a dependency for the current project. Otherwise, try to find
290 # 'quickbook' in user's PATH
293 .quickbook-dir = [ path.make $(.quickbook-dir[1]) ] ;
297 ECHO "QuickBook warning: The path to the quickbook executable was" ;
298 ECHO " not provided. Additionally, couldn't find QuickBook" ;
299 ECHO " sources searching in" ;
300 ECHO " * BOOST_ROOT/tools/quickbook" ;
301 ECHO " * BOOST_BUILD_PATH/../../quickbook" ;
302 ECHO " Will now try to find a precompiled executable by searching" ;
303 ECHO " the PATH for 'quickbook'." ;
304 ECHO " To disable this warning in the future, or to completely" ;
305 ECHO " avoid compilation of quickbook, you can explicitly set the" ;
306 ECHO " path to a quickbook executable command in user-config.jam" ;
307 ECHO " or site-config.jam with the call" ;
308 ECHO " using quickbook : /path/to/quickbook ;" ;
310 # As a last resort, search for 'quickbook' command in path. Note
311 # that even if the 'quickbook' command is not found,
312 # get-invocation-command will still return 'quickbook' and might
313 # generate an error while generating the virtual-target.
315 .quickbook-binary = [ common.get-invocation-command quickbook : quickbook ] ;
322 generators.register [ new quickbook-binary-generator quickbook.quickbook-to-boostbook : QUICKBOOK : XML ] ;
325 # <quickbook-binary> shell command to run QuickBook
326 # <quickbook-binary-dependencies> targets to build QuickBook from sources.
327 toolset.flags quickbook.quickbook-to-boostbook QB-COMMAND <quickbook-binary> ;
328 toolset.flags quickbook.quickbook-to-boostbook QB-DEPENDENCIES <quickbook-binary-dependencies> ;
329 toolset.flags quickbook.quickbook-to-boostbook INCLUDES <include> ;
330 toolset.flags quickbook.quickbook-to-boostbook QB-DEFINES <quickbook-define> ;
331 toolset.flags quickbook.quickbook-to-boostbook QB-INDENT <quickbook-indent> ;
332 toolset.flags quickbook.quickbook-to-boostbook QB-LINE-WIDTH <quickbook-line-width> ;
335 rule quickbook-to-boostbook ( target : source : properties * )
337 # Signal dependency of quickbook sources on <quickbook-binary-dependencies>
338 # upon invocation of quickbook-to-boostbook.
339 DEPENDS $(target) : [ on $(target) return $(QB-DEPENDENCIES) ] ;
343 actions quickbook-to-boostbook
345 "$(QB-COMMAND)" -I"$(INCLUDES)" -D"$(QB-DEFINES)" --indent="$(QB-INDENT)" --linewidth="$(QB-LINE-WIDTH)" --output-file="$(1)" "$(2)"
349 # Declare a main target to convert a quickbook source into a boostbook XML file.
351 rule to-boostbook ( target-name : sources * : requirements * : default-build * )
353 local project = [ project.current ] ;
355 targets.main-target-alternative
356 [ new typed-target $(target-name) : $(project) : XML
357 : [ targets.main-target-sources $(sources) : $(target-name) ]
358 : [ targets.main-target-requirements $(requirements) : $(project) ]
359 : [ targets.main-target-default-build $(default-build) : $(project) ]