Re: [boost] Boost documentation
Cédric Venet wrote:
De : Guillaume Melquiond
Le dimanche 24 juin 2007 à 11:04 +0200, Cédric Venet a écrit :
The fact is if one day, quick book is broken and not supported anymore, you just have to use the last correct version to convert your quickbook doc into docbook and work on the doc book. As far as I understand it, a short term goal of the quickbook developers is actually to get rid of the conversion to boostbook/docbook. So it won't be as easy as you make it sound to get back to a docbook version.
Yes, I remember something like this.
No, "get rid" is too strong a term. The real goal is to provide alternative back ends (e.g. direct HTML, LaTEX, DocUtils, etc., in addition to DocBook). This can be achieved through a set of back end template libraries. And, no, I don't think it is a short term goal. The short term goal is to simplify quickbook a lot more than it is now (a targeted 90% reduction in c++ code size) by moving to template libraries. We'll end up with a standard template library with 90% of the functionality of quickbook plus a set of intrinsics in c++ code. *** We're actually striving to make quickbook simpler, not more complex *** Why? some people, do not like the elaborate tool chain that Doc/BoostBook requires. Some parts of the tool chain, e.g. FOP, is severely broken, XSLT is so slow and difficult to understand and maintain, etc. DocBook is not perfect, you know. It too has its own sets of problems.
Please correct me if docbook is still intended to be a mandatory intermediate stage between quickbook and html/pdf documentations.
I can't speak for quickbook developers, but it could be useful to have a backend in boostbook or docbook, even if it is not anymore used as an intermediate stage. This involve some development cost, but à priori not too much. It could be useful if someone want to use a custom xslt for his doc (in case of use outside boost, since they try to make a common L&F for boost) or for the sake of having a standardized xml backend.
After it depend on the scope of use they want to give to quickbook.
A boost/docbook backend will still be supported, for sure. Backward compatibility is a paramount concern. Most (all?) quickbook documents, except the most simple ones rely on DocBook. As soon as you start "escaping" to DocBook, you become dependent of it. AFAICT, there is no way to break free of that dependency without sacrificing backward compatibility. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
Why? some people, do not like the elaborate tool chain that Doc/BoostBook requires. Some parts of the tool chain, e.g. FOP, is severely broken, XSLT is so slow and difficult to understand and maintain, etc. DocBook is not perfect, you know. It too has its own sets of problems.
I would be one of those people. So blame be if you must. And if it wasn't clear before... I hate XSTL. IMO it is one of the worse programming languages ever invented. But this is probably off-topic ;-)
A boost/docbook backend will still be supported, for sure.
Indeed. I am, personally since i"m the oen doing the changes to Quickbook for plugable backends, to make Quickbook more flexible in this respect. First, to make the maintenance of the XML generation much simpler and easier. Second, to guard against future document format changes. After all someone might decide DocBook is silly and switch to something else, at which point I'd rather rewrite the quickbook generator than all my documentation. And last, for my won personal interest in using Quickbook to generate web pages, RSS feeds, etc. on the fly. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo
On Sun, Jun 24, 2007 at 08:24:42PM +0800, Joel de Guzman wrote:
No, "get rid" is too strong a term. The real goal is to provide alternative back ends (e.g. direct HTML, LaTEX, DocUtils, etc., in addition to DocBook). This can be achieved through a set of back end template libraries. And, no, I don't think it is a short term goal.
If I understand correctly, pandoc, http://sophos.berkeley.edu/macfarlane/pandoc/ works like this. It works well. I did my best to switch to pandoc but I found markdown to be too limited, especially the lack of code syntax highlighting. So a pandocish tool in C++, that reads Quickbook and writes HTML/latex/whatever, and where one can just add back-ends for new formats/tools... very cool.
The short term goal is to simplify quickbook a lot more than it is now (a targeted 90% reduction in c++ code size) by moving to template libraries. We'll end up with a standard template library with 90% of the functionality of quickbook plus a set of intrinsics in c++ code. *** We're actually striving to make quickbook simpler, not more complex ***
Why? some people, do not like the elaborate tool chain that Doc/BoostBook requires. Some parts of the tool chain, e.g. FOP, is severely broken, XSLT is so slow and difficult to understand and maintain, etc. DocBook is not perfect, you know. It too has its own sets of problems.
I'm one of those people. I wrote a lot of docs in quickbook at one point and lost a couple of days to trying to get FOP to make PDFs. I'd hacked quickbook a little (which itself was fun and educational), but it was nearly impossible to tell where the errors were occurring (xsltproc, the stylesheets, apache-fop... egh.) It was also frustrating that nothing that came of the process was contributable back to boost, just a bunch of shell scripts that didn't do anything generally useful. -t
participants (3)
-
Joel de Guzman -
Rene Rivera -
troy d straszheim