1 # Copyright 2003, 2004, 2005 Dave Abrahams
2 # Copyright 2003, 2004, 2005 Douglas Gregor
3 # Copyright 2005, 2006, 2007 Rene Rivera
4 # Copyright 2003, 2004, 2005 Vladimir Prus
5 # Distributed under the Boost Software License, Version 1.0.
6 # (See accompanying file LICENSE_1_0.txt or copy at
7 # http://www.boost.org/LICENSE_1_0.txt)
9 # This module defines rules to handle generation of documentation from BoostBook
12 # The type of output is controlled by the <format> feature which can have the
14 # * html: Generates html documentation. This is the default.
15 # * xhtml: Generates xhtml documentation.
16 # * htmlhelp: Generates html help output.
17 # * onehtml: Generates a single html page.
18 # * man: Generates man pages.
19 # * pdf: Generates pdf documentation.
20 # * ps: Generates postscript output.
21 # * docbook: Generates docbook XML.
22 # * fo: Generates XSL formating objects.
23 # * tests: Extracts test cases from the boostbook XML.
25 # <format> is an implicit feature, so for example, typing pdf on the command
26 # line is a short-cut for format=pdf.
29 import "class" : new ;
46 import virtual-target ;
49 # Make this module into a project.
50 project.initialize $(__name__) ;
53 .debug-configuration = [ MATCH ^(--debug-configuration)$ : [ modules.peek : ARGV
56 feature.feature format
57 : html xhtml htmlhelp onehtml man pdf ps docbook fo tests none
58 : implicit composite propagated ;
60 type.register DTDXML : dtdxml ;
61 type.register BOOSTBOOK : boostbook : XML ;
62 type.register FO : fo : XML ;
63 type.register PS : ps ;
64 type.register XSLT : xsl xslt : XML ;
65 type.register HTMLDIR ;
66 type.register XHTMLDIR ;
67 type.register HTMLHELP ;
68 type.register MANPAGES ;
69 type.register TESTS : tests ;
72 # Initialize BoostBook support.
75 docbook-xsl-dir ? # The DocBook XSL stylesheet directory. If not provided,
76 # we use DOCBOOK_XSL_DIR from the environment (if
77 # available) or look in standard locations. Otherwise,
78 # we let the XML processor load the stylesheets
81 : docbook-dtd-dir ? # The DocBook DTD directory. If not provided, we use
82 # DOCBOOK_DTD_DIR From the environment (if available) or
83 # look in standard locations. Otherwise, we let the XML
84 # processor load the DTD remotely.
86 : boostbook-dir ? # The BoostBook directory with the DTD and XSL subdirs.
93 check-boostbook-dir $(boostbook-dir) ;
94 find-tools $(docbook-xsl-dir) : $(docbook-dtd-dir) : $(boostbook-dir) ;
96 # Register generators only if we were called via "using boostbook ;"
97 local reg-gen = generators.register-standard ;
98 $(reg-gen) boostbook.dtdxml-to-boostbook : DTDXML : XML ;
99 $(reg-gen) boostbook.boostbook-to-docbook : XML : DOCBOOK ;
100 $(reg-gen) boostbook.boostbook-to-tests : XML : TESTS ;
101 $(reg-gen) boostbook.docbook-to-onehtml : DOCBOOK : HTML ;
102 $(reg-gen) boostbook.docbook-to-htmldir : DOCBOOK : HTMLDIR ;
103 $(reg-gen) boostbook.docbook-to-xhtmldir : DOCBOOK : XHTMLDIR ;
104 $(reg-gen) boostbook.docbook-to-htmlhelp : DOCBOOK : HTMLHELP ;
105 $(reg-gen) boostbook.docbook-to-manpages : DOCBOOK : MANPAGES ;
106 $(reg-gen) boostbook.docbook-to-fo : DOCBOOK : FO ;
108 # The same about Jamfile main target rules.
109 IMPORT $(__name__) : boostbook : : boostbook ;
113 if $(docbook-xsl-dir)
116 .docbook-xsl-dir = [ path.make $(docbook-xsl-dir) ] ;
117 check-docbook-xsl-dir ;
119 if $(docbook-dtd-dir)
122 .docbook-dtd-dir = [ path.make $(docbook-dtd-dir) ] ;
123 check-docbook-dtd-dir ;
128 check-boostbook-dir $(boostbook-dir) ;
129 local boostbook-xsl-dir = [ path.glob $(boostbook-dir) : xsl ] ;
130 local boostbook-dtd-dir = [ path.glob $(boostbook-dir) : dtd ] ;
131 .boostbook-xsl-dir = $(boostbook-xsl-dir[1]) ;
132 .boostbook-dtd-dir = $(boostbook-dtd-dir[1]) ;
133 check-boostbook-xsl-dir ;
134 check-boostbook-dtd-dir ;
140 local rule lock-config ( )
145 errors.user-error BoostBook has not been configured. ;
147 if ! $(.config-locked)
149 .config-locked = true ;
153 print-error $(.error-message) ;
159 local rule modify-config ( )
164 errors.user-error BoostBook configuration cannot be changed after it has
169 rule print-error ( location message * )
171 ECHO error: at $(location) ;
172 ECHO error: $(message) ;
176 rule make-error ( message * )
179 return [ errors.nearest-user-location ] $(message) ;
183 rule find-boost-in-registry ( keys * )
186 for local R in $(keys)
188 local installed-boost = [ W32_GETREG
189 "HKEY_LOCAL_MACHINE\\SOFTWARE\\$(R)" : "InstallRoot" ] ;
190 if $(installed-boost)
192 boost-root += [ path.make $(installed-boost) ] ;
195 return $(boost-root) ;
199 rule check-docbook-xsl-dir ( )
201 if $(.docbook-xsl-dir)
203 if ! [ path.glob $(.docbook-xsl-dir) : common/common.xsl ]
205 .error-message = [ make-error BoostBook: could not find docbook XSL stylesheets
206 in: [ path.native $(.docbook-xsl-dir) ] ] ;
208 else if $(.debug-configuration)
210 ECHO notice: BoostBook: found docbook XSL stylesheets in: [
211 path.native $(.docbook-xsl-dir) ] ;
217 rule check-docbook-dtd-dir ( )
219 if $(.docbook-dtd-dir)
221 if ! [ path.glob $(.docbook-dtd-dir) : docbookx.dtd ]
223 .error-message = [ make-error BoostBook: could not find docbook DTD in: [
224 path.native $(.docbook-dtd-dir) ] ] ;
226 else if $(.debug-configuration)
228 ECHO notice: BoostBook: found docbook DTD in: [ path.native
229 $(.docbook-dtd-dir) ] ;
235 rule check-boostbook-xsl-dir ( )
237 if ! $(.boostbook-xsl-dir)
239 .error-message = [ make-error BoostBook: could not find boostbook XSL stylesheets. ] ;
241 else if ! [ path.glob $(.boostbook-xsl-dir) : docbook.xsl ]
243 .error-message = [ make-error BoostBook: could not find docbook XSL stylesheets in:
244 [ path.native $(.boostbook-xsl-dir) ] ] ;
246 else if $(.debug-configuration)
248 ECHO notice: BoostBook: found boostbook XSL stylesheets in: [
249 path.native $(.boostbook-xsl-dir) ] ;
254 rule check-boostbook-dtd-dir ( )
256 if ! $(.boostbook-dtd-dir)
258 .error-message = [ make-error BoostBook: could not find boostbook DTD. ] ;
260 else if ! [ path.glob $(.boostbook-dtd-dir) : boostbook.dtd ]
262 .error-message = [ make-error BoostBook: could not find boostbook DTD in: [
263 path.native $(.boostbook-dtd-dir) ] ] ;
265 else if $(.debug-configuration)
267 ECHO notice: BoostBook: found boostbook DTD in: [ path.native
268 $(.boostbook-dtd-dir) ] ;
273 rule check-boostbook-dir ( boostbook-dir ? )
275 if $(boostbook-dir) && ! [ path.glob $(boostbook-dir) : xsl ]
277 .error-message = [ make-error BoostBook: could not find boostbook in: [ path.native
278 $(boostbook-dir) ] ] ;
283 rule find-tools ( docbook-xsl-dir ? : docbook-dtd-dir ? : boostbook-dir ? )
285 docbook-xsl-dir ?= [ modules.peek : DOCBOOK_XSL_DIR ] ;
286 docbook-dtd-dir ?= [ modules.peek : DOCBOOK_DTD_DIR ] ;
287 boostbook-dir ?= [ modules.peek : BOOSTBOOK_DIR ] ;
289 # Look for the boostbook stylesheets relative to BOOST_ROOT and Boost.Build.
290 local boost-build-root = [ path.make [ build-system.location ] ] ;
291 local boostbook-search-dirs = [ path.join $(boost-build-root) .. .. ] ;
293 local boost-root = [ modules.peek : BOOST_ROOT ] ;
296 boostbook-search-dirs += [ path.join [ path.make $(boost-root) ] tools ]
299 boostbook-dir ?= [ path.glob $(boostbook-search-dirs) : boostbook* ] ;
301 # Try to find the tools in platform specific locations.
304 # If installed by the Boost installer.
307 local boost-installer-versions = snapshot cvs 1.33.0 ;
308 local boost-consulting-installer-versions = 1.33.1 1.34.0 1.34.1 ;
309 local boostpro-installer-versions =
310 1.35.0 1.36.0 1.37.0 1.38.0 1.39.0 1.40.0 1.41.0 1.42.0
311 1.43.0 1.44.0 1.45.0 1.46.0 1.47.0 1.48.0 1.49.0 1.50.0 ;
313 local old-installer-root = [ find-boost-in-registry
314 Boost.org\\$(boost-installer-versions) ] ;
316 # Make sure that the most recent version is searched for first.
317 boost-root += [ sequence.reverse [ find-boost-in-registry
318 Boost-Consulting.com\\$(boost-consulting-installer-versions)
319 boostpro.com\\$(boostpro-installer-versions) ] ] ;
321 # Plausible locations.
322 local root = [ PWD ] ;
323 while $(root) != $(root:D) { root = $(root:D) ; }
324 root = [ path.make $(root) ] ;
326 local docbook-search-dirs ;
327 for local p in $(boost-root)
329 search-dirs += [ path.join $(p) tools ] ;
331 for local p in $(old-installer-root)
333 search-dirs += [ path.join $(p) share ] ;
334 docbook-search-dirs += [ path.join $(p) share ] ;
336 search-dirs += [ path.join $(root) Boost tools ] ;
337 search-dirs += [ path.join $(root) Boost share ] ;
338 docbook-search-dirs += [ path.join $(root) Boost share ] ;
340 docbook-xsl-dir ?= [ path.glob $(docbook-search-dirs) : docbook-xsl* ] ;
341 docbook-dtd-dir ?= [ path.glob $(docbook-search-dirs) : docbook-xml* ] ;
342 boostbook-dir ?= [ path.glob $(search-dirs) : boostbook* ] ;
346 # Plausible locations.
348 local share = /usr/local/share /usr/share /opt/share /opt/local/share ;
349 local dtd-versions = 4.2 ;
351 docbook-xsl-dir ?= [ path.glob $(share) : docbook-xsl* ] ;
352 docbook-xsl-dir ?= [ path.glob $(share)/sgml/docbook : xsl-stylesheets ]
354 docbook-xsl-dir ?= [ path.glob $(share)/xsl : docbook* ] ;
356 docbook-dtd-dir ?= [ path.glob $(share) : docbook-xml* ] ;
357 docbook-dtd-dir ?= [ path.glob $(share)/sgml/docbook :
358 xml-dtd-$(dtd-versions)* ] ;
359 docbook-dtd-dir ?= [ path.glob $(share)/xml/docbook : $(dtd-versions) ]
362 boostbook-dir ?= [ path.glob $(share) : boostbook* ] ;
365 docbook-xsl-dir ?= [ path.glob /usr/share/xml/docbook/stylesheet :
367 docbook-dtd-dir ?= [ path.glob /usr/share/xml/docbook/schema/dtd :
371 docbook-xsl-dir ?= [ path.glob /usr/share/xml/docbook/stylesheet/nwalsh
375 if $(docbook-xsl-dir)
377 .docbook-xsl-dir = [ path.make $(docbook-xsl-dir[1]) ] ;
379 if $(docbook-dtd-dir)
381 .docbook-dtd-dir = [ path.make $(docbook-dtd-dir[1]) ] ;
384 if $(.debug-configuration)
386 ECHO notice: Boost.Book: searching XSL/DTD "in" ;
387 ECHO notice: [ sequence.transform path.native : $(boostbook-dir) ] ;
389 local boostbook-xsl-dir ;
390 for local dir in $(boostbook-dir)
392 boostbook-xsl-dir += [ path.glob $(dir) : xsl ] ;
394 local boostbook-dtd-dir ;
395 for local dir in $(boostbook-dir)
397 boostbook-dtd-dir += [ path.glob $(dir) : dtd ] ;
399 .boostbook-xsl-dir = $(boostbook-xsl-dir[1]) ;
400 .boostbook-dtd-dir = $(boostbook-dtd-dir[1]) ;
402 check-docbook-xsl-dir ;
403 check-docbook-dtd-dir ;
404 check-boostbook-xsl-dir ;
405 check-boostbook-dtd-dir ;
412 return $(.boostbook-xsl-dir) ;
419 return $(.boostbook-dtd-dir) ;
426 return $(.docbook-xsl-dir) ;
433 return $(.docbook-dtd-dir) ;
437 rule dtdxml-to-boostbook ( target : source : properties * )
440 xsltproc.xslt $(target) : $(source)
441 "$(.boostbook-xsl-dir)/dtd/dtd2boostbook.xsl" : $(properties) ;
445 rule boostbook-to-docbook ( target : source : properties * )
448 local stylesheet = [ path.native $(.boostbook-xsl-dir)/docbook.xsl ] ;
449 xsltproc.xslt $(target) : $(source) $(stylesheet) : $(properties) ;
453 rule docbook-to-onehtml ( target : source : properties * )
456 local stylesheet = [ path.native $(.boostbook-xsl-dir)/html-single.xsl ] ;
457 xsltproc.xslt $(target) : $(source) $(stylesheet) : $(properties) ;
461 rule docbook-to-htmldir ( target : source : properties * )
464 local stylesheet = [ path.native $(.boostbook-xsl-dir)/html.xsl ] ;
465 xsltproc.xslt-dir $(target) : $(source) $(stylesheet) : $(properties) : html
470 rule docbook-to-xhtmldir ( target : source : properties * )
473 local stylesheet = [ path.native $(.boostbook-xsl-dir)/xhtml.xsl ] ;
474 xsltproc.xslt-dir $(target) : $(source) $(stylesheet) : $(properties) :
479 rule docbook-to-htmlhelp ( target : source : properties * )
482 local stylesheet = [ path.native $(.boostbook-xsl-dir)/html-help.xsl ] ;
483 xsltproc.xslt-dir $(target) : $(source) $(stylesheet) : $(properties) :
488 rule docbook-to-manpages ( target : source : properties * )
491 local stylesheet = [ path.native $(.boostbook-xsl-dir)/manpages.xsl ] ;
492 xsltproc.xslt-dir $(target) : $(source) $(stylesheet) : $(properties) : man
497 rule docbook-to-fo ( target : source : properties * )
500 local stylesheet = [ path.native $(.boostbook-xsl-dir)/fo.xsl ] ;
501 xsltproc.xslt $(target) : $(source) $(stylesheet) : $(properties) ;
505 rule format-catalog-path ( path )
507 local result = $(path) ;
508 if [ xsltproc.is-cygwin ]
512 drive = [ MATCH ^/(.):(.*)$ : $(path) ] ;
513 result = /cygdrive/$(drive[1])$(drive[2]) ;
518 if [ os.name ] = CYGWIN
520 local native-path = [ path.native $(path) ] ;
521 result = [ path.make $(native-path:W) ] ;
524 return [ regex.replace $(result) " " "%20" ] ;
528 rule generate-xml-catalog ( target : sources * : properties * )
530 print.output $(target) ;
532 # BoostBook DTD catalog entry.
533 local boostbook-dtd-dir = [ boostbook.dtd-dir ] ;
534 if $(boostbook-dtd-dir)
536 boostbook-dtd-dir = [ format-catalog-path $(boostbook-dtd-dir) ] ;
540 "<?xml version=\"1.0\"?>"
542 " PUBLIC \"-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN\""
543 " \"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd\">"
544 "<catalog xmlns=\"urn:oasis:names:tc:entity:xmlns:xml:catalog\">"
545 " <rewriteURI uriStartString=\"http://www.boost.org/tools/boostbook/dtd/\" rewritePrefix=\"file://$(boostbook-dtd-dir)/\"/>"
548 local docbook-xsl-dir = [ boostbook.docbook-xsl-dir ] ;
549 if ! $(docbook-xsl-dir)
551 ECHO "BoostBook warning: no DocBook XSL directory specified." ;
552 ECHO " If you have the DocBook XSL stylesheets installed, please " ;
553 ECHO " set DOCBOOK_XSL_DIR to the stylesheet directory on either " ;
554 ECHO " the command line (via -sDOCBOOK_XSL_DIR=...) or in a " ;
555 ECHO " Boost.Jam configuration file. The DocBook XSL stylesheets " ;
556 ECHO " are available here: http://docbook.sourceforge.net/ " ;
557 ECHO " Stylesheets will be downloaded on-the-fly (very slow!) " ;
561 docbook-xsl-dir = [ format-catalog-path $(docbook-xsl-dir) ] ;
562 print.text " <rewriteURI uriStartString=\"http://docbook.sourceforge.net/release/xsl/current/\" rewritePrefix=\"file://$(docbook-xsl-dir)/\"/>" ;
565 local docbook-dtd-dir = [ boostbook.docbook-dtd-dir ] ;
566 if ! $(docbook-dtd-dir)
568 ECHO "BoostBook warning: no DocBook DTD directory specified." ;
569 ECHO " If you have the DocBook DTD installed, please set " ;
570 ECHO " DOCBOOK_DTD_DIR to the DTD directory on either " ;
571 ECHO " the command line (via -sDOCBOOK_DTD_DIR=...) or in a " ;
572 ECHO " Boost.Jam configuration file. The DocBook DTD is available " ;
573 ECHO " here: http://www.oasis-open.org/docbook/xml/4.2/index.shtml" ;
574 ECHO " The DTD will be downloaded on-the-fly (very slow!) " ;
578 docbook-dtd-dir = [ format-catalog-path $(docbook-dtd-dir) ] ;
579 print.text " <rewriteURI uriStartString=\"http://www.oasis-open.org/docbook/xml/4.2/\" rewritePrefix=\"file://$(docbook-dtd-dir)/\"/>" ;
582 print.text "</catalog>" ;
586 # Returns information about the global XML catalog target, creating it lazily if
587 # needed. To get the global catalog generated only once we do not create it in
588 # every project that requests it but instead only create it based on the first
589 # project requesting it and then reuse it from there for any later requests.
591 # To get 'as close as possible' to having the global catalog stored in the same
592 # location independent of which folder our build was run from, we assign its
593 # target to the given project's base Jamroot project. This works correctly as
594 # long as we know the passed project is not standalone or one of Boost Build's
595 # configuration module projects, as those to not have a Jamroot project in their
596 # parent chain. Note also that we can still get our targets generated in
597 # different folders in case when one build project references a target from
598 # another build project with its own separate Jamroot.
600 # FIXME: Ideally the catalog target should be created as part of the boostbook
601 # project and stored in some central location for all used standalone pojects,
602 # shared between all builds made on that system. This however would require much
603 # more though to add the necessary changes to Boost Build's internal design.
605 local rule xml-catalog ( project )
609 local project-module = [ $(project).project-module ] ;
610 local root-module = [ project.get-jamroot-module $(project-module) ] ;
614 if [ project.is-config-module $(project-module) ]
616 errors.user-error boostbook targets can not be declared in Boost
617 Build's configuration modules. ;
621 errors.user-error boostbook targets can not be declared in
622 standalone projects. : use a Jamfile/Jamroot project
626 local root-project = [ project.target $(root-module) ] ;
628 .xml-catalog = [ virtual-target.register [ new file-target
629 boostbook_catalog : XML : $(root-project) : [ new action :
630 boostbook.generate-xml-catalog ] ] ] ;
631 .xml-catalog-file = [ $(.xml-catalog).path ] [ $(.xml-catalog).name ] ;
632 .xml-catalog-file = $(.xml-catalog-file:J=/) ;
634 return $(.xml-catalog) $(.xml-catalog-file) ;
638 class boostbook-target-class : basic-target
641 import property-set ;
642 import virtual-target ;
645 rule construct ( name : sources * : property-set )
647 # Generate the catalog, but only once.
648 IMPORT boostbook : xml-catalog : $(__name__) : boostbook.xml-catalog ;
649 local global-catalog = [ boostbook.xml-catalog [ project ] ] ;
650 local catalog = $(global-catalog[1]) ;
651 local catalog-file = $(global-catalog[2]) ;
654 # Add the catalog to the property set.
655 property-set = [ $(property-set).add-raw <catalog>$(catalog-file) ] ;
659 local format = [ $(property-set).get <format> ] ;
662 case html : type = HTMLDIR ; manifest = HTML.manifest ;
663 case xhtml : type = XHTMLDIR ; manifest = HTML.manifest ;
664 case htmlhelp : type = HTMLHELP ; manifest = HTML.manifest ;
665 case onehtml : type = HTML ;
666 case man : type = MANPAGES ; manifest = man.manifest ;
667 case docbook : type = DOCBOOK ;
668 case fo : type = FO ;
669 case pdf : type = PDF ;
670 case ps : type = PS ;
671 case tests : type = TESTS ;
677 # Sources --> DOCBOOK.
678 local docbook-target = [ generators.construct [ project ] : DOCBOOK
679 : $(property-set) : $(sources) ] ;
680 docbook-target = $(docbook-target[2]) ;
681 $(docbook-target).depends $(catalog) ;
684 target = [ generators.construct [ project ] $(name)_$(manifest) :
685 $(type) : [ $(property-set).add-raw
686 <xsl:param>manifest=$(name)_$(manifest) ] : $(docbook-target) ]
688 target = $(target[2]) ;
689 local name = [ $(property-set).get <name> ] ;
691 if ! [ path.is-rooted $(name) ]
693 local p = [ project ] ;
694 name = [ path.join [ $(p).location ] $(name) ] ;
696 $(target).set-path $(name) ;
701 target = [ generators.construct [ project ] : $(type) :
702 $(property-set) : $(sources) ] ;
703 target = $(target[2]) ;
707 errors.error Cannot build documentation type '$(format)'. ;
710 $(target).depends $(catalog) ;
712 return [ property-set.empty ] $(target) ;
717 # Declare a boostbook target.
719 rule boostbook ( target-name : sources * : requirements * : default-build * )
721 return [ targets.create-metatarget boostbook-target-class :
722 [ project.current ] : $(target-name) : $(sources) : $(requirements) :
727 rule boostbook-to-tests ( target : source : properties * )
730 local boost_root = [ modules.peek : BOOST_ROOT ] ;
731 local native-path = [ path.native [ path.join $(.boostbook-xsl-dir) testing
733 local stylesheet = $(native-path:S=.xsl) ;
734 xsltproc.xslt $(target) : $(source) $(stylesheet) : $(properties)
735 <xsl:param>boost.root=$(boost_root) ;