Write docs with boost quickbook

Jump in this page:
Start
First: Init
Next: Write a start qbk
Next: Write Jamfile
Next: Build at first time
Next: another qbk as subpage
Next: Install boost media
BTW: Jamfile property

Back: c++ Docs System

Boost quickbook and boostbook are very good to generate html, pdf, man documents. Boost quickbook .qbk file format is good to write.

boost quickbook: Write Simple Docs .

Requires:

First: Init project folders

Init project folders:

> mkdir foo
> cd foo

Next: Write a start .qbk file

File: main.qbk

[book c++ Book
	[id cpp-book]
	[quickbook 1.7]
]

Start, c++

[h1:cpp Hello World!]

Hello, c++

Thanks, website [@https://cppfx.xyz cppfx]

As you see, you will quickly understand .qbk file syntax.

The title is c++ Book, and the html tag <h1> will use that title too.

The [h1 will be translated to html <h2>

To avoid keyword c++ to be parsed as c, and let it to be parsed as cpp, define id anywhere.

For example, document id:

[book c++ Book
	[id cpp-book]

For example, anchor id:

[h1:cpp-text c++ text]

Then c++ will be parsed as cpp

Next: Write Jamfile

File: jamroot

xml abc : main.qbk ;

boostbook xyz : abc ;

The rule xml defines a target abc, so it will generate file abc.xml

The rule boostbook defines a target xyz, and use previous target abc as its source, it will generate files abc.docbook, index.html

A .qbk file refered in the jamfile will generate the html index file: index.html ;
A .qbk file refered in another .qbk file will generate a html subpage, not index.
Read below.

Next: Build at the first time

Just run command b2:

> b2

You will see the html document is generated.

Next: Add another qbk as subpage

File: cpp-article.qbk

[article This is c++ subpage title
	[id cpp-subpage]
	[quickbook 1.7]
]

Hello, c++ World!

This is c++ document

[h1:cpp-text c++ Text]

Hi, I am a room.

Add subpage to the main page

A subpage is not written to the jamfile, but written to the main .qbk file: main.qbk

The updated main.qbk will be like this:

[book c++ Book
	[id cpp-book]
	[quickbook 1.7]
]

[include cpp-article.qbk]

Start, c++

[h1 Hello World!]

Hello, c++

Thanks, website [@https://cppfx.xyz cppfx]

Next: Build Again

> b2

Next: Install boost media

Update jamroot

The html generated above is not so nice-looking, thats because boost media is not installed.

Extract boost c++ library release package, then add the following code to jamroot :

(Please replace my-path/to-extracted/boost-release with your real boost extracted folder path.)

Update jamroot :

boost-path = my-path/to-extracted/boost-release ;
boost-media-path = $(boost-path)/doc/src ;

install
	boost-media
:
	[
		glob
			$(boost-media-path)/*.css
			$(boost-media-path)/images/*.png
	]
:
	<location>./html
	<install-source-root>$(boost-media-path)
;

The rule install defines a target boost-media, and use the files of searched by [ glob ... as its sources, copy the files to location ./html/

<install-source-root>$(boost-media-path)

<install-source-root> means preseriving hierarchical directories.
Its value means remove this path prefix from source path , and then install them to target path .
(the property key is <install-source-root>
the property value is $(boost-media-path), aka. my-path/to-extracted/boost-release/doc/src)

Property
Property key
Property value

A property of b2 jamfile has a key and a value

Property Example:

<include>/usr/include

The above line is a property,
the property key is <include>
the property value is /usr/include

More property Examples:

<cxxflags>"-I/usr/include -freflection"

<define>__my_debug__

<link>shared

Next: Build again

> b2