Re: [Boost-build] [boostbook] Building Boost documentation

From: Edward Diener (eldiener_at_[hidden])
Date: 2007-11-18 15:48:34

Vladimir Prus wrote:
> Edward Diener wrote:
> 
>> Because I wanted to read documentation on some of the new libraries in
>> the latest Boost SVN repository, which existed only in XML format, it
>> was time to go through the annual rite of attempting to use Doug
>> Gregor's excellent documention of "The Boostbook Documentation Format"
>> in order to setup the documentation system to generate documentation
>> using bjam. Although Mr. Gregor's documentation is extremely good, I
>> have never been completely successful in the past, but I had my fingers
>> crossed in hopeful expectation this time. I am doing this on Windows so
>> I have to set things up manually.
>>
>> 1) I downloaded xsltproc and doxygen successfully, and "installed" them
>> into appropriate directories and, to make things easy for myself, put
>> those directories in my PATH.
>>
>> 2) After making sure I had no .jam file of any kind in my home directory
>> I went to the \tools\build\v2\user-config,jam in the directory in which
>> the latest  Boost Subversion resides, and added the line:
>>
>> using xsltproc ;
>>
>> 3) I downloaded the latest XSL stylesheets and Docbook DTD and put them
>> in their own separate directies, "E:\Utilities\docbook-xsl-1.73.2" and
>> "E:\Utilities\docbook-dtd-4.2".
>>
>> 4) I added to my user-config.jam the lines:
>>
>> #  BoostBook configuration
>> using boostbook
>>      : E:/Utilities/docbook-xsl-1.73.2
>>      : E:/Utilities/docbook-dtd-4.2
>>      ;
>>
>> 5) Now further following instructions to test out my installation so far
>> I went to the \libs\function\doc after copying boostbook.css from the
>> \doc\html directory, and tried the bjam command. My result is:
>>
>> "warning: Graph library does not contain optional GraphML reader.
>> note: to enable GraphML support, set EXPAT_INCLUDE and EXPAT_LIBPATH to
>> the note: directories containing the Expat headers and libraries,
>> respectively. warning: skipping optional Message Passing Interface (MPI)
>> library. note: to enable MPI support, add "using mpi ;" to
>> user-config.jam. note: to suppress this message, pass "--without-mpi" to
>> bjam. note: otherwise, you can safely ignore this message.
>> Building Boost.Regex with the optional Unicode/ICU support disabled.
>> Please refer to the Boost.Regex documentation for more information
>> (don't panic: this is a strictly optional feature).
>> E:/Utilities/BoostLibraries/boost_1_34_0/tools/build/v2/tools\boostbook.jam:300:
>>     in object(boostbook-generator)@326.run
>> warning: rulename $(base-target).depends expands to empty string
> 
> 1. Add --debug-generators option to bjam and send the the output.
> 2. Try adding
> 
>         using doxygen ;
> 
> to user-config.jam

I have gotten further along but still an error.

"E:\Programming\Version Control\Subversion\Boost\libs\function\doc>bjam 
--v2 --de
bug-generators
warning: Graph library does not contain optional GraphML reader.
note: to enable GraphML support, set EXPAT_INCLUDE and EXPAT_LIBPATH to the
note: directories containing the Expat headers and libraries, respectively.
warning: skipping optional Message Passing Interface (MPI) library.
note: to enable MPI support, add "using mpi ;" to user-config.jam.
note: to suppress this message, pass "--without-mpi" to bjam.
note: otherwise, you can safely ignore this message.
Building Boost.Regex with the optional Unicode/ICU support disabled.
Please refer to the Boost.Regex documentation for more information
(don't panic: this is a strictly optional feature).
warning: No toolsets are configured.
warning: Configuring default toolset "msvc".
warning: If the default is wrong, you may not be able to build C++ programs.
warning: Use the "--toolset=xxxxx" option to override our guess.
warning: For more configuration options, please consult
warning: 
http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html

      *** construct BOOSTBOOK_MAIN
          from { function.xml.XML }
          properties: <asynch-exceptions>off 
<conditional>@Jamfile</E:/Programmin
g/Version Control/Subversion/Boost>%Jamfile</E:/Programming/Version 
Control/Subv
ersion/Boost>.handle-static-runtime <debug-store>object 
<debug-symbols>on <defin
e>BOOST_ALL_NO_LIB=1 <doxygen.doxproc.index>no 
<doxygen.processor>xsltproc <exce
ption-handling>on <extern-c-nothrow>off <format>html 
<hardcode-dll-paths>true <h
ost-os>windows <include>../../.. <inlining>off <install-dependencies>off 
<link>s
hared <main-target-type>BOOSTBOOK_MAIN <midl-robust>yes 
<midl-stubless-proxy>yes
  <optimization>off <os>NT <pch>on <profiling>off <python-debugging>off 
<python>2
.5 <rtti>on <runtime-debugging>on <runtime-link>shared <stdlib>native 
<suppress-
import-lib>false <symlink-location>project-relative 
<tag>@Jamfile</E:/Programmin
g/Version Control/Subversion/Boost>%Jamfile</E:/Programming/Version 
Control/Subv
ersion/Boost>.tag <target-os>windows <threadapi>win32 <threading>single 
<toolset
-msvc:version>8.0 <toolset>msvc <user-interface>console <variant>debug 
<warnings
-as-errors>off <warnings>on
      find-viable-generators target-type= BOOSTBOOK_MAIN property-set= 
msvc-8.0/d
ebug
      trying type BOOSTBOOK_MAIN
      there are generators for this type
      trying generator boostbook.main ( -> BOOSTBOOK_MAIN )
        is viable
      ***  1  viable generators
          *** construct DOCBOOK
              from { function.xml.XML }
              properties: <asynch-exceptions>off 
<catalog>..\..\..\bin.v2/boostbo
ok_catalog.xml <conditional>@Jamfile</E:/Programming/Version 
Control/Subversion/
Boost>%Jamfile</E:/Programming/Version 
Control/Subversion/Boost>.handle-static-r
untime <debug-store>object <debug-symbols>on <define>BOOST_ALL_NO_LIB=1 
<doxygen
.doxproc.index>no <doxygen.processor>xsltproc <exception-handling>on 
<extern-c-n
othrow>off <format>html <hardcode-dll-paths>true <host-os>windows 
<include>../..
/.. <inlining>off <install-dependencies>off <link>shared 
<main-target-type>BOOST
BOOK_MAIN <midl-robust>yes <midl-stubless-proxy>yes <optimization>off 
<os>NT <pc
h>on <profiling>off <python-debugging>off <python>2.5 <rtti>on 
<runtime-debuggin
g>on <runtime-link>shared <stdlib>native <suppress-import-lib>false 
<symlink-loc
ation>project-relative <tag>@Jamfile</E:/Programming/Version 
Control/Subversion/
Boost>%Jamfile</E:/Programming/Version Control/Subversion/Boost>.tag 
<target-os>
windows <threadapi>win32 <threading>single <toolset-msvc:version>8.0 
<toolset>ms
vc <user-interface>console <variant>debug <warnings-as-errors>off 
<warnings>on
          find-viable-generators target-type= DOCBOOK property-set= 
msvc-8.0/debu
g
          trying type DOCBOOK
          there are generators for this type
          trying generator boostbook.boostbook-to-docbook ( XML -> DOCBOOK )
            is viable
          ***  1  viable generators
            ** generator boostbook.boostbook-to-docbook
            multiple:
            composing:
            SUCCESS:  { 
boostbook%boostbook.boostbook-to-docbook-function.docbook
.DOCBOOK { function.xml.XML } }

          returned { 
boostbook%boostbook.boostbook-to-docbook-function.docbook.DO
CBOOK { function.xml.XML } }
            generator boostbook.boostbook-to-docbook  spawned
            { 
boostbook%boostbook.boostbook-to-docbook-function.docbook.DOCBOOK {
  function.xml.XML } }
            with usage requirements:
          *** construct HTMLDIR
              from { 
boostbook%boostbook.boostbook-to-docbook-function.docbook.DO
CBOOK { function.xml.XML } }
              properties: <asynch-exceptions>off 
<catalog>..\..\..\bin.v2/boostbo
ok_catalog.xml <conditional>@Jamfile</E:/Programming/Version 
Control/Subversion/
Boost>%Jamfile</E:/Programming/Version 
Control/Subversion/Boost>.handle-static-r
untime <debug-store>object <debug-symbols>on <define>BOOST_ALL_NO_LIB=1 
<doxygen
.doxproc.index>no <doxygen.processor>xsltproc <exception-handling>on 
<extern-c-n
othrow>off <format>html <hardcode-dll-paths>true <host-os>windows 
<include>../..
/.. <inlining>off <install-dependencies>off <link>shared 
<main-target-type>BOOST
BOOK_MAIN <midl-robust>yes <midl-stubless-proxy>yes <optimization>off 
<os>NT <pc
h>on <profiling>off <python-debugging>off <python>2.5 <rtti>on 
<runtime-debuggin
g>on <runtime-link>shared <stdlib>native <suppress-import-lib>false 
<symlink-loc
ation>project-relative <tag>@Jamfile</E:/Programming/Version 
Control/Subversion/
Boost>%Jamfile</E:/Programming/Version Control/Subversion/Boost>.tag 
<target-os>
windows <threadapi>win32 <threading>single <toolset-msvc:version>8.0 
<toolset>ms
vc <user-interface>console <variant>debug <warnings-as-errors>off 
<warnings>on <
xsl:param>manifest=function-doc_HTML.manifest
          find-viable-generators target-type= HTMLDIR property-set= 
msvc-8.0/debu
g
          trying type HTMLDIR
          there are generators for this type
          trying generator boostbook.docbook-to-htmldir ( DOCBOOK -> 
HTMLDIR )
            is viable
          ***  1  viable generators
            ** generator boostbook.docbook-to-htmldir
            multiple:
            composing:
            SUCCESS:  { 
boostbook%boostbook.docbook-to-htmldir-function-doc_HTML.
manifest.HTMLDIR { 
boostbook%boostbook.boostbook-to-docbook-function.docbook.DOC
BOOK { function.xml.XML } } }

          returned { 
boostbook%boostbook.docbook-to-htmldir-function-doc_HTML.man
ifest.HTMLDIR { 
boostbook%boostbook.boostbook-to-docbook-function.docbook.DOCBOO
K { function.xml.XML } } }
            generator boostbook.docbook-to-htmldir  spawned
            { 
boostbook%boostbook.docbook-to-htmldir-function-doc_HTML.manifest.H
TMLDIR { 
boostbook%boostbook.boostbook-to-docbook-function.docbook.DOCBOOK { fun
ction.xml.XML } } }
            with usage requirements:
      returned { 
boostbook%boostbook.docbook-to-htmldir-function-doc_HTML.manifes
t.HTMLDIR { 
boostbook%boostbook.boostbook-to-docbook-function.docbook.DOCBOOK {
function.xml.XML } } }
        generator boostbook.main  spawned
        { 
boostbook%boostbook.docbook-to-htmldir-function-doc_HTML.manifest.HTMLD
IR { boostbook%boostbook.boostbook-to-docbook-function.docbook.DOCBOOK { 
functio
n.xml.XML } } }
        with usage requirements:
...found 22 targets...
...updating 1 target...
xslt-xsltproc-dir html\function-doc_HTML.manifest

   set XML_CATALOG_FILES=..\..\..\bin.v2/boostbook_catalog.xml
  "xsltproc" --stringparam manifest "function-doc_HTML.manifest" 
--xinclude -o "h
tml/" "E:\Programming\Version 
Control\Subversion\Boost\tools\boostbook\xsl\html.
xsl" "..\..\..\bin.v2\libs\function\doc\msvc-8.0\debug\function.docbook"

...failed xslt-xsltproc-dir html\function-doc_HTML.manifest...
...failed updating 1 target..."

What does the failure mean ?

The user-config.jam in my home directory now reads:

"# Copyright 2003, 2005 Douglas Gregor
# Copyright 2004 John Maddock
# Copyright 2002, 2003, 2004, 2007 Vladimir Prus
# Distributed under the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or 
http://www.boost.org/LICENSE_1_0.txt)

#  This file is used to configure your Boost.Build installation.
#  You can modify this file in place, or you can place it it
#  permanent location so that it's not overwritten should you
#  get new version of Boost.Build. See:
#
# 
http://boost.org/boost-build2/doc/html/bbv2/reference.html#bbv2.reference.init
#
#  for documentation about permanent location.

#  This file specifies which toolsets (C++ compilers), libraries,
#  and other tools are available.  Often, you should be able to
#  just uncomment existing example lines and adjust them to taste.
#  The complete list of supported tools, and configuration instructions
#  can be found at:
#
#    http://boost.org/boost-build2/doc/html/bbv2/reference/tools.html
#

#  This file uses Jam language syntax to describe available tools.
#  Mostly, there are 'using' lines, that contain the name of the used
#  tools, and parameters to pass to those tools -- where paremeters
#  are separated by semicolons.
#  Important syntax notes:
#
#    - Both ':' and ';' must be separated from other tokens by whitespace
#    - The '\' symbol is quote character, so when specifying Windows paths
#      it's recommended to use '/' instead, or use '\\'.
#
#  More details about syntax can be found at:
#
# 
http://boost.org/boost-build2/doc/html/bbv2/advanced.html#bbv2.advanced.jam_language
#

#  GCC configuration

#  Configure gcc (default version)
#  using gcc ;

#  Configure specific gcc version, giving alternative name to use
#  using gcc : 3.2 : g++-3.2 ;

#  MSVC configuration

#  Configure msvc (default version, searched in standard location
#  and PATH).
#  using msvc ;

#  Borland configuration
#  using borland ;

#  STLPort configuration

#  Configure, specifying location of STLPort headers.
#  Libraries must be either not needed, or available to
#  the compiler by default
#  using stlport : : /usr/include/stlport ;

#  Configure, specifying locatioh of both headers and libraries
#  using stlport : : /usr/include/stlport /usr/lib ;

#  QT configuration

#  Configure, assuming QTDIR gives the installation prefix
#  using qt ;

#  Configure with explicit installation prefix
#  using qt : /usr/opt/qt ;

using xsltproc ;

#  BoostBook configuration
using boostbook
   : E:/Utilities/docbook-xsl-1.73.2
   : E:/Utilities/docbook-dtd-4.2
   ;

using doxygen ;"

Eddie