Quickbook 1.4

Quickbook 1.4 Joel de Guzman Eric Niebler 2002 2004 2006 Joel de Guzman, Eric Niebler 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) WikiWiki style documentation tool

Why program by hand in five days what you can spend five years of your life automating? -- Terrence Parr, author ANTLR/PCCTS

Well, QuickBook started as a weekend hack. It was originally intended to be a sample application using Spirit. What is it? What you are viewing now, this documentation, is autogenerated by QuickBook. These files were generated from one master:

quickbook.qbk

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 BoostBook instead of HTML. The BoostBook documentation format is an extension of DocBook, an SGML or XML based format for describing documentation. 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. Features include: generate BoostBook xml, to generate HTML, PostScript and PDF simple markup to link to Doxygen-generated entities macro system for simple text substitution simple markup for italics, bold, preformatted, blurbs, code samples, tables, URLs, anchors, images, etc. automatic syntax coloring of code samples CSS support

As mentioned, simple markups cannot go past a single block. The text from "have" to "full" in the following paragraph will be rendered as bold: Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full!* One for the master, one for the dame, And one for the little boy who lives down the lane. Baa baa black sheep, have you any wool? Yes sir, yes sir, three bags full! One for the master, one for the dame, And one for the little boy who lives down the lane. But in the following paragraph, bold is not applied: Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full! One for the master, one for the dame, And one for the little boy who lives down the lane. Baa baa black sheep, *have you any wool? Yes sir, yes sir, three bags full! One for the master, one for the dame, And one for the little boy who lives down the lane.

The source mode strings are lowercase.

Indents the paragraph. This applies to one paragraph only.

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 big fat cell with paragraphs Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work well with the C++ Standard Library. Boost libraries are intended to be widely useful, and usable across a broad spectrum of applications. The Boost license encourages both commercial and non-commercial use. ] ] [ [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 big fat cell with paragraphs Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work well with the C++ Standard Library. Boost libraries are intended to be widely useful, and usable across a broad spectrum of applications. The Boost license encourages both commercial and non-commercial use. 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; }

Section contributed by Julio M. Merino Vidal

The following instructions apply to any Windows system based on Windows 2000, including Windows XP, Windows 2003 Server and Windows Vista. The paths shown below are taken from a Windows Vista machine; you will need to adjust them to match your system in case you are running an older version. First of all you need to have a copy of xsltproc for Windows. There are many ways to get this tool, but to keep things simple, use the binary packages made by Igor Zlatkovic. At the very least, you need to download the following packages: iconv, zlib, libxml2 and libxslt. Unpack all these packages in the same directory so that you get unique bin, include and lib directories within the hierarchy. These instructions use C:\Users\example\Documents\boost\xml as the root for all files. From the command line, go to the bin directory and launch xsltproc.exe to ensure it works. You should get usage information on screen. Download Docbook XML 4.2 and unpack it in the same directory used above. That is: C:\Users\example\Documents\boost\xml\docbook-xml. Download the latest Docbook XSL version and unpack it, again in the same directory used before. To make things easier, rename the directory created during the extraction to docbook-xsl (bypassing the version name): C:\Users\example\Documents\boost\xml\docbook-xsl. Add the following to your user-config.jam file, which should live in your home directory (%HOMEDRIVE%%HOMEPATH%). You must already have it somewhere or otherwise you could not be building Boost (i.e. missing tools configuration). using xsltproc : "C:/Users/example/Documents/boost/xml/bin/xsltproc.exe" ; using boostbook : "C:/Users/example/Documents/boost/xml/docbook-xsl" : "C:/Users/example/Documents/boost/xml/docbook-xml" ; The above steps are enough to get a functional BoostBook setup. Quickbook will be automatically built when needed. If you want to avoid these rebuilds: Go to Quickbook's source directory (BOOST_ROOT\tools\quickbook). Build the utility by issuing

bjam
            --v2

. Copy the resulting quickbook.exe binary (located under the BOOST_ROOT\bin.v2 hierarchy) to a safe place. Following our previous example, you can install it into: C:\Users\example\Documents\boost\xml\bin. Add the following to your user-config.jam file: using quickbook : "C:/Users/example/Documents/boost/xml/bin/quickbook.exe" ;

bjam
            --v2

. Copy the resulting quickbook binary (located under the BOOST_ROOT/bin.v2 hierarchy) to a safe place. The traditional location is /usr/local/bin. Add the following to your user-config.jam file, using the full path of the quickbook executable: using quickbook : /usr/local/bin/quickbook ;

Section contributed by Dean Michael Berris

The Scintilla Text Editor (SciTE) is a free source code editor for Win32 and X. It uses the SCIntilla source code editing component. tip SciTE can be downloaded from http://www.scintilla.org/SciTE.html You can use the following settings to highlight quickbook tags when editing quickbook files. qbk=*.qbk lexer.*.qbk=props use.tabs.$(qbk)=0 tab.size.$(qbk)=4 indent.size.$(qbk)=4 style.props.32=$(font.base) comment.stream.start.props=[/ comment.stream.end.props=] comment.box.start.props=[/ comment.box.middle.props= comment.box.end.props=] note Thanks to Rene Rivera for the above SciTE settings.

Faq contributed by Michael Marcin

When building HTML documentation with BoostBook a Boost C++ Libraries header is added to the files. When using QuickBook to document projects outside of Boost this is not desirable. This behavior can be overridden at the BoostBook level by specifying some XSLT options. When using Boost Build version 2 (BBv2) this can be achieved by adding parameters to the BoostBook target declaration. For example: using quickbook ; xml my_doc : my_doc.qbk ; boostbook standalone : my_doc : <xsl:param>boost.image.src=images/my_project_logo.png <xsl:param>boost.image.alt="\"My Project\"" <xsl:param>boost.image.w=100 <xsl:param>boost.image.h=50 <xsl:param>nav.layout=none ;