diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..3e84d7c70 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,96 @@ +* text=auto !eol svneol=native#text/plain +*.gitattributes text svneol=native#text/plain + +# Scriptish formats +*.bat text svneol=native#text/plain +*.bsh text svneol=native#text/x-beanshell +*.cgi text svneol=native#text/plain +*.cmd text svneol=native#text/plain +*.js text svneol=native#text/javascript +*.php text svneol=native#text/x-php +*.pl text svneol=native#text/x-perl +*.pm text svneol=native#text/x-perl +*.py text svneol=native#text/x-python +*.sh eol=lf svneol=LF#text/x-sh +configure eol=lf svneol=LF#text/x-sh + +# Image formats +*.bmp binary svneol=unset#image/bmp +*.gif binary svneol=unset#image/gif +*.ico binary svneol=unset#image/ico +*.jpeg binary svneol=unset#image/jpeg +*.jpg binary svneol=unset#image/jpeg +*.png binary svneol=unset#image/png +*.tif binary svneol=unset#image/tiff +*.tiff binary svneol=unset#image/tiff +*.svg text svneol=native#image/svg%2Bxml + +# Data formats +*.pdf binary svneol=unset#application/pdf +*.avi binary svneol=unset#video/avi +*.doc binary svneol=unset#application/msword +*.dsp text svneol=crlf#text/plain +*.dsw text svneol=crlf#text/plain +*.eps binary svneol=unset#application/postscript +*.gz binary svneol=unset#application/gzip +*.mov binary svneol=unset#video/quicktime +*.mp3 binary svneol=unset#audio/mpeg +*.ppt binary svneol=unset#application/vnd.ms-powerpoint +*.ps binary svneol=unset#application/postscript +*.psd binary svneol=unset#application/photoshop +*.rdf binary svneol=unset#text/rdf +*.rss text svneol=unset#text/xml +*.rtf binary svneol=unset#text/rtf +*.sln text svneol=native#text/plain +*.swf binary svneol=unset#application/x-shockwave-flash +*.tgz binary svneol=unset#application/gzip +*.vcproj text svneol=native#text/xml +*.vcxproj text svneol=native#text/xml +*.vsprops text svneol=native#text/xml +*.wav binary svneol=unset#audio/wav +*.xls binary svneol=unset#application/vnd.ms-excel +*.zip binary svneol=unset#application/zip + +# Text formats +.htaccess text svneol=native#text/plain +*.bbk text svneol=native#text/xml +*.cmake text svneol=native#text/plain +*.css text svneol=native#text/css +*.dtd text svneol=native#text/xml +*.htm text svneol=native#text/html +*.html text svneol=native#text/html +*.ini text svneol=native#text/plain +*.log text svneol=native#text/plain +*.mak text svneol=native#text/plain +*.qbk text svneol=native#text/plain +*.rst text svneol=native#text/plain +*.sql text svneol=native#text/x-sql +*.txt text svneol=native#text/plain +*.xhtml text svneol=native#text/xhtml%2Bxml +*.xml text svneol=native#text/xml +*.xsd text svneol=native#text/xml +*.xsl text svneol=native#text/xml +*.xslt text svneol=native#text/xml +*.xul text svneol=native#text/xul +*.yml text svneol=native#text/plain +boost-no-inspect text svneol=native#text/plain +CHANGES text svneol=native#text/plain +COPYING text svneol=native#text/plain +INSTALL text svneol=native#text/plain +Jamfile text svneol=native#text/plain +Jamroot text svneol=native#text/plain +Jamfile.v2 text svneol=native#text/plain +Jamrules text svneol=native#text/plain +Makefile* text svneol=native#text/plain +README text svneol=native#text/plain +TODO text svneol=native#text/plain + +# Code formats +*.c text svneol=native#text/plain +*.cpp text svneol=native#text/plain +*.h text svneol=native#text/plain +*.hpp text svneol=native#text/plain +*.ipp text svneol=native#text/plain +*.tpp text svneol=native#text/plain +*.jam text svneol=native#text/plain +*.java text svneol=native#text/plain diff --git a/Jamfile.v2 b/Jamfile.v2 new file mode 100755 index 000000000..dfdde2ce2 --- /dev/null +++ b/Jamfile.v2 @@ -0,0 +1,6 @@ + +exe quickbook + : detail/quickbook.cpp + : $(BOOST_ROOT) + ; + diff --git a/detail/actions.hpp b/detail/actions.hpp new file mode 100755 index 000000000..c29e49e58 --- /dev/null +++ b/detail/actions.hpp @@ -0,0 +1,1049 @@ +/*============================================================================= + Copyright (c) 2002 2004 Joel de Guzman + Copyright (c) 2004 Eric Niebler + 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) +=============================================================================*/ +#if !defined(BOOST_SPIRIT_QUICKBOOK_ACTIONS_HPP) +#define BOOST_SPIRIT_QUICKBOOK_ACTIONS_HPP + +#include +#include +#include +#include +#include +#include +#include +#include "../syntax_highlight.hpp" +#include "utils.hpp" + +namespace quickbook +{ + struct error_action + { + // Prints an error message to std::cerr + + template + void operator()(Iterator const& first, Iterator const& /*last*/) const + { + boost::spirit::file_position const pos = first.get_position(); + std::cerr + << "Syntax Error at \"" << pos.file + << "\" line " << pos.line + << ", column " << pos.column << ".\n"; + } + }; + + struct phrase_action + { + // Handles paragraph, h1, h2, h3, h4, h5, h6, + // blurb, blockquote, preformatted, list_item, + // unordered_list, ordered_list + + phrase_action( + std::ostream& out, + std::stringstream& phrase, + std::string& section_id, + std::string const& pre, + std::string const& post, + bool anchor = false) + : out(out) + , phrase(phrase) + , section_id(section_id) + , pre(pre) + , post(post) + , anchor(anchor) {} + + template + void operator()(Iterator const& first, Iterator const& last) const + { + if (out) + { + std::string str = phrase.str(); + if (anchor) + out << ""; + phrase.str(std::string()); + out << pre << str << post; + } + } + + std::ostream& out; + std::stringstream& phrase; + std::string& section_id; + std::string pre; + std::string post; + bool anchor; + }; + + struct simple_phrase_action + { + // Handles simple text formats + + simple_phrase_action( + std::ostream& out, + std::string const& pre, + std::string const& post) + : out(out) + , pre(pre) + , post(post) {} + + template + void operator()(Iterator first, Iterator const& last) const + { + if (out) + { + out << pre; + while (first != last) + detail::print_char(*first++, out); + out << post; + } + } + + std::ostream& out; + std::string pre; + std::string post; + }; + + struct list_action + { + // Handles lists + + list_action( + std::ostream& out + , std::stringstream& list_buffer + , int& indent + , std::stack& list_marks) + : out(out) + , list_buffer(list_buffer) + , indent(indent) + , list_marks(list_marks) {} + + template + void operator()(Iterator const& first, Iterator const& last) const + { + assert(!list_marks.empty()); // there must be at least one item in the stack + std::string str = list_buffer.str(); + list_buffer.str(std::string()); + out << str; + + while (!list_marks.empty()) + { + char mark = list_marks.top(); + list_marks.pop(); + out << std::string((mark == '#') ? "\n" : "\n"); + if (list_marks.size() >= 1) + out << std::string("\n"); + } + + indent = -1; // reset + } + + std::ostream& out; + std::stringstream& list_buffer; + int& indent; + std::stack& list_marks; + }; + + struct list_format_action + { + // Handles list formatting and hierarchy + + list_format_action( + std::stringstream& out + , int& indent + , std::stack& list_marks) + : out(out) + , indent(indent) + , list_marks(list_marks) {} + + template + void operator()(Iterator first, Iterator const& last) const + { + int new_indent = 0; + while (first != last && (*first == ' ' || *first == '\t')) + { + char mark = *first++; + if (mark == ' ') + { + ++new_indent; + } + else // must be a tab + { + assert(mark == '\t'); + // hardcoded tab to 4 for now + new_indent = ((new_indent + 4) / 4) * 4; + } + } + + char mark = *first; + assert(mark == '#' || mark == '*'); // expecting a mark + + if (indent == -1) // the very start + { + assert(new_indent == 0); + } + + if (new_indent > indent) + { + indent = new_indent; + list_marks.push(mark); + if (list_marks.size() > 1) + { + // Make this new list a child of the previous list. + // The previous listelem has already ended so we erase + // to accomodate this sub-list. We'll close + // the listelem later. + + std::string str = out.str(); + std::string::size_type pos = str.rfind("\n"); + assert(pos <= str.size()); + str.erase(str.begin()+pos, str.end()); + out.str(std::string()); + out << str; + } + out << std::string((mark == '#') ? "\n" : "\n"); + } + + else if (new_indent < indent) + { + assert(!list_marks.empty()); + indent = new_indent; + list_marks.pop(); + out << std::string((mark == '#') ? "\n" : "\n"); + if (list_marks.size() >= 1) + out << std::string("\n"); + } + + else if (mark != list_marks.top()) // new_indent == indent + { + boost::spirit::file_position const pos = first.get_position(); + std::cerr + << "Illegal change of list style at \"" << pos.file + << "\" line " << pos.line + << ", column " << pos.column << ".\n"; + std::cerr << "Ignoring change of list style" << std::endl; + } + } + + std::stringstream& out; + int& indent; + std::stack& list_marks; + }; + + struct span + { + // Decorates c++ code fragments + + span(char const* name, std::ostream& out) + : name(name), out(out) {} + + template + void operator()(Iterator first, Iterator last) const + { + if (out) + { + out << ""; + while (first != last) + detail::print_char(*first++, out); + out << ""; + } + } + + char const* name; + std::ostream& out; + }; + + struct unexpected_char + { + // Handles unexpected chars in c++ syntax + + unexpected_char(std::ostream& out) + : out(out) {} + + template + void operator()(Char) const + { + if (out) + out << '#'; // print out an unexpected character + } + + std::ostream& out; + }; + + struct anchor_action + { + // Handles anchors + + anchor_action(std::ostream& out) + : out(out) {} + + template + void operator()(Iterator first, Iterator last) const + { + if (out) + { + out << "\n"; + } + } + + std::ostream& out; + }; + + char const* quickbook_get_date = "__quickbook_get_date__"; + char const* quickbook_get_time = "__quickbook_get_time__"; + + struct do_macro_action + { + // Handles macro substitutions + + do_macro_action(std::ostream& phrase) + : phrase(phrase) {} + + void operator()(std::string const& str) const + { + if (str == quickbook_get_date) + { + char strdate[ 64 ]; + time_t t = time(0); + strftime( strdate, sizeof(strdate), "%Y-%b-%d", localtime(&t) ); + phrase << strdate; + } + else if (str == quickbook_get_time) + { + char strdate[ 64 ]; + time_t t = time(0); + strftime( strdate, sizeof(strdate), "%I:%M:%S %p", localtime(&t) ); + phrase << strdate; + } + else + { + phrase << str; + } + } + + std::ostream& phrase; + }; + + struct space + { + // Prints a space + + space(std::ostream& out) + : out(out) {} + + template + void operator()(Iterator first, Iterator last) const + { + if (out) + { + while (first != last) + detail::print_space(*first++, out); + } + } + + template + void operator()(Char ch) const + { + if (out) + { + detail::print_space(ch, out); + } + } + + std::ostream& out; + }; + + struct code_action + { + // Does the actual syntax highlighing of code + + code_action(std::ostream& out, + std::string const & source_mode, + symbols const& macro) + : out(out) + , source_mode(source_mode) + , cpp_p(out, macro, do_macro_action(out)) + , python_p(out, macro, do_macro_action(out)) + { + } + + template + void operator()(Iterator first, Iterator last) const + { + if (out) + { + // preprocess the code section to remove the initial indentation + std::string program(first, last); + detail::unindent(program); + + out << "\n" + << "\n"; + + // print the code with syntax coloring + if (source_mode == "c++") + { + parse(program.begin(), program.end(), cpp_p); + } + else if (source_mode == "python") + { + parse(program.begin(), program.end(), python_p); + } + + out << "\n" + << "\n"; + } + } + + std::ostream& out; + std::string const& source_mode; + + cpp_highlight< + span + , space + , symbols + , do_macro_action + , unexpected_char + , std::ostream> + cpp_p; + + python_highlight< + span + , space + , symbols + , do_macro_action + , unexpected_char + , std::ostream> + python_p; + }; + + struct inline_code_action + { + // Does the actual syntax highlighing of code inlined in text + + inline_code_action(std::ostream& out, + std::string const& source_mode, + symbols const& macro) + : out(out) + , source_mode(source_mode) + , cpp_p(out, macro, do_macro_action(out)) + , python_p(out, macro, do_macro_action(out)) + {} + + template + void operator()(Iterator first, Iterator last) const + { + if (out) + { + out << ""; + + // print the code with syntax coloring + if (source_mode == "c++") + { + parse(first, last, cpp_p); + } + else if (source_mode == "python") + { + parse(first, last, python_p); + } + + out << ""; + } + } + + std::ostream& out; + std::string const& source_mode; + + cpp_highlight< + span + , space + , symbols + , do_macro_action + , unexpected_char + , std::ostream> + cpp_p; + + python_highlight< + span + , space + , symbols + , do_macro_action + , unexpected_char + , std::ostream> + python_p; + }; + + namespace + { + // Some markups + + const char* paragraph_pre = "\n"; + const char* paragraph_post = "\n"; + const char* h1_pre = ""; + const char* h1_post = ""; + const char* h2_pre = ""; + const char* h2_post = ""; + const char* h3_pre = ""; + const char* h3_post = ""; + const char* h4_pre = ""; + const char* h4_post = ""; + const char* h5_pre = ""; + const char* h5_post = ""; + const char* h6_pre = ""; + const char* h6_post = ""; + const char* hr_ = ""; + + const char* blurb_pre = + "\n" + "\n" + "\n" + "\n" + "\n" + "\n" + ; + + const char* blurb_post = + "\n" + "\n" + "\n" + "\n" + "\n" + ; + + const char* blockquote_pre = "
"; + const char* blockquote_post = "
"; + const char* preformatted_pre = ""; + const char* preformatted_post = ""; + const char* list_item_pre = "\n"; + const char* list_item_post = "\n"; + const char* bold_pre_ = ""; + const char* bold_post_ = ""; + const char* italic_pre_ = ""; + const char* italic_post_ = ""; + const char* underline_pre_ = ""; + const char* underline_post_ = ""; + const char* teletype_pre_ = ""; + const char* teletype_post_ = ""; + const char* break_mark = "\n"; + const char* url_pre_ = "'... etc. + + raw_char_action(std::ostream& phrase) + : phrase(phrase) {} + + template + void operator()(Char const& ch) const + { + phrase << ch; + } + + template + void operator()(Iterator const& first, Iterator const& /*last*/) const + { + phrase << *first; + } + + std::ostream& phrase; + }; + + struct plain_char_action + { + // Prints a single plain char. + // Converts '<' to "<"... etc See utils.hpp + + plain_char_action(std::ostream& phrase) + : phrase(phrase) {} + + template + void operator()(Char const& ch) const + { + detail::print_char(ch, phrase); + } + + template + void operator()(Iterator const& first, Iterator const& /*last*/) const + { + detail::print_char(*first, phrase); + } + + std::ostream& phrase; + }; + + struct image_action + { + // Handles inline images + + image_action(std::ostream& phrase) + : phrase(phrase) {} + + template + void operator()(Iterator first, Iterator last) const + { + phrase << ""; + } + + std::ostream& phrase; + }; + + struct markup_action + { + // A generic markup action + + markup_action(std::ostream& phrase, std::string const& str) + : phrase(phrase), str(str) {} + + template + void operator()(T const&) const + { + phrase << str; + } + + template + void operator()(T const&, T const&) const + { + phrase << str; + } + + std::ostream& phrase; + std::string str; + }; + + template + struct indentifier_action + { + // Handles macro identifiers + + indentifier_action(Actions& actions) + : actions(actions) {} + + template + void operator()(Iterator const& first, Iterator const& last) const + { + actions.macro_id.assign(first, last); + actions.phrase_save = actions.phrase.str(); + actions.phrase.str(std::string()); + } + + Actions& actions; + }; + + template + struct macro_def_action + { + // Handles macro definitions + + macro_def_action(Actions& actions) + : actions(actions) {} + + template + void operator()(Iterator const& first, Iterator const& last) const + { + actions.macro.add( + actions.macro_id.begin() + , actions.macro_id.end() + , actions.phrase.str()); + actions.phrase.str(actions.phrase_save); + } + + Actions& actions; + }; + + struct link_action + { + // Handles links (URL, XML refentry, function, class, member) + + link_action(std::ostream& phrase, char const* tag) + : phrase(phrase), tag(tag) {} + + template + void operator()(Iterator first, Iterator last) const + { + Iterator save = first; + phrase << tag; + while (first != last) + detail::print_char(*first++, phrase); + phrase << "\">"; + + // Yes, it is safe to dereference last here. When we + // reach here, *last is certainly valid. We test if + // *last == ']'. In which case, the url is the text. + // Example: [@http://spirit.sourceforge.net/] + + if (*last == ']') + { + first = save; + while (first != last) + detail::print_char(*first++, phrase); + } + } + + std::ostream& phrase; + char const* tag; + }; + + template + struct variablelist_action + { + // Handles variable lists + + variablelist_action(Actions& actions) + : actions(actions) {} + + template + void operator()(Iterator, Iterator) const + { + if (!!actions.out) + { + actions.out << "\n"; + + actions.out << ""; + std::string::iterator first = actions.table_title.begin(); + std::string::iterator last = actions.table_title.end(); + while (first != last) + detail::print_char(*first++, actions.out); + actions.out << "\n"; + + std::string str = actions.phrase.str(); + actions.phrase.str(std::string()); + actions.out << str; + + actions.out << "\n"; + actions.table_span = 0; + actions.table_header.clear(); + actions.table_title.clear(); + } + } + + Actions& actions; + }; + + template + struct table_action + { + // Handles tables + + table_action(Actions& actions) + : actions(actions) {} + + template + void operator()(Iterator, Iterator) const + { + if (!!actions.out) + { + actions.out << "\n" + << ""; + + actions.out << ""; + std::string::iterator first = actions.table_title.begin(); + std::string::iterator last = actions.table_title.end(); + while (first != last) + detail::print_char(*first++, actions.out); + actions.out << ""; + + actions.out << "\n" + << "\n"; + + if(!actions.table_header.empty()) + { + actions.out << "" << actions.table_header << "\n"; + } + + actions.out << "\n"; + + std::string str = actions.phrase.str(); + actions.phrase.str(std::string()); + actions.out << str; + + actions.out << "\n" + << "\n" + << "\n"; + actions.table_span = 0; + actions.table_header.clear(); + actions.table_title.clear(); + } + } + + Actions& actions; + }; + + struct start_row_action + { + // Handles table rows + + start_row_action(std::stringstream& phrase, unsigned& span, std::string& header) + : phrase(phrase), span(span), header(header) {} + + template + void operator()(T const&) const + { + // the first row is the header + if(header.empty() && !phrase.str().empty()) + { + header = phrase.str(); + phrase.str(std::string()); + } + + phrase << start_row_; + span = 0; + } + + template + void operator()(T const& t,T const&) const + { + (*this)(t); + } + + std::stringstream& phrase; + unsigned& span; + std::string& header; + }; + + struct start_col_action + { + // Handles table columns + + start_col_action(std::ostream& phrase, unsigned& span) + : phrase(phrase), span(span) {} + + template + void operator()(T const&) const + { + phrase << start_cell_; ++span; + } + + std::ostream& phrase; + unsigned& span; + }; + + struct begin_section_action + { + // Handles begin page + + begin_section_action( + std::ostream& phrase + , std::string& library_id + , std::string& section_id) + : phrase(phrase) + , library_id(library_id) + , section_id(section_id) {} + + template + void operator()(Iterator first, Iterator last) const + { + if (section_id.empty()) + section_id = detail::make_identifier(first, last); + phrase << "\n
\n"; + phrase << ""; + while (first != last) + detail::print_char(*first++, phrase); + phrase << "\n"; + } + + std::ostream& phrase; + std::string& library_id; + std::string& section_id; + }; + + struct xinclude_action + { + // Handles XML includes + + xinclude_action(std::ostream& out_) + : out(out_) {} + + template + void operator()(Iterator first, Iterator last) const + { + out << "\n\n"; + } + + std::ostream& out; + }; + + struct xml_author + { + // Handles xml author + + xml_author(std::ostream& out) + : out(out) {} + + void operator()(std::pair const& author) const + { + out << " \n" + << " " << author.first << "\n" + << " " << author.second << "\n" + << " \n"; + } + + std::ostream& out; + }; + + struct xml_year + { + // Handles xml year + + xml_year(std::ostream& out) + : out(out) {} + + void operator()(std::string const &year) const + { + out << " " << year << "\n"; + } + + std::ostream& out; + }; + + template + void pre(std::ostream& out, Actions& actions) + { + // The quickbook file has been parsed. Now, it's time to + // generate the output. Here's what we'll do *before* anything else. + + if (actions.doc_id.empty()) + actions.doc_id = detail::make_identifier( + actions.doc_title.begin(),actions.doc_title.end()); + + if (actions.doc_dirname.empty()) + actions.doc_dirname = actions.doc_id; + + if (actions.doc_last_revision.empty()) + { + // default value for last-revision is now + + char strdate[ 30 ]; + time_t t = time(0); + strftime( + strdate, sizeof(strdate), + "$" /* prevent CVS substitution */ "Date: %Y/%m/%d %H:%M:%S $", + gmtime(&t) + ); + + actions.doc_last_revision = strdate; + } + + out << "\n" + << "\n" + << '<' << actions.doc_type << "\n" + << " id=\"" << actions.doc_id << "\"\n" + << " name=\"" << actions.doc_title << "\"\n" + << " dirname=\"" << actions.doc_dirname << "\"\n" + << " last-revision=\"" << actions.doc_last_revision << "\" \n" + << " xmlns:xi=\"http://www.w3.org/2001/XInclude\">\n" + << " <" << actions.doc_type << "info>\n"; + + for_each( + actions.doc_authors.begin() + , actions.doc_authors.end() + , xml_author(out)); + + if (!actions.doc_copyright_holder.empty()) + { + out << "\n" << " \n"; + + for_each( + actions.doc_copyright_years.begin() + , actions.doc_copyright_years.end() + , xml_year(out)); + + out << " " << actions.doc_copyright_holder << "\n" + << " \n" + << "\n" + ; + } + + if (!actions.doc_license.empty()) + { + out << " \n" + << " \n" + << " " << actions.doc_license << "\n" + << " \n" + << " \n" + << "\n" + ; + } + + if (!actions.doc_purpose.empty()) + { + out << " <" << actions.doc_type << "purpose>\n" + << " " << actions.doc_purpose + << " \n" + << "\n" + ; + } + + if (!actions.doc_purpose.empty()) + { + out << " <" << actions.doc_type << "category name=\"category:" + << actions.doc_category + << "\">\n" + << "\n" + ; + } + + out << " \n" + << "\n" + ; + + if (!actions.doc_title.empty()) + { + out << " " << actions.doc_title; + if (!actions.doc_version.empty()) + out << ' ' << actions.doc_version; + out << "\n\n\n"; + } + } + + template + void post(std::ostream& out, Actions& actions) + { + // We've finished generating our output. Here's what we'll do + // *after* everything else. + out << "\n\n\n"; + } +} + +#endif // BOOST_SPIRIT_QUICKBOOK_UTILS_HPP + diff --git a/detail/quickbook.cpp b/detail/quickbook.cpp new file mode 100755 index 000000000..5f30a2fb3 --- /dev/null +++ b/detail/quickbook.cpp @@ -0,0 +1,345 @@ +/*============================================================================= + Copyright (c) 2002 2004 Joel de Guzman + Copyright (c) 2004 Eric Niebler + 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 "../quickbook.hpp" +#include "../doc_info.hpp" +#include "utils.hpp" +#include "actions.hpp" +#include + +#include +#include +#include + +#if (defined(BOOST_MSVC) && (BOOST_MSVC <= 1310)) +#pragma warning(disable:4355) +#endif + +namespace quickbook +{ + using namespace boost::spirit; + + /////////////////////////////////////////////////////////////////////////// + // + // Our actions + // + /////////////////////////////////////////////////////////////////////////// + struct actions + { + actions(char const* filein_, char const* fileout_) + : filename(filein_) + , out(fileout_) + , table_span(0) + , table_header() + , source_mode("c++") + , code(out, source_mode, macro) + , inline_code(phrase, source_mode, macro) + , paragraph(out, phrase, section_id, paragraph_pre, paragraph_post) + , h1(out, phrase, section_id, h1_pre, h1_post, true) + , h2(out, phrase, section_id, h2_pre, h2_post, true) + , h3(out, phrase, section_id, h3_pre, h3_post, true) + , h4(out, phrase, section_id, h4_pre, h4_post, true) + , h5(out, phrase, section_id, h5_pre, h5_post, true) + , h6(out, phrase, section_id, h6_pre, h6_post, true) + , hr(out, hr_) + , blurb(out, phrase, section_id, blurb_pre, blurb_post) + , blockquote(out, phrase, section_id, blockquote_pre, blockquote_post) + , preformatted(out, phrase, section_id, preformatted_pre, preformatted_post) + , plain_char(phrase) + , raw_char(phrase) + , image(phrase) + , list_buffer() + , list_marks() + , indent(-1) + , list(out, list_buffer, indent, list_marks) + , list_format(list_buffer, indent, list_marks) + , list_item(list_buffer, phrase, section_id, list_item_pre, list_item_post) + , funcref_pre(phrase, funcref_pre_) + , funcref_post(phrase, funcref_post_) + , classref_pre(phrase, classref_pre_) + , classref_post(phrase, classref_post_) + , memberref_pre(phrase, memberref_pre_) + , memberref_post(phrase, memberref_post_) + , enumref_pre(phrase, enumref_pre_) + , enumref_post(phrase, enumref_post_) + , bold_pre(phrase, bold_pre_) + , bold_post(phrase, bold_post_) + , italic_pre(phrase, italic_pre_) + , italic_post(phrase, italic_post_) + , underline_pre(phrase, underline_pre_) + , underline_post(phrase, underline_post_) + , teletype_pre(phrase, teletype_pre_) + , teletype_post(phrase, teletype_post_) + , simple_bold(phrase, bold_pre_, bold_post_) + , simple_italic(phrase, italic_pre_, italic_post_) + , simple_underline(phrase, underline_pre_, underline_post_) + , simple_teletype(phrase, teletype_pre_, teletype_post_) + , variablelist(*this) + , start_varlistentry(phrase, start_varlistentry_) + , end_varlistentry(phrase, end_varlistentry_) + , start_varlistterm(phrase, start_varlistterm_) + , end_varlistterm(phrase, end_varlistterm_) + , start_varlistitem(phrase, start_varlistitem_) + , end_varlistitem(phrase, end_varlistitem_) + , break_(phrase, break_mark) + , identifier(*this) + , macro_def(*this) + , do_macro(phrase) + , url_pre(phrase, url_pre_) + , url_post(phrase, url_post_) + , link_pre(phrase, link_pre_) + , link_post(phrase, link_post_) + , table(*this) + , start_row(phrase, table_span, table_header) + , end_row(phrase, end_row_) + , start_cell(phrase, table_span) + , end_cell(phrase, end_cell_) + , anchor(out) + , begin_section(out, doc_id, section_id) + , end_section(out, "
") + , xinclude(out) + { + std::cout << "Generating Output File: " + << fileout_ + << std::endl; + + // add the predefined macros + macro.add + ("__DATE__", std::string(quickbook_get_date)) + ("__TIME__", std::string(quickbook_get_time)) + ("__FILENAME__", std::string(filein_)) + ; + } + + typedef indentifier_action indentifier_action; + typedef macro_def_action macro_def_action; + typedef table_action table_action; + typedef variablelist_action variablelist_action; + + char const* filename; + std::string directory; + std::string macro_id; + std::string phrase_save; + std::string table_title; + std::ofstream out; + error_action error; + + typedef std::vector copyright_list; + typedef std::vector > author_list; + + std::string doc_type; + std::string doc_title; + std::string doc_version; + std::string doc_id; + std::string doc_dirname; + copyright_list doc_copyright_years; + std::string doc_copyright_holder; + std::string doc_purpose; + std::string doc_category; + author_list doc_authors; + std::string doc_license; + std::string doc_last_revision; + + std::string page_title; + std::string section_id; + std::string previous; + std::stringstream phrase; + unsigned table_span; + std::string table_header; + + symbols macro; + std::string source_mode; + code_action code; + inline_code_action inline_code; + phrase_action paragraph, h1, h2, h3, h4, h5, h6; + markup_action hr; + phrase_action blurb, blockquote, preformatted; + plain_char_action plain_char; + raw_char_action raw_char; + image_action image; + + std::stringstream list_buffer; + std::stack list_marks; + int indent; + list_action list; + list_format_action list_format; + phrase_action list_item; + + link_action funcref_pre; + markup_action funcref_post; + link_action classref_pre; + markup_action classref_post; + link_action memberref_pre; + markup_action memberref_post; + link_action enumref_pre; + markup_action enumref_post; + + markup_action bold_pre; + markup_action bold_post; + markup_action italic_pre; + markup_action italic_post; + markup_action underline_pre; + markup_action underline_post; + markup_action teletype_pre; + markup_action teletype_post; + + simple_phrase_action simple_bold; + simple_phrase_action simple_italic; + simple_phrase_action simple_underline; + simple_phrase_action simple_teletype; + + variablelist_action variablelist; + markup_action start_varlistentry; + markup_action end_varlistentry; + markup_action start_varlistterm; + markup_action end_varlistterm; + markup_action start_varlistitem; + markup_action end_varlistitem; + + markup_action break_; + indentifier_action identifier; + macro_def_action macro_def; + do_macro_action do_macro; + link_action url_pre; + markup_action url_post; + link_action link_pre; + markup_action link_post; + table_action table; + start_row_action start_row; + markup_action end_row; + start_col_action start_cell; + markup_action end_cell; + anchor_action anchor; + + begin_section_action begin_section; + markup_action end_section; + xinclude_action xinclude; + }; + + /////////////////////////////////////////////////////////////////////////// + // + // Load a file + // + /////////////////////////////////////////////////////////////////////////// + typedef std::vector file_storage; + + static int + load(char const* filename, file_storage& storage) + { + using std::cerr; + using std::endl; + using std::ios; + using std::ifstream; + using std::istream_iterator; + + ifstream in(filename); + + if (!in) + { + cerr << "Could not open input file: " << filename << endl; + return 1; + } + + // Turn of white space skipping on the stream + in.unsetf(ios::skipws); + + std::copy( + istream_iterator(in), + istream_iterator(), + std::back_inserter(storage)); + + // ensure that we have enough trailing newlines to eliminate + // the need to check for end of file in the grammar. + storage.push_back('\n'); + storage.push_back('\n'); + return 0; + } + + /////////////////////////////////////////////////////////////////////////// + // + // Parse a file + // + /////////////////////////////////////////////////////////////////////////// + static int + parse(char const* filein_, char const* fileout_) + { + using std::cerr; + using std::vector; + using std::string; + + file_storage storage; + int err = quickbook::load(filein_, storage); + if (err != 0) + return err; + + typedef position_iterator iterator_type; + iterator_type first(storage.begin(), storage.end(), filein_); + iterator_type last(storage.end(), storage.end()); + + actions actor(filein_, fileout_); + + doc_info_grammar l(actor); + parse_info info = parse(first, last, l); + + if (info.hit) + { + pre(actor.out, actor); + + first = info.stop; + quickbook_grammar g(actor); + info = parse(first, last, g); + if (info.full) + { + post(actor.out, actor); + } + } + + if (!info.full) + { + file_position const pos = info.stop.get_position(); + cerr + << "Syntax error at \"" << pos.file + << "\" line " << pos.line + << ", column " << pos.column << ".\n"; + return 1; + } + + return 0; + } +} + +/////////////////////////////////////////////////////////////////////////// +// +// Main program +// +/////////////////////////////////////////////////////////////////////////// +int +main(int argc, char* argv[]) +{ + if (argc > 1) + { + std::string fileout; + if (argc == 2) + { + fileout = quickbook::detail::remove_extension(argv[1]); + fileout += ".xml"; + } + else + { + fileout = argv[2]; + } + + return quickbook::parse(argv[1], fileout.c_str()); + } + else + { + std::cerr << "---NO FILENAME GIVEN---" << std::endl; + } + return 0; +} diff --git a/detail/utils.hpp b/detail/utils.hpp new file mode 100755 index 000000000..fdbba476d --- /dev/null +++ b/detail/utils.hpp @@ -0,0 +1,111 @@ +/*============================================================================= + Copyright (c) 2002 2004 Joel de Guzman + Copyright (c) 2004 Eric Niebler + 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) +=============================================================================*/ +#if !defined(BOOST_SPIRIT_QUICKBOOK_UTILS_HPP) +#define BOOST_SPIRIT_QUICKBOOK_UTILS_HPP + +#include +#include +#include +#include + +namespace quickbook { namespace detail +{ + template + inline void + print_char(Char ch, std::ostream& out) + { + switch (ch) + { + case '<': out << "<"; break; + case '>': out << ">"; break; + case '&': out << "&"; break; + case '"': out << """; break; + default: out << ch; break; + } + } + + template + inline void + print_space(Char ch, std::ostream& out) + { + switch (ch) + { + case ' ': out << " "; break; + default: out << ch; break; + } + } + + template + inline Char + filter_identifier_char(Char ch) + { + if (!std::isalnum(ch)) + ch = '_'; + return tolower(ch); + } + + template + inline std::string + make_identifier(Iterator const& first, Iterator const& last) + { + std::string out_name; + for (Iterator i = first; i != last; ++i) + out_name += filter_identifier_char(*i); + return out_name; + } + + template + struct var_wrapper + : public ::boost::reference_wrapper + { + typedef ::boost::reference_wrapper parent; + + explicit inline var_wrapper(T& t) : parent(t) {} + + inline T& operator()() const { return parent::get(); } + }; + + template + inline var_wrapper + var(T& t) + { + return var_wrapper(t); + } + + // un-indent a code segment + void unindent( std::string& program ) + { + std::string::size_type const n = program.find_first_not_of(" \t"); + BOOST_ASSERT( std::string::npos != n ); + program.erase( 0, n ); + + std::string::size_type pos = 0; + while( std::string::npos != ( pos = program.find( '\n', pos ) ) ) + { + if( std::string::npos == ( pos = program.find_first_not_of('\n', pos) ) ) + { + break; + } + + program.erase( pos, n ); + } + } + + // remove the extension from a filename + std::string + remove_extension(std::string const& filename) + { + std::string::size_type const n = filename.find_last_of('.'); + return std::string(filename.begin(), filename.begin()+n); + } +}} + +#endif // BOOST_SPIRIT_QUICKBOOK_UTILS_HPP + diff --git a/doc/Jamfile.v2 b/doc/Jamfile.v2 new file mode 100755 index 000000000..b4255ac25 --- /dev/null +++ b/doc/Jamfile.v2 @@ -0,0 +1,9 @@ +project boost/quickbook/doc ; +import boostbook : boostbook ; + +boostbook quickbook + : + quickbook.xml + : + boost.root=../../../.. + ; diff --git a/doc/html/boostbook.css b/doc/html/boostbook.css new file mode 100755 index 000000000..9cdda0099 --- /dev/null +++ b/doc/html/boostbook.css @@ -0,0 +1,343 @@ +/*============================================================================= + Copyright (c) 2002 2004 Joel de Guzman, Eric Niebler, Rene Rivera + 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) +=============================================================================*/ + +/* CSS based on w3c documentation which I like a lot, and the classic Spirit +documentation. */ + +/* Body defaults */ +body +{ + padding: 2em 1em 2em 1em; + margin: 1em 1em 1em 1em; + font-family: sans-serif; +} + +/* Paragraphs */ +p +{ + text-align: justify; +} + +pre.synopsis +{ + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; +} + +/* Headings */ +h1, h2, h3, h4, h5, h6 { text-align: left; margin-top: 2pc; } +h1 { font: 170% sans-serif } +h2 { font: bold 140% sans-serif } +h3 { font: 120% sans-serif } +h4 { font: bold 100% sans-serif } +h5 { font: italic 100% sans-serif } +h6 { font: italic 100% sans-serif } + +/* Unordered lists */ +ul +{ + text-align: justify; +} + +/* Links */ +a +{ + text-decoration: none; /* no underline */ +} + +a:hover +{ + text-decoration: underline; +} + +/* Top page title */ +title, h1.title, h2.title, h3.title, + h4.title, h5.title, h6.title, + .refentrytitle +{ + font-weight: bold; + font-size: 2pc; + margin-bottom: 1pc; +} + +/* Spirit style navigation */ +.spirit-nav +{ + text-align: right; +} + +.spirit-nav a +{ + color: white; + padding-left: 0.5em; +} + +.spirit-nav img +{ + border-width: 0px; +} + +/* Program listing box */ +.programlisting, .screen +{ + display: block; + margin-left: 4%; + margin-right: 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; +} + +/* Table of contents */ +.toc +{ + margin: 1pc 4% 0pc 4%; + padding: 0.5pc 0.5pc 0.5pc 0.5pc; +} + +.boost-toc +{ + float: right; + padding: 0.5pc; +} + +/* Tables */ +.table-title, div.table p.title +{ + margin-left: 4%; + padding-right: 0.5em; + padding-left: 0.5em; + font-size: 120%; +} + +.informaltable table, .table table +{ + width: 92%; + margin-left: 4%; + margin-right: 4%; +} + +div.informaltable table, div.table table +{ + padding: 4px 4px 4px 4px; +} + +div.informaltable table tr td, div.table table tr td +{ + padding: 0.5em 0.5em 0.5em 0.5em; + text-align: justify; +} + +div.informaltable table tr th, div.table table tr th +{ + padding: 0.5em 0.5em 0.5em 0.5em; + border: 1pt solid white; +} + +/* inlined images */ +.inlinemediaobject +{ + padding: 0.5em 0.5em 0.5em 0.5em; +} + +/* tone down the title of Parameter lists */ +div.variablelist p.title +{ + font-weight: bold; + font-size: 100%; + text-align: left; +} + +/* tabularize parameter lists */ +div.variablelist dl dt +{ + float: left; + clear: left; + display: block; + font-style: italic; +} + +div.variablelist dl dd +{ + display: block; + clear: right; + padding-left: 8pc; +} + +/* title of books and articles in bibliographies */ +span.title +{ + font-style: italic; +} + +/* tips, notes and warnings done in Spirit style */ +div.tip, div.note, div.warning +{ + position: relative; + padding: 0.5em; + border: 0.5pt solid white; +} + +div.tip .title, div.note .title, div.warning .title +{ + display: block; + font: bold xx-small sans-serif; + margin: 0; + padding: 0; + position: absolute; + left: -4em; + top: 0em; + height: 25px; + width: 24px; + text-indent: 32px; + overflow: hidden; + z-index: 2; +} + +div.tip .title +{ + background: url(images/tip.png); +} + +div.note .title +{ + background: url(images/note.png); +} + +div.warning .title +{ + background: url(images/caution.png); +} + +@media screen +{ + a + { + color: #005a9c; + } + + a:visited + { + color: #9c5a9c; + } + + /* Syntax Highlighting */ + .keyword { color: #0000AA; font-weight: bold; } + .identifier {} + .special { color: #707070; } + .preprocessor { color: #402080; font-weight: bold; } + .char { color: teal; } + .comment { color: #800000; } + .string { color: teal; } + .number { color: teal; } + .copyright { color: #666666; font-size: small; } + .white_bkd { background-color: #FFFFFF; } + .dk_grey_bkd { background-color: #999999; } + + pre.synopsis + { + background-color: #f3f3f3; + } + + .programlisting, .screen + { + background-color: #f3f3f3; + } + + /* Table of contents */ + .toc + { + background-color: #f3f3f3; + } + + div.informaltable table tr td, div.table table tr td + { + background-color: #F3F3F3; + border: 1pt solid white; + } + + div.informaltable table tr th, div.table table tr th + { + background-color: #e4e4e4; + } + + div.tip, div.note, div.warning + { + background-color: #F3F3F3; + } + + span.highlight + { + color: #00A000; + } +} + +@media print +{ + a + { + color: black; + } + + a:visited + { + color: black; + } + + .spirit-nav + { + display: none; + } + + /* Syntax Highlighting */ + .keyword + { + font-weight: bold; + } + + pre.synopsis + { + border: 1px solid gray; + } + + .programlisting, .screen + { + border: 1px solid gray; + } + + /* Table of contents */ + .toc + { + border: 1px solid gray; + } + + .informaltable table, .table table + { + border: 1px solid gray; + border-collapse: collapse; + } + + div.informaltable table tr td, div.table table tr td + { + border: 1px solid gray; + } + + div.informaltable table tr th, div.table table tr th + { + border: 1px solid gray; + } + + div.tip, div.note, div.warning + { + border: 1px solid gray; + } + + span.highlight + { + font-weight: bold; + } +} diff --git a/doc/html/images/alert.png b/doc/html/images/alert.png new file mode 100755 index 000000000..b4645bc7e Binary files /dev/null and b/doc/html/images/alert.png differ diff --git a/doc/html/images/home.png b/doc/html/images/home.png new file mode 100755 index 000000000..5584aacb0 Binary files /dev/null and b/doc/html/images/home.png differ diff --git a/doc/html/images/next.png b/doc/html/images/next.png new file mode 100755 index 000000000..59800b4e8 Binary files /dev/null and b/doc/html/images/next.png differ diff --git a/doc/html/images/note.png b/doc/html/images/note.png new file mode 100755 index 000000000..3ed047cac Binary files /dev/null and b/doc/html/images/note.png differ diff --git a/doc/html/images/prev.png b/doc/html/images/prev.png new file mode 100755 index 000000000..d88a40f92 Binary files /dev/null and b/doc/html/images/prev.png differ diff --git a/doc/html/images/smiley.png b/doc/html/images/smiley.png new file mode 100755 index 000000000..30a77f71c Binary files /dev/null and b/doc/html/images/smiley.png differ diff --git a/doc/html/images/tip.png b/doc/html/images/tip.png new file mode 100755 index 000000000..9f596b0b8 Binary files /dev/null and b/doc/html/images/tip.png differ diff --git a/doc/html/images/up.png b/doc/html/images/up.png new file mode 100755 index 000000000..17d9c3ec4 Binary files /dev/null and b/doc/html/images/up.png differ diff --git a/doc/html/index.html b/doc/html/index.html new file mode 100755 index 000000000..0eeb309df --- /dev/null +++ b/doc/html/index.html @@ -0,0 +1,100 @@ + + + +Part I. quickbook 1.0 + + + + + + + + + + + + + +
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
+
+
Next
+
+
+

