<-- Copyright (c) 2002 2004 Joel de Guzman Copyright (c) 2004 Eric Niebler http://spirit.sourceforge.net/ Use, modification and distribution is subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) -->

| Home | Libraries | People | FAQ | More

### Block Level Elements

#### Document

Every document must begin with a Document Info section, which should look like this:

    [document-type The Document Title
        [quickbook 1.3]
        [version 1.0]
        [id the_document_name]
        [dirname the_document_dir]
        [copyright 2000 2002 2003 Joe Blow, Jane Doe]
        [purpose The document's reason for being]
        [category The document's category]
        [authors [Blow, Joe], [Doe, Jane]]
        [license The document's license]
        [source-mode source-type]
    ]

Where document-type is one of:

- book
- article
- library
- chapter
- part
- appendix
- preface
- qandadiv
- qandaset
- reference
- set

quickbook 1.3 declares the version of quickbook the document is written for. In its absence, version 1.1 is assumed.

`version`, `id`, `dirname`, `copyright`, `purpose`, `category`, `authors`, `license`, `last-revision` and `source-mode` are optional information.

`source-type` is a lowercase string setting the initial Source Mode. If the `source-mode` field is omitted, a default value of `c++` will be used.

#### Section

Starting a new section is accomplished with:

    [section:id The Section Title]

where id is optional. id will be the filename of the generated section. If it is not present, "The Section Title" will be normalized and become the id. Valid characters are `a-Z`, `A-Z`, `0-9` and `_`. All non-valid characters are converted to underscore and all upper-case are converted to lower case. Thus: "The Section Title" will be normalized to "the_section_title".

End a section with:

    [endsect]

Sections can nest, and that results in a hierarchy in the table of contents.

#### xinclude

You can include another XML file with:

    [xinclude file.xml]

This is useful when file.xml has been generated by Doxygen and contains your reference section.

#### Paragraphs

Paragraphs start left-flushed and are terminated by two or more newlines. No markup is needed for paragraphs. QuickBook automatically detects paragraphs from the context. Block markups [section, endsect, h1, h2, h3, h4, h5, h6, blurb, (block-quote) ':', pre, def, table and include ] may also terminate a paragraph.

#### Lists

##### Ordered lists

    # One
    # Two
    # Three

will generate:

1. One
2. Two
3. Three

##### List Hierarchies

List hierarchies are supported. Example:

    # One
    # Two
    # Three
        # Three.a
        # Three.b
        # Three.c
    # Four
        # Four.a
            # Four.a.i
            # Four.a.ii
    # Five

will generate:

1. One
2. Two
3. Three
   1. Three.a
   2. Three.b
   3. Three.c
4. Fourth
   1. Four.a
      1. Four.a.i
      2. Four.a.ii
5. Five

##### Long List Lines

Long lines will be wrapped appropriately. Example:

    # A short item.
    # A very long item. A very long item. A very long item.
      A very long item. A very long item. A very long item.
      A very long item. A very long item. A very long item.
      A very long item. A very long item. A very long item.
      A very long item. A very long item. A very long item.
    # A short item.

1. A short item.
2. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item. A very long item.
3. A short item.

##### Unordered lists

    * First
    * Second
    * Third

will generate:

- First
- Second
- Third

##### Mixed lists

Mixed lists (ordered and unordered) are supported. Example:

    # One
    # Two
    # Three
        * Three.a
        * Three.b
        * Three.c
    # Four

will generate:

1. One
2. Two
3. Three
   - Three.a
   - Three.b
   - Three.c
4. Four

And...

    # 1
        * 1.a
            # 1.a.1
            # 1.a.2
        * 1.b
    # 2
        * 2.a
        * 2.b
            # 2.b.1
            # 2.b.2
                * 2.b.2.a
                * 2.b.2.b

will generate:

1. 1
   - 1.a
     1. 1.a.1
     2. 1.a.2
   - 1.b
2. 2
   - 2.a
   - 2.b
     1. 2.b.1
     2. 2.b.2
        - 2.b.2.a
        - 2.b.2.b

#### Code

Preformatted code starts with a space or a tab. The code will be syntax highlighted according to the current Source Mode:

    #include <iostream>

    int main()
    {
        // Sample code
        std::cout << "Hello, World\n";
        return 0;
    }

    import cgi

    def cookForHtml(text):
        '''"Cooks" the input text for HTML.'''

        return cgi.escape(text)

Macros that are already defined are expanded in source code. Example:

    [def __array__ [@http://www.boost.org/doc/html/array/reference.html array]]
    [def __boost__ [@http://www.boost.org/libs/libraries.htm boost]]

        using __boost__::__array__;

Generates:

    using boost::array;

#### Escaping Back To QuickBook

Inside code, code blocks and inline code, QuickBook does not allow any markup to avoid conflicts with the target syntax (e.g. c++). In case you need to switch back to QuickBook markup inside code, you can do so using a language specific escape-back delimiter. In C++ and Python, the delimiter is the double tick (back-quote): "``" and "``". Example:

    void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
    {
    }

Will generate:

    void foo()
    {
    }

When escaping from code to QuickBook, only phrase level markups are allowed. Block level markups like lists, tables etc. are not allowed.

#### Preformatted

Sometimes, you don't want some preformatted text to be parsed as C++. In such cases, use the `[pre ... ]` markup block.

    [pre

        Some *preformatted* text                    Some *preformatted* text

            Some *preformatted* text            Some *preformatted* text

                Some *preformatted* text    Some *preformatted* text

    ]

Spaces, tabs and newlines are rendered as-is. Unlike all quickbook block level markup, pre (and Code) are the only ones that allow multiple newlines. The markup above will generate:

    Some preformatted text                    Some preformatted text

        Some preformatted text            Some preformatted text

            Some preformatted text    Some preformatted text

Notice that unlike Code, phrase markup such as font style is still permitted inside `pre` blocks.

#### Blockquote

    [:sometext...]

> Indents the paragraph. This applies to one paragraph only.

#### Admonitions

    [note This is a note]
    [tip This is a tip]
    [important This is important]
    [caution This is a caution]
    [warning This is a warning]

generates DocBook admonitions:

| Note
This is a note

| Tip
This is a tip

| Important
This is important

| Caution
This is a caution

| Warning
This is a warning

These are the only admonitions supported by DocBook. So, for example `[information This is some information]` is unlikely to produce the desired effect.

#### Headings

    [h1 Heading 1]
    [h2 Heading 2]
    [h3 Heading 3]
    [h4 Heading 4]
    [h5 Heading 5]
    [h6 Heading 6]

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

##### Heading 6

Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized names with `name="section_id.normalized_header_text"` (i.e. valid characters are `a-z`, `A-Z`, `0-9` and `_`. All non-valid characters are converted to underscore and all upper-case are converted to lower-case. For example: Heading 1 in section Section 2 will be normalized to `section_2.heading_1`). You can use:

    [link section_id.normalized_header_text The link text]

to link to them. See Anchor links and Section for more info.

#### Macros

    [def macro_identifier some text]

When a macro is defined, the identifier replaces the text anywhere in the file, in paragraphs, in markups, etc. macro_identifier is a string of non-white space characters except ']' while the replacement text can be any phrase (even marked up). Example:

    [def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
    sf_logo

Now everywhere the sf_logo is placed, the picture will be inlined.

It's a good idea to use macro identifiers that are distinguishable. For instance, in this document, macro identifiers have two leading and trailing underscores (e.g. `__spirit__` ). The reason is to avoid unwanted macro replacement.

Links (URLS) and images are good candidates for macros. 1) They tend to change a lot. It is a good idea to place all links and images in one place near the top to make it easy to make changes. 2) The syntax is not pretty. It's easier to read and write, e.g. `__spirit__` than `[@http://spirit.sourceforge.net Spirit]` .

Some more examples:

    [def :-)            [$theme/smiley.png]]
    [def __spirit__     [@http://spirit.sourceforge.net Spirit]]

(See Images and Links)

Invoking these macros:

    Hi __spirit__  :-)

will generate this:

Hi Spirit

#### Predefined Macros

Quickbook has some predefined macros that you can already use.

#### Predefined Macros

Macro | Meaning | Example
--- | --- | ---
__DATE__ | Today's date | 2006-Aug-27
__TIME__ | The current time | 06:24:19 AM
__FILENAME__ | Quickbook source filename | /home/daniel/src/boost-1.34/tools/quickbook/doc/quickbook.qbk

#### Blurbs

    [blurb :-) [*An eye catching advertisement or note...]\n\n
        __spirit__ is an object-oriented recursive-descent parser generator framework
        implemented using template meta-programming techniques. Expression templates
        allow us to approximate the syntax of Extended Backus-Normal Form (EBNF)
        completely in C++.
    ]

will generate this:

An eye catching advertisement or note... Spirit is an object-oriented recursive-descent parser generator framework implemented using template meta-programming techniques. Expression templates allow us to approximate the syntax of Extended Backus-Normal Form (EBNF) completely in C++.

#### Tables

    [table A Simple Table
        [[Heading 1] [Heading 2] [Heading 3]]
        [[R0-C0]     [R0-C1]     [R0-C2]]
        [[R1-C0]     [R1-C1]     [R1-C2]]
        [[R2-C0]     [R2-C1]     [R2-C2]]
    ]

will generate:

#### A Simple Table

Heading 1 | Heading 2 | Heading 3
--- | --- | ---
R0-C0 | R0-C1 | R0-C2
R2-C0 | R2-C1 | R2-C2
R3-C0 | R3-C1 | R3-C2

The table title is optional. The first row of the table is automatically treated as the table header; that is, it is wrapped in `<thead>...</thead>` XML tags. Note that unlike the original QuickDoc, the columns are nested in [ cells... ]. The syntax is free-format and allows big cells to be formatted nicely. Example:

    [table Table with fat cells
        [[Heading 1] [Heading 2]]
        [
            [Row 0, Col 0: a small cell]
            [
                Row 0, Col 1:
                A very big cell...A very big cell...A very big cell...
                A very big cell...A very big cell...A very big cell...
                A very big cell...A very big cell...A very big cell...
            ]
        ]
        [
            [Row 1, Col 0: a small cell]
            [Row 1, Col 1: a small cell]
        ]
    ]

and thus:

#### Table with fat cells

Heading 1 | Heading 2
--- | ---
Row 0, Col 0: a small cell | Row 0, Col 1: A very big cell...A very big cell...A very big cell... A very big cell...A very big cell...A very big cell... A very big cell...A very big cell...A very big cell...
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:

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

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

#### Table with code

Comment | Code
--- | ---

My first program

    #include <iostream>

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

#### Variable Lists

    [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:

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".

#### Include

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

    [include someother.qbk]

The included file will be processed as if it had be 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.

As the number of included QuickBook files grows, so too does the likelihood of two sections having the same name. Since QuickBook generates an anchor for each section based on the section name, it is possible to end up with two identically named anchors, leading to link ambiguities. To resolve these ambiguities, the `[include]` directive lets you specify a document id to use for the included file. You can use it like this:

    [include:someid someother.qbk]

When using this form, all auto-generated anchors will use "someid" as a unique prefix. So for instance, if there is a 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]`.

| Copyright © 2002, 2004 Joel de Guzman, Eric Niebler