Quickbook quick start

older
Stepping into a boost::function...

Peng Yu

3 May 2009 3 May '09

4:40 p.m.

Hi, I wan to use Quickbook to generate documentation for my code to be submit to boost. I understand that Quickbook could help make the code and the documentation consistent. But there is no a tutorial webpage that describes how I can get started with Quickbook. I am wondering if there is somebody could give me some hints on how to use it? Regards, Peng

Show replies by date

tom fogal

3 May 3 May

8:34 p.m.

Peng Yu writes:

...

I wan to use Quickbook to generate documentation for my code to be submit to boost. I understand that Quickbook could help make the code and the documentation consistent. But there is no a tutorial webpage that describes how I can get started with Quickbook.

Getting started: http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/install.html Documenting: http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/syntax.html Cheers, -tom

Peng Yu

9:32 p.m.

On Sun, May 3, 2009 at 3:34 PM, tom fogal wrote:

...

Peng Yu writes:

...
I wan to use Quickbook to generate documentation for my code to be submit to boost. I understand that Quickbook could help make the code and the documentation consistent. But there is no a tutorial webpage that describes how I can get started with Quickbook.

Getting started:

http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/install.html

Documenting:

http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/syntax.html

I am looking for some example files so that I can run quickbook on it and generate some test documentation. I see the example at the end of the page the second link points to. But it is hard to see it if you didn't point that page to me. Would you please let me know what command I should use to generate a documentation page from that file? http://www.boost.org/doc/libs/1_39_0/tools/quickbook/test/stub.cpp BTW, I still think that the quickbook document should provide some easy example files so that I try. Regards, Peng

Daniel James

9:45 p.m.

2009/5/3 Peng Yu :

...

I am looking for some example files so that I can run quickbook on it and generate some test documentation.

There isn't really any at the moment. The best examples are existing libraries. I think Boost.Config is a pretty good example. That documentation is at 'libs/boost/config/doc'. You can rebuild the documentation by running 'bjam' in that directory. You might find this guide to setting up the tools useful: https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted Although, it assumes you're already using boost build.

...

BTW, I still think that the quickbook document should provide some easy example files so that I try.

I agree, I've been meaning to put together some better introductory material for a while, but I've got a few things on my plate. Daniel

Peng Yu

5 May 5 May

1:03 a.m.

On Sun, May 3, 2009 at 4:45 PM, Daniel James wrote:

...

2009/5/3 Peng Yu :

...
I am looking for some example files so that I can run quickbook on it and generate some test documentation.

There isn't really any at the moment. The best examples are existing libraries. I think Boost.Config is a pretty good example. That documentation is at 'libs/boost/config/doc'. You can rebuild the documentation by running 'bjam' in that directory.

You might find this guide to setting up the tools useful:

https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted

Although, it assumes you're already using boost build.

...
BTW, I still think that the quickbook document should provide some easy example files so that I try.

I agree, I've been meaning to put together some better introductory material for a while, but I've got a few things on my plate.

I do not know how bjam works. At this moment, I just want to know what command has been called to build the document. Would you please let me know what the commands are or how I can figure out what they are? Regards, Peng

Daniel James

6:41 p.m.

2009/5/5 Peng Yu :

...

I do not know how bjam works. At this moment, I just want to know what command has been called to build the document. Would you please let me know what the commands are or how I can figure out what they are?

The build process is pretty complicated. It's probably best to learn how to use boost build. A Cmake based build is being developed but I don't know how well that works. There's a diagram showing the build process on the page I linked to which should give you an idea. Before I start, I'll summarize the procedure to build pure quickbook documentation, you'll first run quickbook to convert the documentation to boostbook, then you run xsltproc with 'tools/boostbook/xsl/docbook.xsl' to convert that to docbook and then run xsltproc again with 'tools/boostbook/xsl/html.xsl' to convert that to html. In detail, I'll write in a unix style as I don't have a windows computer to hand. So, you'll have to work out how to translate it to windows yourself I'm afraid. First you'll need to setup xsltproc. You'll need to download the xsltproc executables, docbook DTD schemas and XSL stylesheets (details in the page I linked to). Then create an xml catalog file to tell xsltproc where to find the various files. Boost build creates a file call 'boostbook_catalog.xml': <?xml version="1.0"?> <!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"> <catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"> <rewriteURI uriStartString="http://www.boost.org/tools/boostbook/dtd/" rewritePrefix="file:///Users/daniel/boost/git/tools/boostbook/dtd/"/> <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="file:///opt/local/share/xsl/docbook-xsl/"/> <rewriteURI uriStartString="http://www.oasis-open.org/docbook/xml/4.2/" rewritePrefix="file:///opt/local/share/xml/docbook/4.2/"/> </catalog> You'll have to adjust the 'rewritePrefix' values for the location of the files on your computer. I'm not sure how you write it for the windows filesystem. And set the environment variable XML_CATALOG_FILES to its location so that xsltproc will know where to find it. Then, to build Boost.Config (for example), go to 'libs/config/doc'. To convert quickbook to boostbook: quickbook config.qbk This generaters config.qbk. To convert to docbook: xsltproc ../../../tools/boostbook/xsl/docbook.xsl config.xml > config.docbook Finally, to generate html: cd html xsltproc \ --stringparam boost.root "../../../.." --stringparam chunk.section.depth "1" \ --stringparam html.stylesheet "../../../../doc/html/boostbook.css" \ ../../../../tools/boostbook/xsl/html.xsl ../config.docbook At least, that worked for me. Daniel