+quickbook 1.0

+

+Joel de Guzman +

+

+Eric Niebler +

+

Copyright © 2002, 2004 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 + ) + +

+
+
+
+

+ Introduction

+

"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 +
    • +
+
+
+ + + +

Last revised: January 21, 2005 at 06:19:27 GMT

+
+
Next
+ + diff --git a/doc/html/quickbook/docinfo.html b/doc/html/quickbook/docinfo.html new file mode 100755 index 000000000..4e9f14cbf --- /dev/null +++ b/doc/html/quickbook/docinfo.html @@ -0,0 +1,167 @@ + + + + Library Document Grammar + + + + + + + + + + + + + + + +
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+

+ Library Document Grammar

+

+
doc_info =
+        space
+    >>  '['
+    >>  (   str_p("book")
+        |   "article"
+        |   "library"
+        |   "chapter"
+        |   "part"
+        )
+    >> hard_space
+    >>  (  *(anychar_p -
+            (ch_p('[') | ']' | eol_p)
+            )
+        )
+    >> *( doc_version
+        | doc_id
+        | doc_dirname
+        | doc_copyright
+        | doc_purpose
+        | doc_category
+        | doc_authors
+        | doc_license
+        | doc_last_revision
+        )
+    >> ']' >> +eol_p
+    ;
+
+doc_version =
+        space
+    >> "[version" >> hard_space
+    >> (*(anychar_p - ']'))
+    >> ']' >> +eol_p
+    ;
+
+doc_id =
+        space
+    >> "[id" >> hard_space
+    >> (*(anychar_p - ']'))
+    >> ']' >> +eol_p
+    ;
+
+doc_dirname =
+        space
+    >> "[dirname" >> hard_space
+    >> (*(anychar_p - ']'))
+    >> ']' >> +eol_p
+    ;
+
+doc_copyright =
+        space
+    >> "[copyright" >> hard_space
+    >> +( repeat_p(4)[digit_p]
+          >> space
+        )
+    >> space
+    >> (*(anychar_p - ']'))
+    >> ']' >> +eol_p
+    ;
+
+doc_purpose =
+        space
+    >> "[purpose" >> hard_space
+    >> (*(anychar_p - ']'))
+    >> ']' >> +eol_p
+    ;
+
+doc_category =
+        space
+    >> "[category" >> hard_space
+    >> (*(anychar_p - ']'))
+    >> ']' >> +eol_p
+    ;
+
+doc_author =
+        space
+    >>  '[' >> space
+    >>  (*(anychar_p - ','))
+    >>  ',' >> space
+    >>  (*(anychar_p - ']'))
+    >>  ']'
+    ;
+
+doc_authors =
+        space
+    >> "[authors" >> hard_space
+    >> doc_author
+    >> *(   ','
+            >>  doc_author
+        )
+    >> ']' >> +eol_p
+    ;
+
+doc_license =
+        space
+    >> "[license" >> hard_space
+    >> (*(anychar_p - ']'))
+    >> ']' >> +eol_p
+    ;
+
+doc_last_revision =
+        space
+    >> "[last-revision" >> hard_space
+    >> (*(anychar_p - ']'))
+    >> ']' >> +eol_p
+    ;
+
+doc_source_mode =
+    space
+    >> "[source-mode" >> hard_space
+    >> (
+          str_p("c++") 
+       |  "python"
+       )
+    >> space >> ']' >> +eol_p
+    ;
+
+comment =
+    "[/" >> *(anychar_p - ']') >> ']'
+    ;
+
+space =
+    *(space_p | comment)
+    ;
+
+hard_space =
+    (eps_p - (alnum_p | '_')) >> space  // must not be followed by
+    ;                                   // alpha-numeric or underscore
+
+
+ + + +
Copyright © 2002, 2004 Joel de Guzman, Eric Niebler
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/quickbook/highlight.html b/doc/html/quickbook/highlight.html new file mode 100755 index 000000000..61f633d75 --- /dev/null +++ b/doc/html/quickbook/highlight.html @@ -0,0 +1,111 @@ + + + + C++ Syntax Highlighting Grammar + + + + + + + + + + + + + + + +
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+

