[quickbook] Thank you Daniel James

newer
Boost.Pimpl upcoming formal review...

Rene Rivera

4 Jun 2014 4 Jun '14

2:21 p.m.

After being very surprised that I could build Predef documentation without errors by onyl updating to the latest develop version of Quickbook I had to thank Daniel James. Thank Daniel for the continued work on Quickbook. It's made my life much, much, easier! -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Show replies by date

Glen Fernandes

4 Jun 4 Jun

2:23 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

On Wed, Jun 4, 2014 at 7:21 AM, Rene Rivera wrote:

...

Thank Daniel for the continued work on Quickbook.

Seconded. Glen

Peter Dimov

2:51 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

Glen Fernandes wrote:

...

On Wed, Jun 4, 2014 at 7:21 AM, Rene Rivera wrote:

...
Thank Daniel for the continued work on Quickbook.

Seconded.

Is there a tutorial somewhere that explains how, given a .qbk file, one obtains viewable .html in the simplest possible way?

Andrey Semashev

2:59 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

On Wed, Jun 4, 2014 at 6:51 PM, Peter Dimov wrote:

...

Glen Fernandes wrote:

...
On Wed, Jun 4, 2014 at 7:21 AM, Rene Rivera wrote:

...
Thank Daniel for the continued work on Quickbook.

Seconded.

Is there a tutorial somewhere that explains how, given a .qbk file, one obtains viewable .html in the simplest possible way?

I think once you have it installed [1], all you have to do is 'b2 release' in the doc directory. [1] http://www.boost.org/doc/libs/1_55_0/doc/html/quickbook/install.html PS: I think some libraries place the built docs in $BOOST_ROOT/html, others in $LIB_ROOT/doc/html. I'd say we should strive for the second variant, and the libraries that put docs into $BOOST_ROOT/html should be changed at some point.

Peter Dimov

3:12 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

Andrey Semashev wrote:

...

On Wed, Jun 4, 2014 at 6:51 PM, Peter Dimov wrote:

...
Glen Fernandes wrote:

...
On Wed, Jun 4, 2014 at 7:21 AM, Rene Rivera wrote:

...
Thank Daniel for the continued work on Quickbook.

Seconded.

Is there a tutorial somewhere that explains how, given a .qbk file, one obtains viewable .html in the simplest possible way?

I think once you have it installed [1], all you have to do is 'b2 release' in the doc directory.

[1] http://www.boost.org/doc/libs/1_55_0/doc/html/quickbook/install.html

Forgive the stupid question, but why does quickbook generate boostbook xml, which then generates html, instead of quickbook generating html directly? I do know that boostbook can do PDF as well, but in the common case the developer running quickbook doesn't need a PDF.

Andrey Semashev

3:18 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

On Wed, Jun 4, 2014 at 7:12 PM, Peter Dimov wrote:

...

Forgive the stupid question, but why does quickbook generate boostbook xml, which then generates html, instead of quickbook generating html directly?

I do know that boostbook can do PDF as well, but in the common case the developer running quickbook doesn't need a PDF.

I guess PDF is the main reason. It's simpler to output in a single intermediate format and use the existing infrastructure to generate the final product. Daniel knows better though. BTW, I'd also like to thank Daniel for this tool, it really helps.

Rene Rivera

3:19 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

On Wed, Jun 4, 2014 at 10:12 AM, Peter Dimov wrote:

...

Andrey Semashev wrote:

...
On Wed, Jun 4, 2014 at 6:51 PM, Peter Dimov wrote:

...
Glen Fernandes wrote:

...
On Wed, Jun 4, 2014 at 7:21 AM, Rene Rivera wrote:

...
Thank Daniel for the continued work on Quickbook.

Seconded.

Is there a tutorial somewhere that explains how, given a .qbk file, one obtains viewable .html in the simplest possible way?

I think once you have it installed [1], all you have to do is 'b2 release' in the doc directory.

[1] http://www.boost.org/doc/libs/1_55_0/doc/html/quickbook/install.html

Forgive the stupid question, but why does quickbook generate boostbook xml, which then generates html, instead of quickbook generating html directly?

Not a stupid question.. Just a historical one. The precursor to quickbook did generate HTML directly. It was "ported" to generate docbook to have it integrate into the then newish Boost documentation toolchain based on docbook in order to simplify doc writing with a simpler wiki like syntax. I do know that boostbook can do PDF as well, but in the common case the

...

developer running quickbook doesn't need a PDF.

It's been a wish of mine, with some work done long ago towards it, to bring back some form of direct HTML generation. In particular to make quickbook backend generation programmable. -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

John Maddock

3:48 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

...

It's been a wish of mine, with some work done long ago towards it, to bring back some form of direct HTML generation. In particular to make quickbook backend generation programmable.

It's worth pointing out that it would be *very* hard to simulate the flexibility of the Docbook->HTML or Docbook->FO->PDF generators. There are still many things you can do in Docbook that can't be done in quickbook, and yes, I use quickbook's "escape to docbook" feature quite a bit. So for me at least it's worth going through the intermediate format(s) even though I'd be the first to admit that the XSLT processors are very slow, and don't scale to big docs well. John.

Daniel James

3:51 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

On 4 June 2014 16:19, Rene Rivera wrote:

...

On Wed, Jun 4, 2014 at 10:12 AM, Peter Dimov wrote:

...
Andrey Semashev wrote:

...
On Wed, Jun 4, 2014 at 6:51 PM, Peter Dimov wrote:

...
Glen Fernandes wrote:

...
On Wed, Jun 4, 2014 at 7:21 AM, Rene Rivera wrote:

...
Thank Daniel for the continued work on Quickbook.

Seconded.

