mirror of
https://github.com/boostorg/quickbook.git
synced 2026-01-27 07:02:15 +00:00
106 lines
2.9 KiB
Plaintext
106 lines
2.9 KiB
Plaintext
[/
|
|
Copyright 2002,2004,2006 Joel de Guzman, Eric Niebler
|
|
Copyright 2010-2011 Daniel James
|
|
|
|
Distributed under 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])
|
|
]
|
|
|
|
[chapter Basic Syntax
|
|
[quickbook 1.5]
|
|
[id quickbook.syntax]
|
|
[source-mode teletype]
|
|
]
|
|
|
|
Let's start with a simple quickbook document to give you an idea of what
|
|
one looks like, and what it means. Later sections will describe the
|
|
different parts in more detail:
|
|
|
|
[/TODO: Callouts would really help here, need to look into implementing
|
|
the required markup?]
|
|
|
|
[library An example library
|
|
[quickbook 1.5]
|
|
]
|
|
|
|
Since this is just an example, there isn't anything to
|
|
document and this is mostly just /verbiage/.
|
|
|
|
Here's some predictable code:
|
|
|
|
#include <iostream>
|
|
|
|
int main()
|
|
{
|
|
std::cout << "Hello standard example!\n";
|
|
}
|
|
|
|
[template example_library[]
|
|
|
|
[*TODO: display the title?]
|
|
|
|
Since this is just an example, there isn't anything to
|
|
document and this is mostly just /verbiage/.
|
|
|
|
Here's some predictable code:
|
|
|
|
#include <iostream>
|
|
|
|
int main()
|
|
{
|
|
std::cout << "Hello standard example!\n";
|
|
}
|
|
]
|
|
|
|
This starts with the [link ref-docinfo document info block] in square
|
|
brackets. `library` is the type of the document, followed by the title
|
|
on the same line. After that comes the the document metadata. In this
|
|
case, we just have the version of quickbook to be used. This
|
|
documentation mostly describes the current version quickbook 1.5.
|
|
|
|
This is then followed by two paragraphs, which are separated by blank
|
|
lines. The slashes around the word 'verbiage' cause it to be displayed
|
|
in italics. Then finally, there is a block of code which is indented to
|
|
tell quickbook that it is a code block.
|
|
|
|
This generates: [:[example_library]]
|
|
|
|
[*TODO: Move the following to a more detailled section?]
|
|
|
|
Some blocks have special mark-ups. Blocks, except code snippets which
|
|
have their own grammar (C++ or Python), are composed of one or more
|
|
phrases. A phrase can be a simple contiguous run of characters. Phrases
|
|
can have special mark-ups. Marked up phrases can recursively contain
|
|
other phrases, but cannot contain blocks. A terminal is a self contained
|
|
block-level or phrase-level element that does not nest anything.
|
|
|
|
Blocks, in general, are delimited by two end-of-lines (the block terminator).
|
|
Phrases in each block cannot contain a block terminator. This way, syntax errors
|
|
such as un-matched closing brackets do not go haywire and corrupt anything past
|
|
a single block.
|
|
|
|
[section Comments]
|
|
|
|
Can be placed anywhere.
|
|
|
|
[pre
|
|
'''[/ comment (no output generated) ]'''
|
|
]
|
|
|
|
[/ for testing only... ]
|
|
|
|
[pre
|
|
'''[/ comments can be nested [/ some more here] ]'''
|
|
]
|
|
|
|
[/ for testing [/ only ] ]
|
|
|
|
[pre
|
|
'''[/ Quickbook blocks can nest inside comments. [*Comment this out too!] ]'''
|
|
]
|
|
|
|
[/ for testing [*only ] ]
|
|
|
|
[endsect] [/Comments]
|