Hi,
Committed in CVS. See doc and for an example.
When documenting code, you'd surely need to present code from actual
source files. While it is possible to copy some code and paste them in
your QuickBook file, doing so is error prone and the extracted code in
the documentation tends to get out of sync with the actual code as the
code evolves. The problem, as always, is that once documentation is
written, the tendency is for the docs to languish in the archives
without maintenance.
QuickBook's (new) import facility provides a nice solution.
Example:
You can effortlessly import code snippets from source code into your
QuickBook. The following illustrates how this is done:
[import ../test/stub.cpp]
[foo]
[bar]
The first line:
[import ../test/stub.cpp]
collects specially marked-up code snippets from stub.cpp and places them
in your QuickBook file as virtual templates. Each of the specially
marked-up code snippets has a name (e.g. foo and bar in the example
above). This shall be the template identifier for that particular code
snippet. The second and third line above does the actual template expansion:
[foo]
[bar]
Code Snippet Markup
Note how the code snippets in stub.cpp get marked up. We use
distinguishable comments following the form:
//[id
some code here
//]
The first comment line above initiates a named code-snippet. This prefix
will not be visible in quickbook. The entire code-snippet in between
//[id and //] will be inserted as a template in quickbook with name id.
The comment //] ends a code-snippet This too will not be visible in
quickbook.
Special Comments
Special comments of the form:
//` some [*quickbook] markup here
and:
/*` some [*quickbook] markup here */
will be parsed by QuickBook. This can contain quickbook blocks (e.g.
sections, paragraphs, tables, etc). In the first case, the initial
slash-slash, tick and white-space shall be ignored. In the second, the
initial slash-star-tick and the final star-slash shall be ignored.
Attached is the specially marked up cpp file in our example above.
Regards,
--
Joel de Guzman
http://www.boost-consulting.com
http://spirit.sf.net
/*=============================================================================
Copyright (c) 2006 Joel de Guzman
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)
=============================================================================*/
#include <string>
//[ bar
//` This is the [*/bar/] function
std::string bar()
{
// return 'em, bar man!
return "bar";
}
//]
//[ foo
/*` This is the [*['foo]] function. */
std::string foo()
{
// return 'em, foo man!
return "foo";
}
//]
-------------------------------------------------------------------------
Take Surveys. Earn Cash. Influence the Future of IT
Join SourceForge.net's Techsay panel and you'll get the chance to share your
opinions on IT & business topics through brief surveys - and earn cash
http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