+ C++ Syntax Highlighting Grammar

+
program
+    =
+    *(  macro
+    |   preprocessor
+    |   comment
+    |   keyword
+    |   identifier
+    |   special
+    |   string_
+    |   char_
+    |   number
+    |   space_p
+    |   anychar_p
+    )
+    ;
+
+macro
+    =   *space_p >> self.macro
+    ;
+
+preprocessor
+    =   *space_p >> '#' >> ((alpha_p | '_') >> *(alnum_p | '_'))
+    ;
+
+comment
+    =   +(*space_p >> (comment_p("//") | comment_p("/*", "*/")))
+    ;
+
+keyword
+    =   *space_p >> keyword_ >> (eps_p - (alnum_p | '_'))
+    ;   // make sure we recognize whole words only
+
+keyword_
+    =   "and_eq", "and", "asm", "auto", "bitand", "bitor",
+        "bool", "break", "case", "catch", "char", "class",
+        "compl", "const_cast", "const", "continue", "default",
+        "delete", "do", "double", "dynamic_cast",  "else",
+        "enum", "explicit", "export", "extern", "false",
+        "float", "for", "friend", "goto", "if", "inline",
+        "int", "long", "mutable", "namespace", "new", "not_eq",
+        "not", "operator", "or_eq", "or", "private",
+        "protected", "public", "register", "reinterpret_cast",
+        "return", "short", "signed", "sizeof", "static",
+        "static_cast", "struct", "switch", "template", "this",
+        "throw", "true", "try", "typedef", "typeid",
+        "typename", "union", "unsigned", "using", "virtual",
+        "void", "volatile", "wchar_t", "while", "xor_eq", "xor"
+    ;
+
+special
+    =   *space_p >> +chset_p("~!%^&*()+={[}]:;,<.>?/|\\-")
+    ;
+
+string_
+    =   *space_p >> !as_lower_d['l'] >> confix_p('"', *c_escape_ch_p, '"')
+    ;
+
+char_
+    =   *space_p >> !as_lower_d['l'] >> confix_p('\'', *c_escape_ch_p, '\'')
+    ;
+
+number
+    =   *space_p >>
+        (   as_lower_d["0x"] >> hex_p
+        |   '0' >> oct_p
+        |   real_p
+        )
+        >>  *as_lower_d[chset_p("ldfu")]
+    ;
+
+identifier
+    =   *space_p >> ((alpha_p | '_') >> *(alnum_p | '_'))
+    ;
+
+ + + +
Copyright © 2002, 2004 Joel de Guzman, Eric Niebler
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/quickbook/pyhighlight.html b/doc/html/quickbook/pyhighlight.html new file mode 100755 index 000000000..dc552953f --- /dev/null +++ b/doc/html/quickbook/pyhighlight.html @@ -0,0 +1,110 @@ + + + + Python Syntax Highlighting Grammar + + + + + + + + + + + + + + +
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
+
+
+PrevUpHome +
+
+

+ Python Syntax Highlighting Grammar

+

+
program
+    =
+    *(  comment
+    |   keyword
+    |   identifier
+    |   special
+    |   string_
+    |   number
+    |   space_p
+    |   anychar_p
+    )
+    ;
+
+comment
+    =   +(*space_p >> comment_p("#"))
+    ;
+
+keyword
+    =   *space_p >> keyword_ >> (eps_p - (alnum_p | '_'))
+    ;   // make sure we recognize whole words only
+
+keyword_
+    =
+    "and",       "del",       "for",       "is",        "raise",    
+    "assert",    "elif",      "from",      "lambda",    "return",   
+    "break",     "else",      "global",    "not",       "try",  
+    "class",     "except",    "if",        "or",        "while",    
+    "continue",  "exec",      "import",    "pass",      "yield",   
+    "def",       "finally",   "in",        "print",
+
+    // Technically "as" and "None" are not yet keywords (at Python
+    // 2.4). They are destined to become keywords, and we treat them 
+    // as such for syntax highlighting purposes.
+               
+    "as", "None"
+    ;
+
+special
+    =   *space_p >> +chset_p("~!%^&*()+={[}]:;,<.>/|\\-")
+    ;
+
+string_prefix
+    =    as_lower_d[str_p("u") >> ! str_p("r")]
+    ;
+           
+string_
+    =   *space_p >> ! string_prefix >> (long_string | short_string)
+    ;
+
+short_string
+    =   confix_p('"', * c_escape_ch_p, '"') |
+        confix_p("'", * c_escape_ch_p, "'")    
+    ;
+       
+long_string
+    =   confix_p("'''", * lex_escape_ch_p, "'''") |
+        confix_p("\"\"\"", * lex_escape_ch_p, "\"\"\"")
+    ;
+           
+number
+    =   *space_p >>
+        (
+            as_lower_d["0x"] >> hex_p
+        |   '0' >> oct_p
+        |   real_p
+        )
+        >>  *as_lower_d[chset_p("lj")]
+    ;
+
+identifier
+    =   *space_p >> ((alpha_p | '_') >> *(alnum_p | '_'))
+    ;
+
+ + + +
Copyright © 2002, 2004 Joel de Guzman, Eric Niebler
+
+
+PrevUpHome +
+ + diff --git a/doc/html/quickbook/quickbook.html b/doc/html/quickbook/quickbook.html new file mode 100755 index 000000000..d52c5b856 --- /dev/null +++ b/doc/html/quickbook/quickbook.html @@ -0,0 +1,536 @@ + + + + QuickBook Grammar + + + + + + + + + + + + + + + +
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+

+ QuickBook Grammar

