In quickbook 1.6 and later if you wish to use a template, macro or code snippet from a file, you need to import it. This will not include any of the content from that file, but will pull templates, macros and code snippets into the current file's scope.

With quickbook files, this allows you to create template and macro libraries. For python (indicated by the .py extension), C or C++ files this allows you to include code snippets from source files, so that your code examples can be kept up to date and fully tested.

Example

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

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

The first line:

[import ../test/stub.cpp]

collects specially marked-up code snippets from 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:

[foo]
[bar]

And the result is:

This is the foo function.

This description can have paragraphs...

And any quickbook block markup.

std::string foo()
{
    // return 'em, foo man!
    return "foo";
}

This is the bar function

std::string bar()
{
    // return 'em, bar man!
    return "bar";
}

Some trailing text here

Code Snippet Markup

Note how the code snippets in 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.

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.

Special comments of the form:

/*<- this C++ comment will be ignored ->*/

or

/*<-*/ "this c++ code  will be ignored" /*->*/

or

//<-
private:
    int some_member;
//->

can be used to inhibit code from passing through to quickbook. All text between the delimeters will simply be ignored.

Comments of this form:

//=int main() {}

or

/*=foo()*/

will be displayed as code that isn't in comments. This allows you to include some code in the snippet but not actually use it when compiling your example.

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 Callouts for details. Example:

std::string foo_bar() 
{
    return "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 x
{
public:

    x() : n(0)
    {
    }

    ~x()
    {
    }

    int get() const
    {
        return n;
    }

    void set(int n_)
    {
        n = n_;
    }
};

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