quickbook-manual.quickbook

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

        [Row 1, Col 0: a small cell]
        [Row 1, Col 1: a small cell]
    ]
]

Here's how to have preformatted blocks of code in a table cell:

[pre'''
[table Table with code
    [[Comment] [Code]]
    [
        [My first program]
        ['''\`\`
            #include <iostream>

            int main()
            {
                std::cout << "Hello, World!" << std::endl;
                return 0;
            }
        \`\`''']
    ]
]
''']

[table Table with code
    [[Comment] [Code]]
    [
        [My first program]
        [``
            #include <iostream>

            int main()
            {
                std::cout << "Hello, World!" << std::endl;
                return 0;
            }
        ``]
    ]
]

[endsect]
[section Variable Lists]

[pre'''
[variablelist A Variable List
    [[term 1] [The definition of term 1]]
    [[term 2] [The definition of term 2]]
    [[term 3] [The definition of term 3]]
]
''']

will generate:

[variablelist A Variable List
    [[term 1] [The definition of term 1]]
    [[term 2] [The definition of term 2]]
    [[term 3] [The definition of term 3]]
]

The rules for variable lists are the same as for tables, except that
only 2 "columns" are allowed. The first column contains the terms, and
the second column contains the definitions. Those familiar with HTML
will recognize this as a "definition list".

[endsect]
[section Include]

You can include one QuickBook file from another. The syntax is simply:

[pre'''
[include someother.qbk]
''']

The included file will be processed as if it had been cut and pasted
into the current document, with the following exceptions:

* The '''__FILENAME__''' predefined macro will reflect the name of the
  file currently being processed.
* Any macros defined in the included file are scoped to that file.

The [^\[include\]] directive lets you specify a document id to use for the
included file. When this id is not explicitly specified, the id defaults to
the filename ("someother", in the example above). You can specify the id
like this:

[pre'''
[include:someid someother.qbk]
''']

All auto-generated anchors will use the document id as a unique prefix. So
for instance, if there is a top section in someother.qbk named "Intro", the
named anchor for that section will be "someid.intro", and you can link to
it with [^\[link someid.intro The Intro\]].

[endsect]

[section Import]

When documenting code, you'd surely need to present code from actual source
files. While it is possible to copy some code and paste them in your QuickBook
file, doing so is error prone and the extracted code in the documentation tends
to get out of sync with the actual code as the code evolves. The problem, as
always, is that once documentation is written, the tendency is for the docs to
languish in the archives without maintenance.

QuickBook's import facility provides a nice solution.

[heading Example]

You can effortlessly import code snippets from source code into your QuickBook.
The following illustrates how this is done:

[pre'''
[import ../test/stub.cpp]
[foo]
[bar]
''']

The first line:

[pre'''
[import ../test/stub.cpp]
''']

collects specially marked-up code snippets from [@../../test/stub.cpp stub.cpp]
and places them in your QuickBook file as virtual templates. Each of the
specially marked-up code snippets has a name (e.g. `foo` and `bar` in the
example above). This shall be the template identifier for that particular code
snippet. The second and third line above does the actual template expansion:

[pre'''
[foo]
[bar]
''']

And the result is:

[import ../test/stub.cpp]
[foo]
[bar]

[heading Code Snippet Markup]

Note how the code snippets in [@../../test/stub.cpp stub.cpp] get marked up. We
use distinguishable comments following the form:

    //[id
    some code here
    //]

The first comment line above initiates a named code-snippet. This prefix will
not be visible in quickbook. The entire code-snippet in between `//[id` and
`//]` will be inserted as a template in quickbook with name ['/id/]. The comment
`//]` ends a code-snippet This too will not be visible in quickbook.

[heading Special Comments]

Special comments of the form:

    //` some [*quickbook] markup here

and:

    /*` some [*quickbook] markup here */

will be parsed by QuickBook. This can contain quickbook /blocks/ (e.g. sections,
paragraphs, tables, etc). In the first case, the initial slash-slash, tick and
white-space shall be ignored. In the second, the initial slash-star-tick and the
final star-slash shall be ignored.

[heading Callouts]

Special comments of the form:

    /*< some [*quickbook] markup here >*/

will be regarded as callouts. These will be collected, numbered and
rendered as a "callout bug" (a small icon with a number). After the
whole snippet is parsed, the callout list is generated. See
[@http://www.docbook.org/tdg/en/html/callout.html Callouts] for details.
Example:

[foo_bar]

Checkout [@../../test/stub.cpp stub.cpp] to see the actual code.

[endsect]

[endsect]
[endsect]

[section:install Installation and configuration]

This section provides some guidelines on how to install and configure
BoostBook and Quickbook under several operating systems.

Before continuing, it is very important that you keep this in mind: if you
try to build some documents and the process breaks due to misconfiguration,
be absolutely sure to delete any `bin` and `bin.v2` directories generated
by the build before trying again.  Otherwise your configuration fixes will
not take any effect.

[section:windows Windows 2000, XP, 2003, Vista]

[python]

[:['Section contributed by Julio M. Merino Vidal]]

The following instructions apply to any Windows system based on Windows
2000, including Windows XP, Windows 2003 Server and Windows Vista. The
paths shown below are taken from a Windows Vista machine; you will need to
adjust them to match your system in case you are running an older version.

# First of all you need to have a copy of `xsltproc` for Windows.  There
  are many ways to get this tool, but to keep things simple, use the
  [@http://www.zlatkovic.com/pub/libxml/ binary packages] made by Igor
  Zlatkovic.  At the very least, you need to download the following
  packages: `iconv`, `zlib`, `libxml2` and `libxslt`.

# Unpack all these packages in the same directory so that you get unique
  `bin`, `include` and `lib` directories within the hierarchy.  These
  instructions use `C:\Users\example\Documents\boost\xml` as the root for
  all files.

# From the command line, go to the `bin` directory and launch
  `xsltproc.exe` to ensure it works.  You should get usage information on
  screen.

# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
  4.2] and unpack it in the same directory used above.  That is:
  `C:\Users\example\Documents\boost\xml\docbook-xml`.

# Download the latest
  [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
  Docbook XSL] version and unpack it, again in the same directory
  used before.  To make things easier, rename the directory created
  during the extraction to `docbook-xsl` (bypassing the version name):
  `C:\Users\example\Documents\boost\xml\docbook-xsl`.

# Add the following to your `user-config.jam` file, which should live in
  your home directory (`%HOMEDRIVE%%HOMEPATH%`).  You must already have it
  somewhere or otherwise you could not be building Boost (i.e. missing
  tools configuration).

 using xsltproc
     : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe"
     ;

 using boostbook
     : "C:/Users/example/Documents/boost/xml/docbook-xsl"
     : "C:/Users/example/Documents/boost/xml/docbook-xml"
     ;

The above steps are enough to get a functional BoostBook setup.  Quickbook
will be automatically built when needed.  If you want to avoid these
rebuilds:

# Go to Quickbook's source directory (`BOOST_ROOT\tools\quickbook`).

# Build the utility by issuing `bjam --v2`.

# Copy the resulting `quickbook.exe` binary (located under the
  `BOOST_ROOT\bin.v2` hierarchy) to a safe place.  Following our previous
  example, you can install it into:
  `C:\Users\example\Documents\boost\xml\bin`.

# Add the following to your `user-config.jam` file:

 using quickbook
     : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe"
     ;

[endsect]

[section:linux Debian, Ubuntu]

The following instructions apply to Debian and its derivatives. They are based
on a Ubuntu Edgy install but should work on other Debian based systems.

First install the `bjam`, `xsltproc`, `docbook-xsl` and `docbook-xml` packages.
For example, using `apt-get`:

    sudo apt-get install xsltprc docbook-xsl docbook-xml

If you're planning on building boost's documentation, you'll also need to
install the `doxygen` package as well.

Next, we need to configure Boost Build to compile BoostBook files. Add the
following to your `user-config.jam` file, which should be in your home
directory. If you don't have one, create a file containing this text. For more
information on setting up `user-config.jam`, see the
[@http://boost.org/boost-build2/doc/html/bbv2/advanced/configuration.html Boost
Build documentation].

    using xsltproc ;

    using boostbook
        : /usr/share/xml/docbook/stylesheet/nwalsh
        : /usr/share/xml/docbook/schema/dtd/4.2
        ;

    # Remove this line if you're not using doxygen
    using doxygen ;

The above steps are enough to get a functional BoostBook setup.  Quickbook
will be automatically built when needed.  If you want to avoid these
rebuilds:

# Go to Quickbook's source directory (`BOOST_ROOT/tools/quickbook`).

# Build the utility by issuing `bjam --v2`.

# Copy the resulting `quickbook` binary (located under the
  `BOOST_ROOT/bin.v2` hierarchy) to a safe place.  The traditional location is
  `/usr/local/bin`.

# Add the following to your `user-config.jam` file, using the full path of the
  quickbook executable:

 using quickbook
     : /usr/local/bin/quickbook
     ;

[endsect]
[endsect] [/Installation and configuration]

[section:editors Editor Support]

Editing quickbook files is usually done with text editors both simple and
powerful. The following sections list the settings for some editors which can
help make editing quickbook files a bit easier.

[blurb __note__ You may submit your settings, tips, and suggestions to the
authors, or through the [@https://lists.sourceforge.net/lists/listinfo/boost-
docs Boost Docs mailing list].]

[section:scite Scintilla Text Editor]

[:['Section contributed by Dean Michael Berris]]

The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X.
It uses the SCIntilla source code editing component.

[blurb __tip__ SciTE can be downloaded from [@http://www.scintilla.org/SciTE.html]]

You can use the following settings to highlight quickbook tags when
editing quickbook files.

[pre'''
qbk=*.qbk
lexer.*.qbk=props
use.tabs.$(qbk)=0
tab.size.$(qbk)=4
indent.size.$(qbk)=4
style.props.32=$(font.base)
comment.stream.start.props=[/
comment.stream.end.props=]
comment.box.start.props=[/
comment.box.middle.props=
comment.box.end.props=]
''']

[blurb __note__ Thanks to Rene Rivera for the above SciTE settings.]

[endsect] [/scite]
[endsect] [/editors]

[section:faq Frequently Asked Questions]

[heading Can I use QuickBook for non-Boost documentation?]

QuickBook can be used for non-Boost documentation with a little extra work.

[:['Faq contributed by Michael Marcin]]

When building HTML documentation with BoostBook a Boost C++ Libraries header
is added to the files. When using QuickBook to document projects outside of
Boost this is not desirable. This behavior can be overridden at the BoostBook
level by specifying some XSLT options. When using Boost Build version 2 (BBv2)
this can be achieved by adding parameters to the BoostBook target declaration.

For example:
[pre
using quickbook ;

xml my_doc : my_doc.qbk ;

boostbook standalone
    :
        my_doc
    :
        <xsl:param>boost.image.src=images/my_project_logo.png
        <xsl:param>boost.image.alt="\\"My Project\\""
        <xsl:param>boost.image.w=100
        <xsl:param>boost.image.h=50
        <xsl:param>nav.layout=none
    ;
]

[endsect] [/faq]

[section:ref Quick Reference]

[cpp]

[template ordered_list_sample[]
[pre'''
# one
# two
# three
''']
]

[template unordered_list_sample[]
[pre'''
* one
* two
* three
''']
]

[template table_sample[]
[pre'''
[table Title
[[a][b][c]]
[[a][b][c]]
]
''']
]

[template var_list_sample[]
[pre'''
[variablelist Title
[[a][b]]
[[a][b]]
]
''']
]


[table Syntax Compendium
    [[To do this...]        [Use this...]                                   [See this...]]
    [[comment]              [[^'''[/ some comment]''']]                     [__comments__]]
    [[['italics]]           [[^'''['italics] or /italics/''']]              [__font_styles__ and __simple_formatting__]]
    [[[*bold]]              [[^'''[*bold] or *bold*''']]                    [__font_styles__ and __simple_formatting__]]
    [[[_underline]]         [[^'''[_underline] or _underline_''']]          [__font_styles__ and __simple_formatting__]]
    [[[^teletype]]          [[^'''[^teletype] or =teletype=''']]            [__font_styles__ and __simple_formatting__]]
    [[[-strikethrough]]     [[^'''[-strikethrough]''']]                     [__font_styles__ and __simple_formatting__]]
    [[[~replaceable]]       [[^'''[~replaceable]''']]                       [__replaceable__]]
    [[source mode]          [[^\[c++\]] or [^\[python\]]]                   [__source_mode__]]
    [[inline code]          [[^'''`int main();`''']]                        [__inline_code__]]
    [[code block]           [[^'''``int main();``''']]                      [__code__]]
    [[code escape]          [[^'''``from c++ to QuickBook``''']]            [__escape_back__]]
    [[line break]           [[^'''[br] or \n''']]                           [__line_break__ *DEPRECATED*]]
    [[anchor]               [[^'''[#anchor]''']]                            [__anchors__]]
    [[link]                 [[^'''[@http://www.boost.org Boost]''']]        [__links__]]
    [[anchor link]          [[^'''[link section.anchor Link text]''']]      [__anchor_links__]]
    [[refentry link]        [[^'''[link xml.refentry Link text]''']]        [__refentry_links__]]
    [[function link]        [[^'''[funcref fully::qualified::function_name Link text]''']]      [__code_links__]]
    [[class link]           [[^'''[classref fully::qualified::class_name Link text]''']]        [__code_links__]]
    [[member link]          [[^'''[memberref fully::qualified::member_name Link text]''']]      [__code_links__]]
    [[enum link]            [[^'''[enumref fully::qualified::enum_name Link text]''']]          [__code_links__]]
    [[macro link]           [[^'''[macroref MACRO_NAME Link text]''']]                          [__code_links__]]
    [[concept link]         [[^'''[conceptref ConceptName Link text]''']]                       [__code_links__]]
    [[header link]          [[^'''[headerref path/to/header.hpp Link text]''']]                 [__code_links__]]
    [[escape]               [[^\'\'\'escaped text (no processing/formatting)\'\'\']]            [__escape__]]
    [[single char escape]   [[^\\c]]                                        [__single_char_escape__]]
    [[images]               [[^'''[$image.jpg]''']]                         [__images__]]
    [[begin section]        [[^'''[section The Section Title]''']]          [__section__]]
    [[end section]          [[^'''[endsect]''']]                            [__section__]]
    [[paragraph]            [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.]  [__paragraphs__]]
    [[ordered list]         [[ordered_list_sample]]                         [__ordered_lists__]]
    [[unordered list]       [[unordered_list_sample]]                       [__unordered_lists__]]
    [[code]                 [No markup. Preformatted code starts with a space or a tab.]        [__code__]]
    [[preformatted]         [[^'''[pre preformatted]''']]                   [__preformatted__]]
    [[block quote]          [[^'''[:sometext...]''']]                       [__blockquote__]]
    [[heading 1]            [[^'''[h1 Heading 1]''']]                       [__heading__]]
    [[heading 2]            [[^'''[h2 Heading 2]''']]                       [__heading__]]
    [[heading 3]            [[^'''[h3 Heading 3]''']]                       [__heading__]]
    [[heading 4]            [[^'''[h4 Heading 4]''']]                       [__heading__]]
    [[heading 5]            [[^'''[h5 Heading 5]''']]                       [__heading__]]
    [[heading 6]            [[^'''[h6 Heading 6]''']]                       [__heading__]]
    [[macro]                [[^'''[def macro_identifier some text]''']]     [__macros__]]
    [[template]             [[^'''[template[a b] [a] body [b]]''']]         [__templates__]]
    [[blurb]                [[^'''[blurb advertisement or note...]''']]     [__blurbs__]]
    [[admonition]           [[^'''[warning Warning text...]''']]            [__admonitions__]]
    [[table]                [[table_sample]]                                [__tables__]]
    [[variablelist]         [[var_list_sample]]                             [__variable_lists__]]
    [[include]              [[^'''[include someother.qbk]''']]              [__include__]]
]

[endsect]