NewBie: help needed generating documentation with quickbook and bjam

older
serialization: pointers to base...

Prof. Dr.-Ing. Wilhelm Meier

3 Dec 2010 3 Dec '10

5:38 p.m.

Hello, this is a absolute newbie question: I try to write some documentation using quickbook. I was able to generate a .xml file. But now I have no idea how to produce a html or pdf version thereof. I read some documentation about bjam and installed the neccessary libraries (I hope). But I didn't find any documentation about how to write a .jam file for this purpose. Can someone help solving this (dumb) question? -- Wilhelm

Show replies by date

Edward Diener

3 Dec 3 Dec

5:52 p.m.

New subject: NewBie: help needed generating documentation with quickbook and bjam

On 12/3/2010 12:38 PM, Prof. Dr.-Ing. Wilhelm Meier wrote:

...

Hello,

this is a absolute newbie question:

I try to write some documentation using quickbook. I was able to generate a .xml file.

But now I have no idea how to produce a html or pdf version thereof. I read some documentation about bjam and installed the neccessary libraries (I hope). But I didn't find any documentation about how to write a .jam file for this purpose.

Can someone help solving this (dumb) question?

If you look at the jamfile in the 'example' library in the Boost sandbox, in ist libs/example/doc directory, it pretty well will show you the basics of all that you need to write a jamfile for generating docs.

Wilhelm

6 Dec 6 Dec

11:28 a.m.

New subject: NewBie: help needed generating documentation with quickbook and bjam

Am 03.12.2010 18:52, schrieb Edward Diener:

...

...
Hello,

this is a absolute newbie question:

I try to write some documentation using quickbook. I was able to generate a .xml file.

But now I have no idea how to produce a html or pdf version thereof. I read some documentation about bjam and installed the neccessary libraries (I hope). But I didn't find any documentation about how to write a .jam file for this purpose.

Can someone help solving this (dumb) question?

If you look at the jamfile in the 'example' library in the Boost sandbox, in ist libs/example/doc directory, it pretty well will show you the basics of all that you need to write a jamfile for generating docs.

Ok, thank you for this advise. I'm now able to generate the documentation. The next question is how to enable non-US language for all generated sections e.g. "Table of Contents". I tried to set the XSL parameter "lang=de" but that seems to have no effect. Any hints?

...

_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

-- Wilhelm

Daniel James

12:13 p.m.

New subject: NewBie: help needed generating documentation with quickbook and bjam

On 6 December 2010 11:28, Wilhelm wrote:

...

Ok, thank you for this advise. I'm now able to generate the documentation.

The next question is how to enable non-US language for all generated sections e.g. "Table of Contents". I tried to set the XSL parameter "lang=de" but that seems to have no effect.

Any hints?

I think you have to set the language in the docbook document itself, adding 'lang=de' to the root element. There's currently no support for the lang attribute in quickbook. If you can wait it's pretty trivial to implement (should just take a day or two, and will be released in a few months). If you can't, you have to write a boostbook/docbook document and use 'xi:include' to include the quickbook documentation. I'll write an example for you later if you wish, or you can look at 'doc/src/boost.xml' which uses a lot of quickbook generated documentation. In boostbook you should currently only use the docbook document types (such as book, chapter etc. not 'boostbook' or 'library') as the 'lang' attribute is lost when converting boostbook document types from to docbook document types. I'll also fix that in the next release. And finally, you'll need to avoid anything that generates text during the boostbook to docbook conversion. I think that's just the reference documentation features, although there might be other parts. I'm afraid I don't know what's involved with implementing localisation in xsl. Hope that helps, Daniel

Wilhelm

12:26 p.m.

New subject: NewBie: help needed generating documentation with quickbook and bjam

Am 06.12.2010 13:13, schrieb Daniel James:

...

On 6 December 2010 11:28, Wilhelm wrote:

...
Ok, thank you for this advise. I'm now able to generate the documentation.

The next question is how to enable non-US language for all generated sections e.g. "Table of Contents". I tried to set the XSL parameter "lang=de" but that seems to have no effect.

Any hints?

I think you have to set the language in the docbook document itself, adding 'lang=de' to the root element. There's currently no support for the lang attribute in quickbook. If you can wait it's pretty trivial to implement (should just take a day or two, and will be released in a few months).

Well, I'm looking around for efficient documentation tools. And I want to decide that in a few weeks... If you can't, you have to write a boostbook/docbook

...

document and use 'xi:include' to include the quickbook documentation. I'll write an example for you later if you wish,

that would be very nice and helpfull or you can look at

...

'doc/src/boost.xml' which uses a lot of quickbook generated documentation.

In boostbook you should currently only use the docbook document types (such as book, chapter etc. not 'boostbook' or 'library') as the 'lang' attribute is lost when converting boostbook document types from to docbook document types. I'll also fix that in the next release.

