[prev in list] [next in list] [prev in thread] [next in thread]
List: boost
Subject: [boost] [quickbook] Including source files in the document
From: "Julio M. Merino Vidal" <jmmv84 () gmail ! com>
Date: 2006-07-30 16:53:17
Message-ID: 6b2d1e190607300953q79543289gd7edeac04506dbb4 () mail ! gmail ! com
[Download RAW message or body]
Hi,
I've just started adding example programs to my SoC project and I was
wondering if there was a way to bundle their code into the
documentation (which I'm writing with Quickbook). Of course I can
hyperlink to the source file, but this could be useless in printed
documentation. Also I'd copy&paste the C++ code in the qbk file, but
that is asking for trouble (desyncronization). Hence, I think it'd be
useful to be able to include this code in the final document straight
from the qbk file.
I tried with the [include ...] command but it did not work as I
expected. And indenting it in the .qbk file so that it was formatted
as source code made things worse because the inclusion had no effect
at all. Similarly, [xinclude ...] cannot work either for obvious
reasons (source code is not XML).
So... I added a 'cinclude' tag (standing for code include) to
quickbook which, given a file, includes it in the documentation marked
up (and colored!) appropriately. The implementation is attached. It
can very well be flawed as it is basically a copy&paste of other parts
of the code, but so far seems to work.
Any chance this -- or something similar -- can be integrated?
Thanks.
--
Julio M. Merino Vidal <jmmv84@gmail.com>
The Julipedia - http://julipedia.blogspot.com/
["patch.diff" (text/x-patch)]
Index: block.hpp
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/block.hpp,v
retrieving revision 1.15
diff -u -p -r1.15 block.hpp
--- block.hpp 7 Jun 2006 04:20:13 -0000 1.15
+++ block.hpp 30 Jul 2006 16:45:34 -0000
@@ -108,6 +108,7 @@ namespace quickbook
| def_macro
| table
| variablelist
+ | cinclude
| xinclude
| include
| template_
@@ -306,6 +307,13 @@ namespace quickbook
)
;
+ cinclude =
+ "cinclude"
+ >> hard_space
+ >> (*(anychar_p -
+ close_bracket)) [actions.cinclude]
+ ;
+
xinclude =
"xinclude"
>> hard_space
@@ -396,7 +404,7 @@ namespace quickbook
macro_identifier, table, table_row, variablelist,
varlistentry, varlistterm, varlistitem, table_cell,
preformatted, list_item, begin_section, end_section,
- xinclude, include, hard_space, eol, paragraph_end,
+ cinclude, xinclude, include, hard_space, eol, paragraph_end,
template_, template_id, template_formal_arg,
template_body, identifier;
Index: doc/quickbook.qbk
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/doc/quickbook.qbk,v
retrieving revision 1.44
diff -u -p -r1.44 quickbook.qbk
--- doc/quickbook.qbk 20 Jul 2006 13:13:15 -0000 1.44
+++ doc/quickbook.qbk 30 Jul 2006 16:45:34 -0000
@@ -48,6 +48,7 @@
[def __document__ [link quickbook.syntax.block.document Document]]
[def __section__ [link quickbook.syntax.block.section Section]]
+[def __cinclude__ [link quickbook.syntax.block.cinclude cinclude]]
[def __xinclude__ [link quickbook.syntax.block.xinclude xinclude]]
[def __paragraphs__ [link quickbook.syntax.block.paragraphs Paragraphs]]
[def __ordered_lists__ [link quickbook.syntax.block.lists.ordered_lists Ordered lists]]
@@ -108,6 +109,10 @@ Features include:
[section:change_log Change Log]
+[h3 Version 1.4]
+
+* Inclusion of external source code files via \`\`cinclude\`\`.
+
[h3 Version 1.3]
* Quickbook file inclusion \[include\].
@@ -620,6 +625,18 @@ End a section with:
Sections can nest, and that results in a hierarchy in the table of contents.
[endsect]
+[section cinclude]
+
+You can include a source code file (either C++ or Python) with:
+
+[pre'''
+[cinclude source_file.cpp]
+''']
+
+This is specially useful to include source code examples accompanying a
+library.
+
+[endsect]
[section xinclude]
You can include another XML file with:
Index: detail/actions.cpp
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/detail/actions.cpp,v
retrieving revision 1.40
diff -u -p -r1.40 actions.cpp
--- detail/actions.cpp 9 Jun 2006 03:16:04 -0000 1.40
+++ detail/actions.cpp 30 Jul 2006 16:45:35 -0000
@@ -10,6 +10,8 @@
=============================================================================*/
#include <numeric>
#include <functional>
+#include <fstream>
+#include <stdexcept>
#include <boost/bind.hpp>
#include <boost/filesystem/convenience.hpp>
#include "./actions.hpp"
@@ -767,6 +769,52 @@ namespace quickbook
return std::accumulate(xml, xmlfile.end(), xmltmp, concat);
}
+ void cinclude_action::operator()(iterator first, iterator last) const
+ {
+ std::string save;
+ phrase.swap(save);
+
+ fs::path filein(std::string(first, last), fs::native);
+
+ // check to see if the path is complete and if not, make it relative to the current path
+ if (!filein.is_complete())
+ {
+ filein = actions.filename.branch_path() / filein;
+ filein.normalize();
+ }
+
+ // load the input file into 'program'.
+ std::string program;
+ std::ifstream in(filein.string().c_str(), std::ios_base::in);
+ if (!in)
+ throw std::runtime_error(std::string("Could not open input file ") + filein.string());
+ in.unsetf(std::ios::skipws);
+ std::copy(std::istream_iterator<char>(in),
+ std::istream_iterator<char>(),
+ std::back_inserter(program));
+ in.close();
+
+ iterator first_(program.begin(), program.end());
+ iterator last_(program.end(), program.end());
+ first_.set_position(first.get_position());
+
+ // 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);
+ }
+
+ std::string str;
+ temp.swap(str);
+ phrase.swap(save);
+
+ out << "<programlisting>" << str << "</programlisting>\n";
+ }
+
void xinclude_action::operator()(iterator first, iterator last) const
{
// Given an xml file to include and the current filename, calculate the
Index: detail/actions.hpp
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/detail/actions.hpp,v
retrieving revision 1.34
diff -u -p -r1.34 actions.hpp
--- detail/actions.hpp 9 Jun 2006 03:16:04 -0000 1.34
+++ detail/actions.hpp 30 Jul 2006 16:45:35 -0000
@@ -599,6 +599,38 @@ namespace quickbook
std::string& qualified_section_id;
};
+ struct cinclude_action
+ {
+ // Handles code includes
+ cinclude_action(
+ collector& out_
+ , collector& phrase_
+ , collector& temp_
+ , std::string const& source_mode_
+ , string_symbols const& macro_
+ , quickbook::actions& actions_)
+ : out(out_)
+ , phrase(phrase_)
+ , temp(temp_)
+ , source_mode(source_mode_)
+ , actions(actions_)
+ , cpp_p(temp, macro_, do_macro_action(temp), actions_)
+ , python_p(temp, macro_, do_macro_action(temp), actions_)
+ {
+ }
+
+ void operator()(iterator first, iterator last) const;
+
+ collector& out;
+ collector& phrase;
+ collector& temp;
+ std::string const& source_mode;
+ quickbook::actions& actions;
+
+ cpp_p_type cpp_p;
+ python_p_type python_p;
+ };
+
struct xinclude_action
{
// Handles XML includes
Index: detail/actions_class.cpp
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/detail/actions_class.cpp,v
retrieving revision 1.4
diff -u -p -r1.4 actions_class.cpp
--- detail/actions_class.cpp 9 Jun 2006 03:16:04 -0000 1.4
+++ detail/actions_class.cpp 30 Jul 2006 16:45:35 -0000
@@ -157,6 +157,7 @@ namespace quickbook
, begin_section(out, phrase, doc_id, section_id, section_level, qualified_section_id)
, end_section(out, section_level, qualified_section_id)
+ , cinclude(out, phrase, temp, source_mode, macro, *this)
, xinclude(out, *this)
, include(*this)
Index: detail/actions_class.hpp
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/detail/actions_class.hpp,v
retrieving revision 1.4
diff -u -p -r1.4 actions_class.hpp
--- detail/actions_class.hpp 9 Jun 2006 03:16:04 -0000 1.4
+++ detail/actions_class.hpp 30 Jul 2006 16:45:35 -0000
@@ -177,6 +177,7 @@ namespace quickbook
begin_section_action begin_section;
end_section_action end_section;
+ cinclude_action cinclude;
xinclude_action xinclude;
include_action include;
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic