Joel de Guzman wrote:
...Does this seem like the right way to do what I wanted (and was
what I wanted reasonable in the first place)?
Yes, I think so. Please submit a full patch for the code and the
docs. I can evaluate the patch in more detail. It's ok, AFAICT.
OK, I've attached the output from "cvs diff". I haven't had much
experience generating patches with CVS, so let me know if there's a
better way and I'll do it over. I think I started with a slightly
older rev of quickbook.cpp (didn't use boost::program_options) and
quickbook.qbk (version number change?). I didn't incorporate the newer
changes from CVS yet, mainly because I wanted to keep this (the patch
process) simple at first, but I can update my source and rerun diff if
you'd like.
Updating the QuickBook docs caused me to rethink a few things. All the
existing "*ref" entries are link to the reference docs, which isn't
really consistent with this addition - so it's now "sectionlink" instead
of "sectionref". Adding the ".top" anchor in each section turned out to
be unnecessary and it complicated the (yet to be tested) possibility of
linking to external sections, so that's gone. Finally, I added in
support for "macroref" (similar to classref / functionref / etc...).
This depends on the BoostBook element <macroname ...>, which appears to
be currently working but undocumented (at least, it works so far for me : ).
- james
--
__________________________________________________________
James Fowler, Open Sea Consulting
http://www.OpenSeaConsulting.com, Marietta, Georgia, USA
Do C++ Right. http://www.OpenCpp.org, opening soon!
Index: quickbook.hpp
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/quickbook.hpp,v
retrieving revision 1.2
diff -c -r1.2 quickbook.hpp
*** quickbook.hpp 30 Jan 2005 22:52:27 -0000 1.2
--- quickbook.hpp 18 Feb 2005 20:27:30 -0000
***************
*** 422,430 ****
--- 422,432 ----
>> ( image
| url
| link
+ | sectionlink
| anchor
| source_mode
| funcref
+ | macroref
| classref
| memberref
| enumref
***************
*** 472,477 ****
--- 474,488 ----
)
[self.actions.link_post]
;
+ sectionlink =
+ "sectionlink" >> hard_space
+ >> (*(anychar_p -
+ (']' | hard_space)))
[self.actions.sectionlink_pre]
+ >> ( eps_p(']')
+ | (hard_space >> phrase)
+ )
[self.actions.sectionlink_post]
+ ;
+
anchor =
'#'
>> blank
***************
*** 489,494 ****
--- 500,514 ----
)
[self.actions.funcref_post]
;
+ macroref =
+ "macroref" >> hard_space
+ >> (*(anychar_p -
+ (']' | hard_space)))
[self.actions.macroref_pre]
+ >> ( eps_p(']')
+ | (hard_space >> phrase)
+ )
[self.actions.macroref_post]
+ ;
+
classref =
"classref" >> hard_space
>> (*(anychar_p -
***************
*** 556,563 ****
escape, def_macro, identifier, url, table,
table_row,
variablelist, varlistentry, varlistterm,
varlistitem,
table_cell, preformatted, list_item, common,
! funcref, classref, memberref, enumref, headerref,
anchor, link,
! begin_section, end_section, xinclude, hard_space,
eol,
inline_code, simple_format, simple_bold,
simple_italic,
simple_underline, simple_teletype;
--- 576,583 ----
escape, def_macro, identifier, url, table,
table_row,
variablelist, varlistentry, varlistterm,
varlistitem,
table_cell, preformatted, list_item, common,
! macroref, funcref, classref, memberref, enumref,
headerref, anchor, link,
! begin_section, end_section, sectionlink,
xinclude, hard_space, eol,
inline_code, simple_format, simple_bold,
simple_italic,
simple_underline, simple_teletype;
Index: detail/actions.hpp
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/detail/actions.hpp,v
retrieving revision 1.2
diff -c -r1.2 actions.hpp
*** detail/actions.hpp 30 Jan 2005 22:52:28 -0000 1.2
--- detail/actions.hpp 18 Feb 2005 21:11:35 -0000
***************
*** 551,556 ****
--- 551,558 ----
const char* end_cell_ = "</entry>";
const char* funcref_pre_ = "<functionname alt=\"";
const char* funcref_post_ = "</functionname>";
+ const char* macroref_pre_ = "<macroname alt=\"";
+ const char* macroref_post_ = "</macroname>";
const char* classref_pre_ = "<classname alt=\"";
const char* classref_post_ = "</classname>";
const char* memberref_pre_ = "<methodname alt=\"";
***************
*** 722,727 ****
--- 724,755 ----
char const* tag;
};
+ struct sectionlink_action
+ {
+ // Handles link to top of section
+
+ sectionlink_action(std::ostream& phrase, std::string& library_id)
+ : phrase(phrase), library_id(library_id) {}
+
+ template <typename Iterator>
+ void operator()(Iterator first, Iterator last) const
+ {
+ std::string target;
+ while (first != last)
+ target += *first++;
+ if( target.find('.') == std::string::npos )
+ target = library_id + "." + target;
+ //phrase << "<link linkend=\"" << target << ".top\" ";
+ phrase << "<link linkend=\"" << target << "\" ";
+ phrase << "endterm=\"" << target << ".title\"";
+ phrase << " >";
+ }
+
+ std::ostream& phrase;
+ std::string& library_id;
+ };
+
+
template <typename Actions>
struct variablelist_action
{
***************
*** 874,880 ****
if (section_id.empty())
section_id = detail::make_identifier(first, last);
phrase << "\n<section id=\"" << library_id << "." << section_id
<< "\">\n";
! phrase << "<title>";
while (first != last)
detail::print_char(*first++, phrase);
phrase << "</title>\n";
--- 902,910 ----
if (section_id.empty())
section_id = detail::make_identifier(first, last);
phrase << "\n<section id=\"" << library_id << "." << section_id
<< "\">\n";
! //phrase << "<para/>\n";
! //phrase << "<anchor id=\"" << library_id << "." <<
section_id << ".top\" />\n";
! phrase << "<title id=\"" << library_id << "." << section_id <<
".title\">";
while (first != last)
detail::print_char(*first++, phrase);
phrase << "</title>\n";
Index: detail/quickbook.cpp
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/detail/quickbook.cpp,v
retrieving revision 1.3
diff -c -r1.3 quickbook.cpp
*** detail/quickbook.cpp 14 Feb 2005 06:36:16 -0000 1.3
--- detail/quickbook.cpp 18 Feb 2005 20:03:52 -0000
***************
*** 12,18 ****
#include "utils.hpp"
#include "actions.hpp"
#include <boost/spirit/iterator/position_iterator.hpp>
- #include <boost/program_options.hpp>
#include <fstream>
#include <iostream>
--- 12,17 ----
***************
*** 22,29 ****
#pragma warning(disable:4355)
#endif
- #define QUICKBOOK_VERSION "Quickbook Version 1.1"
-
namespace quickbook
{
using namespace boost::spirit;
--- 21,26 ----
***************
*** 65,70 ****
--- 62,69 ----
, list_item(list_buffer, phrase, section_id, list_item_pre,
list_item_post)
, funcref_pre(phrase, funcref_pre_)
, funcref_post(phrase, funcref_post_)
+ , macroref_pre(phrase, macroref_pre_)
+ , macroref_post(phrase, macroref_post_)
, classref_pre(phrase, classref_pre_)
, classref_post(phrase, classref_post_)
, memberref_pre(phrase, memberref_pre_)
***************
*** 100,105 ****
--- 99,106 ----
, url_post(phrase, url_post_)
, link_pre(phrase, link_pre_)
, link_post(phrase, link_post_)
+ , sectionlink_pre(phrase, doc_id )
+ , sectionlink_post(phrase, link_post_)
, table(*this)
, start_row(phrase, table_span, table_header)
, end_row(phrase, end_row_)
***************
*** 178,183 ****
--- 179,186 ----
link_action funcref_pre;
markup_action funcref_post;
+ link_action macroref_pre;
+ markup_action macroref_post;
link_action classref_pre;
markup_action classref_post;
link_action memberref_pre;
***************
*** 217,222 ****
--- 220,227 ----
markup_action url_post;
link_action link_pre;
markup_action link_post;
+ sectionlink_action sectionlink_pre;
+ markup_action sectionlink_post;
table_action table;
start_row_action start_row;
markup_action end_row;
***************
*** 253,259 ****
return 1;
}
! // Turn off white space skipping on the stream
in.unsetf(ios::skipws);
std::copy(
--- 258,264 ----
return 1;
}
! // Turn of white space skipping on the stream
in.unsetf(ios::skipws);
std::copy(
***************
*** 329,395 ****
int
main(int argc, char* argv[])
{
! try
{
! using boost::program_options::options_description;
! using boost::program_options::variables_map;
! using boost::program_options::store;
! using boost::program_options::parse_command_line;
! using boost::program_options::notify;
!
! options_description desc("Allowed options");
! desc.add_options()
! ("help", "produce help message")
! ("version,v", "print version string")
! ;
!
! variables_map vm;
! store(parse_command_line(argc, argv, desc), vm);
! notify(vm);
!
! if (vm.count("help"))
! {
! std::cout << desc << "\n";
! return 0;
! }
!
! if (vm.count("version"))
{
! std::cout << QUICKBOOK_VERSION << std::endl;
! return 0;
! }
!
! 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 << "Error: No filename given" << std::endl;
}
- }
-
- catch(std::exception& e)
- {
- std::cerr << "Error: " << e.what() << "\n";
- return 1;
- }
! catch(...)
{
! std::cerr << "Error: Exception of unknown type caught\n";
}
-
return 0;
}
--- 334,357 ----
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;
}
Index: doc/quickbook.qbk
===================================================================
RCS file: /cvsroot/boost/boost/tools/quickbook/doc/quickbook.qbk,v
retrieving revision 1.4
diff -c -r1.4 quickbook.qbk
*** doc/quickbook.qbk 14 Feb 2005 06:36:16 -0000 1.4
--- doc/quickbook.qbk 18 Feb 2005 21:41:46 -0000
***************
*** 1,5 ****
[part quickbook
! [version 1.1]
[authors [de Guzman, Joel], [Niebler, Eric]]
[copyright 2002 2004 Joel de Guzman, Eric Niebler]
[purpose WikiWiki style documentation tool]
--- 1,5 ----
[part quickbook
! [version 1.0]
[authors [de Guzman, Joel], [Niebler, Eric]]
[copyright 2002 2004 Joel de Guzman, Eric Niebler]
[purpose WikiWiki style documentation tool]
***************
*** 10,22 ****
http://www.boost.org/LICENSE_1_0.txt
</ulink>)
]
! [last-revision $Date: 2005/02/14 06:36:16 $]
]
! [/ QuickBook Document version 1.1 ]
[/ Sept 24, 2002 ]
[/ Sept 2, 2004 ]
- [/ Feb 14, 2005 ]
[/ Some links]
--- 10,21 ----
http://www.boost.org/LICENSE_1_0.txt
</ulink>)
]
! [last-revision $Date: 2005/02/04 14:52:07 $]
]
! [/ QuickBook Document version 0.9 ]
[/ Sept 24, 2002 ]
[/ Sept 2, 2004 ]
[/ Some links]
***************
*** 265,270 ****
--- 264,313 ----
See sections [link syntax.section Section] and [link syntax.headings Headings]
for more info.
+ [h3 Section links]
+
+ You can link to the top of a section within a document using:
+
+ [pre'''
+ [sectionlink section_id]
+ [sectionlink document_id.section_id]
+ ''']
+
+ Section links automatically use the title of the section /section_id/ for
their text.
+ If /document_id/ is ommitted, it defaults to the current QuickBook document.
For example,
+ given that this section was defined using
+
+ [pre'''
+ [section:syntax Syntax Summary]
+ ''']
+
+ using sectionlink as follows
+
+ [pre'''
+ Local link to section : [sectionlink syntax]\n
+ Global link to section : [sectionlink quickbook.syntax]
+ ''']
+
+ will generate:
+
+ Local link to section : [sectionlink syntax]\n
+ Global link to section : [sectionlink quickbook.syntax]
+
+ Note that this may not work as well for sections which were not created by
QuickBook. More
+ specifically, it depends a section to be defined with an id attribute of
"/document_id.section_id/"
+ and contain a title element with an id of "/document_id.section_id/.title".
For example, the
+ xml QuickBook creates for this section looks something like
+
+ [pre'''
+ <section id="quickbook.syntax">
+ <title id="quickbook.syntax.title"> Syntax Summary</title>
+ ''']
+
+ To make things even more interesting, creating a sectionlink to a section
outside of
+ the current document has not yet been tested...
+
+ See sections [link syntax.section Section] for more info.
+
[h3 refentry links]
In addition, you can link internally to an XML refentry like:
***************
*** 284,296 ****
This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>].
! [h3 function, class, member, enum or header links]
! If you want to link to a function, class, member, enum or header 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]
--- 327,340 ----
This gets converted into [^<link linkend="xml.refentry">xml.refentry</link>].
! [h3 function, macro, class, member, enum or header links]
! If you want to link to a function, macro, class, member, enum or header in
the reference
section, you can use:
[pre'''
[funcref fully::qualified::function_name The link text]
+ [macroref macro_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]
***************
*** 298,304 ****
''']
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]
--- 342,348 ----
''']
Again, the link text is optional. If this is not present, the link text will
! automatically be the function, macro, class, member or enum. Example:
[pre'''
[classref boost::bar::baz]
***************
*** 364,370 ****
[category The document's category]
[authors [Blow, Joe], [Doe, Jane]]
[license The document's license]
! [last-revision $Date: 2005/02/14 06:36:16 $]
[source-mode source-type]
]
''']
--- 408,414 ----
[category The document's category]
[authors [Blow, Joe], [Doe, Jane]]
[license The document's license]
! [last-revision $Date: 2005/02/04 14:52:07 $]
[source-mode source-type]
]
''']
***************
*** 819,826 ****
--- 863,872 ----
[[anchor] [[^'''[#anchor]''']]]
[[link] [[^'''[EMAIL PROTECTED]://www.boost.org
Boost]''']]]
[[anchor link] [[^'''[link section.anchor Link text]''']]]
+ [[section link] [[^'''[sectionlink section]''']]]
[[refentry link] [[^'''[link xml.refentry Link text]''']]]
[[function link] [[^'''[funcref fully::qualified::function_name
Link text]''']]]
+ [[macro link] [[^'''[macroref macro_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]''']]]
***************
*** 1370,1378 ****
--- 1416,1426 ----
>> ( image
| url
| link
+ | sectionlink
| anchor
| source_mode
| funcref
+ | macroref
| classref
| memberref
| enumref
***************
*** 1420,1425 ****
--- 1468,1482 ----
)
;
+ sectionlink =
+ "sectionlink" >> hard_space
+ >> (*(anychar_p -
+ (']' | hard_space)))
+ >> ( eps_p(']')
+ | (hard_space >> phrase)
+ )
+ ;
+
anchor =
'#'
>> blank
***************
*** 1437,1442 ****
--- 1494,1508 ----
)
;
+ macroref =
+ "macroref" >> hard_space
+ >> (*(anychar_p -
+ (']' | hard_space)))
+ >> ( eps_p(']')
+ | (hard_space >> phrase)
+ )
+ ;
+
classref =
"classref" >> hard_space
>> (*(anychar_p -