And finally, you'll need to avoid anything that generates text during the boostbook to docbook conversion. I think that's just the reference documentation features, although there might be other parts. I'm afraid I don't know what's involved with implementing localisation in xsl.

Hope that helps,

Daniel _______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

-- Wilhelm

Daniel James

7 Dec 7 Dec

8:54 p.m.

New subject: NewBie: help needed generating documentation with quickbook and bjam

On 6 December 2010 12:26, Wilhelm wrote:

...

Am 06.12.2010 13:13, schrieb Daniel James:

...
If you can't, you have to write a boostbook/docbook document and use 'xi:include' to include the quickbook documentation. I'll write an example for you later if you wish,

that would be very nice and helpfull

See attached. 'book.xml' is a book in boostbook, it includes a couple of chapters as individual quickbook files. There's a fair amount of boilerplate required in the jamfile. In the next version of boost you'll be able to do all of this in quickbook. Daniel

Wilhelm

12 Dec 12 Dec

11:03 a.m.

New subject: NewBie: help needed generating documentation with quickbook and bjam

Am 07.12.2010 21:54, schrieb Daniel James:

...

On 6 December 2010 12:26, Wilhelm wrote:

...
Am 06.12.2010 13:13, schrieb Daniel James:

...
If you can't, you have to write a boostbook/docbook document and use 'xi:include' to include the quickbook documentation. I'll write an example for you later if you wish,

that would be very nice and helpfull

See attached. 'book.xml' is a book in boostbook, it includes a couple of chapters as individual quickbook files. There's a fair amount of boilerplate required in the jamfile. In the next version of boost you'll be able to do all of this in quickbook.

Thank you. Just another question: is there a simple way to generate slides (html / pdf) with quickbook?

...

Daniel

-- Wilhelm

Daniel James

11:39 a.m.

New subject: NewBie: help needed generating documentation with quickbook and bjam

On 12 December 2010 11:03, Wilhelm wrote:

...

Just another question:

is there a simple way to generate slides (html / pdf) with quickbook?

No, not a simple way. There is some docbook support for slides: http://docbook.sourceforge.net/release/slides/current/doc/ Quickbook would have to be adapted to support the slide document type (which would be pretty easy), then the build system would have to be adapted to support this (might be easy for someone who understands Boost Build better than I do) or you'd need to set up an alternative build system (this could be pretty simple if you have a build system that supports docbook, it could probably skip the boostbook to docbook stage). After that, it'd probably require some tweaking since quickbook is tailored towards documentation generation (could be done with quickbook templates at first). So it's possible, but you'd only want to do it if you're already invested in quickbook. Daniel

John Maddock

11:52 a.m.

...

So it's possible, but you'd only want to do it if you're already invested in quickbook.

Just thinking out loud here... but if each "slide" was a section of a quickbook doc, and you rendered as PDF, one page per section, wouldn't that more or less give you what you want? For sure it would require some experimenting to get the headers and footers correct (or even absent altogether), but it might work OK? John.

Wilhelm

7 Dec 7 Dec

3:18 p.m.

New subject: NewBie: help needed generating documentation with quickbook and bjam

Hello again, Am 06.12.2010 13:13, schrieb Daniel James:

...

On 6 December 2010 11:28, Wilhelm wrote:

...
Ok, thank you for this advise. I'm now able to generate the documentation.

The next question is how to enable non-US language for all generated sections e.g. "Table of Contents". I tried to set the XSL parameter "lang=de" but that seems to have no effect.

Any hints?

I think you have to set the language in the docbook document itself, adding 'lang=de' to the root element. There's currently no support for the lang attribute in quickbook. If you can wait it's pretty trivial to implement (should just take a day or two, and will be released in a few months).

do you have any release schedule, which feature will be included in what future version? Thank you! If you can't, you have to write a boostbook/docbook

...

document and use 'xi:include' to include the quickbook documentation. I'll write an example for you later if you wish, or you can look at 'doc/src/boost.xml' which uses a lot of quickbook generated documentation.

In boostbook you should currently only use the docbook document types (such as book, chapter etc. not 'boostbook' or 'library') as the 'lang' attribute is lost when converting boostbook document types from to docbook document types. I'll also fix that in the next release.

And finally, you'll need to avoid anything that generates text during the boostbook to docbook conversion. I think that's just the reference documentation features, although there might be other parts. I'm afraid I don't know what's involved with implementing localisation in xsl.

Hope that helps,

Daniel _______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

-- Wilhelm

5085

Age (days ago)

5094

Last active (days ago)

List overview

Download

9 comments

5 participants

participants (5)

Daniel James
Edward Diener
John Maddock
Prof. Dr.-Ing. Wilhelm Meier
Wilhelm