mirror of
https://github.com/boostorg/quickbook.git
synced 2026-01-22 05:22:47 +00:00
233 lines
6.4 KiB
Plaintext
233 lines
6.4 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])
|
|
]
|
|
|
|
[section:syntax Syntax Summary]
|
|
|
|
A simple quickbook document might look something like:
|
|
|
|
[pre'''
|
|
[book A sweet little horror story
|
|
[quickbook 1.5]
|
|
[author Brown, Fredric]
|
|
]
|
|
|
|
The last man on Earth sat alone in a room. There was a knock on
|
|
the door...
|
|
''']
|
|
|
|
The document starts with the
|
|
[link quickbook.syntax.docinfo document info block].
|
|
This describes the type of the document, it's title and document
|
|
metadata. In this case just the version of quickbook to be used.
|
|
|
|
This is then followed by one or more blocks. An example of
|
|
a block is the paragraph or a C++ code snippet. In this example we just
|
|
have a single paragraph. 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:docinfo Document Info]
|
|
|
|
Every document must begin with a Document Info section, which looks something
|
|
like this:
|
|
|
|
[pre'''
|
|
[article The Document Title
|
|
[quickbook 1.5]
|
|
[version 1.0]
|
|
[id the_document_name]
|
|
[copyright 2000 2002 2003 Joe Blow, Jane Doe]
|
|
[authors [Blow, Joe] [Doe, Jane]]
|
|
[license The document's license]
|
|
[source-mode c++]
|
|
]
|
|
''']
|
|
|
|
`article` is the document type. There are several possible document types,
|
|
most of these are based on docbook document elements. These are fully
|
|
described in
|
|
[@http://www.docbook.org/tdg/ DocBook: The Definitive Guide]:
|
|
|
|
* [@http://www.docbook.org/tdg/en/html/book.html book]
|
|
* [@http://www.docbook.org/tdg/en/html/article.html article]
|
|
* [@http://www.docbook.org/tdg/en/html/chapter.html chapter]
|
|
* [@http://www.docbook.org/tdg/en/html/part.html part]
|
|
* [@http://www.docbook.org/tdg/en/html/appendix.html appendix]
|
|
* [@http://www.docbook.org/tdg/en/html/preface.html preface]
|
|
* [@http://www.docbook.org/tdg/en/html/qandadiv.html qandadiv]
|
|
* [@http://www.docbook.org/tdg/en/html/qandaset.html qandaset]
|
|
* [@http://www.docbook.org/tdg/en/html/reference.html reference]
|
|
* [@http://www.docbook.org/tdg/en/html/set.html set]
|
|
|
|
Boostbook also adds another document type [^[link boostbook.defining library]]
|
|
for documenting software libraries.
|
|
|
|
So the documentation for the 'foo' library might start:
|
|
|
|
[pre'''
|
|
[library Foo
|
|
[quickbook 1.5]
|
|
[id foo]
|
|
[version 1.0]
|
|
]
|
|
''']
|
|
|
|
[section:attributes Document Info Attributes]
|
|
|
|
The document info block has a few different types of attributes.
|
|
They are all optional.
|
|
|
|
[heading Quickbook specific meta data]
|
|
|
|
[pre'''
|
|
[quickbook 1.5]
|
|
''']
|
|
|
|
The `quickbook` attribute declares the version of quickbook
|
|
the document is written for.
|
|
In its absence, version 1.1 is assumed. It's recommended that
|
|
you use `[quickbook 1.5]` which is the version described here.
|
|
|
|
[pre'''
|
|
[source-mode teletype]
|
|
''']
|
|
|
|
The `source-mode` attribute sets the initial __source_mode__. If
|
|
it is omitted, the default value of =c++= will be used.
|
|
|
|
[heading Boostbook/Docbook root element attributes]
|
|
|
|
[pre'''
|
|
[id foo]
|
|
''']
|
|
|
|
`id` specifies the id of the document element. If it isn't specified
|
|
the id is automatically generated from the title. This id is also
|
|
used to generate the nested ids.
|
|
|
|
[pre'''
|
|
[lang en]
|
|
''']
|
|
|
|
`lang` specifies the document language. This is used by docbook to
|
|
localize the documentation. Note that Boostbook doesn't have any
|
|
localization support so if you use it to generate the reference
|
|
documentation it will be in English regardless.
|
|
|
|
It should be a language code
|
|
drawn from ISO 639 (perhaps extended with a country code drawn from
|
|
ISO 3166, as en-US).
|
|
|
|
[pre'''
|
|
[dirname foo]
|
|
''']
|
|
|
|
`dirname` is used to specify the directory name of the library in the
|
|
repository. This is a boostbook extension so it's only valid for
|
|
`library` documentation blocks. It's used for some boostbook
|
|
functionality, but for pure quickbook documentation has no practical
|
|
effect.
|
|
|
|
[heading Docbook Metadata]
|
|
|
|
=version=, =copyright=, =authors=,
|
|
=license=, =last-revision= and =bibliod= are optional information.
|
|
|
|
[heading Boostbook Metadata]
|
|
|
|
=purpose= and =category= are boostbook attributes which are only
|
|
valid for =library= documents. If you use them for other document types,
|
|
quickbook will warn about them, but still use them, generating invalid markup,
|
|
that's just ignored by the style sheets.
|
|
|
|
[endsect] [/attributes]
|
|
|
|
[endsect] [/docinfo]
|
|
|
|
[section:section Sections]
|
|
|
|
Quickbook documents are structured using 'sections'. These are used
|
|
to generate the table of contents, and, when generating html, to
|
|
split the document into pages. This is optional but a good idea for
|
|
all but the simplest of documents.
|
|
|
|
A sectioned document might look like:
|
|
|
|
[pre'''
|
|
[book Title
|
|
[quickbook 1.5]
|
|
]
|
|
|
|
[section First Section]
|
|
|
|
[/...]
|
|
|
|
[endsect]
|
|
|
|
[section Second Section]
|
|
|
|
[/...]
|
|
|
|
[endsect]
|
|
''']
|
|
|
|
Sections start with the `section` tag, and end with the `[endsect]` tag.
|
|
(`[/...]` is a comment, [link quickbook.syntax.comments described later]).
|
|
|
|
Sections can be given an optional id:
|
|
|
|
[pre'''
|
|
[section:id The Section Title]
|
|
''']
|
|
|
|
`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".
|
|
|
|
Sections can nest, and that results in a hierarchy in the table of contents.
|
|
|
|
[endsect] [/Section]
|
|
|
|
[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]
|
|
|
|
[endsect] [/Syntax Summary]
|