Build and Install Boost Docs System: boost quickbook

Jump in this page:
Start
Requirements
Install docbook tools
Install boostbook
Install quickbook
Configure /etc/site-config.jam

Back: c++ Docs System

Install Boost Docs System

Requirements

To install boost docs system, you need to install b2 build, the tutorial of which can be found at:

Build and Install b2 Build

Install docbook tools

Install docbook-xsl, docbook-xml, xsltproc

xsl is provided by docbook-xsl

dtd is provided by docbook-xml

docbook-xsl and docbook-xml are the xsl and dtd 's package names on q4os linux, they might have different package names on different linux distributions, you should find them for youself.

docbook-xsl and docbook-xml are most likely already installed on your system. If not, install them.

$ su -
# apt install docbook-xsl docbook-xml xsltproc

Find the docbook-xsl-dir path

The full path of xsl dir contains common/common.xsl

$ dpkg -L docbook-xsl | ugrep 'common/common.xsl'
/usr/share/xml/docbook/stylesheet/docbook-xsl/common/common.xsl
/usr/share/xml/docbook/stylesheet/docbook-xsl/slides/common/common.xsl

Do not choose the slides one, choose this:

/usr/share/xml/docbook/stylesheet/docbook-xsl/common/common.xsl

Now remove the last part /common/common.xsl , we get:

/usr/share/xml/docbook/stylesheet/docbook-xsl

We can name it docbook-xsl-dir path for b2 build, write down the path, it will be used laterly.

Find the docbook-dtd-dir path

The full path of dtd dir contains docbookx.dtd

$ dpkg -L docbook-xml | ugrep 'docbookx.dtd'
/usr/share/xml/docbook/schema/dtd/4.0/docbookx.dtd
/usr/share/xml/docbook/schema/dtd/4.1.2/docbookx.dtd
/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd
/usr/share/xml/docbook/schema/dtd/4.3/docbookx.dtd
/usr/share/xml/docbook/schema/dtd/4.4/docbookx.dtd
/usr/share/xml/docbook/schema/dtd/4.5/docbookx.dtd

The version 4.2 is proved working by me, so we choose the path:

/usr/share/xml/docbook/schema/dtd/4.2/docbookx.dtd

Now remove the last part /docbookx.dtd from the path, we get:

/usr/share/xml/docbook/schema/dtd/4.2

We can name it docbook-dtd-dir path for b2 build, write down the path, it will be used laterly.

Install boostbook (from boost)

boostbook can be found in boost source code, copy it only: copy it to your operating system's shared location.

For example, I copy boostbook to /sand/share/boostbook and then use /sand/share/boostbook as the shared location.

$ cd <BOOST-SOURCE-ROOT>/tools
$ su
# cp -rf boostbook /sand/share/

Now /sand/share/boostbook is the boostbook location, which will be used laterly.

Install quickbook (from boost)

quickbook must be compiled from the quickbook source code in boost source code, then a binary file quickbook will be generated, we only need that binary file quickbook.

$ cd <BOOST-SOURCE-ROOT>/tools/quickbook/build
$ b2 -q -j7

Then, quickbook will be generated at <BOOST-SOURCE-ROOT>/dist/bin/quickbook, just copy it to your system bin path.

For example, I copy it as /sand/bin/quickbook, and my /sand/bin is already added to PATH environment variable.

$ cd <BOOST-SOURCE-ROOT>/dist/bin
$ su
# cp ./quickbook /sand/bin/

To check if quickbook and its PATH work, type quickbook to run it:

$ quickbook

Configure /etc/site-config.jam

Final /etc/site-config.jam

The final configure appending to /etc/site-config.jam :

using quickbook : /sand/bin/quickbook ;

using
	boostbook
:
	/usr/share/xml/docbook/stylesheet/docbook-xsl
:
	/usr/share/xml/docbook/schema/dtd/4.2
:
	/sand/share/boostbook
;

I explain it one by one:

quickbook

using quickbook : /sand/bin/quickbook ;

Setup quickbook,
the first parameter of "using" is quickbook,
the second parameter of "using" is the quickbook binary path;
If its path can be found at commandline, the second parameter can be empty.

	Tip
B2 build use a colon : to split parameters. For example: exe prog : a.cpp : <library>b ; exe is a rule name; prog is the first parameter, which is a target; a.cpp is the second paramter; <library>b is the third parameter;

Tip

B2 build use a colon : to split parameters. For example:

exe prog : a.cpp : <library>b ;

exe is a rule name;
prog is the first parameter, which is a target;
a.cpp is the second paramter;
<library>b is the third parameter;

boostbook

using boostbook : ... ... ... ;

Setup boostbook:

The first parameter of "using" is boostbook ;

docbook xsl path

The second parameter of "using" is the docbook-xsl-dir path, we have already got it as described in the beginning of this doc, just copy it here.

docbook dtd path

The third parameter of "using" is the docbook-dtd-dir path, we have already got it as described in the beginning of this doc, just copy it here.

boostbook path

The fourth paramter of "using" is the boostbook path.