quickbook.qbk

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

[foo_bar]

This is the actual code:

    //[ foo_bar
    std::string foo_bar() /*< The /Mythical/ FooBar.
                          See [@http://en.wikipedia.org/wiki/Foobar Foobar for details] >*/
    {
        return "foo-bar"; /*< return 'em, foo-bar man! >*/
    }
    //]

The callouts bugs are placed exactly where the special callout comment
is situated. It can be anywhere in the code. The bugs can be rather
obtrusive, however. They get in the way of the clarity of the code.
Another special callout comment style is available:

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

This is the line-oriented version of the callout. With this, the "bug"
is placed at the very left of the code block, away from the actual code.
By placing it at the far left, the code is rendered un-obscured.
Example:

[class_]

See the actual code here: [@../../tools/quickbook/test/stub.cpp]

[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:macosx Mac OS X]

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

The following instructions explain how to install Docbook XML, Docbook XSL
and Doxygen in a Mac OS X system, how to configure Boost.Build v2 to
recognize them and how to build and install Quickbook.  They were taken
from a 10.4 (Tiger) machine so it is likely that they also apply to future
versions; they may not work with older ones, though.

The text below assumes you want to install all the necessary utilities in a
system-wide location, allowing any user in the machine to have access to
them. Therefore, all files will be put in the `/usr/local` hierarchy.  If
you do not want this, you can choose any other prefix such as
`~/Applications` for a single-user installation.

Mac OS X comes with `xsltproc` and all related libraries preinstalled, so
you do not need to take any extra steps to set them up.  It is probable
that future versions will include them too, but these instructions may not
apply to older versions.

To get started:

# Download [@http://www.docbook.org/xml/4.2/docbook-xml-4.2.zip Docbook XML
  4.2] and unpack it inside `/usr/local/share/xml/docbook/4.2`.

# Download the latest
  [@http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608
  Docbook XSL] version and unpack it.  Put the results in
  `/usr/local/share/xsl/docbook`, thus effectively removing the version
  number from the directory name (for simplicity).

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

 using xsltproc ;

 using boostbook
     : "/usr/local/share/xsl/docbook"
     : "/usr/local/share/xml/docbook/4.2"
     ;

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 and install a system-wide Quickbook instead:

# 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.  Following our previous
  example, you can install it into: `/usr/local/bin`.

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

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

Additionally, if you need to build documentation that uses
[@http://www.doxygen.org Doxygen], you will need to install it too:

# Go to the [@http://www.stack.nl/~dimitri/doxygen/download.html#latestsrc
  downloads section] and get the disk image (`dmg` file) for Mac OS X.

# Open the disk image and drag the Doxygen application to your
  `Applications` folder to install it.

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

 using doxygen
     : /Applications/Doxygen.app/Contents/Resources/doxygen
     ;

Alternatively, you may want to install all the prerequistes through a
package system to avoid manual management of the installations.  In that
case, check out [@http://www.pkgsrc.org pkgsrc].

[endsect]

[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 xsltproc 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]

[/ KDE support (Kate, KWrite, Konqueror, KDevelop) ]
[include ../extra/katepart/katepart.qbk]

[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
    ;
]

[heading Is there an easy way to convert BoostBook docs to QuickBook?]

There's a stylesheet that allows Boostbook generated HTML to be viewed
as quickbook source, see
[@http://svn.boost.org/trac/boost/wiki/QuickbookSourceStylesheetProject],
so it's then just a cut and paste job to convert the BoostBook to
QuickBook (which IMO is a whole lot easier to edit and maintain).

--John Maddock

[endsect] [/faq]

[section:ref Quick Reference]

[c++]

[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__]]
    [[global link]          [[^'''[globalref fully::qualified::global 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__]]
    [[conditional generation]
                            [[^'''[? symbol phrase]''']]