Re: [Boost-users] Quickbook quick start

Subject: Re: [Boost-users] Quickbook quick start
From: Daniel James (daniel_james_at_[hidden])
Date: 2009-05-05 14:41:16

2009/5/5 Peng Yu <pengyu.ut_at_[hidden]>:

> I do not know how bjam works. At this moment, I just want to know what
> command has been called to build the document. Would you please let me
> know what the commands are or how I can figure out what they are?

The build process is pretty complicated. It's probably best to learn
how to use boost build. A Cmake based build is being developed but I
don't know how well that works. There's a diagram showing the build
process on the page I linked to which should give you an idea.

Before I start, I'll summarize the procedure to build pure quickbook
documentation, you'll first run quickbook to convert the documentation
to boostbook, then you run xsltproc with
'tools/boostbook/xsl/docbook.xsl' to convert that to docbook and then
run xsltproc again with 'tools/boostbook/xsl/html.xsl' to convert that
to html.

In detail, I'll write in a unix style as I don't have a windows
computer to hand. So, you'll have to work out how to translate it to
windows yourself I'm afraid.

First you'll need to setup xsltproc. You'll need to download the
xsltproc executables, docbook DTD schemas and XSL stylesheets (details
in the page I linked to). Then create an xml catalog file to tell
xsltproc where to find the various files. Boost build creates a file
call 'boostbook_catalog.xml':

    <?xml version="1.0"?>
    <!DOCTYPE catalog
      PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
      "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">
    <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
      <rewriteURI uriStartString="http://www.boost.org/tools/boostbook/dtd/"
        rewritePrefix="file:///Users/daniel/boost/git/tools/boostbook/dtd/"/>
    <rewriteURI
uriStartString="http://docbook.sourceforge.net/release/xsl/current/"
        rewritePrefix="file:///opt/local/share/xsl/docbook-xsl/"/>
    <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.2/"
      rewritePrefix="file:///opt/local/share/xml/docbook/4.2/"/>
    </catalog>

You'll have to adjust the 'rewritePrefix' values for the location of
the files on your computer. I'm not sure how you write it for the
windows filesystem. And set the environment variable XML_CATALOG_FILES
to its location so that xsltproc will know where to find it.

Then, to build Boost.Config (for example), go to 'libs/config/doc'.

To convert quickbook to boostbook:

    quickbook config.qbk

This generaters config.qbk. To convert to docbook:

    xsltproc ../../../tools/boostbook/xsl/docbook.xsl config.xml >
config.docbook

Finally, to generate html:

    cd html
    xsltproc \
        --stringparam boost.root "../../../.." --stringparam
chunk.section.depth "1" \
        --stringparam html.stylesheet "../../../../doc/html/boostbook.css" \
        ../../../../tools/boostbook/xsl/html.xsl ../config.docbook

At least, that worked for me.

Daniel