[quickbook] Thank you Daniel James
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
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?
On Wed, Jun 4, 2014 at 6:51 PM, Peter Dimov <lists@pdimov.com> 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.
Andrey Semashev wrote:
On Wed, Jun 4, 2014 at 6:51 PM, Peter Dimov <lists@pdimov.com> 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.
On Wed, Jun 4, 2014 at 7:12 PM, Peter Dimov <lists@pdimov.com> 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.
On Wed, Jun 4, 2014 at 10:12 AM, Peter Dimov <lists@pdimov.com> wrote:
Andrey Semashev wrote:
On Wed, Jun 4, 2014 at 6:51 PM, Peter Dimov <lists@pdimov.com> 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
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.
On 4 June 2014 16:19, Rene Rivera <grafikrobot@gmail.com> wrote:
On Wed, Jun 4, 2014 at 10:12 AM, Peter Dimov <lists@pdimov.com> wrote:
Andrey Semashev wrote:
On Wed, Jun 4, 2014 at 6:51 PM, Peter Dimov <lists@pdimov.com> 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.
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.
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
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.
-----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
participants (8)
-
Andrey Semashev -
Daniel James -
Eric Niebler -
Glen Fernandes -
John Maddock -
Paul A. Bristow -
Peter Dimov -
Rene Rivera