mirror of
https://github.com/boostorg/quickbook.git
synced 2026-01-27 19:12:17 +00:00
1870 lines
73 KiB
XML
Executable File
1870 lines
73 KiB
XML
Executable File
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE library PUBLIC "-//Boost//DTD BoostBook XML V1.0//EN" "http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<article id="quickbook" name="quickbook" dirname="quickbook" last-revision="DEBUG MODE Date: 2000/12/20 12:00:00 $"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<articleinfo>
|
|
<author>
|
|
<firstname>Joel</firstname> <surname>de Guzman</surname>
|
|
</author>
|
|
<author>
|
|
<firstname>Eric</firstname> <surname>Niebler</surname>
|
|
</author>
|
|
<copyright>
|
|
<year>2002</year> <year>2004</year> <holder>Joel de Guzman, Eric Niebler</holder>
|
|
</copyright>
|
|
<legalnotice>
|
|
<para>
|
|
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
|
file LICENSE_1_0.txt or copy at <ulink url="http://www.boost.org/LICENSE_1_0.txt">http://www.boost.org/LICENSE_1_0.txt</ulink>)
|
|
</para>
|
|
</legalnotice>
|
|
<articlepurpose>
|
|
<emphasis>WikiWiki</emphasis> style documentation tool
|
|
</articlepurpose>
|
|
</articleinfo>
|
|
<title>quickbook 1.3</title>
|
|
<section id="quickbook.intro">
|
|
<title> Introduction</title>
|
|
<blockquote>
|
|
<para>
|
|
<emphasis role="bold"><emphasis><quote>Why program by hand in five days what
|
|
you can spend five years of your life automating?</quote></emphasis></emphasis><sbr/>
|
|
<sbr/> -- Terrence Parr, author ANTLR/PCCTS
|
|
</para>
|
|
</blockquote>
|
|
<para>
|
|
Well, QuickBook started as a weekend hack. It was originally intended to be
|
|
a sample application using <ulink url="http://spirit.sourceforge.net">Spirit</ulink>.
|
|
What is it? What you are viewing now, this documentation, is autogenerated
|
|
by QuickBook. These files were generated from one master:
|
|
</para>
|
|
<blockquote>
|
|
<para>
|
|
<ulink url="../quickbook.qbk">quickbook.qbk</ulink>
|
|
</para>
|
|
</blockquote>
|
|
<para>
|
|
Originally named QuickDoc, this funky tool that never dies evolved into a funkier
|
|
tool thanks to Eric Niebler who resurrected the project making it generate
|
|
<ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
|
|
instead of HTML. The <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
|
|
documentation format is an extension of <ulink url="http://www.docbook.org/">DocBook</ulink>,
|
|
an SGML or XML based format for describing documentation.
|
|
</para>
|
|
<para>
|
|
QuickBook is a WikiWiki style documentation tool geared towards C++ documentation
|
|
using simple rules and markup for simple formatting tasks. QuickBook extends
|
|
the WikiWiki concept. Like the WikiWiki, QuickBook documents are simple text
|
|
files. A single QuickBook document can generate a fully linked set of nice
|
|
HTML and PostScript/PDF documents complete with images and syntax- colorized
|
|
source code.
|
|
</para>
|
|
<para>
|
|
Features include:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
generate <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
|
|
xml, to generate HTML, PostScript and PDF
|
|
</listitem>
|
|
<listitem>
|
|
simple markup to link to Doxygen-generated entities
|
|
</listitem>
|
|
<listitem>
|
|
macro system for simple text substitution
|
|
</listitem>
|
|
<listitem>
|
|
simple markup for italics, bold, preformatted, blurbs, code samples, tables,
|
|
URLs, anchors, images, etc.
|
|
</listitem>
|
|
<listitem>
|
|
automatic syntax coloring of code samples
|
|
</listitem>
|
|
<listitem>
|
|
CSS support
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section id="quickbook.change_log">
|
|
<title> Change Log</title> <anchor id="quickbook.change_log.version_1_3" />
|
|
<bridgehead renderas="sect3">
|
|
Version 1.3
|
|
</bridgehead>
|
|
<itemizedlist>
|
|
<listitem>
|
|
Quickbook file inclusion [include].
|
|
</listitem>
|
|
<listitem>
|
|
Better xml output (pretty layout). Check out the generated XML.
|
|
</listitem>
|
|
<listitem>
|
|
Regression testing facility: to make sure your document will always be compatible
|
|
(full backward compatibility) regardless of changes to QuickBook.
|
|
</listitem>
|
|
<listitem>
|
|
Code cleanup and refactoring.
|
|
</listitem>
|
|
<listitem>
|
|
Allow phrase markup in the doc-info.
|
|
</listitem>
|
|
<listitem>
|
|
Preformatted code blocks via ``code`` (double ticks) allows code in tables
|
|
and lists, for example.
|
|
</listitem>
|
|
<listitem>
|
|
Quickbook versioning; allows full backward compatibility. You have to add
|
|
[quickbook 1.3] to the doc-info header to enable the new features. Without
|
|
this, QuickBook will assume that the document is a pre-1.3 document.
|
|
</listitem>
|
|
<listitem>
|
|
Better (intuitive) paragraph termination. Some markups may terminate a paragraph.
|
|
Example:
|
|
<programlisting>
|
|
<phrase role="special">[</phrase><phrase role="identifier">section</phrase> <phrase role="identifier">x</phrase><phrase role="special">]</phrase>
|
|
<phrase role="identifier">blah</phrase><phrase role="special">...</phrase>
|
|
<phrase role="special">[</phrase><phrase role="identifier">endsect</phrase><phrase role="special">]</phrase></programlisting>
|
|
</listitem>
|
|
<listitem>
|
|
Fully qualified section and headers. Subsection names are concatenated to
|
|
the ID to avoid clashing. Example: <code><phrase role="identifier">doc_name</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">sect_name</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">sub_sect_name</phrase><phrase
|
|
role="special">.</phrase><phrase role="identifier">sub_sub_sect_name</phrase></code>
|
|
</listitem>
|
|
<listitem>
|
|
Better &nbsp; and whitespace handling in code snippets.
|
|
</listitem>
|
|
<listitem>
|
|
[xinclude] fixes up the relative path to the target XML file when input_directory
|
|
is not the same as the output_directory.
|
|
</listitem>
|
|
<listitem>
|
|
Allow untitled tables.
|
|
</listitem>
|
|
<listitem>
|
|
Allow phrase markups in section titles.
|
|
</listitem>
|
|
<listitem>
|
|
Allow escaping back to QuickBook from code, code blocks and inline code.
|
|
</listitem>
|
|
<listitem>
|
|
Footnotes, with the [footnote This is the footnote] syntax.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section id="quickbook.syntax">
|
|
<title> Syntax Summary</title>
|
|
<para>
|
|
A QuickBook document is composed of one or more blocks. An example of a block
|
|
is the paragraph or a C++ code snippet. 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.
|
|
</para>
|
|
<para>
|
|
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.
|
|
</para>
|
|
<section id="quickbook.syntax.comments">
|
|
<title>Comments</title>
|
|
<para>
|
|
Can be placed anywhere.
|
|
</para>
|
|
|
|
<programlisting>[/ comment (no output generated) ]
|
|
</programlisting>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase">
|
|
<title> Phrase Level Elements</title>
|
|
<section id="quickbook.syntax.phrase.font_styles">
|
|
<title>Font Styles</title>
|
|
<programlisting>['italic], [*bold], [_underline], [^teletype], [-strikethrough]
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
<emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
|
|
role="underline">underline</emphasis>, <literal>teletype</literal>, <emphasis
|
|
role="strikethrough">strikethrough</emphasis>
|
|
</para>
|
|
<para>
|
|
Like all non-terminal phrase level elements, this can of course be nested:
|
|
</para>
|
|
|
|
<programlisting>[*['bold-italic]]
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
<emphasis role="bold"><emphasis>bold-italic</emphasis></emphasis>
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.quotations">
|
|
<title>Quotations</title>
|
|
<programlisting>["A question that sometimes drives me hazy: am I or are the others crazy?]--Einstein
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
<quote>A question that sometimes drives me hazy: am I or are the others
|
|
crazy?</quote>--Einstein
|
|
</para>
|
|
<para>
|
|
Note the proper left and right quote marks. Also, while you can simply
|
|
use ordinary quote marks like "quoted", our quotation, above,
|
|
will generate correct DocBook quotations (e.g. <quote>quoted</quote>).
|
|
</para>
|
|
<para>
|
|
Like all phrase elements, quotations may be nested. Example:
|
|
</para>
|
|
|
|
<programlisting>["Here's the rule for bargains: ["Do other men, for they would do you.] That's
|
|
the true business precept.]
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
<quote>Here's the rule for bargains: <quote>Do other men, for they would
|
|
do you.</quote> That's the true business precept.</quote>
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.simple_formatting">
|
|
<title>Simple formatting</title>
|
|
<para>
|
|
Simple markup for formatting text, common in many applications, is now
|
|
supported:
|
|
</para>
|
|
|
|
<programlisting>/italic/, *bold*, _underline_, =teletype=
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
<emphasis>italic</emphasis>, <emphasis role="bold">bold</emphasis>, <emphasis
|
|
role="underline">underline</emphasis>, <literal>teletype</literal>
|
|
</para>
|
|
<para>
|
|
Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives
|
|
are much stricter.
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
Simple markups cannot nest. You can combine a simple markup with a nestable
|
|
markup.
|
|
</listitem>
|
|
<listitem>
|
|
A non-space character must follow the leading markup
|
|
</listitem>
|
|
<listitem>
|
|
A non-space character must precede the trailing markup
|
|
</listitem>
|
|
<listitem>
|
|
A space or a punctuation must follow the trailing markup
|
|
</listitem>
|
|
<listitem>
|
|
If the matching markup cannot be found within a line, the formatting
|
|
will not be applied. This is to ensure that un-matched formatting markups,
|
|
which can be a common mistake, does not corrupt anything past a single
|
|
line. We do not want the rest of the document to be rendered bold just
|
|
because we forgot a trailing '*'.
|
|
</listitem>
|
|
<listitem>
|
|
A line starting with the star will be interpreted as an unordered list.
|
|
See <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
|
|
lists</link>.
|
|
</listitem>
|
|
</itemizedlist>
|
|
<informaltable frame="all">
|
|
<bridgehead renderas="sect4">
|
|
<phrase role="table-title">More Formatting Samples</phrase>
|
|
</bridgehead>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Markup</entry><entry>Result</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry><literal>*Bold*</literal></entry><entry><emphasis role="bold">Bold</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>*Is bold*</literal></entry><entry><emphasis role="bold">Is
|
|
bold</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>* Not bold* *Not bold * * Not bold *</literal></entry><entry>*
|
|
Not bold* *Not bold * * Not bold *</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>This*Isn't*Bold (no bold)</literal></entry><entry>This*Isn't*Bold
|
|
(no bold)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>(*Bold Inside*) (parenthesis not bold)</literal></entry><entry>(<emphasis
|
|
role="bold">Bold Inside</emphasis>) (parenthesis not bold)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>*(Bold Outside)* (parenthesis bold)</literal></entry><entry><emphasis
|
|
role="bold">(Bold Outside)</emphasis> (parenthesis bold)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>3*4*5 = 60 (no bold)</literal></entry><entry>3*4*5
|
|
= 60 (no bold)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>3 * 4 * 5 = 60 (no bold)</literal></entry><entry>3
|
|
* 4 * 5 = 60 (no bold)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>3 *4* 5 = 60 (4 is bold)</literal></entry><entry>3
|
|
<emphasis role="bold">4</emphasis> 5 = 60 (4 is bold)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>*This is bold* this is not *but this is*</literal></entry><entry><emphasis
|
|
role="bold">This is bold</emphasis> this is not <emphasis role="bold">but
|
|
this is</emphasis></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>*This is bold*.</literal></entry><entry><emphasis
|
|
role="bold">This is bold</emphasis>.</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>*B*. (bold B)</literal></entry><entry><emphasis role="bold">B</emphasis>.
|
|
(bold B)</entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>['*Bold-Italic*]</literal></entry><entry><emphasis><emphasis
|
|
role="bold">Bold-Italic</emphasis></emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<informaltable frame="all">
|
|
<?dbhtml table-width="74%" ?>
|
|
<tgroup cols="1">
|
|
<tbody>
|
|
<row>
|
|
<entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>note</phrase>
|
|
</textobject>
|
|
</inlinemediaobject> Thanks to David Barrett, author of <ulink url="http://quinthar.com/qwikiwiki/index.php?page=Home">Qwiki</ulink>,
|
|
for sharing these samples and teaching me these obscure formatting
|
|
rules. I wasn't sure at all if <ulink url="http://spirit.sourceforge.net">Spirit</ulink>,
|
|
being more or less a formal EBNF parser, can handle the context sensitivity
|
|
and ambiguity.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.inline_code">
|
|
<title>Inline code</title>
|
|
<para>
|
|
Inlining code in paragraphs is quite common when writing C++ documentation.
|
|
We provide a very simple markup for this. For example, this:
|
|
</para>
|
|
|
|
<programlisting>This text has inlined code `int main() { return 0; }` in it.
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
This text has inlined code <code><phrase role="keyword">int</phrase> <phrase
|
|
role="identifier">main</phrase><phrase role="special">()</phrase> <phrase
|
|
role="special">{</phrase> <phrase role="keyword">return</phrase> <phrase
|
|
role="number">0</phrase><phrase role="special">;</phrase> <phrase
|
|
role="special">}</phrase></code> in it. The code will be syntax highlighted.
|
|
</para>
|
|
<informaltable frame="all">
|
|
<?dbhtml table-width="74%" ?>
|
|
<tgroup cols="1">
|
|
<tbody>
|
|
<row>
|
|
<entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>note</phrase>
|
|
</textobject>
|
|
</inlinemediaobject> Note that we simply enclose the code with the
|
|
tick: <literal>"`"</literal>, not the single quote: <code><phrase
|
|
role="string">"'"</phrase></code>. Note too that <literal>`some
|
|
code`</literal> is preferred over <literal>[^some code]</literal>.
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.code_blocks">
|
|
<title>Code blocks</title>
|
|
<para>
|
|
Preformatted code simply starts with a space or a tab (See <link linkend="quickbook.syntax.block.code">Code</link>).
|
|
However, such a simple syntax cannot be used as phrase elements in lists
|
|
(See <link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
|
|
lists</link> and <link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
|
|
lists</link>), tables (See <link linkend="quickbook.syntax.block.tables">Tables</link>),
|
|
etc. Inline code (see above) can. The problem is, inline code does not
|
|
allow formatting with newlines, spaces, and tabs. These are lost.
|
|
</para>
|
|
<para>
|
|
We provide a phrase level markup that is a mix between the two. By using
|
|
the double-tick, instead of the single-tick, we are telling QuickBook to
|
|
use preformatted blocks of code. Example:
|
|
</para>
|
|
|
|
<programlisting>``
|
|
#include <iostream>
|
|
|
|
int main()
|
|
{
|
|
std::cout << "Hello, World!" << std::endl;
|
|
return 0;
|
|
}
|
|
``
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
|
|
<programlisting>
|
|
<phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.source_mode">
|
|
<title>Source Mode</title>
|
|
<para>
|
|
If a document contains more than one type of source code then the source
|
|
mode may be changed dynamically as the document is processed. All QuickBook
|
|
documents are initially in C++ mode by default, though an alternative initial
|
|
value may be set in the <link linkend="quickbook.syntax.block.document">Document</link>
|
|
section.
|
|
</para>
|
|
<para>
|
|
To change the source mode, use the <literal>[source-mode]</literal> markup,
|
|
where <literal>source-mode</literal> is one of the supported modes. For
|
|
example, this:
|
|
</para>
|
|
|
|
<programlisting>Python's [python] `import` is rather like C++'s [c++] `#include`. A
|
|
C++ comment `// looks like this` whereas a Python comment [python]
|
|
`# looks like this`.
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
Python's <code><phrase role="keyword">import</phrase></code> is rather
|
|
like C++'s <code><phrase role="preprocessor">#include</phrase></code>.
|
|
A C++ comment <code><phrase role="comment">// looks like this</phrase></code>
|
|
whereas a Python comment <code><phrase role="comment">#looks like this</phrase></code>.
|
|
</para>
|
|
<informaltable frame="all">
|
|
<bridgehead renderas="sect4">
|
|
<phrase role="table-title">Supported Source Modes</phrase>
|
|
</bridgehead>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Mode</entry><entry>Source Mode Markup</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>C++</entry><entry><literal>[c++]</literal></entry>
|
|
</row>
|
|
<row>
|
|
<entry>Python</entry><entry><literal>[python]</literal></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<informaltable frame="all">
|
|
<?dbhtml table-width="74%" ?>
|
|
<tgroup cols="1">
|
|
<tbody>
|
|
<row>
|
|
<entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>note</phrase>
|
|
</textobject>
|
|
</inlinemediaobject> The source mode strings are lowercase.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.line_break">
|
|
<title>line-break</title>
|
|
<programlisting>[br]
|
|
</programlisting>
|
|
<informaltable frame="all">
|
|
<?dbhtml table-width="74%" ?>
|
|
<tgroup cols="1">
|
|
<tbody>
|
|
<row>
|
|
<entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/note.png"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>note</phrase>
|
|
</textobject>
|
|
</inlinemediaobject> Note that <code><phrase role="special">\</phrase><phrase
|
|
role="identifier">n</phrase></code> is now preferred over <code><phrase
|
|
role="special">[</phrase><phrase role="identifier">br</phrase><phrase
|
|
role="special">]</phrase></code>.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.anchors">
|
|
<title>Anchors</title>
|
|
<programlisting>[#named_anchor]
|
|
</programlisting>
|
|
<para>
|
|
A named anchor is a hook that can be referenced by a link elsewhere in
|
|
the document. You can then reference an anchor with <literal>[link named_anchor
|
|
Some link text]</literal>. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor
|
|
links</link>, <link linkend="quickbook.syntax.block.section">Section</link>
|
|
and <link linkend="quickbook.syntax.block.headings">Heading</link>.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.links">
|
|
<title>Links</title>
|
|
<programlisting>[@http://www.boost.org this is [*boost's] website....]
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
<ulink url="http://www.boost.org">this is <emphasis role="bold">boost's</emphasis>
|
|
website....</ulink>
|
|
</para>
|
|
<para>
|
|
URL links where the link text is the link itself is common. Example:
|
|
</para>
|
|
|
|
<programlisting>see http://spirit.sourceforge.net/
|
|
</programlisting>
|
|
<para>
|
|
so, when the text is absent in a link markup, the URL is assumed. Example:
|
|
</para>
|
|
|
|
<programlisting>see [@http://spirit.sourceforge.net/]
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<para>
|
|
see <ulink url="http://spirit.sourceforge.net/">http://spirit.sourceforge.net/</ulink>
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.anchor_links">
|
|
<title>Anchor links</title>
|
|
<para>
|
|
You can link within a document using:
|
|
</para>
|
|
|
|
<programlisting>[link section_id.normalized_header_text The link text]
|
|
</programlisting>
|
|
<para>
|
|
See sections <link linkend="quickbook.syntax.block.section">Section</link>
|
|
and <link linkend="quickbook.syntax.block.headings">Heading</link> for
|
|
more info.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.refentry_links">
|
|
<title>refentry links</title>
|
|
<para>
|
|
In addition, you can link internally to an XML refentry like:
|
|
</para>
|
|
|
|
<programlisting>[link xml.refentry The link text]
|
|
</programlisting>
|
|
<para>
|
|
This gets converted into <literal><link linkend="xml.refentry">The
|
|
link text</link></literal>.
|
|
</para>
|
|
<para>
|
|
Like URLs, the link text is optional. If this is not present, the link
|
|
text will automatically be the refentry. Example:
|
|
</para>
|
|
|
|
<programlisting>[link xml.refentry]
|
|
</programlisting>
|
|
<para>
|
|
This gets converted into <literal><link linkend="xml.refentry">xml.refentry</link></literal>.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.code_links">
|
|
<title> Code Links</title>
|
|
<para>
|
|
If you want to link to a function, class, member, enum or header in the
|
|
reference section, you can use:
|
|
</para>
|
|
|
|
<programlisting>[funcref fully::qualified::function_name The link text]
|
|
[classref fully::qualified::class_name The link text]
|
|
[memberref fully::qualified::member_name The link text]
|
|
[enumref fully::qualified::enum_name The link text]
|
|
[headerref path/to/header.hpp The link text]
|
|
</programlisting>
|
|
<para>
|
|
Again, the link text is optional. If this is not present, the link text
|
|
will automatically be the function, class, member or enum. Example:
|
|
</para>
|
|
|
|
<programlisting>[classref boost::bar::baz]
|
|
</programlisting>
|
|
<para>
|
|
would have "boost::bar::baz" as the link text.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.escape">
|
|
<title>Escape</title>
|
|
<para>
|
|
The escape mark-up is used when we don't want to do any processing.
|
|
</para>
|
|
|
|
<programlisting>'''
|
|
escape (no processing/formatting)
|
|
'''
|
|
</programlisting>
|
|
<para>
|
|
Escaping allows us to pass XML markup to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>
|
|
or <ulink url="http://www.docbook.org/">DocBook</ulink>. For example:
|
|
</para>
|
|
|
|
<programlisting>'''
|
|
<emphasis role="bold">This is direct XML markup</emphasis>
|
|
'''
|
|
</programlisting>
|
|
<para>
|
|
<emphasis role="bold">This is direct XML markup</emphasis>
|
|
</para>
|
|
<informaltable frame="all">
|
|
<?dbhtml table-width="74%" ?>
|
|
<tgroup cols="1">
|
|
<tbody>
|
|
<row>
|
|
<entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/alert.png"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>alert</phrase>
|
|
</textobject>
|
|
</inlinemediaobject> Be careful when using the escape. The text must
|
|
conform to <ulink url="http://www.boost.org/doc/html/boostbook.html">BoostBook</ulink>/<ulink
|
|
url="http://www.docbook.org/">DocBook</ulink> syntax.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.single_char_escape">
|
|
<title>Single char escape</title>
|
|
<para>
|
|
The backslash may be used to escape a single punctuation character. The
|
|
punctuation immediately after the backslash is passed without any processing.
|
|
This is useful when we need to escape QuickBook punctuations such as <code><phrase
|
|
role="special">[</phrase></code> and <code><phrase role="special">]</phrase></code>.
|
|
For example, how do you escape the triple quote? Simple: <literal>\'\'\'</literal>
|
|
</para>
|
|
<para>
|
|
<code><phrase role="special">\</phrase><phrase role="identifier">n</phrase></code>
|
|
has a special meaning. It is used to generate line breaks. Note that <code><phrase
|
|
role="special">\</phrase><phrase role="identifier">n</phrase></code> is
|
|
now preferred over <code><phrase role="special">[</phrase><phrase role="identifier">br</phrase><phrase
|
|
role="special">]</phrase></code>.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.images">
|
|
<title>Images</title>
|
|
<programlisting>[$image.jpg]
|
|
</programlisting>
|
|
</section>
|
|
<section id="quickbook.syntax.phrase.footnotes">
|
|
<title>Footnotes</title>
|
|
<para>
|
|
As of version 1.3, QuickBook supports footnotes. Just put the text of the
|
|
footnote in a <code><phrase role="special">[</phrase><phrase role="identifier">footnote</phrase><phrase
|
|
role="special">]</phrase></code> block, and the text will be put at the
|
|
bottom of the current page. For example, this:
|
|
</para>
|
|
|
|
<programlisting>[footnote A sample footnote]
|
|
</programlisting>
|
|
<para>
|
|
will generate this
|
|
<footnote>
|
|
<para>
|
|
A sample footnote
|
|
</para>
|
|
</footnote>
|
|
.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
<section id="quickbook.syntax.block">
|
|
<title> Block Level Elements</title>
|
|
<section id="quickbook.syntax.block.document">
|
|
<title>Document</title>
|
|
<para>
|
|
Every document must begin with a Document Info section, which should look
|
|
like this:
|
|
</para>
|
|
|
|
<programlisting>[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]
|
|
]
|
|
</programlisting>
|
|
<para>
|
|
Where document-type is one of:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
book
|
|
</listitem>
|
|
<listitem>
|
|
article
|
|
</listitem>
|
|
<listitem>
|
|
library
|
|
</listitem>
|
|
<listitem>
|
|
chapter
|
|
</listitem>
|
|
<listitem>
|
|
part
|
|
</listitem>
|
|
<listitem>
|
|
appendix
|
|
</listitem>
|
|
<listitem>
|
|
preface
|
|
</listitem>
|
|
<listitem>
|
|
qandadiv
|
|
</listitem>
|
|
<listitem>
|
|
qandaset
|
|
</listitem>
|
|
<listitem>
|
|
reference
|
|
</listitem>
|
|
<listitem>
|
|
set
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
quickbook 1.3 declares the version of quickbook the document is written
|
|
for. In its absence, version 1.1 is assumed.
|
|
</para>
|
|
<para>
|
|
<literal>version</literal>, <literal>id</literal>, <literal>dirname</literal>,
|
|
<literal>copyright</literal>, <literal>purpose</literal>, <literal>category</literal>,
|
|
<literal>authors</literal>, <literal>license</literal>, <literal>last-revision</literal>
|
|
and <literal>source-mode</literal> are optional information.
|
|
</para>
|
|
<para>
|
|
<literal>source-type</literal> is a lowercase string setting the initial
|
|
<link linkend="quickbook.syntax.phrase.source_mode">Source Mode</link>.
|
|
If the <literal>source-mode</literal> field is omitted, a default value
|
|
of <literal>c++</literal> will be used.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.section">
|
|
<title>Section</title>
|
|
<para>
|
|
Starting a new section is accomplished with:
|
|
</para>
|
|
|
|
<programlisting>[section:id The Section Title]
|
|
</programlisting>
|
|
<para>
|
|
where <emphasis>id</emphasis> 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 <literal>a-Z</literal>,
|
|
<literal>A-Z</literal>, <literal>0-9</literal> and <literal>_</literal>.
|
|
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".
|
|
</para>
|
|
<para>
|
|
End a section with:
|
|
</para>
|
|
|
|
<programlisting>[endsect]
|
|
</programlisting>
|
|
<para>
|
|
Sections can nest, and that results in a hierarchy in the table of contents.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.xinclude">
|
|
<title>xinclude</title>
|
|
<para>
|
|
You can include another XML file with:
|
|
</para>
|
|
|
|
<programlisting>[xinclude file.xml]
|
|
</programlisting>
|
|
<para>
|
|
This is useful when file.xml has been generated by Doxygen and contains
|
|
your reference section.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.paragraphs">
|
|
<title>Paragraphs</title>
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.lists">
|
|
<title>Lists</title>
|
|
<section id="quickbook.syntax.block.lists.ordered_lists">
|
|
<title>Ordered lists</title>
|
|
<programlisting># One
|
|
# Two
|
|
# Three
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
One
|
|
</listitem>
|
|
<listitem>
|
|
Two
|
|
</listitem>
|
|
<listitem>
|
|
Three
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
<section id="quickbook.syntax.block.lists.list_hierarchies">
|
|
<title>List Hierarchies</title>
|
|
<para>
|
|
List hierarchies are supported. Example:
|
|
</para>
|
|
|
|
<programlisting># One
|
|
# Two
|
|
# Three
|
|
# Three.a
|
|
# Three.b
|
|
# Three.c
|
|
# Four
|
|
# Four.a
|
|
# Four.a.i
|
|
# Four.a.ii
|
|
# Five
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
One
|
|
</listitem>
|
|
<listitem>
|
|
Two
|
|
</listitem>
|
|
<listitem>
|
|
Three
|
|
<orderedlist>
|
|
<listitem>
|
|
Three.a
|
|
</listitem>
|
|
<listitem>
|
|
Three.b
|
|
</listitem>
|
|
<listitem>
|
|
Three.c
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
<listitem>
|
|
Fourth
|
|
<orderedlist>
|
|
<listitem>
|
|
Four.a
|
|
<orderedlist>
|
|
<listitem>
|
|
Four.a.i
|
|
</listitem>
|
|
<listitem>
|
|
Four.a.ii
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
<listitem>
|
|
Five
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
<section id="quickbook.syntax.block.lists.long_list_lines">
|
|
<title>Long List Lines</title>
|
|
<para>
|
|
Long lines will be wrapped appropriately. Example:
|
|
</para>
|
|
|
|
<programlisting># 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.
|
|
</programlisting>
|
|
<orderedlist>
|
|
<listitem>
|
|
A short item.
|
|
</listitem>
|
|
<listitem>
|
|
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.
|
|
</listitem>
|
|
<listitem>
|
|
A short item.
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
<section id="quickbook.syntax.block.lists.unordered_lists">
|
|
<title>Unordered lists</title>
|
|
<programlisting>* First
|
|
* Second
|
|
* Third
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
First
|
|
</listitem>
|
|
<listitem>
|
|
Second
|
|
</listitem>
|
|
<listitem>
|
|
Third
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section id="quickbook.syntax.block.lists.mixed_lists">
|
|
<title>Mixed lists</title>
|
|
<para>
|
|
Mixed lists (ordered and unordered) are supported. Example:
|
|
</para>
|
|
|
|
<programlisting># One
|
|
# Two
|
|
# Three
|
|
* Three.a
|
|
* Three.b
|
|
* Three.c
|
|
# Four
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
One
|
|
</listitem>
|
|
<listitem>
|
|
Two
|
|
</listitem>
|
|
<listitem>
|
|
Three
|
|
<itemizedlist>
|
|
<listitem>
|
|
Three.a
|
|
</listitem>
|
|
<listitem>
|
|
Three.b
|
|
</listitem>
|
|
<listitem>
|
|
Three.c
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
Four
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>
|
|
And...
|
|
</para>
|
|
|
|
<programlisting># 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
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
1
|
|
<itemizedlist>
|
|
<listitem>
|
|
1.a
|
|
<orderedlist>
|
|
<listitem>
|
|
1.a.1
|
|
</listitem>
|
|
<listitem>
|
|
1.a.2
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
<listitem>
|
|
1.b
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
2
|
|
<itemizedlist>
|
|
<listitem>
|
|
2.a
|
|
</listitem>
|
|
<listitem>
|
|
2.b
|
|
<orderedlist>
|
|
<listitem>
|
|
2.b.1
|
|
</listitem>
|
|
<listitem>
|
|
2.b.2
|
|
<itemizedlist>
|
|
<listitem>
|
|
2.b.2.a
|
|
</listitem>
|
|
<listitem>
|
|
2.b.2.b
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
</section>
|
|
<section id="quickbook.syntax.block.code">
|
|
<title>Code</title>
|
|
<para>
|
|
Preformatted code starts with a space or a tab. The code will be syntax
|
|
highlighted according to the current <link linkend="quickbook.syntax.phrase.source_mode">Source
|
|
Mode</link>:
|
|
</para>
|
|
<para>
|
|
</para>
|
|
|
|
<programlisting>
|
|
<phrase role="preprocessor">#include</phrase> <phrase role="special"><</phrase><phrase role="identifier">iostream</phrase><phrase role="special">></phrase>
|
|
|
|
<phrase role="keyword">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="comment">// Sample code
|
|
</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World\n"</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
<para>
|
|
</para>
|
|
|
|
<programlisting>
|
|
<phrase role="keyword">import</phrase> <phrase role="identifier">cgi</phrase>
|
|
|
|
<phrase role="keyword">def</phrase> <phrase role="identifier">cookForHtml</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">):</phrase>
|
|
<phrase role="string">'''"Cooks" the input text for HTML.'''</phrase>
|
|
|
|
<phrase role="keyword">return</phrase> <phrase role="identifier">cgi</phrase><phrase role="special">.</phrase><phrase role="identifier">escape</phrase><phrase role="special">(</phrase><phrase role="identifier">text</phrase><phrase role="special">)</phrase>
|
|
</programlisting>
|
|
<para>
|
|
Macros that are already defined are expanded in source code. Example:
|
|
</para>
|
|
|
|
<programlisting>[def __syntax_highlight__ [@quickbook/highlight.html syntax_highlight]]
|
|
[def __quickbook__ [@index.html quickbook]]
|
|
|
|
using __quickbook__::__syntax_highlight__;
|
|
</programlisting>
|
|
<para>
|
|
Generates:
|
|
</para>
|
|
|
|
<programlisting>
|
|
<phrase role="identifier">using</phrase> <ulink url="index.html">quickbook</ulink><phrase role="special">::</phrase><ulink url="quickbook/highlight.html">syntax_highlight</ulink><phrase role="special">;</phrase>
|
|
</programlisting>
|
|
</section>
|
|
<section id="quickbook.syntax.block.escape_back">
|
|
<title> Escaping Back To QuickBook</title>
|
|
<para>
|
|
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 <emphasis>escape-back</emphasis> delimiter. In C++
|
|
and Python, the delimiter is the double tick (back-quote): "``"
|
|
and "``". Example:
|
|
</para>
|
|
|
|
<programlisting>void ``[@http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz foo]``()
|
|
{
|
|
}
|
|
</programlisting>
|
|
<para>
|
|
Will generate:
|
|
</para>
|
|
|
|
<programlisting>
|
|
<phrase role="identifier">void</phrase> <ulink url="http://en.wikipedia.org/wiki/Foo#Foo.2C_Bar_and_Baz">foo</ulink><phrase role="special">()</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
<para>
|
|
When escaping from code to QuickBook, only phrase level markups are allowed.
|
|
Block level markups like lists, tables etc. are not allowed.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.preformatted">
|
|
<title>Preformatted</title>
|
|
<para>
|
|
Sometimes, you don't want some preformatted text to be parsed as C++. In
|
|
such cases, use the <literal>[pre ... ]</literal> markup block.
|
|
</para>
|
|
|
|
<programlisting>[pre
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
Some *preformatted* text Some *preformatted* text
|
|
|
|
]
|
|
</programlisting>
|
|
<para>
|
|
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:
|
|
</para>
|
|
|
|
<programlisting>Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
|
|
|
|
Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
|
|
|
|
Some <emphasis role="bold">preformatted</emphasis> text Some <emphasis role="bold">preformatted</emphasis> text
|
|
|
|
</programlisting>
|
|
<para>
|
|
Notice that unlike Code, phrase markup such as font style is still permitted
|
|
inside <literal>pre</literal> blocks.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.blockquote">
|
|
<title>Blockquote</title>
|
|
<programlisting>[:sometext...]
|
|
</programlisting>
|
|
<blockquote>
|
|
<para>
|
|
Indents the paragraph. This applies to one paragraph only.
|
|
</para>
|
|
</blockquote>
|
|
</section>
|
|
<section id="quickbook.syntax.block.admonitions">
|
|
<title>Admonitions</title>
|
|
<programlisting>[note This is a note]
|
|
[tip This is a tip]
|
|
[important This is important]
|
|
[caution This is a caution]
|
|
[warning This is a warning]
|
|
</programlisting>
|
|
<para>
|
|
generates <ulink url="http://www.docbook.org/">DocBook</ulink> admonitions:
|
|
</para>
|
|
<note>
|
|
<para>
|
|
This is a note
|
|
</para>
|
|
</note>
|
|
<tip>
|
|
<para>
|
|
This is a tip
|
|
</para>
|
|
</tip>
|
|
<important>
|
|
<para>
|
|
This is important
|
|
</para>
|
|
</important>
|
|
<caution>
|
|
<para>
|
|
This is a caution
|
|
</para>
|
|
</caution>
|
|
<warning>
|
|
<para>
|
|
This is a warning
|
|
</para>
|
|
</warning>
|
|
<para>
|
|
These are the only admonitions supported by <ulink url="http://www.docbook.org/">DocBook</ulink>.
|
|
So, for example <literal>[information This is some information]</literal>
|
|
is unlikely to produce the desired effect.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.headings">
|
|
<title>Headings</title>
|
|
<programlisting>[h1 Heading 1]
|
|
[h2 Heading 2]
|
|
[h3 Heading 3]
|
|
[h4 Heading 4]
|
|
[h5 Heading 5]
|
|
[h6 Heading 6]
|
|
</programlisting>
|
|
<anchor id="quickbook.syntax.block.headings.heading_1" />
|
|
<bridgehead renderas="sect1">
|
|
Heading 1
|
|
</bridgehead>
|
|
<anchor id="quickbook.syntax.block.headings.heading_2" />
|
|
<bridgehead renderas="sect2">
|
|
Heading 2
|
|
</bridgehead>
|
|
<anchor id="quickbook.syntax.block.headings.heading_3" />
|
|
<bridgehead renderas="sect3">
|
|
Heading 3
|
|
</bridgehead>
|
|
<anchor id="quickbook.syntax.block.headings.heading_4" />
|
|
<bridgehead renderas="sect4">
|
|
Heading 4
|
|
</bridgehead>
|
|
<anchor id="quickbook.syntax.block.headings.heading_5" />
|
|
<bridgehead renderas="sect5">
|
|
Heading 5
|
|
</bridgehead>
|
|
<anchor id="quickbook.syntax.block.headings.heading_6" />
|
|
<bridgehead renderas="sect6">
|
|
Heading 6
|
|
</bridgehead>
|
|
<para>
|
|
Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized
|
|
names with <literal>name="section_id.normalized_header_text"</literal>
|
|
(i.e. valid characters are <literal>a-z</literal>, <literal>A-Z</literal>,
|
|
<literal>0-9</literal> and <literal>_</literal>. 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 <literal>section_2.heading_1</literal>).
|
|
You can use:
|
|
</para>
|
|
|
|
<programlisting>[link section_id.normalized_header_text The link text]
|
|
</programlisting>
|
|
<para>
|
|
to link to them. See <link linkend="quickbook.syntax.phrase.anchor_links">Anchor
|
|
links</link> and <link linkend="quickbook.syntax.block.section">Section</link>
|
|
for more info.
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.macros">
|
|
<title>Macros</title>
|
|
<programlisting>[def macro_identifier some text]
|
|
</programlisting>
|
|
<para>
|
|
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:
|
|
</para>
|
|
|
|
<programlisting>[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
|
|
sf_logo
|
|
</programlisting>
|
|
<para>
|
|
Now everywhere the sf_logo is placed, the picture will be inlined.
|
|
</para>
|
|
<para>
|
|
<inlinemediaobject><imageobject><imagedata fileref="http://sourceforge.net/sflogo.php?group_id=28447&type=1"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>sflogo</phrase>
|
|
</textobject>
|
|
</inlinemediaobject>
|
|
</para>
|
|
<informaltable frame="all">
|
|
<?dbhtml table-width="74%" ?>
|
|
<tgroup cols="1">
|
|
<tbody>
|
|
<row>
|
|
<entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/tip.png"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>tip</phrase>
|
|
</textobject>
|
|
</inlinemediaobject> 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. <literal>__spirit__</literal>).
|
|
The reason is to avoid unwanted macro replacement.</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
Links (URLS) and images are good candidates for macros. <emphasis role="bold">1</emphasis>)
|
|
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. <emphasis role="bold">2</emphasis>)
|
|
The syntax is not pretty. It's easier to read and write, e.g. <literal>__spirit__</literal>
|
|
than <literal>[@http://spirit.sourceforge.net Spirit]</literal>.
|
|
</para>
|
|
<para>
|
|
Some more examples:
|
|
</para>
|
|
|
|
<programlisting>[def :-) [$theme/smiley.png]]
|
|
[def __spirit__ [@http://spirit.sourceforge.net Spirit]]
|
|
</programlisting>
|
|
<para>
|
|
(See <link linkend="quickbook.syntax.phrase.images">Images</link> and
|
|
<link linkend="quickbook.syntax.phrase.links">Links</link>)
|
|
</para>
|
|
<para>
|
|
Invoking these macros:
|
|
</para>
|
|
|
|
<programlisting>Hi __spirit__ :-)
|
|
</programlisting>
|
|
<para>
|
|
will generate this:
|
|
</para>
|
|
<para>
|
|
Hi <ulink url="http://spirit.sourceforge.net">Spirit</ulink> <inlinemediaobject><imageobject><imagedata
|
|
fileref="images/smiley.png"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>smiley</phrase>
|
|
</textobject>
|
|
</inlinemediaobject>
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.predefined_macros">
|
|
<title>Predefined Macros</title>
|
|
<para>
|
|
Quickbook has some predefined macros that you can already use.
|
|
</para>
|
|
<informaltable frame="all">
|
|
<bridgehead renderas="sect4">
|
|
<phrase role="table-title">Predefined Macros</phrase>
|
|
</bridgehead>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Macro</entry><entry>Meaning</entry><entry>Example</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>__DATE__</entry><entry>Today's date</entry><entry>2000-Dec-20</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__TIME__</entry><entry>The current time</entry><entry>12:00:00
|
|
PM</entry>
|
|
</row>
|
|
<row>
|
|
<entry>__FILENAME__</entry><entry>Quickbook source filename</entry><entry>NO_FILENAME_MACRO_GENERATED_IN_DEBUG_MODE</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
<section id="quickbook.syntax.block.blurbs">
|
|
<title>Blurbs</title>
|
|
<programlisting>[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++.
|
|
]
|
|
</programlisting>
|
|
<para>
|
|
will generate this:
|
|
</para>
|
|
<informaltable frame="all">
|
|
<?dbhtml table-width="74%" ?>
|
|
<tgroup cols="1">
|
|
<tbody>
|
|
<row>
|
|
<entry role="blurb"> <inlinemediaobject><imageobject><imagedata fileref="images/smiley.png"></imagedata></imageobject>
|
|
<textobject>
|
|
<phrase>smiley</phrase>
|
|
</textobject>
|
|
</inlinemediaobject> <emphasis role="bold">An eye catching advertisement
|
|
or note...</emphasis><sbr/> <sbr/> <ulink url="http://spirit.sourceforge.net">Spirit</ulink>
|
|
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++. </entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
<section id="quickbook.syntax.block.tables">
|
|
<title>Tables</title>
|
|
<programlisting>[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]]
|
|
]
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<informaltable frame="all">
|
|
<bridgehead renderas="sect4">
|
|
<phrase role="table-title">A Simple Table</phrase>
|
|
</bridgehead>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Heading 1</entry><entry>Heading 2</entry><entry>Heading 3</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>R0-C0</entry><entry>R0-C1</entry><entry>R0-C2</entry>
|
|
</row>
|
|
<row>
|
|
<entry>R2-C0</entry><entry>R2-C1</entry><entry>R2-C2</entry>
|
|
</row>
|
|
<row>
|
|
<entry>R3-C0</entry><entry>R3-C1</entry><entry>R3-C2</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
The table title is optional. The first row of the table is automatically
|
|
treated as the table header; that is, it is wrapped in <literal><thead>...</thead></literal>
|
|
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:
|
|
</para>
|
|
|
|
<programlisting>[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]
|
|
]
|
|
]
|
|
</programlisting>
|
|
<para>
|
|
and thus:
|
|
</para>
|
|
<informaltable frame="all">
|
|
<bridgehead renderas="sect4">
|
|
<phrase role="table-title">Table with fat cells</phrase>
|
|
</bridgehead>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Heading 1</entry><entry>Heading 2</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>Row 0, Col 0: a small cell</entry><entry> 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... </entry>
|
|
</row>
|
|
<row>
|
|
<entry>Row 1, Col 0: a small cell</entry><entry>Row 1, Col 1: a small
|
|
cell</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
<para>
|
|
Here's how to have preformatted blocks of code in a table cell:
|
|
</para>
|
|
|
|
<programlisting>[table Table with code
|
|
[[Comment] [Code]]
|
|
[
|
|
[My first program]
|
|
[``
|
|
#include <iostream>
|
|
|
|
int main()
|
|
{
|
|
std::cout << "Hello, World!" << std::endl;
|
|
return 0;
|
|
}
|
|
``]
|
|
]
|
|
]
|
|
</programlisting>
|
|
<informaltable frame="all">
|
|
<bridgehead renderas="sect4">
|
|
<phrase role="table-title">Table with code</phrase>
|
|
</bridgehead>
|
|
<tgroup cols="2">
|
|
<thead>
|
|
<row>
|
|
<entry>Comment</entry><entry>Code</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>My first program</entry><entry>
|
|
<programlisting>
|
|
<phrase role="comment">#include <iostream>
|
|
</phrase>
|
|
<phrase role="identifier">int</phrase> <phrase role="identifier">main</phrase><phrase role="special">()</phrase>
|
|
<phrase role="special">{</phrase>
|
|
<phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">cout</phrase> <phrase role="special"><<</phrase> <phrase role="string">"Hello, World!"</phrase> <phrase role="special"><<</phrase> <phrase role="identifier">std</phrase><phrase role="special">::</phrase><phrase role="identifier">endl</phrase><phrase role="special">;</phrase>
|
|
<phrase role="keyword">return</phrase> <phrase role="number">0</phrase><phrase role="special">;</phrase>
|
|
<phrase role="special">}</phrase>
|
|
</programlisting>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
<section id="quickbook.syntax.block.variable_lists">
|
|
<title>Variable Lists</title>
|
|
<programlisting>[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]]
|
|
]
|
|
</programlisting>
|
|
<para>
|
|
will generate:
|
|
</para>
|
|
<variablelist>
|
|
<title>A Variable List</title> <varlistentry><term>term 1</term>
|
|
<listitem>
|
|
The definition of term 1
|
|
</listitem>
|
|
</varlistentry> <varlistentry><term>term 2</term>
|
|
<listitem>
|
|
The definition of term 2
|
|
</listitem>
|
|
</varlistentry> <varlistentry><term>term 3</term>
|
|
<listitem>
|
|
The definition of term 3
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
<para>
|
|
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".
|
|
</para>
|
|
</section>
|
|
<section id="quickbook.syntax.block.include">
|
|
<title>Include</title>
|
|
<para>
|
|
You can include one QuickBook file from another. The syntax is simply:
|
|
</para>
|
|
|
|
<programlisting>[include someother.qbk]
|
|
</programlisting>
|
|
<para>
|
|
The included file will be processed as if it had be cut and pasted into
|
|
the current document, with the following exceptions:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
The __FILENAME__ predefined macro will reflect the name of the file currently
|
|
being processed.
|
|
</listitem>
|
|
<listitem>
|
|
Any macros defined in the included file are scoped to that file.
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
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 <literal>[include]</literal> directive lets you
|
|
specify a document id to use for the included file. You can use it like
|
|
this:
|
|
</para>
|
|
|
|
<programlisting>[include:someid someother.qbk]
|
|
</programlisting>
|
|
<para>
|
|
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 <literal>[link someid.intro The Intro]</literal>.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
<section id="quickbook.ref">
|
|
<title> Quick Reference</title>
|
|
<informaltable frame="all">
|
|
<bridgehead renderas="sect4">
|
|
<phrase role="table-title">Syntax Compendium</phrase>
|
|
</bridgehead>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>To do this...</entry><entry>Use this...</entry><entry>See this...</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody>
|
|
<row>
|
|
<entry>comment</entry><entry><literal>[/ some comment]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.comments">Comments</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis>italics</emphasis></entry><entry><literal>['italics]
|
|
or /italics/</literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
|
|
Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
|
|
Simple formatting</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="bold">bold</emphasis></entry><entry><literal>[*bold]
|
|
or *bold*</literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
|
|
Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
|
|
Simple formatting</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="underline">underline</emphasis></entry><entry><literal>[_underline]
|
|
or _underline_</literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
|
|
Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
|
|
Simple formatting</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry><literal>teletype</literal></entry><entry><literal>[^teletype]
|
|
or =teletype=</literal></entry><entry><link linkend="quickbook.syntax.phrase.font_styles">Font
|
|
Styles</link> and <link linkend="quickbook.syntax.phrase.simple_formatting">formatting
|
|
Simple formatting</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry><emphasis role="strikethrough">strikethrough</emphasis></entry><entry><literal>[-strikethrough]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.font_styles">Font Styles</link> and
|
|
<link linkend="quickbook.syntax.phrase.simple_formatting">formatting
|
|
Simple formatting</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>source mode</entry><entry><literal>[c++]</literal> or <literal>[python]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.source_mode">Source Mode</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>inline code</entry><entry><literal>`int main();`</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.inline_code">Inline code</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>code block</entry><entry><literal>``int main();``</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.code">Code</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>code escape</entry><entry><literal>``from c++ to QuickBook``</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.escape_back">Escaping Back To QuickBook</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>line break</entry><entry><literal>[br] or \n</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.line_break">line-break</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>anchor</entry><entry><literal>[#anchor]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.anchors">Anchors</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>link</entry><entry><literal>[@http://www.boost.org Boost]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.links">Links</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>anchor link</entry><entry><literal>[link section.anchor Link text]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.anchor_links">Anchor links</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>refentry link</entry><entry><literal>[link xml.refentry Link text]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.refentry_links">refentry links</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>function link</entry><entry><literal>[funcref fully::qualified::function_name
|
|
Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
|
|
class, member, enum or header links</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>class link</entry><entry><literal>[classref fully::qualified::class_name
|
|
Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
|
|
class, member, enum or header links</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>member link</entry><entry><literal>[memberref fully::qualified::member_name
|
|
Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
|
|
class, member, enum or header links</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>enum link</entry><entry><literal>[enumref fully::qualified::enum_name
|
|
Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
|
|
class, member, enum or header links</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>header link</entry><entry><literal>[headerref path/to/header.hpp
|
|
Link text]</literal></entry><entry><link linkend="quickbook.syntax.phrase.code_links">function,
|
|
class, member, enum or header links</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>escape</entry><entry><literal>'''escaped text (no processing/formatting)'''</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.escape">Escape</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>single char escape</entry><entry><literal>\c</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.single_char_escape">Single char escape</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>images</entry><entry><literal>[$image.jpg]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.phrase.images">Images</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>begin section</entry><entry><literal>[section The Section Title]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.section">Section</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>end section</entry><entry><literal>[endsect]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.section">Section</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>paragraph</entry><entry>No markup. Paragraphs start left-flushed
|
|
and are terminated by two or more newlines.</entry><entry><link linkend="quickbook.syntax.block.paragraphs">Paragraphs</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>ordered list</entry><entry><literal># one<sbr/> # two<sbr/> #
|
|
three<sbr/> </literal></entry><entry><link linkend="quickbook.syntax.block.lists.ordered_lists">Ordered
|
|
lists</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>unordered list</entry><entry><literal>* one<sbr/> * two<sbr/>
|
|
* three<sbr/> </literal></entry><entry><link linkend="quickbook.syntax.block.lists.unordered_lists">Unordered
|
|
lists</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>code</entry><entry>No markup. Preformatted code starts with a
|
|
space or a tab.</entry><entry><link linkend="quickbook.syntax.block.code">Code</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>preformatted</entry><entry><literal>[pre preformatted]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.preformatted">Preformatted</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>block quote</entry><entry><literal>[:sometext...]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.blockquote">Blockquote</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>heading 1</entry><entry><literal>[h1 Heading 1]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.headings">Heading</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>heading 2</entry><entry><literal>[h2 Heading 2]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.headings">Heading</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>heading 3</entry><entry><literal>[h3 Heading 3]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.headings">Heading</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>heading 4</entry><entry><literal>[h4 Heading 4]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.headings">Heading</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>heading 5</entry><entry><literal>[h5 Heading 5]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.headings">Heading</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>heading 6</entry><entry><literal>[h6 Heading 6]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.headings">Heading</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>macro</entry><entry><literal>[def macro_identifier some text]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.macros">Macros</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>blurb</entry><entry><literal>[blurb advertisement or note...]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.blurbs">Blurbs</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>admonition</entry><entry><literal>[warning Warning text...]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.admonitions">Admonitions</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>table</entry><entry><literal>[table Title<sbr/> [[a][b][c]]<sbr/>
|
|
[[a][b][c]]<sbr/> ]</literal></entry><entry><link linkend="quickbook.syntax.block.tables">Tables</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>variablelist</entry><entry><literal>[variablelist Title<sbr/>
|
|
[[a][b]]<sbr/> [[a][b]]<sbr/> ]</literal></entry><entry><link linkend="quickbook.syntax.block.variable_lists">Variable
|
|
Lists</link></entry>
|
|
</row>
|
|
<row>
|
|
<entry>include</entry><entry><literal>[include someother.qbk]</literal></entry><entry><link
|
|
linkend="quickbook.syntax.block.include">Include</link></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</section>
|
|
</article>
|