[Boost-docs] Minor issues with QuickBook

[James Fowler]

I've been using QuickBook to create Boost style docs for a recent project, and it's been quite helpful!  I have run into a few issues, and worked out some tentative solutions, but since IANABoostExpert just yet any feedback (along the lines of "that looks good" or "yeah, but that will catastrophically implode when ...") would be appreciated. Item #1: Jam'in with QuickBook... Is there a proper (or already finished) mechanism for getting QuickBook integrated with v2 bjam and boostbook?  What I did for now was create a "quickbook.jam" file in $BOOST/tools/v2/build/tools containing import type ; import boostbook ; type.register QUICKBOOK : qbk ; import generators ; generators.register-standard quickbook.inline-file : QUICKBOOK : XML ; actions inline-file { quickbook #(>) #(<) } This is working so far (i.e., it allowed me to create docs using the following jam file) import toolset ; toolset.using doxygen ; import quickbook ; boostbook boost/stacktrack/doc : stacktrack.qbk ; doxygen autodoc     : [ glob ../../../boost/stacktrack/*.hpp ] ; but looking through "doxygen.jam", I'm thinking that there might be more to getting this right under various conditions.  I'm not exactly an expert with bjam yet... any comments? Item #2:  List alignment I ran into a problem with alignment on unordered lists.  The following source *foo1  *bar1 *foo2 this works *foo1  *bar1   *baz1  *bar2 *foo2 this works too *foo1  *bar1   *baz1 *foo2 this doesn't, foo2 is indented at bar1's level produces the following output (hope you're email reader likes html...) foo1 bar1 foo2 this works foo1 bar1 baz1 bar2 foo2 this works too foo1 bar1 baz1 foo2 this doesn't, foo2 is indented at bar1's level Any idea if this is QuickBook issue, or something deeper (like, in BoostBook or DocBook... I really don't want to go there....) Item #3) Links to section id Anchors are automatically created for each header within a section, such that given [section:my_section My Section] [h2 Header 1] some text [endsect] I can create a link from another section in my qbk file using [link my_section.header_1 see My Section Header 1].  However, what I would like (I think) is to be able to create a link to the "top" of the section, something like [link my_section My Section]. Ideally, if I just used [link my_section] it would default the text for the link to the section title instead of the id ("My Section" instead of "my_section").  Is there currently any way to link to just the section_id (without having to add a header)?  I was able to get part of the way by inserting             phrase << "<anchor id=\"" << section_id << ".top\" />\n"; at the end of begin_section_action::operator() in $BOOST/tools/quickbook/detail/actions.hpp (line 881), which lets me write [link my_section.top], although it doesn't ...  anyhow, an hour or so just went by - that got me curious and I ended up modifying the title output in begin_section_action::operator()                     phrase << "\n<title id=\"" << library_id << "." << section_id << ".title\">"; and adding     struct sectionref_action     {         // Handles link to top of section         sectionref_action(std::ostream& phrase, std::string& library_id)         : phrase(phrase), library_id(library_id) {}         template <typename Iterator>         void operator()(Iterator first, Iterator last) const         {             Iterator save = first;             phrase << "<link linkend=\"";             while (first != last)                 detail::print_char(*first++, phrase);             phrase << ".top\" endterm=\"" << library_id << ".";             first = save;             while (first != last)                 detail::print_char(*first++, phrase);             phrase << ".title\" >";         }         std::ostream& phrase;         std::string& library_id;     }; (along with the requisite bits to hook it in, mimicking "link") which seems to do what I wanted.  Now I can just say [sectionref my_section] and the result is a link to the top of section my_section with the text "My Section".  Does this seem like the right way to do what I wanted (and was what I wanted reasonable in the first place)? Thanks, that's all for the moment,  now back to writing more docs... -- james __________________________________________________________ James Fowler, Open Sea Consulting http://www.OpenSeaConsulting.com, Marietta, Georgia, USA Do C++ Right. http://www.OpenCpp.org, opening soon!