+
library =
+    *(space_p | comment) >> blocks >> blank
+    ;
+
+blocks =
+   +(   block_markup
+    |   code
+    |   list
+    |   hr
+    |   comment >> *eol
+    |   paragraph
+    |   eol
+    )
+    ;
+
+space =
+    *(space_p | comment)
+    ;
+
+blank =
+    *(blank_p | comment)
+    ;
+
+eol = blank >> eol_p
+    ;
+
+close_bracket =
+    ']' |
+    if_p(var(is_not_preformatted))
+    [
+        eol_p >> eol_p                  // Make sure that we don't go
+    ]                                   // past a single block, except
+    ;                                   // when preformatted.
+
+hard_space =
+    (eps_p - (alnum_p | '_')) >> space  // must not be followed by
+    ;                                   // alpha-numeric or underscore
+
+comment =
+    "[/" >> *(anychar_p - ']') >> ']'
+    ;
+
+hr =
+    str_p("----")
+    >> *(anychar_p - eol)
+    >> +eol
+    ;
+
+block_markup =
+        '['
+    >>  (   begin_section
+        |   end_section
+        |   headings
+        |   blurb
+        |   blockquote
+        |   preformatted
+        |   def_macro
+        |   table
+        |   variablelist
+        |   xinclude
+        )
+    >>  (   (']' >> +eol)
+        |   eps_p
+        )
+    ;
+
+begin_section =
+       "section"
+    >> hard_space
+    >>  (':' >> (*(alnum_p | '_'))
+        | eps_p
+        )
+    >> (*(anychar_p -
+            close_bracket))
+    ;
+
+end_section =
+    str_p("endsect")
+    ;
+
+headings =
+    h1 | h2 | h3 | h4 | h5 | h6
+    ;
+
+h1 = "h1" >> hard_space >> phrase
+h2 = "h2" >> hard_space >> phrase
+h3 = "h3" >> hard_space >> phrase
+h4 = "h4" >> hard_space >> phrase
+h5 = "h5" >> hard_space >> phrase
+h6 = "h6" >> hard_space >> phrase
+
+blurb =
+    "blurb" >> hard_space
+    >> phrase
+    ;
+
+blockquote =
+    ':' >> blank >>
+    phrase
+    ;
+
+preformatted =
+    "pre" >> hard_space
+    >> !eol >> phrase
+    >> eps_p
+    ;
+
+def_macro =
+    "def" >> hard_space
+    >> identifier
+    >> blank >> phrase
+    ;
+
+table =
+    "table" >> hard_space
+    >>  (*(anychar_p - eol))
+    >>  +eol
+    >>  *table_row
+    >>  eps_p
+    ;
+
+table_row =
+    space
+    >>  ch_p('[')
+    >>
+    (
+        (
+            *table_cell
+            >>  ch_p(']')
+            >>  space
+        )
+        | eps_p
+    )
+    ;
+
+table_cell =
+    space
+    >>  ch_p('[')
+    >>
+    (
+        (
+            phrase
+            >>  ch_p(']')
+            >>  space
+        )
+        | eps_p
+    )
+    ;
+
+variablelist =
+    "variablelist" >> hard_space
+    >>  (*(anychar_p - eol))
+    >>  +eol
+    >>  *varlistentry
+    >>  eps_p
+    ;
+
+varlistentry =
+    space
+    >>  ch_p('[')
+    >>
+    (
+        (
+            varlistterm
+            >> +varlistitem
+            >>  ch_p(']')
+            >>  space
+        )
+        | eps_p
+    )
+    ;
+
+varlistterm =
+    space
+    >>  ch_p('[')
+    >>
+    (
+        (
+            phrase
+            >>  ch_p(']')
+            >>  space
+        )
+        | eps_p
+    )
+    ;
+
+varlistitem =
+    space
+    >>  ch_p('[')
+    >>
+    (
+        (
+            phrase
+            >>  ch_p(']')
+            >>  space
+        )
+        | eps_p
+    )
+    ;
+
+xinclude =
+       "xinclude"
+    >> hard_space
+    >> (*(anychar_p -
+            close_bracket))
+    ;
+
+identifier =
+    *(anychar_p - (space_p | ']'))
+    ;
+
+source_mode =
+   (
+       str_p("c++")
+       |   "python"
+   )
+   ;
+            
+code =
+    (
+        code_line
+        >> *(*eol >> code_line)
+    )
+    >> +eol
+    ;
+
+code_line =
+    ((ch_p(' ') | '\t'))
+    >> *(anychar_p - eol) >> eol
+    ;
+
+list =
+    eps_p(ch_p('*') | '#') >>
+   +(
+        (*blank_p
+        >> (ch_p('*') | '#'))
+        >> *blank_p
+        >> list_item
+    )
+    ;
+
+list_item =
+   *(   common
+    |   (anychar_p -
+            (   eol_p >> *blank_p >> eps_p(ch_p('*') | '#')
+            |   (eol >> eol)
+            )
+        )
+    )
+    >> +eol
+    ;
+
+common =
+        self.actions.macro
+    |   phrase_markup
+    |   inline_code
+    |   simple_format
+    |   escape
+    |   comment
+    ;
+
+inline_code =
+    '`' >>
+    (
+       *(anychar_p -
+            (   '`'
+            |   (eol >> eol)            // Make sure that we don't go
+            )                           // past a single block
+        ) >> eps_p('`')
+    )
+    >>  '`'
+    ;
+
+simple_format =
+        simple_bold
+    |   simple_italic
+    |   simple_underline
+    |   simple_teletype
+    ;
+
+simple_bold =
+    '*' >>
+    (
+        (   graph_p >>                  // graph_p must follow '*'
+            *(anychar_p -
+                (   eol                 // Make sure that we don't go
+                |   (graph_p >> '*')    // past a single line
+                )
+            ) >> graph_p                // graph_p must precede '*'
+            >> eps_p('*'
+                >> (space_p | punct_p)) // space_p or punct_p must
+        )                               // follow '*'
+    |   (
+            graph_p                     // A single char. e.g. *c*
+            >> eps_p('*'
+                >> (space_p | punct_p))
+        )
+    )
+    >> '*'
+    ;
+
+simple_italic =
+    '/' >>
+    (
+        (   graph_p >>                  // graph_p must follow '/'
+            *(anychar_p -
+                (   eol                 // Make sure that we don't go
+                |   (graph_p >> '/')    // past a single line
+                )
+            ) >> graph_p                // graph_p must precede '/'
+            >> eps_p('/'
+                >> (space_p | punct_p)) // space_p or punct_p must
+        )                               // follow '/'
+    |   (
+            graph_p                     // A single char. e.g. /c/
+            >> eps_p('/'
+                >> (space_p | punct_p))
+        )
+    )
+    >> '/'
+    ;
+
+simple_underline =
+    '_' >>
+    (
+        (   graph_p >>                  // graph_p must follow '_'
+            *(anychar_p -
+                (   eol                 // Make sure that we don't go
+                |   (graph_p >> '_')    // past a single line
+                )
+            ) >> graph_p                // graph_p must precede '_'
+            >> eps_p('_'
+                >> (space_p | punct_p)) // space_p or punct_p must
+        )                               // follow '_'
+    |   (
+            graph_p                     // A single char. e.g. _c_
+            >> eps_p('_'
+                >> (space_p | punct_p))
+        )
+    )
+    >> '_'
+    ;
+
+simple_teletype =
+    '=' >>
+    (
+        (   graph_p >>                  // graph_p must follow '='
+            *(anychar_p -
+                (   eol                 // Make sure that we don't go
+                |   (graph_p >> '=')    // past a single line
+                )
+            ) >> graph_p                // graph_p must precede '='
+            >> eps_p('='
+                >> (space_p | punct_p)) // space_p or punct_p must
+        )                               // follow '='
+    |   (
+            graph_p                     // A single char. e.g. =c=
+            >> eps_p('='
+                >> (space_p | punct_p))
+        )
+    )
+    >> '='
+    ;
+
+paragraph =
+   *(   common
+    |   (anychar_p -                    // Make sure we don't go past
+            (eol >> eol)                // a single block.
+        )
+    )
+    >> +eol
+    ;
+
+phrase =
+   *(   common
+    |   comment
+    |   (anychar_p -
+            close_bracket)
+    )
+    ;
+
+phrase_markup =
+        '['
+    >>  (   image
+        |   url
+        |   link
+        |   anchor
+        |   source_mode
+        |   funcref
+        |   classref
+        |   memberref
+        |   enumref
+        |   bold
+        |   italic
+        |   underline
+        |   teletype
+        |   str_p("br")
+        )
+    >>  ']'
+    ;
+
+escape =
+        str_p("\\n")
+    |   '\\' >> punct_p
+    |   (
+            "'''" >> !eol
+        >>  *(anychar_p - "'''")
+        >>  "'''"
+        )
+    ;
+
+image =
+        '$' >> blank
+    >> (*(anychar_p -
+            close_bracket))
+    ;
+
+url =
+        '@'
+    >>  (*(anychar_p -
+            (']' | hard_space)))
+    >>  (   eps_p(']')
+        |   (hard_space >> phrase)
+        )
+    ;
+
+link =
+        "link" >> hard_space
+    >>  (*(anychar_p -
+            (']' | hard_space)))
+    >>  (   eps_p(']')
+        |   (hard_space >> phrase)
+        )
+    ;
+
+anchor =
+        '#'
+    >>  blank
+    >>  (   *(anychar_p -
+                close_bracket)
+        )
+    ;
+
+funcref =
+    "funcref" >> hard_space
+    >>  (*(anychar_p -
+            (']' | hard_space)))
+    >>  (   eps_p(']')
+        |   (hard_space >> phrase)
+        )
+    ;
+
+classref =
+    "classref" >> hard_space
+    >>  (*(anychar_p -
+            (']' | hard_space)))
+    >>  (   eps_p(']')
+        |   (hard_space >> phrase)
+        )
+    ;
+
+memberref =
+    "memberref" >> hard_space
+    >>  (*(anychar_p -
+            (']' | hard_space)))
+    >>  (   eps_p(']')
+        |   (hard_space >> phrase)
+        )
+    ;
+
+enumref =
+    "enumref" >> hard_space
+    >>  (*(anychar_p -
+            (']' | hard_space)))
+    >>  (   eps_p(']')
+        |   (hard_space >> phrase)
+        )
+    ;
+
+bold =
+        ch_p('*')
+    >>  blank >> phrase
+    ;
+
+italic =
+        ch_p('\'')
+    >>  blank >> phrase
+    ;
+
+underline =
+        ch_p('_')
+    >>  blank >> phrase
+    ;
+
+teletype =
+        ch_p('^')
+    >>  blank >> phrase
+    ;
+
+ + + +
Copyright © 2002, 2004 Joel de Guzman, Eric Niebler
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/quickbook/ref.html b/doc/html/quickbook/ref.html new file mode 100755 index 000000000..13d1bc37e --- /dev/null +++ b/doc/html/quickbook/ref.html @@ -0,0 +1,219 @@ + + + + Quick Reference + + + + + + + + + + + + + + + +
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+

+ Quick Reference

+
+

