[ Boostbook - Quickbook ] Silly questions
Hi, finally I succeed in generating a documentation from a quickbook file (.qbk); however, I have some doubts about the correct procedure to do that. I use Fedora 7 and its prepackaged version of Boost but, unfortunately, it seems that there is nothing about Boost.build or BoostBoook. Thus, I downloaded the source distribution from Boost.org and untar it in my home directory where I also copied (and customized) the user-config.jam. Then, I downloaded the dtd and the xsl as stated from "getting started section". After that, I went in $BOOST_ROOT/doc and I succeed in regenerating doc through bjam --v2. My questions are: 1) is it possible to build a documentation outside the $BOOST_ROOT? if yes, what kind of jamfile / Jamroot is needed ?? 2) what is the minimal set of tools needed to build a documentation? Is it strictly necessary to download the entire boost distribution? 3) I noted that stylesheet and images miss from generated documentation. I suspect that it is due to the fact that these files are supposed to be there (since they are part of boost distribution). Is this correct? I am not very familiar with these tools, thus my questions could be fool, but, at other hand, they could be useful to understand what are the main difficulties of an unexperienced user. Best regards Manuel Fiorelli
Hi Manuel, On 6/15/07, Manuel Fiorelli <manuel.fiorelli@gmail.com> wrote:
Hi, finally I succeed in generating a documentation from a quickbook file (.qbk); however, I have some doubts about the correct procedure to do that.
I have recently also learned to use these tools to some degree. My answers might not be the best procedure, but maybe they will be helpful... Anyway, maybe we will both learn something if the experts comment:
My questions are: 1) is it possible to build a documentation outside the $BOOST_ROOT? if yes, what kind of jamfile / Jamroot is needed ??
Yes. I don't know what is absolutely needed but the following works with Boost.Build that is in the CVS HEAD (I have scavenged these files from other boost projects): In the root directory of your project: a project-root.jam file with contents (exact, i.e., you don't have to substitute anything for BOOST_ROOT as long as you have that environment variable set): import os ; path-constant BOOST_ROOT : [ os.environ BOOST_ROOT ] ; This seems to take in the system environment variable BOOST_ROOT and makes it available to bjam. ...In the same place, a boost-build.jam file with contents: boost-build $(BOOST_ROOT)/tools/build/v2 ; That seems to point to boost build 2. What I have, then, is a Jamfile that says (this might only be necessary if you are also building code that uses boost) use-project boost : $(BOOST_ROOT) ; project boost/my_library : build-dir bin.v2 ; ... and a few directories underneath, the Jamfile for the actual documentation.
3) I noted that stylesheet and images miss from generated documentation. I suspect that it is due to the fact that these files are supposed to be there (since they are part of boost distribution). Is this correct?
Wherever your docs end up, you might need to place the css files and stylesheets there yourself. Most of the out-of-boost-distribution projects I've looked at have the docs/html directory with the stylesheets already there, and docs/html/images with the images. When the docs get generated in the html directory they work with the stylesheets and images that have been placed there. HTH, Stjepan
Thank you Stephan, I followed your step-by-step procedure and successfully build my project outside boost directories. For my test I use this Jamfile use-project boost : $(BOOST_ROOT) ; project boost/my_library : build-dir bin.v2 ; import quickbook ; xml test : test.qbk ; boostbook standalone : test : <xsl:param>toc.max.depth=3 <xsl:param>toc.section.depth=3 <xsl:param>chunk.section.depth=3 ; exe prova : main.cpp ; When you write project boost/my_library do you mean to define a library inside the project boost??? It seems that the fundamental line is use-project boost, because when I eliminate it, I got the following error Building Boost.Regex with the optional Unicode/ICU support disabled. Please refer to the Boost.Regex documentation for more information (don't panic: this is a strictly optional feature). /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:996: in virtual-target.register-actual-name from module virtual-target error: Duplicate name of actual target: <pbin/gcc-4.1.2/debug>test.xml error: previous virtual target { quickbook%quickbook.quickbook- to-boostbook-test.xml.XML { test.qbk.QUICKBOOK } } error: created from ./test error: another virtual target { quickbook%quickbook.quickbook- to-boostbook-test.xml.XML { test.qbk.QUICKBOOK } } error: created from ./test error: added properties: <python-debugging>off <python>2.5 error: removed properties: none /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:459: in actualize-no-scanner from module object(file-target)@462 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:111: in object(file-target)@462.actualize from module object(file-target)@462 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:743: in actualize-source-type from module object(action)@471 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:764: in actualize-sources from module object(action)@471 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:709: in object(action)@471.actualize from module object(action)@471 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:274: in actualize-action from module object(file-target)@472 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:467: in actualize-no-scanner from module object(file-target)@472 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:111: in object(file-target)@472.actualize from module object(file-target)@472 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:743: in actualize-source-type from module object(action)@474 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:764: in actualize-sources from module object(action)@474 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:709: in object(action)@474.actualize from module object(action)@474 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:274: in actualize-action from module object(file-target)@475 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:467: in actualize-no-scanner from module object(file-target)@475 /home/manuel/boost_1_34_0/tools/build/v2/build/virtual-target.jam:111: in object(file-target)@475.actualize from module object(file-target)@475 /home/manuel/boost_1_34_0/tools/build/v2/build-system.jam:476: in load from module build-system /home/manuel/boost_1_34_0//tools/build/v2/kernel/modules.jam:261: in import from module modules /home/manuel/boost_1_34_0//tools/build/v2/kernel/bootstrap.jam:132: in boost-build from module /home/manuel/Prova/boost-build.jam:1: in module scope from module which is exactly what I got before you reveal me your procedure. I hope to have time to study closer Boost.Build and, moreover, to write a decent library for Boost project.. Best Regards Manuel Fiorelli
On 6/15/07, Manuel Fiorelli <manuel.fiorelli@gmail.com> wrote:
Thank you Stephan, I followed your step-by-step procedure and successfully build my project outside boost directories. For my test I use this Jamfile [snip jamfile]
You are very welcome! Glad it helped.
When you write project boost/my_library do you mean to define a library inside the project boost???
I think it's just to give the project a name... projects can be hierarchical so you can have "project" as your root project, and then "project/docs" etc for your subprojects. The lib I stole this from probably had the top project "boost/whatever" so I just kept the format.
It seems that the fundamental line is use-project boost, because when I eliminate it, I got the following error
Cool, good to know.
I hope to have time to study closer Boost.Build and, moreover, to write a decent library for Boost project..
If that's what you're planning to do, I would suggest checking out the boost sandbox from the subversion repository: http://svn.boost.org/trac/boost/wiki/BoostSubversion There are lots of projects there that you can learn from by example (regarding boost.build). Also, I've been working on a little script that generates starting project layouts from a template, which you can try out if you'd like. I just recently updated it to work on non-windows platforms (after finding out it only worked on windows and python 2.5, yikes!!). I've since tested it on OS X and tuned it to work with Python 2.3. If you check out the sandbox, you can find the template under the template-under-construction directory, and if you go there and run: python make_template.py sandbox , it should ask you a few questions (your name and the name of your library) and generate a sample project tree with working (hopefully) builds for docs, examples and tests. If something doesn't work please let me know and I'd be happy to fix it. More info on the template is at: http://dancinghacker.com/code/template/ Best regards, Stjepan
Manuel Fiorelli wrote:
Hi, finally I succeed in generating a documentation from a quickbook file (.qbk); however, I have some doubts about the correct procedure to do that. I use Fedora 7 and its prepackaged version of Boost but, unfortunately, it seems that there is nothing about Boost.build or BoostBoook. Thus, I downloaded the source distribution from Boost.org and untar it in my home directory where I also copied (and customized) the user-config.jam. Then, I downloaded the dtd and the xsl as stated from "getting started section". After that, I went in $BOOST_ROOT/doc and I succeed in regenerating doc through bjam --v2.
My questions are: 1) is it possible to build a documentation outside the $BOOST_ROOT? if yes, what kind of jamfile / Jamroot is needed ??
Yes. See http://svn.boost.org/trac/boost/browser/sandbox/doc_test/doc/project-root.ja... and http://svn.boost.org/trac/boost/browser/sandbox/doc_test/doc/Jamfile.v2 for examples but ignore the experimental Jamfile options starting with "# The page style" for now :-) With the project-root.jam shown you need only set the environment variable BOOST_ROOT to point to your main Boost tree to get things to work. At least that's the general idea!
2) what is the minimal set of tools needed to build a documentation? Is it strictly necessary to download the entire boost distribution?
You need Docbook DTD and XSL, xsltproc (should be there already on Linux), plus most of the contents of boost-path/tools. You can save some time in rebuilds if you build quickbook in release mode and then add a: using quickbook : some-path/quickbook ; to your user-config.jam, but it's not essential to do this. Doxygen is optional, as is an FO processor (for PDF output).
3) I noted that stylesheet and images miss from generated documentation. I suspect that it is due to the fact that these files are supposed to be there (since they are part of boost distribution). Is this correct?
Until now folks have had to copy these into the html sub-directory after the docs are generated, however with current cvs you can just add <xsl:param>boost.root=relative-path-to-boost ; to the Jamfile and the docs will automatically pick up the Boost versions of these under boost/path/doc. See the current Boost.Config docs in cvs for an example of this in action. HTH, John.
On 6/16/07, John Maddock <john@johnmaddock.co.uk> wrote:
Manuel Fiorelli wrote:
1) is it possible to build a documentation outside the $BOOST_ROOT? if yes, what kind of jamfile / Jamroot is needed ??
Yes.
See http://svn.boost.org/trac/boost/browser/sandbox/doc_test/doc/project-root.ja... and http://svn.boost.org/trac/boost/browser/sandbox/doc_test/doc/Jamfile.v2 for examples but ignore the experimental Jamfile options starting with "# The page style" for now :-)
Nice! From looking a few things I found on the web, looks like modules.peek can be used for various things - in this case is [ modules.peek : BOOST_ROOT ] equivalent to [ os.environ BOOST_ROOT ] or is there a difference? In general, where can one can find documentation on all the importable modules (os, path, modules...)? I am only able to find discussion threads that hint at how they can be used. [...]
plus most of the contents of boost-path/tools. You can save some time in rebuilds if you build quickbook in release mode and then add a:
using quickbook : some-path/quickbook ;
Didn't know that either... [...]
Until now folks have had to copy these into the html sub-directory after the docs are generated, however with current cvs you can just add
<xsl:param>boost.root=relative-path-to-boost ;
to the Jamfile and the docs will automatically pick up the Boost versions of these under boost/path/doc. See the current Boost.Config docs in cvs for an example of this in action.
...insert another "oh, cool" here...
HTH, John.
That helped me out too! Thanks, John. Stjepan
Stjepan Rajko wrote:
Nice! From looking a few things I found on the web, looks like modules.peek can be used for various things - in this case is [ modules.peek : BOOST_ROOT ] equivalent to [ os.environ BOOST_ROOT ] or is there a difference?
In general, where can one can find documentation on all the importable modules (os, path, modules...)? I am only able to find discussion threads that hint at how they can be used.
Me too, as you can see from the copyright, I just pinched someone elses code here I don't really understand bbv2 at present :-(
to the Jamfile and the docs will automatically pick up the Boost versions of these under boost/path/doc. See the current Boost.Config docs in cvs for an example of this in action.
...insert another "oh, cool" here...
Nah, if you want cool, then see what Matias Capelleto has been up to: http://tinyurl.com/ysk7z8 John.
In Matias Capelleto pages I clicked on the "XHTML 1.0 validation link" and I find they are not Valid XHTML pages: it seems there is a problem with an attribute called "xmlns" (I don't know what it is exactly). Best regards, Manuel Fiorelli
On Jun 17, 2007, at 9:35 AM, Manuel Fiorelli wrote:
In Matias Capelleto pages I clicked on the "XHTML 1.0 validation link" and I find they are not Valid XHTML pages: it seems there is a problem with an attribute called "xmlns" (I don't know what it is exactly).
Matias and others know about this problem and are working to fix it. - Doug
participants (4)
-
Douglas Gregor -
John Maddock -
Manuel Fiorelli -
Stjepan Rajko