Deane Yang

3 May 3 May

9:43 p.m.

tom fogal wrote:

...

Peng Yu writes:

...
I wan to use Quickbook to generate documentation for my code to be submit to boost. I understand that Quickbook could help make the code and the documentation consistent. But there is no a tutorial webpage that describes how I can get started with Quickbook.

Getting started:

http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/install.html

Documenting:

http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/syntax.html

Cheers,

-tom

Hi, I just followed the instructions for Windows. Then I went to boost/doc and ran "bjam". It appears that doxygen is required, no? Shouldn't installation instructions for doxygen be included in the Windows section? There seem to be such instructions in the MacOS X section. Deane

Deane Yang

4 May 4 May

1:25 p.m.

Deane Yang wrote:

...

tom fogal wrote:

...
Peng Yu writes:

...
I wan to use Quickbook to generate documentation for my code to be submit to boost. I understand that Quickbook could help make the code and the documentation consistent. But there is no a tutorial webpage that describes how I can get started with Quickbook.

Getting started:

http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/install.html

Documenting:

http://www.boost.org/doc/libs/1_39_0/doc/html/quickbook/syntax.html

Cheers,

-tom

Hi,

I just followed the instructions for Windows. Then I went to boost/doc and ran "bjam". It appears that doxygen is required, no? Shouldn't installation instructions for doxygen be included in the Windows section? There seem to be such instructions in the MacOS X section.

Deane

A followup: I installed doxygen and added using doxygen ; to my user-config.jam file. This did not work. I tried replacing the line above by: using doxygen : <absolute path to doxygen.exe> ; This also did not work. I get the following error message below. Any advice or help would be welcome. warn: Unable to construct ../libs/asio/doc/asio c:\home\deane\git\software\boost\libs\accumulators\doc\Jamfile.v2:18: in modules.load rule doxygen unknown in module Jamfile. c:/home/deane/git/software/boost/tools/build/v2/build\project.jam:307: in load-jamfile c:/home/deane/git/software/boost/tools/build/v2/build\project.jam:62: in load c:/home/deane/git/software/boost/tools/build/v2/build\project.jam:168: in project.find c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:361: in find-really c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:427: in object(project-target)@376.find c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:851: in resolve-reference c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:868: in targets.generate-from-reference c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:1168: in generate-dependencies c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:1216: in object(typed-target)@383.generate c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:767: in generate-really c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:739: in object(main-target)@397.generate c:/home/deane/git/software/boost/tools/build/v2/build\targets.jam:257: in object(project-target)@376.generate c:/home/deane/git/software/boost/tools/build/v2\build-system.jam:682: in load c:\home\deane\git\software\boost\tools\build\v2/kernel\modules.jam:283: in import c:\home\deane\git\software\boost\tools\build\v2\kernel\bootstrap.jam:128: in boost-build c:\home\deane\git\software\boost\boost-build.jam:16: in module scope

Daniel James

5 May 5 May

6:52 p.m.

2009/5/4 Deane Yang :

...

A followup: I installed doxygen and added

using doxygen ;

to my user-config.jam file. This did not work.

It should work if you add your doxygen executable to your path.

...

I tried replacing the line above by:

using doxygen : <absolute path to doxygen.exe> ;

Can you give the actual line? If you're using backslashed you'll need to escape them (e.g. c:\\home\\deane). If there's a space in the path you'll need to use quotes (e.g. "c:\\Program Files\\doxygen\\bin\\doxygen.exe").

...

This also did not work. I get the following error message below. Any advice or help would be welcome.

warn: Unable to construct ../libs/asio/doc/asio

Have you got a complete copy of boost - I don't see why boost build would want to construct this, as it should already be there?

...

c:\home\deane\git\software\boost\libs\accumulators\doc\Jamfile.v2:18: in modules.load rule doxygen unknown in module

I think this suggests that the using doxygen line didn't work. Although, I'm not sure.

...

Jamfile.

That leading slash is a bit odd. I don't know if it's necessarily a problem though. Sorry I can't help you much with this, as I don't really use windows much. Daniel

Daniel James

6:58 p.m.

2009/5/5 Daniel James :

...

Sorry I can't help you much with this, as I don't really use windows much.

Btw, you might want to get the attention of someone who understands boost build better than I do, either by posting to the boost build list or by starting a new thread with a subject that will get their attention. Daniel

Daniel James

6:46 p.m.

2009/5/3 Deane Yang :

...

I just followed the instructions for Windows. Then I went to boost/doc and ran "bjam". It appears that doxygen is required, no?

If you want to build the complete documentation you need doxygen, latex and ghostscript. But this is only needed for some of the libraries' documentation. This is a bit complicated, but we do supply prebuilt documentation ourselves. If you want to get the documentation for the trunk or release branches of boost you can download 'boost-trunk-docs.7z' or 'boost-docs.7z' (for release) from http://boost.cowic.de/rc, although this is built irregularly so it sometimes gets out of date.

...

Shouldn't installation instructions for doxygen be included in the Windows section? There seem to be such instructions in the MacOS X section.

Possibly, I'm going to eventually write new getting stated and installation documentation. The wiki page I linked to is my starting point for that. Daniel

5684

Age (days ago)

5686

Last active (days ago)

List overview

Download

10 comments

5 participants

participants (5)

Daniel James
Deane Yang
Peng Yu
Peng Yu
tom fogal