+Syntax Compendium +

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
To do this...Use this...
comment[/ some comment]
italics['italics] or /italics/
bold[*bold] or *bold*
underline[_underline] or _underline_
teletype[^teletype] or =teletype=
source mode +[c++] or [python] +
inline code`int main();`
line break[br]
line break\n
anchor[#anchor]
link[@http://www.boost.org Boost]
anchor link[link section.anchor Link text]
refentry link[link xml.refentry Link text]
function link[funcref fully::qualified::function_name Link text]
class link[classref fully::qualified::class_name Link text]
member link[memberref fully::qualified::member_name Link text]
enum link[enumref fully::qualified::enum_name Link text]
escape'''escaped text (no processing/formatting)'''
single char escape\c
images[$image.jpg]
begin section[section The Section Title]
end section[endsect]
paragraphNo markup. Paragraphs start left-flushed and are terminated by two or more newlines.
ordered list# one
+# two
+# three
unordered list* one
+* two
+* three
codeNo markup. Preformatted code starts with a space or a tab.
preformatted[pre preformatted]
block quote[:sometext...]
heading 1[h1 Heading 1]
heading 2[h2 Heading 2]
heading 3[h3 Heading 3]
heading 4[h4 Heading 4]
heading 5[h5 Heading 5]
heading 6[h6 Heading 6]
macro[def macro_identifier some text]
blurb[blurb advertisement or note...]
table[table Title
+ [[a][b][c]]
+ [[a][b][c]]
+]
variablelist[variablelist Title
+ [[a][b]]
+ [[a][b]]
+]
+
+
+ + + +
Copyright © 2002, 2004 Joel de Guzman, Eric Niebler
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/html/quickbook/syntax.html b/doc/html/quickbook/syntax.html new file mode 100755 index 000000000..3a9af625c --- /dev/null +++ b/doc/html/quickbook/syntax.html @@ -0,0 +1,927 @@ + + + + Syntax Summary + + + + + + + + + + + + + + + +
boost.png (6897 bytes)HomeLibrariesPeopleFAQMore
+
+
+PrevUpHomeNext +
+
+

+ Syntax Summary

+

+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.

+

+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.

+

+Comments

+

+Can be placed anywhere.

+
[/ comment (no output generated) ]
+
+

+Phrase Level Elements

+

+Font Styles

+
['italic], [*bold], [_underline], [^teletype]
+
+

+will generate:

+

italic, bold, underline, teletype

+

+Like all non-terminal phrase level elements, this can of course be nested:

+
[*['bold-italic]]
+
+

+will generate:

+

bold-italic

+

+Simple formatting

+

+Simple markup for formatting text, common in many applications, is now supported:

+
/italic/, *bold*, _underline_, =teletype=
+
+

+will generate:

+

italic, bold, underline, teletype

+

+Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives +are much stricter.

+
    +
  • +Simple markups cannot nest. You can combine a simple markup with a nestable markup. +
    • +
  • +A non-space character must follow the leading markup +
    • +
  • +A non-space character must precede the trailing markup +
    • +
  • +A space or a punctuation must follow the trailing markup +
    • +
  • +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 '*'. +
    • +
  • +A line starting with the star will be interpreted as an unordered list. + See Unordered lists. +
    • +
+
+

+More Formatting Samples +

+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
MarkupResult
*Bold*Bold
*Is bold*Is bold
* Not bold* *Not bold * * Not bold ** Not bold* *Not bold * * Not bold *
This*Isn't*Bold (no bold)This*Isn't*Bold (no bold)
(*Bold Inside*) (parenthesis not bold)(Bold Inside) (parenthesis not bold)
*(Bold Outside)* (parenthesis bold) +(Bold Outside) (parenthesis bold)
3*4*5 = 60 (no bold)3*4*5 = 60 (no bold)
3 * 4 * 5 = 60 (no bold)3 * 4 * 5 = 60 (no bold)
3 *4* 5 = 60 (4 is bold)3 4 5 = 60 (4 is bold)
*This is bold* this is not *but this is* +This is bold this is not but this is +
*This is bold*. +This is bold.
*B*. (bold B) +B. (bold B)
['*Bold-Italic*]Bold-Italic
+
+
+ + +
+ Thanks to David Barrett, author of +Qwiki, for sharing these samples +and teaching me these obscure formatting rules. I wasn't sure at all if Spirit, +being more or less a formal EBNF parser, can handle the context sensitivity and ambiguity.
+

+Inline code

+

+Inlining code in paragraphs is quite common when writing C++ documentation. We +provide a very simple markup for this. For example, this:

+
This text has inlined code `int main() { return 0; }` in it.
+
+

+will generate:

+

+This text has inlined code int main() { return 0; } in it. The code will be +syntax highlighted.

+
+ + +
+ +Note that we simply enclose the code with the tick: "`", not the +single quote: "'". Note too that `some code` is prefered over +[^some code]. +
+

+Source Mode

+

+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 Document Info section.

+

+To change the source mode, use the [source-mode] markup, where +source-mode is one of the supported modes. For example, this:

+
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`.
+
+

+will generate:

+

+Python's import is rather like C++'s #include. A +C++ comment // looks like this whereas a Python comment +#looks like this.

+
+

+Supported Source Modes +

+ ++++ + + + + + + + + + + + + + + +
ModeSource Mode Markup
C++[c++]
Python[python]
+
+
+ + +
+ The source mode strings are lowercase.
+

+line-break

+
[br]
+
+
+ + +
+ Note that \n is now preferred over [br].
+

+Anchors

+
[#named_anchor]
+
+

+A named anchor is a hook that can be referenced by a link elsewhere in the +document. You can then reference an anchor with [link named_anchor Some link text]. +More on anchors here, here and +here.

+

+Links

+
[@http://www.boost.org this is [*boost's] website....]
+
+

+will generate:

+

this is boost's website....

+

+URL links where the link text is the link itself is common. Example:

+
see http://spirit.sourceforge.net/
+
+

+so, when the text is absent in a link markup, the URL is assumed. Example:

+
see [@http://spirit.sourceforge.net/]
+
+

+will generate:

+

+see http://spirit.sourceforge.net/

+

+Anchor links

+

+You can link within a document using:

+
[link section_id.normalized_header_text The link text]
+
+

+See sections Section and Headings +for more info.

+

+refentry links

+

+In addition, you can link internally to an XML refentry like:

+
[link xml.refentry The link text]
+
+

+This gets converted into <link linkend="xml.refentry">The link text</link>.

+

+Like URLs, the link text is optional. If this is not present, the link text will +automatically be the refentry. Example:

+
[link xml.refentry]
+
+

+This gets converted into <link linkend="xml.refentry">xml.refentry</link>.

+

+function, class or member links

+

+If you want to link to a function, class, member or enum in the reference section, you +can use:

+
[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]
+
+

+Again, the link text is optional. If this is not present, the link text will +automatically be the function, class, member or enum. Example:

+
[classref boost::bar::baz]
+
+

+would have "boost::bar::baz" as the link text.

+

+Escape

+

+The escape mark-up is used when we don't want to do any processing.

+
'''
+escape (no processing/formatting)
+'''
+
+

+Escaping allows us to pass XML markup to BoostBook or DocBook. For example:

+
'''
+<emphasis role="bold">This is direct XML markup</emphasis>
+'''
+
+

This is direct XML markup

+
+ + +
+ Be careful when using the escape. The text must conform to +BoostBook/DocBook syntax.
+

+Single char escape

+

+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 [ and ]. +For example, how do you escape the triple quote? Simple: \'\'\'

+

\n has a special meaning. It is used to generate line breaks. Note that \n +is now preferred over [br].

+

+Images (terminal)

+
[$image.jpg]
+
+

+Block Level Elements

+

+Document

+

+Every document must begin with a Document Info section, which should look +like this:

+
[document-type The Document Title
+    [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]
+    [last-revision $Date$]
+    [source-mode source-type]
+]
+
+

+Where document-type is one of:

+
    +
  • +book +
    • +
  • +library +
    • +
  • +part +
    • +
  • +article +
    • +
  • +chapter +
    • +
+

+and version, id, dirname, copyright, purpose, category, authors, +license, last-revision and source-mode are optional information.

+

+Here source-type is a lowercase string setting the initial +source mode. If the source-mode field is omitted, a +default value of c++ will be used.

+

+Section

+

+Starting a new section is accomplished with:

+
[section:id The Section Title]
+
+

+where id 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 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".

+

+End a section with:

+
[endsect]
+
+

+Sections can nest, and that results in a hierarchy in the table of contents.

+

+xinclude

+

+You can include another XML file with:

+
[xinclude file.xml]
+
+

+This is useful when file.xml has been generated by Doxygen and contains your +reference section.

+

+Paragraphs

+

+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.

+

+Ordered lists

+
# One
+# Two
+# Three
+
+

+will generate:

+
    +
  1. +One +
    2. +
  2. +Two +
    3. +
  3. +Three +
    4. +
+

+List hierarchies are supported. Example:

+
# One
+# Two
+# Three
+    # Three.a
+    # Three.b
+    # Three.c
+# Four
+    # Four.a
+        # Four.a.i
+        # Four.a.ii
+    # Four.b
+
+

+will generate:

+
    +
  1. +One +
    2. +
  2. +Two +
    3. +
  3. +Three
      +
    1. +Three.a +
      2. +
    2. +Three.b +
      3. +
    3. +Three.c +
      4. +
    +
    4. +
  4. +Fourth
      +
    1. +Four.a
        +
      1. +Four.a.i +
        2. +
      2. +Four.a.ii +
        3. +
      +
      2. +
    2. +Four.b +
      3. +
    +
    5. +
+

+Long lines will be wrapped appropriately. Example:

+
# 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.
+
+
    +
  1. +A short item. +
    2. +
  2. +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. +
    3. +
  3. +A short item. +
    4. +
+

+Unordered lists

+
* First
+* Second
+* Third
+
+

+will generate:

+
    +
  • +First +
    • +
  • +Second +
    • +
  • +Third +
    • +
+

+Mixed lists (ordered and unordered) are supported. Example:

+
# One
+# Two
+# Three
+    * Three.a
+    * Three.b
+    * Three.c
+
+

+will generate:

+
    +
  1. +One +
    2. +
  2. +Two +
    3. +
  3. +Three
      +
    • +Three.a +
      • +
    • +Three.b +
      • +
    • +Three.c +
      • +
    +
    4. +
+

+Code

+

+Preformatted code starts with a space or a tab. The code will be +syntax highlighted according to the current source mode:

+

+
#include <iostream>
+
+int main()
+{
+    // Sample code
+    std::cout << "Hello, World\n";
+    return 0;
+}
+

+
import cgi
+
+def cookForHtml(text):
+    '''"Cooks" the input text for HTML.'''
+    
+    return cgi.escape(text)
+

+Macros that are already defined are expanded in source code. Example:

+
[def __syntax_highlight__ [@highlight.html syntax_highlight]]
+[def __quickbook__ [@../index.html quickbook]]
+
+    using __quickbook__::__syntax_highlight__;
+
+

+Generates:

+
using __quickbook__::__syntax_highlight__;
+

+Preformatted

+

+Sometimes, you don't want some preformatted text to be parsed as C++. In such +cases, use the [pre ... ] markup block.

+
[pre
+
+    Some *preformatted* text                    Some *preformatted* text
+
+        Some *preformatted* text            Some *preformatted* text
+
+            Some *preformatted* text    Some *preformatted* text
+
+]
+
+

+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:

+
Some preformatted text                    Some preformatted text
+
+    Some preformatted text            Some preformatted text
+
+        Some preformatted text    Some preformatted text
+
+
+

+Notice that unlike Code, phrase markup such as font style is still permitted +inside pre blocks.

+

+Blockquote

+
[:sometext...]
+
+

Indents the paragraph. This applies to one paragraph only.

+

+Headings

+
[h1 Heading 1]
+[h2 Heading 2]
+[h3 Heading 3]
+[h4 Heading 4]
+[h5 Heading 5]
+[h6 Heading 6]
+
+

+Heading 1

+

+Heading 2

+

+Heading 3

+

+Heading 4

+
+Heading 5
+

+Heading 6

+

+Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized +names with name="section_id.normalized_header_text" (i.e. 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. For example: Heading +1 in section Section 2 will be normalized to section_2.heading_1). You can use:

+
[link section_id.normalized_header_text The link text]
+
+

+to link to them. See Anchor links and +Section for more info.

+

+Macros

+
[def macro_identifier some text]
+
+

+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:

+
[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]]
+sf_logo
+
+

+Now everywhere the sf_logo is placed, the picture will be inlined.

+

+
+ + +
+ 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. __spirit__). The reason is to avoid unwanted macro replacement.
+

+Links (URLS) and images are good candidates for macros. 1) 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. 2) The syntax is not pretty. It's easier to read and +write, e.g. __spirit__ than [@http://spirit.sourceforge.net Spirit].

+

+Some more examples:

+
[def :-)            [$theme/smiley.png]]
+[def __spirit__     [@http://spirit.sourceforge.net Spirit]]
+
+

+(See Images +and Links)

+

+Invoking these macros:

+
Hi __spirit__  :-)
+
+

+will generate this:

+

+Hi Spirit

+

+Predefined Macros

+

+Quickbook has some predefined macros that you can already use.

+
+

+Predefined Macros +

+ +++++ + + + + + + + + + + + + + + + + + + + + + + +
MacroMeaningExample
__DATE__Today's date2005-Jan-26
__TIME__The current time10:59:00 AM
__FILENAME__Quickbook source filenamequickbook.qbk
+
+

+Blurbs

+
[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++.
+]
+
+

+will generate this:

+
+ + +
+An eye catching advertisement or note...

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++. +
+

+Tables

+
[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]]
+]
+
+

+will generate:

+
+

+A Simple Table +

+ +++++ + + + + + + + + + + + + + + + + + + + + + + +
Heading 1Heading 2Heading 3
R0-C0R0-C1R0-C2
R2-C0R2-C1R2-C2
R3-C0R3-C1R3-C2
+
+

+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 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]
+    ]
+]
+
+

+and thus:

+
+

+Table with fat cells +

+ ++++ + + + + + + + + + + + + + + +
Heading 1Heading 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 cellRow 1, Col 1: a small cell
+
+

+Variable Lists

+
[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]]
+]
+
+

+will generate:

+
+

A Variable List

+
+
term 1
+
The definition of term 1
+
term 2
+
The definition of term 2
+
term 3
+
The definition of term 3
+
+
+

+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".

+
+ + + +
Copyright © 2002, 2004 Joel de Guzman, Eric Niebler
+
+
+PrevUpHomeNext +
+ + diff --git a/doc/quickbook.qbk b/doc/quickbook.qbk new file mode 100755 index 000000000..c07368ded --- /dev/null +++ b/doc/quickbook.qbk @@ -0,0 +1,1638 @@ +[part quickbook + [version 1.0] + [authors [de Guzman, Joel], [Niebler, Eric]] + [copyright 2002 2004 Joel de Guzman, Eric Niebler] + [purpose WikiWiki style documentation tool] + [license + 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 + ) + ] + [last-revision $Date$] +] + +[/ QuickBook Document version 0.9 ] +[/ Sept 24, 2002 ] +[/ Sept 2, 2004 ] + +[/ Some links] + +[def __note__ [$images/note.png]] +[def __alert__ [$images/alert.png]] +[def __tip__ [$images/tip.png]] +[def :-) [$images/smiley.png]] +[def __spirit__ [@http://spirit.sourceforge.net Spirit]] +[def __boostbook__ [@http://www.boost.org/doc/html/boostbook.html BoostBook]] +[def __docbook__ [@http://www.docbook.org/ DocBook]] + +[section:intro Introduction] + +[:[*['"Why program by hand in five days what you can spend five years of your +life automating?"]]\n\n-- 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 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 + +[endsect] +[section:syntax Syntax Summary] + +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. + +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. + +[h2 Comments] + +Can be placed anywhere. + +[pre +'''[/ comment (no output generated) ]''' +] + +[h2 Phrase Level Elements] + +[h3 Font Styles] + +[pre''' +['italic], [*bold], [_underline], [^teletype] +'''] + +will generate: + +['italic], [*bold], [_underline], [^teletype] + +Like all non-terminal phrase level elements, this can of course be nested: + +[pre''' +[*['bold-italic]] +'''] + +will generate: + +[*['bold-italic]] + +[h3 Simple formatting] + +Simple markup for formatting text, common in many applications, is now supported: + +[pre''' +/italic/, *bold*, _underline_, =teletype= +'''] + +will generate: + +/italic/, *bold*, _underline_, =teletype= + +Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives +are much stricter. + +* Simple markups cannot nest. You can combine a simple markup with a nestable markup. +* A non-space character must follow the leading markup +* A non-space character must precede the trailing markup +* A space or a punctuation must follow the trailing markup +* 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 '*'. +* A line starting with the star will be interpreted as an unordered list. + See [link syntax.unordered_lists Unordered lists]. + +[table More Formatting Samples + [[Markup] [Result]] + [[[^'''*Bold*''']] [*Bold*]] + [[[^'''*Is bold*''']] [*Is bold*]] + [[[^'''* Not bold* *Not bold * * Not bold *''']] [* Not bold* *Not bold * * Not bold *]] + [[[^'''This*Isn't*Bold (no bold)''']] [This*Isn't*Bold (no bold)]] + [[[^'''(*Bold Inside*) (parenthesis not bold)''']] [(*Bold Inside*) (parenthesis not bold)]] + [[[^'''*(Bold Outside)* (parenthesis bold)''']] [*(Bold Outside)* (parenthesis bold)]] + [[[^'''3*4*5 = 60 (no bold)''']] [3*4*5 = 60 (no bold)]] + [[[^'''3 * 4 * 5 = 60 (no bold)''']] [3 * 4 * 5 = 60 (no bold)]] + [[[^'''3 *4* 5 = 60 (4 is bold)''']] [3 *4* 5 = 60 (4 is bold)]] + [[[^'''*This is bold* this is not *but this is*''']][*This is bold* this is not *but this is*]] + [[[^'''*This is bold*.''']] [*This is bold*.]] + [[[^'''*B*. (bold B)''']] [*B*. (bold B)]] + [[[^'''['*Bold-Italic*]''']] [['*Bold-Italic*]]] +] + +[blurb __note__ Thanks to David Barrett, author of +[@http://quinthar.com/qwikiwiki/index.php?page=Home Qwiki], for sharing these samples +and teaching me these obscure formatting rules. I wasn't sure at all if __spirit__, +being more or less a formal EBNF parser, can handle the context sensitivity and ambiguity.] + +[h3 Inline code] + +Inlining code in paragraphs is quite common when writing C++ documentation. We +provide a very simple markup for this. For example, this: + +[pre''' +This text has inlined code `int main() { return 0; }` in it. +'''] + +will generate: + +This text has inlined code `int main() { return 0; }` in it. The code will be +syntax highlighted. + +[blurb __note__ +Note that we simply enclose the code with the tick: [^'''"`"'''], not the +single quote: `"'"`. Note too that [^'''`some code`'''] is prefered over +[^'''[^some code]''']. +] + +[h3 Source Mode] + +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 syntax.document Document Info] section. + +To change the source mode, use the [^\[source-mode\]] markup, where +=source-mode= is one of the supported modes. For example, this: + +[pre''' +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`. +'''] + +will generate: + +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`. + +[table Supported Source Modes + [[Mode] [Source Mode Markup]] + [[C++] [[^\[c++\]]]] + [[Python] [[^\[python\]]]] +] + +[blurb __note__ The source mode strings are lowercase.] + +[h3 line-break] + +[pre''' +[br] +'''] + +[blurb __note__ Note that `\n` is now preferred over `[br]`.] + +[h3 Anchors] + +[pre''' +[#named_anchor] +'''] + +A named anchor is a hook that can be referenced by a link elsewhere in the +document. You can then reference an anchor with [^'''[link named_anchor Some link text]''']. +More on anchors [link syntax.anchor_links here], [link syntax.section here] and +[link syntax.headings here]. + +[h3 Links] + +[pre''' +[@http://www.boost.org this is [*boost's] website....] +'''] + +will generate: + +[@http://www.boost.org this is [*boost's] website....] + +URL links where the link text is the link itself is common. Example: + +[pre''' +see http://spirit.sourceforge.net/ +'''] + +so, when the text is absent in a link markup, the URL is assumed. Example: + +[pre +see '''[@http://spirit.sourceforge.net/]''' +] + +will generate: + +see [@http://spirit.sourceforge.net/] + +[h3 Anchor links] + +You can link within a document using: + +[pre''' +[link section_id.normalized_header_text The link text] +'''] + +See sections [link syntax.section Section] and [link syntax.headings Headings] +for more info. + +[h3 refentry links] + +In addition, you can link internally to an XML refentry like: + +[pre''' +[link xml.refentry The link text] +'''] + +This gets converted into [^The link text]. + +Like URLs, the link text is optional. If this is not present, the link text will +automatically be the refentry. Example: + +[pre''' +[link xml.refentry] +'''] + +This gets converted into [^xml.refentry]. + +[h3 function, class or member links] + +If you want to link to a function, class, member or enum in the reference section, you +can use: + +[pre''' +[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] +'''] + +Again, the link text is optional. If this is not present, the link text will +automatically be the function, class, member or enum. Example: + +[pre''' +[classref boost::bar::baz] +'''] + +would have "boost::bar::baz" as the link text. + +[h3 Escape] + +The escape mark-up is used when we don't want to do any processing. + +[pre +\'\'\' +escape (no processing/formatting) +\'\'\' +] + +Escaping allows us to pass XML markup to __boostbook__ or __docbook__. For example: + +[pre +\'\'\' +This is direct XML markup +\'\'\' +] + +''' +This is direct XML markup +''' + +[blurb __alert__ Be careful when using the escape. The text must conform to +__boostbook__/__docbook__ syntax.] + +[h3 Single char escape] + +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 `[` and `]`. +For example, how do you escape the triple quote? Simple: [^\\'\\'\\'] + +`\n` has a special meaning. It is used to generate line breaks. Note that `\n` +is now preferred over `[br]`. + +[h3 Images (terminal)] + +[pre''' +[$image.jpg] +'''] + +[h2 Block Level Elements] + +[h3 Document] + +Every document must begin with a Document Info section, which should look +like this: + +[pre''' +[document-type The Document Title + [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] + [last-revision $Date$] + [source-mode source-type] +] +'''] + +Where document-type is one of: + +* book +* library +* part +* article +* chapter + +and =version=, =id=, =dirname=, =copyright=, =purpose=, =category=, =authors=, +=license=, =last-revision= and =source-mode= are optional information. + +Here =source-type= is a lowercase string setting the initial +[link syntax.source_mode source mode]. If the =source-mode= field is omitted, a +default value of =c++= will be used. + +[h3 Section] + +Starting a new section is accomplished with: + +[pre''' +[section:id The Section Title] +'''] + +where /id/ 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 =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". + +End a section with: + +[pre''' +[endsect] +'''] + +Sections can nest, and that results in a hierarchy in the table of contents. + +[h3 xinclude] + +You can include another XML file with: + +[pre''' +[xinclude file.xml] +'''] + +This is useful when file.xml has been generated by Doxygen and contains your +reference section. + +[h3 Paragraphs] + +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. + +[h3 Ordered lists] + +[pre +# One +# Two +# Three +] + +will generate: + +# One +# Two +# Three + +List hierarchies are supported. Example: + +[pre +# One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Four + # Four.a + # Four.a.i + # Four.a.ii + # Four.b +] + +will generate: + +# One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Fourth + # Four.a + # Four.a.i + # Four.a.ii + # Four.b + +Long lines will be wrapped appropriately. Example: + +[pre +# 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. +] + +# 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. + +[h3 Unordered lists] + +[pre''' +* First +* Second +* Third +'''] + +will generate: + +* First +* Second +* Third + +Mixed lists (ordered and unordered) are supported. Example: + +[pre''' +# One +# Two +# Three + * Three.a + * Three.b + * Three.c +'''] + +will generate: + +# One +# Two +# Three + * Three.a + * Three.b + * Three.c + +[h3 Code] + +Preformatted code starts with a space or a tab. The code will be +syntax highlighted according to the current [link syntax.source_mode source mode]: + +[c++] + + #include + + int main() + { + // Sample code + std::cout << "Hello, World\n"; + return 0; + } + +[python] + + import cgi + + def cookForHtml(text): + '''"Cooks" the input text for HTML.''' + + return cgi.escape(text) + +Macros that are already defined are expanded in source code. Example: + +[pre''' +[def __syntax_highlight__ [@highlight.html syntax_highlight]] +[def __quickbook__ [@../index.html quickbook]] + + using __quickbook__::__syntax_highlight__; +'''] + +Generates: + +[def __syntax_highlight__ [@highlight.html syntax_highlight]] +[def __quickbook__ [@../index.html quickbook]] + + using __quickbook__::__syntax_highlight__; + +[h3 Preformatted] + +Sometimes, you don't want some preformatted text to be parsed as C++. In such +cases, use the [^[pre ... \]] markup block. + +[pre''' +[pre + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] +'''] + +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: + +[pre + +Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] + +Notice that unlike Code, phrase markup such as font style is still permitted +inside =pre= blocks. + +[h3 Blockquote] + +[pre +'''[:sometext...]''' +] + +[:Indents the paragraph. This applies to one paragraph only.] + +[h3 Headings] + +[pre''' +[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] +'''] + +[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] + +Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized +names with [^name="section_id.normalized_header_text"] (i.e. 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. For example: Heading +1 in section Section 2 will be normalized to [^section_2.heading_1]). You can use: + +[pre''' +[link section_id.normalized_header_text The link text] +'''] + +to link to them. See [link syntax.anchor_links Anchor links] and +[link syntax.section Section] for more info. + +[h3 Macros] + +[pre''' +[def macro_identifier some text] +'''] + +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: + +[pre''' +[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo +'''] + +Now everywhere the sf_logo is placed, the picture will be inlined. + +[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo + +[blurb __tip__ 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. [^'''__spirit__''']). The reason is to avoid unwanted macro replacement.] + +Links (URLS) and images are good candidates for macros. *1*) 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. *2*) The syntax is not pretty. It's easier to read and +write, e.g. [^'''__spirit__'''] than [^'''[@http://spirit.sourceforge.net Spirit]''']. + +Some more examples: + +[pre''' +[def :-) [$theme/smiley.png]] +[def __spirit__ [@http://spirit.sourceforge.net Spirit]] +'''] + +(See [link syntax.images__terminal_ Images] +and [link syntax.links Links]) + +Invoking these macros: + +[pre''' +Hi __spirit__ :-) +'''] + +will generate this: + +Hi __spirit__ :-) + +[h3 Predefined Macros] + +Quickbook has some predefined macros that you can already use. + +[table Predefined Macros + [[Macro] [Meaning] [Example]] + [['''__DATE__'''] [Today's date] [__DATE__]] + [['''__TIME__'''] [The current time] [__TIME__]] + [['''__FILENAME__'''] [Quickbook source filename] [__FILENAME__]] +] + +[h3 Blurbs] + +[pre''' +[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++. +] +'''] + +will generate this: + +[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++. +] + +[h3 Tables] + +[pre''' +[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]] +] +'''] + +will generate: + +[table A Simple Table + [[Heading 1] [Heading 2] [Heading 3]] + [[R0-C0] [R0-C1] [R0-C2]] + [[R2-C0] [R2-C1] [R2-C2]] + [[R3-C0] [R3-C1] [R3-C2]] +] + +The first row of the table is automatically treated as the table header; that is, +it is wrapped in [^...] 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: + +[pre''' +[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] + ] +] +'''] + +and thus: + +[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] + ] +] + +[h3 Variable Lists] + +[pre''' +[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]] +] +'''] + +will generate: + +[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]] +] + +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". + +[endsect] +[section:ref Quick Reference] + +[table Syntax Compendium + [[To do this...] [Use this...]] + [[comment] [[^'''[/ some comment]''']]] + [[['italics]] [[^'''['italics] or /italics/''']]] + [[[*bold]] [[^'''[*bold] or *bold*''']]] + [[[_underline]] [[^'''[_underline] or _underline_''']]] + [[[^teletype]] [[^'''[^teletype] or =teletype=''']]] + [[source mode] [[^\[c++\]] or [^\[python\]]]] + [[inline code] [[^'''`int main();`''']]] + [[line break] [[^'''[br]''']]] + [[line break] [[^'''\n''']]] + [[anchor] [[^'''[#anchor]''']]] + [[link] [[^'''[@http://www.boost.org Boost]''']]] + [[anchor link] [[^'''[link section.anchor Link text]''']]] + [[refentry link] [[^'''[link xml.refentry Link text]''']]] + [[function link] [[^'''[funcref fully::qualified::function_name Link text]''']]] + [[class link] [[^'''[classref fully::qualified::class_name Link text]''']]] + [[member link] [[^'''[memberref fully::qualified::member_name Link text]''']]] + [[enum link] [[^'''[enumref fully::qualified::enum_name Link text]''']]] + [[escape] [[^\'\'\'escaped text (no processing/formatting)\'\'\']]] + [[single char escape] [[^\\c]]] + [[images] [[^'''[$image.jpg]''']]] + [[begin section] [[^'''[section The Section Title]''']]] + [[end section] [[^'''[endsect]''']]] + [[paragraph] [No markup. Paragraphs start left-flushed and are terminated by two or more newlines.]] + [[ordered list] [[^# one\n# two\n# three\n]]] + [[unordered list] [[^\* one\n\* two\n\* three\n]]] + [[code] [No markup. Preformatted code starts with a space or a tab.]] + [[preformatted] [[^'''[pre preformatted]''']]] + [[block quote] [[^'''[:sometext...]''']]] + [[heading 1] [[^'''[h1 Heading 1]''']]] + [[heading 2] [[^'''[h2 Heading 2]''']]] + [[heading 3] [[^'''[h3 Heading 3]''']]] + [[heading 4] [[^'''[h4 Heading 4]''']]] + [[heading 5] [[^'''[h5 Heading 5]''']]] + [[heading 6] [[^'''[h6 Heading 6]''']]] + [[macro] [[^'''[def macro_identifier some text]''']]] + [[blurb] [[^'''[blurb advertisement or note...]''']]] + [[table] [[^[table Title\n \[\[a\]\[b\]\[c\]\]\n \[\[a\]\[b\]\[c\]\]\n\]]]] + [[variablelist] [[^[variablelist Title\n \[\[a\]\[b\]\]\n \[\[a\]\[b\]\]\n\]]]] +] + +[endsect] +[section:docinfo Library Document Grammar] + +[c++] + + doc_info = + space + >> '[' + >> ( str_p("book") + | "article" + | "library" + | "chapter" + | "part" + ) + >> hard_space + >> ( *(anychar_p - + (ch_p('[') | ']' | eol_p) + ) + ) + >> *( doc_version + | doc_id + | doc_dirname + | doc_copyright + | doc_purpose + | doc_category + | doc_authors + | doc_license + | doc_last_revision + ) + >> ']' >> +eol_p + ; + + doc_version = + space + >> "[version" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + + doc_id = + space + >> "[id" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + + doc_dirname = + space + >> "[dirname" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + + doc_copyright = + space + >> "[copyright" >> hard_space + >> +( repeat_p(4)[digit_p] + >> space + ) + >> space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + + doc_purpose = + space + >> "[purpose" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + + doc_category = + space + >> "[category" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + + doc_author = + space + >> '[' >> space + >> (*(anychar_p - ',')) + >> ',' >> space + >> (*(anychar_p - ']')) + >> ']' + ; + + doc_authors = + space + >> "[authors" >> hard_space + >> doc_author + >> *( ',' + >> doc_author + ) + >> ']' >> +eol_p + ; + + doc_license = + space + >> "[license" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + + doc_last_revision = + space + >> "[last-revision" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + + doc_source_mode = + space + >> "[source-mode" >> hard_space + >> ( + str_p("c++") + | "python" + ) + >> space >> ']' >> +eol_p + ; + + comment = + "[/" >> *(anychar_p - ']') >> ']' + ; + + space = + *(space_p | comment) + ; + + hard_space = + (eps_p - (alnum_p | '_')) >> space // must not be followed by + ; // alpha-numeric or underscore + +[endsect] +[section:quickbook QuickBook Grammar] + + library = + *(space_p | comment) >> blocks >> blank + ; + + blocks = + +( block_markup + | code + | list + | hr + | comment >> *eol + | paragraph + | eol + ) + ; + + space = + *(space_p | comment) + ; + + blank = + *(blank_p | comment) + ; + + eol = blank >> eol_p + ; + + close_bracket = + ']' | + if_p(var(is_not_preformatted)) + [ + eol_p >> eol_p // Make sure that we don't go + ] // past a single block, except + ; // when preformatted. + + hard_space = + (eps_p - (alnum_p | '_')) >> space // must not be followed by + ; // alpha-numeric or underscore + + comment = + "[/" >> *(anychar_p - ']') >> ']' + ; + + hr = + str_p("----") + >> *(anychar_p - eol) + >> +eol + ; + + block_markup = + '[' + >> ( begin_section + | end_section + | headings + | blurb + | blockquote + | preformatted + | def_macro + | table + | variablelist + | xinclude + ) + >> ( (']' >> +eol) + | eps_p + ) + ; + + begin_section = + "section" + >> hard_space + >> (':' >> (*(alnum_p | '_')) + | eps_p + ) + >> (*(anychar_p - + close_bracket)) + ; + + end_section = + str_p("endsect") + ; + + headings = + h1 | h2 | h3 | h4 | h5 | h6 + ; + + h1 = "h1" >> hard_space >> phrase + h2 = "h2" >> hard_space >> phrase + h3 = "h3" >> hard_space >> phrase + h4 = "h4" >> hard_space >> phrase + h5 = "h5" >> hard_space >> phrase + h6 = "h6" >> hard_space >> phrase + + blurb = + "blurb" >> hard_space + >> phrase + ; + + blockquote = + ':' >> blank >> + phrase + ; + + preformatted = + "pre" >> hard_space + >> !eol >> phrase + >> eps_p + ; + + def_macro = + "def" >> hard_space + >> identifier + >> blank >> phrase + ; + + table = + "table" >> hard_space + >> (*(anychar_p - eol)) + >> +eol + >> *table_row + >> eps_p + ; + + table_row = + space + >> ch_p('[') + >> + ( + ( + *table_cell + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + + table_cell = + space + >> ch_p('[') + >> + ( + ( + phrase + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + + variablelist = + "variablelist" >> hard_space + >> (*(anychar_p - eol)) + >> +eol + >> *varlistentry + >> eps_p + ; + + varlistentry = + space + >> ch_p('[') + >> + ( + ( + varlistterm + >> +varlistitem + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + + varlistterm = + space + >> ch_p('[') + >> + ( + ( + phrase + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + + varlistitem = + space + >> ch_p('[') + >> + ( + ( + phrase + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + + xinclude = + "xinclude" + >> hard_space + >> (*(anychar_p - + close_bracket)) + ; + + identifier = + *(anychar_p - (space_p | ']')) + ; + + source_mode = + ( + str_p("c++") + | "python" + ) + ; + + code = + ( + code_line + >> *(*eol >> code_line) + ) + >> +eol + ; + + code_line = + ((ch_p(' ') | '\t')) + >> *(anychar_p - eol) >> eol + ; + + list = + eps_p(ch_p('*') | '#') >> + +( + (*blank_p + >> (ch_p('*') | '#')) + >> *blank_p + >> list_item + ) + ; + + list_item = + *( common + | (anychar_p - + ( eol_p >> *blank_p >> eps_p(ch_p('*') | '#') + | (eol >> eol) + ) + ) + ) + >> +eol + ; + + common = + self.actions.macro + | phrase_markup + | inline_code + | simple_format + | escape + | comment + ; + + inline_code = + '`' >> + ( + *(anychar_p - + ( '`' + | (eol >> eol) // Make sure that we don't go + ) // past a single block + ) >> eps_p('`') + ) + >> '`' + ; + + simple_format = + simple_bold + | simple_italic + | simple_underline + | simple_teletype + ; + + simple_bold = + '*' >> + ( + ( graph_p >> // graph_p must follow '*' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '*') // past a single line + ) + ) >> graph_p // graph_p must precede '*' + >> eps_p('*' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '*' + | ( + graph_p // A single char. e.g. *c* + >> eps_p('*' + >> (space_p | punct_p)) + ) + ) + >> '*' + ; + + simple_italic = + '/' >> + ( + ( graph_p >> // graph_p must follow '/' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '/') // past a single line + ) + ) >> graph_p // graph_p must precede '/' + >> eps_p('/' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '/' + | ( + graph_p // A single char. e.g. /c/ + >> eps_p('/' + >> (space_p | punct_p)) + ) + ) + >> '/' + ; + + simple_underline = + '_' >> + ( + ( graph_p >> // graph_p must follow '_' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '_') // past a single line + ) + ) >> graph_p // graph_p must precede '_' + >> eps_p('_' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '_' + | ( + graph_p // A single char. e.g. _c_ + >> eps_p('_' + >> (space_p | punct_p)) + ) + ) + >> '_' + ; + + simple_teletype = + '=' >> + ( + ( graph_p >> // graph_p must follow '=' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '=') // past a single line + ) + ) >> graph_p // graph_p must precede '=' + >> eps_p('=' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '=' + | ( + graph_p // A single char. e.g. =c= + >> eps_p('=' + >> (space_p | punct_p)) + ) + ) + >> '=' + ; + + paragraph = + *( common + | (anychar_p - // Make sure we don't go past + (eol >> eol) // a single block. + ) + ) + >> +eol + ; + + phrase = + *( common + | comment + | (anychar_p - + close_bracket) + ) + ; + + phrase_markup = + '[' + >> ( image + | url + | link + | anchor + | source_mode + | funcref + | classref + | memberref + | enumref + | bold + | italic + | underline + | teletype + | str_p("br") + ) + >> ']' + ; + + escape = + str_p("\\n") + | '\\' >> punct_p + | ( + "'''" >> !eol + >> *(anychar_p - "'''") + >> "'''" + ) + ; + + image = + '$' >> blank + >> (*(anychar_p - + close_bracket)) + ; + + url = + '@' + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + + link = + "link" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + + anchor = + '#' + >> blank + >> ( *(anychar_p - + close_bracket) + ) + ; + + funcref = + "funcref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + + classref = + "classref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + + memberref = + "memberref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + + enumref = + "enumref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + + bold = + ch_p('*') + >> blank >> phrase + ; + + italic = + ch_p('\'') + >> blank >> phrase + ; + + underline = + ch_p('_') + >> blank >> phrase + ; + + teletype = + ch_p('^') + >> blank >> phrase + ; + +[endsect] +[section:highlight C++ Syntax Highlighting Grammar] + + program + = + *( macro + | preprocessor + | comment + | keyword + | identifier + | special + | string_ + | char_ + | number + | space_p + | anychar_p + ) + ; + + macro + = *space_p >> self.macro + ; + + preprocessor + = *space_p >> '#' >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + + comment + = +(*space_p >> (comment_p("//") | comment_p("/*", "*/"))) + ; + + keyword + = *space_p >> keyword_ >> (eps_p - (alnum_p | '_')) + ; // make sure we recognize whole words only + + keyword_ + = "and_eq", "and", "asm", "auto", "bitand", "bitor", + "bool", "break", "case", "catch", "char", "class", + "compl", "const_cast", "const", "continue", "default", + "delete", "do", "double", "dynamic_cast", "else", + "enum", "explicit", "export", "extern", "false", + "float", "for", "friend", "goto", "if", "inline", + "int", "long", "mutable", "namespace", "new", "not_eq", + "not", "operator", "or_eq", "or", "private", + "protected", "public", "register", "reinterpret_cast", + "return", "short", "signed", "sizeof", "static", + "static_cast", "struct", "switch", "template", "this", + "throw", "true", "try", "typedef", "typeid", + "typename", "union", "unsigned", "using", "virtual", + "void", "volatile", "wchar_t", "while", "xor_eq", "xor" + ; + + special + = *space_p >> +chset_p("~!%^&*()+={[}]:;,<.>?/|\\-") + ; + + string_ + = *space_p >> !as_lower_d['l'] >> confix_p('"', *c_escape_ch_p, '"') + ; + + char_ + = *space_p >> !as_lower_d['l'] >> confix_p('\'', *c_escape_ch_p, '\'') + ; + + number + = *space_p >> + ( as_lower_d["0x"] >> hex_p + | '0' >> oct_p + | real_p + ) + >> *as_lower_d[chset_p("ldfu")] + ; + + identifier + = *space_p >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + +[endsect] +[section:pyhighlight Python Syntax Highlighting Grammar] + +[c++] + + program + = + *( comment + | keyword + | identifier + | special + | string_ + | number + | space_p + | anychar_p + ) + ; + + comment + = +(*space_p >> comment_p("#")) + ; + + keyword + = *space_p >> keyword_ >> (eps_p - (alnum_p | '_')) + ; // make sure we recognize whole words only + + keyword_ + = + "and", "del", "for", "is", "raise", + "assert", "elif", "from", "lambda", "return", + "break", "else", "global", "not", "try", + "class", "except", "if", "or", "while", + "continue", "exec", "import", "pass", "yield", + "def", "finally", "in", "print", + + // Technically "as" and "None" are not yet keywords (at Python + // 2.4). They are destined to become keywords, and we treat them + // as such for syntax highlighting purposes. + + "as", "None" + ; + + special + = *space_p >> +chset_p("~!%^&*()+={[}]:;,<.>/|\\-") + ; + + string_prefix + = as_lower_d[str_p("u") >> ! str_p("r")] + ; + + string_ + = *space_p >> ! string_prefix >> (long_string | short_string) + ; + + short_string + = confix_p('"', * c_escape_ch_p, '"') | + confix_p("'", * c_escape_ch_p, "'") + ; + + long_string + = confix_p("'''", * lex_escape_ch_p, "'''") | + confix_p("\"\"\"", * lex_escape_ch_p, "\"\"\"") + ; + + number + = *space_p >> + ( + as_lower_d["0x"] >> hex_p + | '0' >> oct_p + | real_p + ) + >> *as_lower_d[chset_p("lj")] + ; + + identifier + = *space_p >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + +[endsect] \ No newline at end of file diff --git a/doc/quickbook.xml b/doc/quickbook.xml new file mode 100755 index 000000000..cf08d92bb --- /dev/null +++ b/doc/quickbook.xml @@ -0,0 +1,1632 @@ + + + + + + Joel + de Guzman + + + Eric + Niebler + + + + 2002 + 2004 + 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 + + + + + + quickbook 1.0 + + + +
+ Introduction +
"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 + +
+
+ Syntax Summary + +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. + +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. +Comments +Can be placed anywhere. +[/ comment (no output generated) ] +Phrase Level ElementsFont Styles['italic], [*bold], [_underline], [^teletype] + +will generate: + +italic, bold, underline, teletype + +Like all non-terminal phrase level elements, this can of course be nested: +[*['bold-italic]] + +will generate: + +bold-italic +Simple formatting +Simple markup for formatting text, common in many applications, is now supported: +/italic/, *bold*, _underline_, =teletype= + +will generate: + +italic, bold, underline, teletype + +Unlike QuickBook's standard formatting scheme, the rules for simpler alternatives +are much stricter. + + +Simple markups cannot nest. You can combine a simple markup with a nestable markup. + +A non-space character must follow the leading markup + +A non-space character must precede the trailing markup + +A space or a punctuation must follow the trailing markup + +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 '*'. + +A line starting with the star will be interpreted as an unordered list. + See Unordered lists. + + +More Formatting Samples + +MarkupResult + + +*Bold*Bold +*Is bold*Is bold +* Not bold* *Not bold * * Not bold ** Not bold* *Not bold * * Not bold * +This*Isn't*Bold (no bold)This*Isn't*Bold (no bold) +(*Bold Inside*) (parenthesis not bold)(Bold Inside) (parenthesis not bold) +*(Bold Outside)* (parenthesis bold)(Bold Outside) (parenthesis bold) +3*4*5 = 60 (no bold)3*4*5 = 60 (no bold) +3 * 4 * 5 = 60 (no bold)3 * 4 * 5 = 60 (no bold) +3 *4* 5 = 60 (4 is bold)3 4 5 = 60 (4 is bold) +*This is bold* this is not *but this is*This is bold this is not but this is +*This is bold*.This is bold. +*B*. (bold B)B. (bold B) +['*Bold-Italic*]Bold-Italic + + + + + + + + + + Thanks to David Barrett, author of +Qwiki, for sharing these samples +and teaching me these obscure formatting rules. I wasn't sure at all if Spirit, +being more or less a formal EBNF parser, can handle the context sensitivity and ambiguity. + + + + +Inline code +Inlining code in paragraphs is quite common when writing C++ documentation. We +provide a very simple markup for this. For example, this: +This text has inlined code `int main() { return 0; }` in it. + +will generate: + +This text has inlined code int main() { return 0; } in it. The code will be +syntax highlighted. + + + + + + + +Note that we simply enclose the code with the tick: "`", not the +single quote: "'". Note too that `some code` is prefered over +[^some code]. + + + + + +Source Mode +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 Document Info section. + +To change the source mode, use the [source-mode] markup, where +source-mode is one of the supported modes. For example, this: +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`. + +will generate: + +Python's import is rather like C++'s #include. A +C++ comment // looks like this whereas a Python comment +#looks like this. + +Supported Source Modes + +ModeSource Mode Markup + + +C++[c++] +Python[python] + + + + + + + + + + The source mode strings are lowercase. + + + + +line-break[br] + + + + + + + Note that \n is now preferred over [br]. + + + + +Anchors[#named_anchor] + +A named anchor is a hook that can be referenced by a link elsewhere in the +document. You can then reference an anchor with [link named_anchor Some link text]. +More on anchors here, here and +here. +Links[@http://www.boost.org this is [*boost's] website....] + +will generate: + +this is boost's website.... + +URL links where the link text is the link itself is common. Example: +see http://spirit.sourceforge.net/ + +so, when the text is absent in a link markup, the URL is assumed. Example: +see [@http://spirit.sourceforge.net/] + +will generate: + +see http://spirit.sourceforge.net/ +Anchor links +You can link within a document using: +[link section_id.normalized_header_text The link text] + +See sections Section and Headings +for more info. +refentry links +In addition, you can link internally to an XML refentry like: +[link xml.refentry The link text] + +This gets converted into <link linkend="xml.refentry">The link text</link>. + +Like URLs, the link text is optional. If this is not present, the link text will +automatically be the refentry. Example: +[link xml.refentry] + +This gets converted into <link linkend="xml.refentry">xml.refentry</link>. +function, class or member links +If you want to link to a function, class, member or enum in the reference section, you +can use: +[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] + +Again, the link text is optional. If this is not present, the link text will +automatically be the function, class, member or enum. Example: +[classref boost::bar::baz] + +would have "boost::bar::baz" as the link text. +Escape +The escape mark-up is used when we don't want to do any processing. +''' +escape (no processing/formatting) +''' + +Escaping allows us to pass XML markup to BoostBook or DocBook. For example: +''' +<emphasis role="bold">This is direct XML markup</emphasis> +''' + +This is direct XML markup + + + + + + + + Be careful when using the escape. The text must conform to +BoostBook/DocBook syntax. + + + + +Single char escape +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 [ and ]. +For example, how do you escape the triple quote? Simple: \'\'\' + +\n has a special meaning. It is used to generate line breaks. Note that \n +is now preferred over [br]. +Images (terminal)[$image.jpg] +Block Level ElementsDocument +Every document must begin with a Document Info section, which should look +like this: +[document-type The Document Title + [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] + [last-revision $Date$] + [source-mode source-type] +] + +Where document-type is one of: + + +book + +library + +part + +article + +chapter + + +and version, id, dirname, copyright, purpose, category, authors, +license, last-revision and source-mode are optional information. + +Here source-type is a lowercase string setting the initial +source mode. If the source-mode field is omitted, a +default value of c++ will be used. +Section +Starting a new section is accomplished with: +[section:id The Section Title] + +where id 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 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". + +End a section with: +[endsect] + +Sections can nest, and that results in a hierarchy in the table of contents. +xinclude +You can include another XML file with: +[xinclude file.xml] + +This is useful when file.xml has been generated by Doxygen and contains your +reference section. +Paragraphs +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. +Ordered lists# One +# Two +# Three + +will generate: + + +One + +Two + +Three + + +List hierarchies are supported. Example: +# One +# Two +# Three + # Three.a + # Three.b + # Three.c +# Four + # Four.a + # Four.a.i + # Four.a.ii + # Four.b + +will generate: + + +One + +Two + +Three + +Three.a + +Three.b + +Three.c + + + +Fourth + +Four.a + +Four.a.i + +Four.a.ii + + + +Four.b + + + + +Long lines will be wrapped appropriately. Example: +# 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. + + +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. + +Unordered lists* First +* Second +* Third + +will generate: + + +First + +Second + +Third + + +Mixed lists (ordered and unordered) are supported. Example: +# One +# Two +# Three + * Three.a + * Three.b + * Three.c + +will generate: + + +One + +Two + +Three + +Three.a + +Three.b + +Three.c + + + +Code +Preformatted code starts with a space or a tab. The code will be +syntax highlighted according to the current source mode: + + + + +#include <iostream> + +int main() +{ + // Sample code + std::cout << "Hello, World\n"; + return 0; +} + + + + + + +import cgi + +def cookForHtml(text): + '''"Cooks" the input text for HTML.''' + + return cgi.escape(text) + + +Macros that are already defined are expanded in source code. Example: +[def __syntax_highlight__ [@highlight.html syntax_highlight]] +[def __quickbook__ [@../index.html quickbook]] + + using __quickbook__::__syntax_highlight__; + +Generates: + + +using __quickbook__::__syntax_highlight__; + +Preformatted +Sometimes, you don't want some preformatted text to be parsed as C++. In such +cases, use the [pre ... ] markup block. +[pre + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + + Some *preformatted* text Some *preformatted* text + +] + +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: +Some preformatted text Some preformatted text + + Some preformatted text Some preformatted text + + Some preformatted text Some preformatted text + + +Notice that unlike Code, phrase markup such as font style is still permitted +inside pre blocks. +Blockquote[:sometext...] +
Indents the paragraph. This applies to one paragraph only.
Headings[h1 Heading 1] +[h2 Heading 2] +[h3 Heading 3] +[h4 Heading 4] +[h5 Heading 5] +[h6 Heading 6] +Heading 1Heading 2Heading 3Heading 4Heading 5Heading 6 +Headings 1-3 [h1 h2 and h3] will automatically have anchors with normalized +names with name="section_id.normalized_header_text" (i.e. 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. For example: Heading +1 in section Section 2 will be normalized to section_2.heading_1). You can use: +[link section_id.normalized_header_text The link text] + +to link to them. See Anchor links and +Section for more info. +Macros[def macro_identifier some text] + +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: +[def sf_logo [$http://sourceforge.net/sflogo.php?group_id=28447&type=1]] +sf_logo + +Now everywhere the sf_logo is placed, the picture will be inlined. + + + + + + + + + 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. __spirit__). The reason is to avoid unwanted macro replacement. + + + + + +Links (URLS) and images are good candidates for macros. 1) 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. 2) The syntax is not pretty. It's easier to read and +write, e.g. __spirit__ than [@http://spirit.sourceforge.net Spirit]. + +Some more examples: +[def :-) [$theme/smiley.png]] +[def __spirit__ [@http://spirit.sourceforge.net Spirit]] + +(See Images +and Links) + +Invoking these macros: +Hi __spirit__ :-) + +will generate this: + +Hi Spirit +Predefined Macros +Quickbook has some predefined macros that you can already use. + +Predefined Macros + +MacroMeaningExample + + +__DATE__Today's date2005-Jan-26 +__TIME__The current time10:59:00 AM +__FILENAME__Quickbook source filenamequickbook.qbk + + + +Blurbs[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++. +] + +will generate this: + + + + + + + An eye catching advertisement or note... + + + 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++. + + + + + +Tables[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]] +] + +will generate: + +A Simple Table + +Heading 1Heading 2Heading 3 + + +R0-C0R0-C1R0-C2 +R2-C0R2-C1R2-C2 +R3-C0R3-C1R3-C2 + + + + +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 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] + ] +] + +and thus: + +Table with fat cells + +Heading 1Heading 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 cellRow 1, Col 1: a small cell + + + +Variable Lists[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]] +] + +will generate: + +A Variable List +term 1The definition of term 1 +term 2The definition of term 2 +term 3The definition of term 3 + + +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". +
+
+ Quick Reference + +Syntax Compendium + +To do this...Use this... + + +comment[/ some comment] +italics['italics] or /italics/ +bold[*bold] or *bold* +underline[_underline] or _underline_ +teletype[^teletype] or =teletype= +source mode[c++] or [python] +inline code`int main();` +line break[br] +line break\n +anchor[#anchor] +link[@http://www.boost.org Boost] +anchor link[link section.anchor Link text] +refentry link[link xml.refentry Link text] +function link[funcref fully::qualified::function_name Link text] +class link[classref fully::qualified::class_name Link text] +member link[memberref fully::qualified::member_name Link text] +enum link[enumref fully::qualified::enum_name Link text] +escape'''escaped text (no processing/formatting)''' +single char escape\c +images[$image.jpg] +begin section[section The Section Title] +end section[endsect] +paragraphNo markup. Paragraphs start left-flushed and are terminated by two or more newlines. +ordered list# one +# two +# three + +unordered list* one +* two +* three + +codeNo markup. Preformatted code starts with a space or a tab. +preformatted[pre preformatted] +block quote[:sometext...] +heading 1[h1 Heading 1] +heading 2[h2 Heading 2] +heading 3[h3 Heading 3] +heading 4[h4 Heading 4] +heading 5[h5 Heading 5] +heading 6[h6 Heading 6] +macro[def macro_identifier some text] +blurb[blurb advertisement or note...] +table[table Title + [[a][b][c]] + [[a][b][c]] +] +variablelist[variablelist Title + [[a][b]] + [[a][b]] +] + + + +
+
+ Library Document Grammar + + + + +doc_info = + space + >> '[' + >> ( str_p("book") + | "article" + | "library" + | "chapter" + | "part" + ) + >> hard_space + >> ( *(anychar_p - + (ch_p('[') | ']' | eol_p) + ) + ) + >> *( doc_version + | doc_id + | doc_dirname + | doc_copyright + | doc_purpose + | doc_category + | doc_authors + | doc_license + | doc_last_revision + ) + >> ']' >> +eol_p + ; + +doc_version = + space + >> "[version" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + +doc_id = + space + >> "[id" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + +doc_dirname = + space + >> "[dirname" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + +doc_copyright = + space + >> "[copyright" >> hard_space + >> +( repeat_p(4)[digit_p] + >> space + ) + >> space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + +doc_purpose = + space + >> "[purpose" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + +doc_category = + space + >> "[category" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + +doc_author = + space + >> '[' >> space + >> (*(anychar_p - ',')) + >> ',' >> space + >> (*(anychar_p - ']')) + >> ']' + ; + +doc_authors = + space + >> "[authors" >> hard_space + >> doc_author + >> *( ',' + >> doc_author + ) + >> ']' >> +eol_p + ; + +doc_license = + space + >> "[license" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + +doc_last_revision = + space + >> "[last-revision" >> hard_space + >> (*(anychar_p - ']')) + >> ']' >> +eol_p + ; + +doc_source_mode = + space + >> "[source-mode" >> hard_space + >> ( + str_p("c++") + | "python" + ) + >> space >> ']' >> +eol_p + ; + +comment = + "[/" >> *(anychar_p - ']') >> ']' + ; + +space = + *(space_p | comment) + ; + +hard_space = + (eps_p - (alnum_p | '_')) >> space // must not be followed by + ; // alpha-numeric or underscore + + +
+
+ QuickBook Grammar + + +library = + *(space_p | comment) >> blocks >> blank + ; + +blocks = + +( block_markup + | code + | list + | hr + | comment >> *eol + | paragraph + | eol + ) + ; + +space = + *(space_p | comment) + ; + +blank = + *(blank_p | comment) + ; + +eol = blank >> eol_p + ; + +close_bracket = + ']' | + if_p(var(is_not_preformatted)) + [ + eol_p >> eol_p // Make sure that we don't go + ] // past a single block, except + ; // when preformatted. + +hard_space = + (eps_p - (alnum_p | '_')) >> space // must not be followed by + ; // alpha-numeric or underscore + +comment = + "[/" >> *(anychar_p - ']') >> ']' + ; + +hr = + str_p("----") + >> *(anychar_p - eol) + >> +eol + ; + +block_markup = + '[' + >> ( begin_section + | end_section + | headings + | blurb + | blockquote + | preformatted + | def_macro + | table + | variablelist + | xinclude + ) + >> ( (']' >> +eol) + | eps_p + ) + ; + +begin_section = + "section" + >> hard_space + >> (':' >> (*(alnum_p | '_')) + | eps_p + ) + >> (*(anychar_p - + close_bracket)) + ; + +end_section = + str_p("endsect") + ; + +headings = + h1 | h2 | h3 | h4 | h5 | h6 + ; + +h1 = "h1" >> hard_space >> phrase +h2 = "h2" >> hard_space >> phrase +h3 = "h3" >> hard_space >> phrase +h4 = "h4" >> hard_space >> phrase +h5 = "h5" >> hard_space >> phrase +h6 = "h6" >> hard_space >> phrase + +blurb = + "blurb" >> hard_space + >> phrase + ; + +blockquote = + ':' >> blank >> + phrase + ; + +preformatted = + "pre" >> hard_space + >> !eol >> phrase + >> eps_p + ; + +def_macro = + "def" >> hard_space + >> identifier + >> blank >> phrase + ; + +table = + "table" >> hard_space + >> (*(anychar_p - eol)) + >> +eol + >> *table_row + >> eps_p + ; + +table_row = + space + >> ch_p('[') + >> + ( + ( + *table_cell + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + +table_cell = + space + >> ch_p('[') + >> + ( + ( + phrase + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + +variablelist = + "variablelist" >> hard_space + >> (*(anychar_p - eol)) + >> +eol + >> *varlistentry + >> eps_p + ; + +varlistentry = + space + >> ch_p('[') + >> + ( + ( + varlistterm + >> +varlistitem + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + +varlistterm = + space + >> ch_p('[') + >> + ( + ( + phrase + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + +varlistitem = + space + >> ch_p('[') + >> + ( + ( + phrase + >> ch_p(']') + >> space + ) + | eps_p + ) + ; + +xinclude = + "xinclude" + >> hard_space + >> (*(anychar_p - + close_bracket)) + ; + +identifier = + *(anychar_p - (space_p | ']')) + ; + +source_mode = + ( + str_p("c++") + | "python" + ) + ; + +code = + ( + code_line + >> *(*eol >> code_line) + ) + >> +eol + ; + +code_line = + ((ch_p(' ') | '\t')) + >> *(anychar_p - eol) >> eol + ; + +list = + eps_p(ch_p('*') | '#') >> + +( + (*blank_p + >> (ch_p('*') | '#')) + >> *blank_p + >> list_item + ) + ; + +list_item = + *( common + | (anychar_p - + ( eol_p >> *blank_p >> eps_p(ch_p('*') | '#') + | (eol >> eol) + ) + ) + ) + >> +eol + ; + +common = + self.actions.macro + | phrase_markup + | inline_code + | simple_format + | escape + | comment + ; + +inline_code = + '`' >> + ( + *(anychar_p - + ( '`' + | (eol >> eol) // Make sure that we don't go + ) // past a single block + ) >> eps_p('`') + ) + >> '`' + ; + +simple_format = + simple_bold + | simple_italic + | simple_underline + | simple_teletype + ; + +simple_bold = + '*' >> + ( + ( graph_p >> // graph_p must follow '*' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '*') // past a single line + ) + ) >> graph_p // graph_p must precede '*' + >> eps_p('*' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '*' + | ( + graph_p // A single char. e.g. *c* + >> eps_p('*' + >> (space_p | punct_p)) + ) + ) + >> '*' + ; + +simple_italic = + '/' >> + ( + ( graph_p >> // graph_p must follow '/' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '/') // past a single line + ) + ) >> graph_p // graph_p must precede '/' + >> eps_p('/' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '/' + | ( + graph_p // A single char. e.g. /c/ + >> eps_p('/' + >> (space_p | punct_p)) + ) + ) + >> '/' + ; + +simple_underline = + '_' >> + ( + ( graph_p >> // graph_p must follow '_' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '_') // past a single line + ) + ) >> graph_p // graph_p must precede '_' + >> eps_p('_' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '_' + | ( + graph_p // A single char. e.g. _c_ + >> eps_p('_' + >> (space_p | punct_p)) + ) + ) + >> '_' + ; + +simple_teletype = + '=' >> + ( + ( graph_p >> // graph_p must follow '=' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '=') // past a single line + ) + ) >> graph_p // graph_p must precede '=' + >> eps_p('=' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '=' + | ( + graph_p // A single char. e.g. =c= + >> eps_p('=' + >> (space_p | punct_p)) + ) + ) + >> '=' + ; + +paragraph = + *( common + | (anychar_p - // Make sure we don't go past + (eol >> eol) // a single block. + ) + ) + >> +eol + ; + +phrase = + *( common + | comment + | (anychar_p - + close_bracket) + ) + ; + +phrase_markup = + '[' + >> ( image + | url + | link + | anchor + | source_mode + | funcref + | classref + | memberref + | enumref + | bold + | italic + | underline + | teletype + | str_p("br") + ) + >> ']' + ; + +escape = + str_p("\\n") + | '\\' >> punct_p + | ( + "'''" >> !eol + >> *(anychar_p - "'''") + >> "'''" + ) + ; + +image = + '$' >> blank + >> (*(anychar_p - + close_bracket)) + ; + +url = + '@' + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + +link = + "link" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + +anchor = + '#' + >> blank + >> ( *(anychar_p - + close_bracket) + ) + ; + +funcref = + "funcref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + +classref = + "classref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + +memberref = + "memberref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + +enumref = + "enumref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) + >> ( eps_p(']') + | (hard_space >> phrase) + ) + ; + +bold = + ch_p('*') + >> blank >> phrase + ; + +italic = + ch_p('\'') + >> blank >> phrase + ; + +underline = + ch_p('_') + >> blank >> phrase + ; + +teletype = + ch_p('^') + >> blank >> phrase + ; + + +
+
+ C++ Syntax Highlighting Grammar + + +program + = + *( macro + | preprocessor + | comment + | keyword + | identifier + | special + | string_ + | char_ + | number + | space_p + | anychar_p + ) + ; + +macro + = *space_p >> self.macro + ; + +preprocessor + = *space_p >> '#' >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + +comment + = +(*space_p >> (comment_p("//") | comment_p("/*", "*/"))) + ; + +keyword + = *space_p >> keyword_ >> (eps_p - (alnum_p | '_')) + ; // make sure we recognize whole words only + +keyword_ + = "and_eq", "and", "asm", "auto", "bitand", "bitor", + "bool", "break", "case", "catch", "char", "class", + "compl", "const_cast", "const", "continue", "default", + "delete", "do", "double", "dynamic_cast", "else", + "enum", "explicit", "export", "extern", "false", + "float", "for", "friend", "goto", "if", "inline", + "int", "long", "mutable", "namespace", "new", "not_eq", + "not", "operator", "or_eq", "or", "private", + "protected", "public", "register", "reinterpret_cast", + "return", "short", "signed", "sizeof", "static", + "static_cast", "struct", "switch", "template", "this", + "throw", "true", "try", "typedef", "typeid", + "typename", "union", "unsigned", "using", "virtual", + "void", "volatile", "wchar_t", "while", "xor_eq", "xor" + ; + +special + = *space_p >> +chset_p("~!%^&*()+={[}]:;,<.>?/|\\-") + ; + +string_ + = *space_p >> !as_lower_d['l'] >> confix_p('"', *c_escape_ch_p, '"') + ; + +char_ + = *space_p >> !as_lower_d['l'] >> confix_p('\'', *c_escape_ch_p, '\'') + ; + +number + = *space_p >> + ( as_lower_d["0x"] >> hex_p + | '0' >> oct_p + | real_p + ) + >> *as_lower_d[chset_p("ldfu")] + ; + +identifier + = *space_p >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + + +
+
+ Python Syntax Highlighting Grammar + + + + +program + = + *( comment + | keyword + | identifier + | special + | string_ + | number + | space_p + | anychar_p + ) + ; + +comment + = +(*space_p >> comment_p("#")) + ; + +keyword + = *space_p >> keyword_ >> (eps_p - (alnum_p | '_')) + ; // make sure we recognize whole words only + +keyword_ + = + "and", "del", "for", "is", "raise", + "assert", "elif", "from", "lambda", "return", + "break", "else", "global", "not", "try", + "class", "except", "if", "or", "while", + "continue", "exec", "import", "pass", "yield", + "def", "finally", "in", "print", + + // Technically "as" and "None" are not yet keywords (at Python + // 2.4). They are destined to become keywords, and we treat them + // as such for syntax highlighting purposes. + + "as", "None" + ; + +special + = *space_p >> +chset_p("~!%^&*()+={[}]:;,<.>/|\\-") + ; + +string_prefix + = as_lower_d[str_p("u") >> ! str_p("r")] + ; + +string_ + = *space_p >> ! string_prefix >> (long_string | short_string) + ; + +short_string + = confix_p('"', * c_escape_ch_p, '"') | + confix_p("'", * c_escape_ch_p, "'") + ; + +long_string + = confix_p("'''", * lex_escape_ch_p, "'''") | + confix_p("\"\"\"", * lex_escape_ch_p, "\"\"\"") + ; + +number + = *space_p >> + ( + as_lower_d["0x"] >> hex_p + | '0' >> oct_p + | real_p + ) + >> *as_lower_d[chset_p("lj")] + ; + +identifier + = *space_p >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + + +
+ + diff --git a/doc_info.hpp b/doc_info.hpp new file mode 100755 index 000000000..3c2a56261 --- /dev/null +++ b/doc_info.hpp @@ -0,0 +1,178 @@ +/*============================================================================= + Copyright (c) 2002 2004 Joel de Guzman + Copyright (c) 2004 Eric Niebler + 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) +=============================================================================*/ +#if !defined(BOOST_SPIRIT_QUICKBOOK_DOC_INFO_HPP) +#define BOOST_SPIRIT_QUICKBOOK_DOC_INFO_HPP + +#include +#include +#include + +namespace quickbook +{ + using namespace boost::spirit; + + template + struct doc_info_grammar + : public grammar > + { + doc_info_grammar(Actions& actions) + : actions(actions) {} + + template + struct definition + { + definition(doc_info_grammar const& self) + { + doc_info = + space + >> '[' + >> ( str_p("book") + | "article" + | "library" + | "chapter" + | "part" + ) [assign_a(self.actions.doc_type)] + >> hard_space + >> ( *(anychar_p - + (ch_p('[') | ']' | eol_p) + ) + ) [assign_a(self.actions.doc_title)] + >> *( doc_version + | doc_id + | doc_dirname + | doc_copyright + | doc_purpose + | doc_category + | doc_authors + | doc_license + | doc_last_revision + | doc_source_mode + ) + >> ']' >> +eol_p + ; + + doc_version = + space + >> "[version" >> hard_space + >> (*(anychar_p - ']')) [assign_a(self.actions.doc_version)] + >> ']' >> +eol_p + ; + + doc_id = + space + >> "[id" >> hard_space + >> (*(anychar_p - ']')) [assign_a(self.actions.doc_id)] + >> ']' >> +eol_p + ; + + doc_dirname = + space + >> "[dirname" >> hard_space + >> (*(anychar_p - ']')) [assign_a(self.actions.doc_dirname)] + >> ']' >> +eol_p + ; + + doc_copyright = + space + >> "[copyright" >> hard_space + >> +( repeat_p(4)[digit_p] [push_back_a(self.actions.doc_copyright_years)] + >> space + ) + >> space + >> (*(anychar_p - ']')) [assign_a(self.actions.doc_copyright_holder)] + >> ']' >> +eol_p + ; + + doc_purpose = + space + >> "[purpose" >> hard_space + >> (*(anychar_p - ']')) [assign_a(self.actions.doc_purpose)] + >> ']' >> +eol_p + ; + + doc_category = + space + >> "[category" >> hard_space + >> (*(anychar_p - ']')) [assign_a(self.actions.doc_category)] + >> ']' >> +eol_p + ; + + doc_author = + space + >> '[' >> space + >> (*(anychar_p - ',')) [assign_a(name.second)] // surname + >> ',' >> space + >> (*(anychar_p - ']')) [assign_a(name.first)] // firstname + >> ']' + ; + + doc_authors = + space + >> "[authors" >> hard_space + >> doc_author [push_back_a(self.actions.doc_authors, name)] + >> *( ',' + >> doc_author [push_back_a(self.actions.doc_authors, name)] + ) + >> ']' >> +eol_p + ; + + doc_license = + space + >> "[license" >> hard_space + >> (*(anychar_p - ']')) [assign_a(self.actions.doc_license)] + >> ']' >> +eol_p + ; + + doc_last_revision = + space + >> "[last-revision" >> hard_space + >> (*(anychar_p - ']')) [assign_a(self.actions.doc_last_revision)] + >> ']' >> +eol_p + ; + + doc_source_mode = + space + >> "[source-mode" >> hard_space + >> ( + str_p("c++") + | "python" + ) [assign_a(self.actions.source_mode)] + >> space >> ']' >> +eol_p + ; + + comment = + "[/" >> *(anychar_p - ']') >> ']' + ; + + space = + *(space_p | comment) + ; + + hard_space = + (eps_p - (alnum_p | '_')) >> space // must not be followed by + ; // alpha-numeric or underscore + } + + std::pair name; + rule doc_info, doc_title, doc_version, doc_id, doc_dirname, + doc_copyright, doc_purpose,doc_category, doc_authors, + doc_author, comment, space, hard_space, doc_license, + doc_last_revision, doc_source_mode; + + rule const& + start() const { return doc_info; } + }; + + Actions& actions; + }; +} + +#endif // BOOST_SPIRIT_QUICKBOOK_DOC_INFO_HPP + diff --git a/index.html b/index.html new file mode 100755 index 000000000..b6ce29ba0 --- /dev/null +++ b/index.html @@ -0,0 +1,10 @@ + + + + + + + Automatic redirection failed, click this + link + + diff --git a/quickbook.hpp b/quickbook.hpp new file mode 100755 index 000000000..88b45fe21 --- /dev/null +++ b/quickbook.hpp @@ -0,0 +1,563 @@ +/*============================================================================= + Copyright (c) 2002 2004 Joel de Guzman + Copyright (c) 2004 Eric Niebler + 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) +=============================================================================*/ +#if !defined(BOOST_SPIRIT_QUICKBOOK_HPP) +#define BOOST_SPIRIT_QUICKBOOK_HPP + +#include "detail/utils.hpp" +#include +#include +#include +#include +#include + +namespace quickbook +{ + using namespace boost::spirit; + + template + struct quickbook_grammar + : public grammar > + { + quickbook_grammar(Actions& actions_) + : actions(actions_) {} + + template + struct definition + { + definition(quickbook_grammar const& self) + : is_not_preformatted(true) + { + using detail::var; + + library = + *(space_p | comment) >> blocks >> blank + ; + + blocks = + +( block_markup + | code + | list [self.actions.list] + | hr [self.actions.hr] + | comment >> *eol + | paragraph [self.actions.paragraph] + | eol + ) + ; + + space = + *(space_p | comment) + ; + + blank = + *(blank_p | comment) + ; + + eol = blank >> eol_p + ; + + close_bracket = + ']' | + if_p(var(is_not_preformatted)) + [ + eol_p >> eol_p // Make sure that we don't go + ] // past a single block, except + ; // when preformatted. + + hard_space = + (eps_p - (alnum_p | '_')) >> space // must not be followed by + ; // alpha-numeric or underscore + + comment = + "[/" >> *(anychar_p - ']') >> ']' + ; + + hr = + str_p("----") + >> *(anychar_p - eol) + >> +eol + ; + + block_markup = + '[' + >> ( begin_section + | end_section + | headings + | blurb + | blockquote + | preformatted + | def_macro + | table + | variablelist + | xinclude + ) + >> ( (']' >> +eol) + | eps_p [self.actions.error] + ) + ; + + begin_section = + "section" + >> hard_space + >> (':' >> (*(alnum_p | '_')) [assign_a(self.actions.section_id)] + | eps_p [assign_a(self.actions.section_id)] + ) + >> (*(anychar_p - + close_bracket)) [self.actions.begin_section] + ; + + end_section = + str_p("endsect") [self.actions.end_section] + ; + + headings = + h1 | h2 | h3 | h4 | h5 | h6 + ; + + h1 = "h1" >> hard_space >> phrase [self.actions.h1]; + h2 = "h2" >> hard_space >> phrase [self.actions.h2]; + h3 = "h3" >> hard_space >> phrase [self.actions.h3]; + h4 = "h4" >> hard_space >> phrase [self.actions.h4]; + h5 = "h5" >> hard_space >> phrase [self.actions.h5]; + h6 = "h6" >> hard_space >> phrase [self.actions.h6]; + + blurb = + "blurb" >> hard_space + >> phrase [self.actions.blurb] + ; + + blockquote = + ':' >> blank >> + phrase [self.actions.blockquote] + ; + + preformatted = + "pre" >> hard_space [assign_a(is_not_preformatted, false)] + >> !eol >> phrase [self.actions.preformatted] + >> eps_p [assign_a(is_not_preformatted, true)] + ; + + def_macro = + "def" >> hard_space + >> identifier [self.actions.identifier] + >> blank >> phrase [self.actions.macro_def] + ; + + variablelist = + "variablelist" >> hard_space + >> (*(anychar_p - eol)) [assign_a(self.actions.table_title)] + >> +eol + >> *varlistentry + >> eps_p [self.actions.variablelist] + ; + + varlistentry = + space + >> ch_p('[') [self.actions.start_varlistentry] + >> + ( + ( + varlistterm + >> +varlistitem + >> ch_p(']') [self.actions.end_varlistentry] + >> space + ) + | eps_p [self.actions.error] + ) + ; + + varlistterm = + space + >> ch_p('[') [self.actions.start_varlistterm] + >> + ( + ( + phrase + >> ch_p(']') [self.actions.end_varlistterm] + >> space + ) + | eps_p [self.actions.error] + ) + ; + + varlistitem = + space + >> ch_p('[') [self.actions.start_varlistitem] + >> + ( + ( + phrase [self.actions.end_varlistitem] + >> ch_p(']') + >> space + ) + | eps_p [self.actions.error] + ) + ; + + table = + "table" >> hard_space + >> (*(anychar_p - eol)) [assign_a(self.actions.table_title)] + >> +eol + >> *table_row + >> eps_p [self.actions.table] + ; + + table_row = + space + >> ch_p('[') [self.actions.start_row] + >> + ( + ( + *table_cell + >> ch_p(']') [self.actions.end_row] + >> space + ) + | eps_p [self.actions.error] + ) + ; + + table_cell = + space + >> ch_p('[') [self.actions.start_cell] + >> + ( + ( + phrase + >> ch_p(']') [self.actions.end_cell] + >> space + ) + | eps_p [self.actions.error] + ) + ; + + xinclude = + "xinclude" + >> hard_space + >> (*(anychar_p - + close_bracket)) [self.actions.xinclude] + ; + + identifier = + *(anychar_p - (space_p | ']')) + ; + + source_mode = + ( + str_p("c++") + | "python" + ) [assign_a(self.actions.source_mode)] + ; + + code = + ( + code_line + >> *(*eol >> code_line) + ) [self.actions.code] + >> +eol + ; + + code_line = + ((ch_p(' ') | '\t')) + >> *(anychar_p - eol) >> eol + ; + + list = + eps_p(ch_p('*') | '#') >> + +( + (*blank_p + >> (ch_p('*') | '#')) [self.actions.list_format] + >> *blank_p + >> list_item + ) [self.actions.list_item] + ; + + list_item = + *( common + | (anychar_p - + ( eol_p >> *blank_p >> eps_p(ch_p('*') | '#') + | (eol >> eol) + ) + ) [self.actions.plain_char] + ) + >> +eol + ; + + common = + self.actions.macro [self.actions.do_macro] + | phrase_markup + | inline_code + | simple_format + | escape + | comment + ; + + inline_code = + '`' >> + ( + *(anychar_p - + ( '`' + | (eol >> eol) // Make sure that we don't go + ) // past a single block + ) >> eps_p('`') + ) [self.actions.inline_code] + >> '`' + ; + + simple_format = + simple_bold + | simple_italic + | simple_underline + | simple_teletype + ; + + simple_bold = + '*' >> + ( + ( graph_p >> // graph_p must follow '*' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '*') // past a single line + ) + ) >> graph_p // graph_p must precede '*' + >> eps_p('*' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '*' + | ( + graph_p // A single char. e.g. *c* + >> eps_p('*' + >> (space_p | punct_p)) + ) + ) [self.actions.simple_bold] + >> '*' + ; + + simple_italic = + '/' >> + ( + ( graph_p >> // graph_p must follow '/' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '/') // past a single line + ) + ) >> graph_p // graph_p must precede '/' + >> eps_p('/' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '/' + | ( + graph_p // A single char. e.g. /c/ + >> eps_p('/' + >> (space_p | punct_p)) + ) + ) [self.actions.simple_italic] + >> '/' + ; + + simple_underline = + '_' >> + ( + ( graph_p >> // graph_p must follow '_' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '_') // past a single line + ) + ) >> graph_p // graph_p must precede '_' + >> eps_p('_' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '_' + | ( + graph_p // A single char. e.g. _c_ + >> eps_p('_' + >> (space_p | punct_p)) + ) + ) [self.actions.simple_underline] + >> '_' + ; + + simple_teletype = + '=' >> + ( + ( graph_p >> // graph_p must follow '=' + *(anychar_p - + ( eol // Make sure that we don't go + | (graph_p >> '=') // past a single line + ) + ) >> graph_p // graph_p must precede '=' + >> eps_p('=' + >> (space_p | punct_p)) // space_p or punct_p must + ) // follow '=' + | ( + graph_p // A single char. e.g. =c= + >> eps_p('=' + >> (space_p | punct_p)) + ) + ) [self.actions.simple_teletype] + >> '=' + ; + + paragraph = + *( common + | (anychar_p - // Make sure we don't go past + (eol >> eol) // a single block. + ) [self.actions.plain_char] + ) + >> +eol + ; + + phrase = + *( common + | comment + | (anychar_p - + close_bracket) [self.actions.plain_char] + ) + ; + + phrase_markup = + '[' + >> ( image + | url + | link + | anchor + | source_mode + | funcref + | classref + | memberref + | enumref + | bold + | italic + | underline + | teletype + | str_p("br") [self.actions.break_] + ) + >> ']' + ; + + escape = + str_p("\\n") [self.actions.break_] + | '\\' >> punct_p [self.actions.raw_char] + | ( + "'''" >> !eol + >> *(anychar_p - "'''") [self.actions.raw_char] + >> "'''" + ) + ; + + image = + '$' >> blank + >> (*(anychar_p - + close_bracket)) [self.actions.image] + ; + + url = + '@' + >> (*(anychar_p - + (']' | hard_space))) [self.actions.url_pre] + >> ( eps_p(']') + | (hard_space >> phrase) + ) [self.actions.url_post] + ; + + link = + "link" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) [self.actions.link_pre] + >> ( eps_p(']') + | (hard_space >> phrase) + ) [self.actions.link_post] + ; + + anchor = + '#' + >> blank + >> ( *(anychar_p - + close_bracket) + ) [self.actions.anchor] + ; + + funcref = + "funcref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) [self.actions.funcref_pre] + >> ( eps_p(']') + | (hard_space >> phrase) + ) [self.actions.funcref_post] + ; + + classref = + "classref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) [self.actions.classref_pre] + >> ( eps_p(']') + | (hard_space >> phrase) + ) [self.actions.classref_post] + ; + + memberref = + "memberref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) [self.actions.memberref_pre] + >> ( eps_p(']') + | (hard_space >> phrase) + ) [self.actions.memberref_post] + ; + + enumref = + "enumref" >> hard_space + >> (*(anychar_p - + (']' | hard_space))) [self.actions.enumref_pre] + >> ( eps_p(']') + | (hard_space >> phrase) + ) [self.actions.enumref_post] + ; + + bold = + ch_p('*') [self.actions.bold_pre] + >> blank >> phrase [self.actions.bold_post] + ; + + italic = + ch_p('\'') [self.actions.italic_pre] + >> blank >> phrase [self.actions.italic_post] + ; + + underline = + ch_p('_') [self.actions.underline_pre] + >> blank >> phrase [self.actions.underline_post] + ; + + teletype = + ch_p('^') [self.actions.teletype_pre] + >> blank >> phrase [self.actions.teletype_post] + ; + } + + bool is_not_preformatted; + + rule library, blocks, lib_info, block_markup, source_mode, code, + code_line, paragraph, space, blank, comment, headings, + h1, h2, h3, h4, h5, h6, hr, blurb, blockquote, + phrase, phrase_markup, image, list, close_bracket, + ordered_list, bold, italic, underline, teletype, + escape, def_macro, identifier, url, table, table_row, + variablelist, varlistentry, varlistterm, varlistitem, + table_cell, preformatted, list_item, common, + funcref, classref, memberref, enumref, anchor, link, + begin_section, end_section, xinclude, hard_space, eol, + inline_code, simple_format, simple_bold, simple_italic, + simple_underline, simple_teletype; + + rule const& + start() const { return library; } + }; + + Actions& actions; + }; +} + +#endif // BOOST_SPIRIT_QUICKBOOK_HPP + diff --git a/syntax_highlight.hpp b/syntax_highlight.hpp new file mode 100755 index 000000000..f99094300 --- /dev/null +++ b/syntax_highlight.hpp @@ -0,0 +1,246 @@ +/*============================================================================= + Copyright (c) 2002 2004 Joel de Guzman + Copyright (c) 2004 Eric Niebler + 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) +=============================================================================*/ +#if !defined(BOOST_SPIRIT_QUICKBOOK_SYNTAX_HIGHLIGHT_HPP) +#define BOOST_SPIRIT_QUICKBOOK_SYNTAX_HIGHLIGHT_HPP + +#include +#include +#include +#include +#include + +namespace quickbook +{ + using namespace boost::spirit; + + // Grammar for C++ highlighting + template < + typename Process + , typename Space + , typename Macro + , typename DoMacro + , typename Unexpected + , typename Out> + struct cpp_highlight + : public grammar > + { + cpp_highlight(Out& out, Macro const& macro, DoMacro do_macro) + : out(out), macro(macro), do_macro(do_macro) {} + + template + struct definition + { + definition(cpp_highlight const& self) + { + program + = + *( macro + | preprocessor [Process("preprocessor", self.out)] + | comment [Process("comment", self.out)] + | keyword [Process("keyword", self.out)] + | identifier [Process("identifier", self.out)] + | special [Process("special", self.out)] + | string_ [Process("string", self.out)] + | char_ [Process("char", self.out)] + | number [Process("number", self.out)] + | space_p [Space(self.out)] + | anychar_p [Unexpected(self.out)] + ) + ; + + macro + = eps_p(*space_p >> self.macro) + >> (*space_p) [Space(self.out)] + >> self.macro [self.do_macro] + ; + + preprocessor + = *space_p >> '#' >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + + comment + = +(*space_p >> (comment_p("//") | comment_p("/*", "*/"))) + ; + + keyword + = *space_p >> keyword_ >> (eps_p - (alnum_p | '_')) + ; // make sure we recognize whole words only + + keyword_ + = "and_eq", "and", "asm", "auto", "bitand", "bitor", + "bool", "break", "case", "catch", "char", "class", + "compl", "const_cast", "const", "continue", "default", + "delete", "do", "double", "dynamic_cast", "else", + "enum", "explicit", "export", "extern", "false", + "float", "for", "friend", "goto", "if", "inline", + "int", "long", "mutable", "namespace", "new", "not_eq", + "not", "operator", "or_eq", "or", "private", + "protected", "public", "register", "reinterpret_cast", + "return", "short", "signed", "sizeof", "static", + "static_cast", "struct", "switch", "template", "this", + "throw", "true", "try", "typedef", "typeid", + "typename", "union", "unsigned", "using", "virtual", + "void", "volatile", "wchar_t", "while", "xor_eq", "xor" + ; + + special + = *space_p >> +chset_p("~!%^&*()+={[}]:;,<.>?/|\\-") + ; + + string_ + = *space_p >> !as_lower_d['l'] >> confix_p('"', *c_escape_ch_p, '"') + ; + + char_ + = *space_p >> !as_lower_d['l'] >> confix_p('\'', *c_escape_ch_p, '\'') + ; + + number + = *space_p >> + ( + as_lower_d["0x"] >> hex_p + | '0' >> oct_p + | real_p + ) + >> *as_lower_d[chset_p("ldfu")] + ; + + identifier + = *space_p >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + } + + rule program, macro, preprocessor, comment, special, + string_, char_, number, identifier, keyword; + symbols<> keyword_; + + rule const& + start() const { return program; } + }; + + Out& out; + Macro const& macro; + DoMacro do_macro; + }; + + // Grammar for Python highlighting + // See also: The Python Reference Manual + // http://docs.python.org/ref/ref.html + template < + typename Process + , typename Space + , typename Macro + , typename DoMacro + , typename Unexpected + , typename Out> + struct python_highlight + : public grammar > + { + python_highlight(Out& out, Macro const& macro, DoMacro do_macro) + : out(out), macro(macro), do_macro(do_macro) {} + + template + struct definition + { + definition(python_highlight const& self) + { + program + = + *( comment [Process("comment", self.out)] + | keyword [Process("keyword", self.out)] + | identifier [Process("identifier", self.out)] + | special [Process("special", self.out)] + | string_ [Process("string", self.out)] + | number [Process("number", self.out)] + | space_p + | anychar_p [Unexpected(self.out)] + ) + ; + + comment + = +(*space_p >> comment_p("#")) + ; + + keyword + = *space_p >> keyword_ >> (eps_p - (alnum_p | '_')) + ; // make sure we recognize whole words only + + keyword_ + = + "and", "del", "for", "is", "raise", + "assert", "elif", "from", "lambda", "return", + "break", "else", "global", "not", "try", + "class", "except", "if", "or", "while", + "continue", "exec", "import", "pass", "yield", + "def", "finally", "in", "print", + + // Technically "as" and "None" are not yet keywords (at Python + // 2.4). They are destined to become keywords, and we treat them + // as such for syntax highlighting purposes. + + "as", "None" + ; + + special + = *space_p >> +chset_p("~!%^&*()+={[}]:;,<.>/|\\-") + ; + + string_prefix + = as_lower_d[str_p("u") >> ! str_p("r")] + ; + + string_ + = *space_p >> ! string_prefix >> (long_string | short_string) + ; + + short_string + = confix_p('\'', * c_escape_ch_p, '\'') | + confix_p('"', * c_escape_ch_p, '"') + ; + + long_string + // Note: the "str_p" on the next two lines are required for + // to avoid an INTERNAL COMPILER ERROR when using VC7.1 + = confix_p(str_p("'''"), * lex_escape_ch_p, "'''") | + confix_p(str_p("\"\"\""), * lex_escape_ch_p, "\"\"\"") + ; + + number + = *space_p >> + ( + as_lower_d["0x"] >> hex_p + | '0' >> oct_p + | real_p + ) + >> *as_lower_d[chset_p("lj")] + ; + + identifier + = *space_p >> ((alpha_p | '_') >> *(alnum_p | '_')) + ; + } + + rule program, comment, special, + string_, string_prefix, short_string, long_string, + number, identifier, keyword; + symbols<> keyword_; + + rule const& + start() const { return program; } + }; + + Out& out; + Macro const& macro; + DoMacro do_macro; + }; +} + +#endif // BOOST_SPIRIT_QUICKBOOK_SYNTAX_HIGHLIGHT_HPP +