You're welcome.

...

...
...
...
Is there a tutorial somewhere that explains how, given a .qbk file, one obtains viewable .html in the simplest possible way?

A while ago, I started writing some user documentation for the documentation toolchain, although I stopped work on it for the git transition. Progress so far is at: http://boostorg.github.io/quickbook/doc/html/boost_doc_tools.html

...

...
Forgive the stupid question, but why does quickbook generate boostbook xml, which then generates html, instead of quickbook generating html directly?

Not a stupid question.. Just a historical one. The precursor to quickbook did generate HTML directly. It was "ported" to generate docbook to have it integrate into the then newish Boost documentation toolchain based on docbook in order to simplify doc writing with a simpler wiki like syntax.

Yes, boostbook markup is hard-coded into a lot of places. I had a crude html generator in the abandoned spirit 2 branch, I think it's the only feature I didn't backport. It could do a passable job of simple markup, but for complicated documents it wasn't much use. Especially for documents which use doxygen, as that is used to generate boostbook. I felt it was more useful to concentrate on improving the language.

John Maddock

4:26 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

...

...
...
...
...
Is there a tutorial somewhere that explains how, given a .qbk file, one obtains viewable .html in the simplest possible way?

A while ago, I started writing some user documentation for the documentation toolchain, although I stopped work on it for the git transition. Progress so far is at:

http://boostorg.github.io/quickbook/doc/html/boost_doc_tools.html

See also https://svn.boost.org/trac/boost/wiki/BoostDocs/GettingStarted which details how to get the toolchain up and running on various platforms. John.

Eric Niebler

9:18 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

On 06/04/2014 08:51 AM, Daniel James wrote:

...

...
...
Forgive the stupid question, but why does quickbook generate boostbook

...
...
xml, which then generates html, instead of quickbook generating html directly?

Not a stupid question.. Just a historical one. The precursor to quickbook did generate HTML directly. It was "ported" to generate docbook to have it integrate into the then newish Boost documentation toolchain based on docbook in order to simplify doc writing with a simpler wiki like syntax. Yes, boostbook markup is hard-coded into a lot of places.

I had a crude html generator in the abandoned spirit 2 branch, I think it's the only feature I didn't backport. It could do a passable job of simple markup, but for complicated documents it wasn't much use. Especially for documents which use doxygen, as that is used to generate boostbook. I felt it was more useful to concentrate on improving the language.

I was the one who took Joel de Guzman's QuickDoc tool, which generated HTML, re-purposed it to generate BoostBook XML, and rechristened it QuickBook. It has been terrifically useful, and other have run with it. As others have pointed out, the Docbook toolchain is powerful. Escaping to BoostBook/Docbook XML is a great way to Get Things Done when QuickBook doesn't offer a pithy syntax. And as Daniel points out, Doxygen generates XML which can be integrated with the XML spit out by QuickBook, allowing you to easily link from your user docs to your reference and (with some difficulty), the reverse. It's ugly and round-about, and it cries out for a better solution, but it's the best we've got, and it gets the job done. Eric

Peter Dimov

5 Jun 5 Jun

3:10 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

Eric Niebler wrote:

...

I was the one who took Joel de Guzman's QuickDoc tool, which generated HTML, re-purposed it to generate BoostBook XML, and rechristened it QuickBook. It has been terrifically useful, and other have run with it. As others have pointed out, the Docbook toolchain is powerful. Escaping to BoostBook/Docbook XML is a great way to Get Things Done when QuickBook doesn't offer a pithy syntax. And as Daniel points out, Doxygen generates XML which can be integrated with the XML spit out by QuickBook, allowing you to easily link from your user docs to your reference and (with some difficulty), the reverse.

Thanks for the explanations. I've actually did get that running, and it's not remotely as difficult as it first appears. The main problem is a psychological one - download this from site A, that from site B, that other thing from site C, but be careful to not download something else from there. The installation procedure could probably be improved considerably by just putting docbook-xml and docbook-xslt into our repository. I'm not sure how things would stand license-wise though.

Paul A. Bristow

4:22 p.m.

New subject: [Boost-docs] [quickbook] Thank you Daniel James

...

-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Peter Dimov Sent: 05 June 2014 16:10 To: boost@lists.boost.org Subject: Re: [boost] [Boost-docs] [quickbook] Thank you Daniel James

Eric Niebler wrote:

...
I was the one who took Joel de Guzman's QuickDoc tool, which generated HTML, re-purposed it to generate BoostBook XML, and rechristened it QuickBook. It has been terrifically useful, and other have run with it. As others have pointed out, the Docbook toolchain is powerful. Escaping to BoostBook/Docbook XML is a great way to Get Things Done when QuickBook doesn't offer a pithy syntax. And as Daniel points out, Doxygen generates XML which can be integrated with the XML spit out by QuickBook, allowing you to easily link from your user docs to your reference and (with some difficulty), the reverse.

Thanks for the explanations. I've actually did get that running, and it's not remotely as difficult as it first appears. The main problem is a psychological one - download this from site A, that from site B, that other thing from site C, but be careful to not download something else from there.

The installation procedure could probably be improved considerably by just

putting

...

docbook-xml and docbook-xslt into our repository. I'm not sure how things would stand license-wise though.

This would certainly lower the barrier to getting started with Quickbook toolchain. It would also ensure that we are also all using the same version - some newer versions seemed not work as I recall. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 01539 561830

3830

Age (days ago)

3831

Last active (days ago)

List overview

Download

12 comments

8 participants

participants (8)

Andrey Semashev
Daniel James
Eric Niebler
Glen Fernandes
John Maddock
Paul A. Bristow
Peter Dimov
Rene Rivera