[boostbook] First experiments
Hi, I am trying to convert the interval library HTML documentation to the BoostBook format. I will describe my experience with it, as it may help improve BoostBook and its documentation. As I am a user of DocBook, I already have a proper installation of DocBook. So I didn't want to run the automatic setup script. The documentation should stress that, if the user does not modify the user-config.jam file, bjam (or at least the jam files) will crash with hundred of lines of nonsensical warnings. Would it be possible to get some clearer message? Actually, the only important line is "using boostbook", as bjam does not seem to mind if the other lines are missing. Concerning "using boostbook", having to specify the directories is a bit annoying. As a regular user of DocBook, my catalog files for DocBook are already properly configured and BoostBook should not override them with its own version. The documentation should point that BoostBook is not compatible with the recent releases of DocBook (4.3, 4.4, and 4.5), as it redefines the code element and its id and last-revision attributes. Running BoostBook creates a bin/mycompiler-version/debug directory. Perhaps it is an intrinsic defect of bjam. But if it is not, it would be great if BoostBook could avoid using a directory that depends on the compiler currently used. While a bin/.../debug directory has been created, it is not used to store the main Doxygen-generated .xml file. This file is directly stored amongst the documentation files. Moreover, an additional bin/.../debug directory is created there, in order to store all the other temporary Doxygen files. Is it possible to get all the generated files stored in the same place instead of polluting the original documentation repositories? As BoostBook does not seem to be usable without bjam, the documentation should at least contain a sample jam file and explain the parameters of the boostbook and doxygen rules. And if it is usable without bjam, the documentation should explain how. The documentation states that the list of library categories is in the file src/boost.xml. I can't find this list. There are only the examples given by the existing libraries. Does the documentation means that I should find a related library and copy its library category? To conclude this mail, let me say that it took me six hours from the moment I decided to start a BoostBook documentation to the point I had finally generated an empty documentation including Doxygen references. In my opinion, the delay for getting started is a bit too long. Best regards, Guillaume
Hello, I always wanted to use BoostBook and QuickBook but I had never time to proper install them. However, one day I used setup_boostbook.sh and I found it refers to a broken link when downloading fop: the link "http://mirrors.ibiblio.org/pub/mirrors/apache/xml/fop/" doesn't exist. Best regards, Manuel Fiorelli
Guillaume Melquiond wrote:
Concerning "using boostbook", having to specify the directories is a bit annoying. As a regular user of DocBook, my catalog files for DocBook are already properly configured and BoostBook should not override them with its own version.
Can you clarify that? Are you suggesting that you should be able to provide the name of your existing catalog file instead? I'm not sure that's good idea -- most users of BoostBook are not experts in writing catalog files, so having just to specified DTD and XSLT directories is simpler. - Volodya
Le jeudi 07 juin 2007 à 17:02 +0400, Vladimir Prus a écrit :
Concerning "using boostbook", having to specify the directories is a bit annoying. As a regular user of DocBook, my catalog files for DocBook are already properly configured and BoostBook should not override them with its own version.
Can you clarify that? Are you suggesting that you should be able to provide the name of your existing catalog file instead? I'm not sure that's good idea -- most users of BoostBook are not experts in writing catalog files, so having just to specified DTD and XSLT directories is simpler.
You make it sound like both configuration methods would necessarily be exclusive and only one can be used. If it is so, then I agree the current solution is better. Anyway, what I meant was a bit different. My /etc/xml/catalog file is properly configured and xsltproc automatically reads it to get the location of all my catalogs (including DocBook). By defining the XML_CATALOG_FILES environment variable, bjam prevents xsltproc to read its configuration file. As a consequence, xsltproc does not find the DocBook files anymore and tries to download them. So the command "using boostbook ;" without arguments should be careful not to override the local configuration of xsltproc, in my opinion. Best regards, Guillaume
Guillaume Melquiond wrote:
Le jeudi 07 juin 2007 à 17:02 +0400, Vladimir Prus a écrit :
Concerning "using boostbook", having to specify the directories is a bit annoying. As a regular user of DocBook, my catalog files for DocBook are already properly configured and BoostBook should not override them with its own version.
Can you clarify that? Are you suggesting that you should be able to provide the name of your existing catalog file instead? I'm not sure that's good idea -- most users of BoostBook are not experts in writing catalog files, so having just to specified DTD and XSLT directories is simpler.
You make it sound like both configuration methods would necessarily be exclusive and only one can be used. If it is so, then I agree the current solution is better.
Anyway, what I meant was a bit different. My /etc/xml/catalog file is properly configured and xsltproc automatically reads it to get the location of all my catalogs (including DocBook). By defining the XML_CATALOG_FILES environment variable, bjam prevents xsltproc to read its configuration file. As a consequence, xsltproc does not find the DocBook files anymore and tries to download them.
Given that downloading them is pretty much always bad idea, maybe we should just not use XML_CATALOG_FILES at all for using boostbook ; Doug? - Volodya
Guillaume Melquiond wrote:
As I am a user of DocBook, I already have a proper installation of DocBook. So I didn't want to run the automatic setup script.
Neither did I :-) Because I wanted to use all the latest versions of stuff. The unfortunate part is that for Windows I *have* to use the old patched xsltproc.
Concerning "using boostbook", having to specify the directories is a bit annoying.
I just use: using doxygen ; import xsltproc-config ; import boostbook-config ; import quickbook-config ;
The documentation should point that BoostBook is not compatible with the recent releases of DocBook (4.3, 4.4, and 4.5), as it redefines the code element and its id and last-revision attributes.
I still manage to use docbook 4.5. I just ignore the warnings about the overridden code element.
Running BoostBook creates a bin/mycompiler-version/debug directory. Perhaps it is an intrinsic defect of bjam. But if it is not, it would be great if BoostBook could avoid using a directory that depends on the compiler currently used.
Yea. That one's on our TODO list.
While a bin/.../debug directory has been created, it is not used to store the main Doxygen-generated .xml file. This file is directly stored amongst the documentation files. Moreover, an additional bin/.../debug directory is created there, in order to store all the other temporary Doxygen files. Is it possible to get all the generated files stored in the same place instead of polluting the original documentation repositories?
If I understand you correctly, that's what we currently do. So you are likely not using the CVS HEAD version of the code.
As BoostBook does not seem to be usable without bjam, the documentation should at least contain a sample jam file and explain the parameters of the boostbook and doxygen rules. And if it is usable without bjam, the documentation should explain how.
Yea, good point.
The documentation states that the list of library categories is in the file src/boost.xml. I can't find this list.
Hm, I see a boost-root/doc/src/boost.xml.
There are only the examples given by the existing libraries. Does the documentation means that I should find a related library and copy its library category?
It seems like that's what it want :-\
To conclude this mail, let me say that it took me six hours from the moment I decided to start a BoostBook documentation to the point I had finally generated an empty documentation including Doxygen references. In my opinion, the delay for getting started is a bit too long.
Lucky you... First time I tried this on Windows it took me a week ;-) -- -- 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
participants (4)
-
Guillaume Melquiond -
Manuel Fiorelli -
Rene Rivera -
Vladimir Prus