Help request, boost docs
Hi! I few of us have been working to improve boost docs. If you are interested please join us in the boost-docs list. There are some very exiting new features. We need to have every piece of doc in boostbook format in order to use a general look and feel. The best thing will be to have all docs in Quickbook. We need help to translate html based boost docs to boostbook, or even better, to quickbook. I have already translated to quickbook Boost.Optional (4 hours), Boost.NumericConversion (5 hours) and Boost.Config (3 hours). The process is very easy once you get some practice A html to quickbook converter will be fantastic but no one seems to be interested enough in developing it. Even an incomplete translator may help us with the manual translation process. In the mean time, if someone wants to investigate a html to boostbook converter it can look for a docbook converter like this one: http://www.eecs.umich.edu/~ppadala/projects/tidy If you can help us, please jump in. Thanks! King regards Matias
On Tue, 2007-06-19 at 23:36 -0300, Matias Capeletto wrote:
I few of us have been working to improve boost docs. If you are interested please join us in the boost-docs list. There are some very exiting new features.
I've been looking at some of the improvements, and they are very nice.
We need to have every piece of doc in boostbook format in order to use a general look and feel. The best thing will be to have all docs in Quickbook.
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options. Thanks for your work on this! - Doug
On 6/20/07, Douglas Gregor <doug.gregor@gmail.com> wrote:
On Tue, 2007-06-19 at 23:36 -0300, Matias Capeletto wrote:
We need to have every piece of doc in boostbook format in order to use a general look and feel. The best thing will be to have all docs in Quickbook.
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
110% agree :) Stjepan Rajko has jumped in and is now looking for stuff to translate. If we can assemble a small group of three or four volunteers we can tackle the html to quickbook migration in no time.
Thanks for your work on this!
A pleasure, Thanks to John, Rene, Paul, Daniel, Marcin, Stjepan and Peter too. Best regards Matias
Matias, I can devote some this weekend to doing some translations too. Regards, Glyn On 20/06/07, Matias Capeletto <matias.capeletto@gmail.com> wrote:
On 6/20/07, Douglas Gregor <doug.gregor@gmail.com> wrote:
On Tue, 2007-06-19 at 23:36 -0300, Matias Capeletto wrote:
We need to have every piece of doc in boostbook format in order to use a general look and feel. The best thing will be to have all docs in Quickbook.
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
110% agree :)
Stjepan Rajko has jumped in and is now looking for stuff to translate. If we can assemble a small group of three or four volunteers we can tackle the html to quickbook migration in no time.
Thanks for your work on this!
A pleasure, Thanks to John, Rene, Paul, Daniel, Marcin, Stjepan and Peter too. Best regards Matias _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
Has there been any thought to adding to the Boostbook the facility for automatically generating a navigation window similar to what the serialization documentation uses. I believe this could be generated automatically by Boostbook. We already have javascript which has been vetted on all used browsers to implement this. The serialization library really depends upon this for navigating around the documentation. Robert Ramey Douglas Gregor wrote:
On Tue, 2007-06-19 at 23:36 -0300, Matias Capeletto wrote:
I few of us have been working to improve boost docs. If you are interested please join us in the boost-docs list. There are some very exiting new features.
I've been looking at some of the improvements, and they are very nice.
We need to have every piece of doc in boostbook format in order to use a general look and feel. The best thing will be to have all docs in Quickbook.
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
Thanks for your work on this!
- Doug
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 6/20/07, Robert Ramey <ramey@rrsd.com> wrote:
Has there been any thought to adding to the Boostbook the facility for automatically generating a navigation window similar to what the serialization documentation uses. I believe this could be generated automatically by Boostbook. We already have javascript which has been vetted on all used browsers to implement this. The serialization library really depends upon this for navigating around the documentation.
Hi Rovert, I have give it more than one thought to it. Iostream navigation style use frames. Frames are not part of XHTML because they cause lot of troubles. We have implemented a new navigation approach based on GropedLinks () select boxes. Look at the top-right corner of the page: http://tinyurl.com/22sja5 GroupedLinks is documented here: http://tinyurl.com/332tsh IMHO this select boxes offers a great deal of functionality and do not get in your way. We are working in an automated algorithm to make the GroupedLinks definition files. Do you think your docs will work fine with GroupedLinks instead of frames? Best regards Matias
Matias Capeletto wrote:
On 6/20/07, Robert Ramey <ramey@rrsd.com> wrote:
Has there been any thought to adding to the Boostbook the facility for automatically generating a navigation window similar to what the serialization documentation uses. I believe this could be generated automatically by Boostbook. We already have javascript which has been vetted on all used browsers to implement this. The serialization library really depends upon this for navigating around the documentation.
Hi Rovert,
I have give it more than one thought to it. Iostream navigation style use frames. Frames are not part of XHTML because they cause lot of troubles. We have implemented a new navigation approach based on GropedLinks () select boxes. Look at the top-right corner of the page: http://tinyurl.com/22sja5
I didn't see anything at the top-right hand corner of the page. But I - assuming that the table of contents is automatically generated from the *.qbk documents - it seems to me that the table of contents page is almost what I want. All you have to do is: a) put it in a separate pane so it can be used to navigate around the documentation. b) add in the code - already written by J. Turkanis and tested by several of us on different browsers. I really like the expand/contract feature that the javascriptcontrol provides- though if I had to I could probably live without it. I would think that it would be an optional "add-on" that not everyone else has to use. Robert Ramey
GroupedLinks is documented here: http://tinyurl.com/332tsh
IMHO this select boxes offers a great deal of functionality and do not get in your way.
We are working in an automated algorithm to make the GroupedLinks definition files. Do you think your docs will work fine with GroupedLinks instead of frames?
Best regards Matias _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 6/20/07, Robert Ramey <ramey@rrsd.com> wrote:
Matias Capeletto wrote:
On 6/20/07, Robert Ramey <ramey@rrsd.com> wrote:
Has there been any thought to adding to the Boostbook the facility for automatically generating a navigation window similar to what the serialization documentation uses. I believe this could be generated automatically by Boostbook. We already have javascript which has been vetted on all used browsers to implement this. The serialization library really depends upon this for navigating around the documentation.
Hi Rovert,
I have give it more than one thought to it. Iostream navigation style use frames. Frames are not part of XHTML because they cause lot of troubles. We have implemented a new navigation approach based on GropedLinks () select boxes. Look at the top-right corner of the page: http://tinyurl.com/22sja5
I didn't see anything at the top-right hand corner of the page.
Browser?
But I - assuming that the table of contents is automatically generated from the *.qbk documents - it seems to me that the table of contents page is almost what I want. All you have to do is:
a) put it in a separate pane so it can be used to navigate around the documentation. b) add in the code - already written by J. Turkanis and tested by several of us on different browsers.
IMHO working with frames is not the right direction. We can investigate iframes, a module of XHTML 1.1 but for now is it out of the scope of the proposal.
I really like the expand/contract feature that the javascriptcontrol provides- though if I had to I could probably live without it. I would think that it would be an optional "add-on" that not everyone else has to use.
Can you get Firefox, Opera or IE7 to see the GroupedLinks select boxes and see if that is enough for now. Best regards Matias
Matias Capeletto wrote:
On 6/20/07, Robert Ramey <ramey@rrsd.com> wrote:
Matias Capeletto wrote:
On 6/20/07, Robert Ramey <ramey@rrsd.com> wrote:
Has there been any thought to adding to the Boostbook the facility for automatically generating a navigation window similar to what the serialization documentation uses. I believe this could be generated automatically by Boostbook. We already have javascript which has been vetted on all used browsers to implement this. The serialization library really depends upon this for navigating around the documentation.
Hi Rovert,
I have give it more than one thought to it. Iostream navigation style use frames. Frames are not part of XHTML because they cause lot of troubles. We have implemented a new navigation approach based on GropedLinks () select boxes. Look at the top-right corner of the page: http://tinyurl.com/22sja5
I didn't see anything at the top-right hand corner of the page.
Browser?
sorry, all I'm seeing is a nice green rectangle above the words "Search Boost" and a right pointer arrow that displays the word "Next" when the pointer is placed over it.
But I - assuming that the table of contents is automatically generated from the *.qbk documents - it seems to me that the table of contents page is almost what I want. All you have to do is:
a) put it in a separate pane so it can be used to navigate around the documentation. b) add in the code - already written by J. Turkanis and tested by several of us on different browsers.
IMHO working with frames is not the right direction. We can investigate iframes, a module of XHTML 1.1 but for now is it out of the scope of the proposal.
Well, I certainly don't want to be guilty of promoting scope creep. Though I would menention that frames have been a part of standard html forever and documentation for many boost libraries have them for just this purpose. The usage of javascript is a little more problematic in that it depends on the particular case. In the case of J.Turkanis navigator control this was discussed at some length and the final consensus seemed to be that this was an acceptable and useful tool.
I really like the expand/contract feature that the javascriptcontrol provides- though if I had to I could probably live without it. I would think that it would be an optional "add-on" that not everyone else has to use.
Can you get Firefox, Opera or IE7 to see the GroupedLinks select boxes and see if that is enough for now.
I think I'm running IE7. At least it seems so as it crashes from time to time. Robert Ramey
Best regards Matias _______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
I have give it more than one thought to it. Iostream navigation style use frames. Frames are not part of XHTML because they cause lot of troubles. We have implemented a new navigation approach based on GropedLinks () select boxes. Look at the top-right corner of the page: http://tinyurl.com/22sja5
I didn't see anything at the top-right hand corner of the page.
Browser?
sorry, all I'm seeing is a nice green rectangle above the words "Search Boost" and a right pointer arrow that displays the word "Next" when the pointer is placed over it.
Weird, it has been tested in IE7 several times in different machines.
IMHO working with frames is not the right direction. We can investigate iframes, a module of XHTML 1.1 but for now is it out of the scope of the proposal.
Well, I certainly don't want to be guilty of promoting scope creep. Though I would menention that frames have been a part of standard html forever and documentation for many boost libraries have them for just this purpose.
The standard is moving towards an unframed web.
The usage of javascript is a little more problematic in that it depends on the particular case. In the case of J.Turkanis navigator control this was discussed at some length and the final consensus seemed to be that this was an acceptable and useful tool.
If we use only W3C allowed js, and if we make sure that it degrades gracefully when used in an old browser IMHO we should include js in our docs. Look at our design, the places where js has been used are very discrete. We do not want flashy things flying around, really. We only add dynamic support for useful and discrete tools that do not interfere with the user. Best regards Matias
I didn't see anything at the top-right hand corner of the page.
Browser?
sorry, all I'm seeing is a nice green rectangle above the words "Search Boost" and a right pointer arrow that displays the word "Next" when the pointer is placed over it.
Weird, it has been tested in IE7 several times in different machines.
I also have IE7 (7.0.5730.11) under WinXP SP2 and I see the same things (like the screen shot of IE5) (firefox ok)
Move the mouse to the upper-right corner of a code block and you will see what I am talking about :)
and I didn't see anythings in the corner of the code either... even with firefox.
IMHO working with frames is not the right direction. We can investigate iframes, a module of XHTML 1.1 but for now is it out of the scope of the proposal.
Well, I certainly don't want to be guilty of promoting scope creep. Though I would menention that frames have been a part of standard html forever and documentation for many boost libraries have them for just this purpose.
The standard is moving towards an unframed web.
I think the grouped link is good (if it worked on IE). But if you prefer another menu, there is no frame based alternative: At the cost of reproducing the menu in each page (the generation is automatic, but the download is a little longer), there is many possibilities: - use a div with fixed or static positioning - use a css based unroling menu (pure css) (http://www.alistapart.com/articles/horizdropdowns/ http://www.alistapart.com/d/horizdropdowns/horizontal2.htm http://www.alistapart.com/articles/dropdowns/#resettop http://www.htmldog.com/articles/suckerfish/example/ ) - hybrid menu http://www.alistapart.com/articles/hybrid/ http://www.alistapart.com/d/hybrid/hybrid-4.html http://search.atomz.com/search/?sp-q=menu&sp-a=sp1002d27b&sp-f=ISO-8859-1&sp -p=All&sp-k=All
The usage of javascript is a little more problematic in that it depends on the particular case. In the case of J.Turkanis navigator control this was discussed at some length and the final consensus seemed to be that this was an acceptable and useful tool.
If we use only W3C allowed js, and if we make sure that it degrades gracefully when used in an old browser IMHO we should include js in our docs. Look at our design, the places where js has been used are very discrete. We do not want flashy things flying around, really. We only add dynamic support for useful and discrete tools that do not interfere with the user.
As long as the navigator (with default options) don't ask you if you want to enable js each time you goo to the page, I think it is really useful. -- Cédric Venet
Robert Ramey said: (by the date of Wed, 20 Jun 2007 11:58:25 -0700)
IMHO working with frames is not the right direction. We can investigate iframes, a module of XHTML 1.1 but for now is it out of the scope of the proposal.
Well, I certainly don't want to be guilty of promoting scope creep. Though I would menention that frames have been a part of standard html forever and documentation for many boost libraries have them for just this purpose.
The usage of javascript is a little more problematic in that it depends on the particular case. In the case of J.Turkanis navigator control this was discussed at some length and the final consensus seemed to be that this was an acceptable and useful tool.
It is possible to have a folding tree menu *without* frames. You can just make a <div style="width:20%;"> (I'm typing off my head without checking). Or at a last resort it could be a table. I'm sure this can work without frames - on all browsers. You could just make a left pane (a div or a table) and put there a tree menu with folding. It will be really useful to ease the browsing. I just made some google search, and unfortunately a tree menu with folding is not possible in CSS. In CSS you can only make a menu that expands when hovered by mouse. And does not remeber what was expanded when browsing webpages. So everytime you want to find something you need to start looking for it from the very begginning - hover over all the menu positions again, and again from start. The same problem is with your drop down menu on the top-right - you always need to click the drop down menu and look (again and again) alphabetically from start. On the other hand, a tree menu that remembers what was unfolded and folded helps in quick finding what you need, because you don't need to unfold again, and again, always from beginning. It's not to criticize, just some my observations about usability of webpages. I think that you could make a hacky version just to see how it works by taking javascript from Robort and putting it in the right pane of width about 20%. I repeat: 1. to my knowledge folding tree menu can't be done with CSS only. 2. folding tree menu has big usability advantage above options offered by plain CSS. moreover: 3. when javascript is not available: - by default the tree menu stays all unfolded - but also you can detect this, and simply don't show the left pane with that menu. Sorry, it got a bit lenghty. -- Janek Kozicki |
Janek Kozicki wrote: I think this could be handled in a simple way - in fact this is how I'm going to do it if I have no other choice. get boost serialization converted to quickbook in whatever way that whoever does it wants to do it. From what I've seen, there will be a one to one correspondence between the current html pages and the quickbook generated pages. I also presume the original tags/ and sections will still exist although perhaps with different names. Given this I can a) by hook or by crook make a small page with the tree navigation using J. Turkanis control. If this can't be done automatically I'll just do it by hand. b) In the file ../libs/index.html I'll include a page with two frames. The left with the navigator and the right with the generated pages. c) Then I'll be done without giving up what I have now. Of course this means that the "navigator" is optional - as it is now. It only comes up of you go in through the top. So I'm all in favor converting Boost serialization documention to quickbooks. Robert Ramey
Robert Ramey wrote: Of course this means that the "navigator" is optional - as it is now. It only comes up of you go in through the top. So I'm all in favor converting Boost serialization documention to quickbooks.
Yeah! That is the spirit... Thanks Robert Best regards Matias PS: There is a high possibility that I will implement a sidebar menu like the one you have. I keep you informed.
Matias Capeletto said: (by the date of Wed, 20 Jun 2007 15:48:17 -0300)
We have implemented a new navigation approach based on GropedLinks () select boxes. Look at the top-right corner of the page: http://tinyurl.com/22sja5
I didn't see anything at the top-right hand corner of the page.
Browser?
heh, I digged up my old windows 2000 buried inside vmware for long time with IE5 installed there. This cute menu doesn't work there :) Here's the screenshot: http://tinyurl.com/2ynd9q (the other window below to right with boost website working is firefox) It's up to you if you want to support IE5 ;-) I just saw that wikipedia is "working", at least to enough extend that it's usable and browseable. -- Janek Kozicki |
On 6/20/07, Janek Kozicki <janek_listy@wp.pl> wrote:
Matias Capeletto said: (by the date of Wed, 20 Jun 2007 15:48:17 -0300)
We have implemented a new navigation approach based on GropedLinks () select boxes. Look at the top-right corner of the page: http://tinyurl.com/22sja5
I didn't see anything at the top-right hand corner of the page.
Browser?
heh, I digged up my old windows 2000 buried inside vmware for long time with IE5 installed there. This cute menu doesn't work there :)
ie5!!??
(the other window below to right with boost website working is firefox)
yep, firefox rules...
It's up to you if you want to support IE5 ;-) I just saw that wikipedia is "working", at least to enough extend that it's usable and browseable.
If someone want to help us to support ie5 and ie6 it will be great. The idea is that if you use an old browser, you will not see the new cool stuff but it will degrade gracefully showing you the best we can do with it. Best regards Matias PS: Please note that *all* this stuff is only two weeks old. Please help us testing it.
[mailto:boost-bounces@lists.boost.org] On Behalf Of Matias Capeletto On 6/20/07, Janek Kozicki <janek_listy@wp.pl> wrote:
Matias Capeletto said: (by the date of Wed, 20 Jun 2007 15:48:17 -0300)
We have implemented a new navigation approach based on GropedLinks () select boxes. Look at the top-right corner of the page: http://tinyurl.com/22sja5
I didn't see anything at the top-right hand corner of the page.
Browser?
heh, I digged up my old windows 2000 buried inside vmware for long time with IE5 installed there. This cute menu doesn't work there :)
ie5!!??
(the other window below to right with boost website working is firefox)
yep, firefox rules...
It's up to you if you want to support IE5 ;-) I just saw that wikipedia is "working", at least to enough extend that it's usable and browseable.
If someone want to help us to support ie5 and ie6 it will be great. The idea is that if you use an old browser, you will not see the new cool stuff but it will degrade gracefully showing you the best we can do with it.
Best regards Matias
PS: Please note that *all* this stuff is only two weeks old. Please help us testing it.
Ahhh, I think this explains a lot of what I (wasn't) seeing. I'm using IE6/win2K, If I go to a computer that bypasses our internal network and run firefox I can see all the cool things you're talking about. Nice! Now to get it working on IE6 inside a firewall... Regards, Matt Scanned by McAfee GroupShield {X3BTB534}
On Wed, 2007-06-20 at 10:38 -0700, Robert Ramey wrote:
I really like the expand/contract feature that the javascriptcontrol provides- though if I had to I could probably live without it. I would think that it would be an optional "add-on" that not everyone else has to use.
One of the great things about what Matias et al are doing is that it will give all of Boost's library documentation a consistent look and feel. That's really important for making Boost feel like a coherent collection of libraries and helping users navigate the documentation of new libraries. I'm not for or against the navigation control, but I would be very much against having it available in some libraries but not others. The whole point of BoostBook was to do what they're doing now... get all Boost docs into one format with a nice, consistent L&F, then add searching, indexing, etc. to make it more coherent. - Doug
Douglas Gregor wrote:
On Wed, 2007-06-20 at 10:38 -0700, Robert Ramey wrote:
I really like the expand/contract feature that the javascriptcontrol provides- though if I had to I could probably live without it. I would think that it would be an optional "add-on" that not everyone else has to use.
One of the great things about what Matias et al are doing is that it will give all of Boost's library documentation a consistent look and feel.
That's really important for making Boost feel like a coherent collection of libraries and helping users navigate the documentation of new libraries.
I'm not for or against the navigation control, but I would be very much against having it available in some libraries but not others. The whole point of BoostBook was to do what they're doing now... get all Boost docs into one format with a nice, consistent L&F, then add searching, indexing, etc. to make it more coherent.
A... so either something like BOOST_STATIC_ASSERT should have its own navigator even though its one page or Boost Serialization shouldn't have one even though its maybe 100 pages long? How can that make any sense? I think the idea that boost can so consistent/coherent/uniform (or whatever term one wants to use) accross all its libraries (spanning 8 years so far) is unrealistic, and in general not a good idea. Variation in depth, scope, size, application area, etc is just too broad to think this is really doable, and attempts to make them look more alike than they are involve a lot of effort which could be better spent elsewhere. That making things more consistent can be a good idea - but its not an end in itself and can be taken too far. Robert Ramey
I headed over to the serialization library docs on the website to see the frames and something stuck out. The first sentence of the Release Notes says: "This is the Boost 1.33 Serialization Library." shouldn't that be 1.34? - Michael Marcin
On Wed, 2007-06-20 at 15:12 -0700, Robert Ramey wrote:
A... so either something like BOOST_STATIC_ASSERT should have its own navigator even though its one page or Boost Serialization shouldn't have one even though its maybe 100 pages long? How can that make any sense?
I'd rather see little utilities like BOOST_STATIC_ASSERT folded into the "utility" library. As we get more an more large libraries like Serialization, it seems almost silly to have small things like BOOST_STATIC_ASSERT be their own "library".
I think the idea that boost can so consistent/coherent/uniform (or whatever term one wants to use) accross all its libraries (spanning 8 years so far) is unrealistic, and in general not a good idea. Variation in depth, scope, size, application area, etc is just too broad to think this is really doable, and attempts to make them look more alike than they are involve a lot of effort which could be better spent elsewhere. That making things more consistent can be a good idea - but its not an end in itself and can be taken too far.
Given that we've never seen anything like consistency in the Boost documentation, I guess I'd like to see it first before we say that this principle (which is often a very good principle) is rejected. Here's what I'm saying, concretely: convert everything to Quickbook/Boostbook and see how things work. Make that expanding/collapsing tree control work for *all* Quickbook/Boostbook documentation. Then, if we like it, we can decide when it's silly (say, based on the depth/size of the table of contents) and use it when it isn't silly. - Doug
Douglas Gregor said: (by the date of Wed, 20 Jun 2007 18:30:24 -0400)
Here's what I'm saying, concretely: convert everything to Quickbook/Boostbook and see how things work. Make that expanding/collapsing tree control work for *all* Quickbook/Boostbook documentation. Then, if we like it, we can decide when it's silly (say, based on the depth/size of the table of contents) and use it when it isn't silly.
yay! The best possible decision to make :) -- Janek Kozicki |
Douglas Gregor wrote:
On Tue, 2007-06-19 at 23:36 -0300, Matias Capeletto wrote:
I few of us have been working to improve boost docs. If you are interested please join us in the boost-docs list. There are some very exiting new features.
I've been looking at some of the improvements, and they are very nice.
We need to have every piece of doc in boostbook format in order to use a general look and feel. The best thing will be to have all docs in Quickbook.
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
What options? Since you've authored Boostbook you must know better, but I still don't see the value in using home-grown documentation format. - Volodya
On Wed, 2007-06-20 at 19:59 +0400, Vladimir Prus wrote:
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
What options? Since you've authored Boostbook you must know better, but I still don't see the value in using home-grown documentation format.
The option to eliminate BoostBook entirely, so that one can translate directly from Quickbook to Docbook. I'm making the assumption that it's better to have something home-grown but simple (Quickbook) rather than something loosely standards-based (extends DocBook) that is hard to use. I may have built BoostBook, but I write everything with Quickbook +Doxygen nowadays. Those two work very well together as the user-level interface to the documentation toolchain; BoostBook and its XSL is really just an inconvenient intermediate format right now. - Doug
Douglas Gregor wrote:
On Wed, 2007-06-20 at 19:59 +0400, Vladimir Prus wrote:
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
What options? Since you've authored Boostbook you must know better, but I still don't see the value in using home-grown documentation format.
The option to eliminate BoostBook entirely, so that one can translate directly from Quickbook to Docbook.
I'm making the assumption that it's better to have something home-grown but simple (Quickbook) rather than something loosely standards-based (extends DocBook) that is hard to use.
I'm not sure. DocBook is something with lots of information available. Anyway, I sure don't want to use quickbook for Boost.Build documentation, so as soon as I'm not forced to, I'm fine. But Boost.Build is probably pure DocBook -- I don't think any BoostBook extensions are used. - Volodya
Vladimir Prus wrote:
Douglas Gregor wrote:
The option to eliminate BoostBook entirely, so that one can translate directly from Quickbook to Docbook.
I'm making the assumption that it's better to have something home-grown but simple (Quickbook) rather than something loosely standards-based (extends DocBook) that is hard to use.
I'm not sure. DocBook is something with lots of information available. Anyway, I sure don't want to use quickbook for Boost.Build documentation, so as soon as I'm not forced to, I'm fine. But Boost.Build is probably pure DocBook -- I don't think any BoostBook extensions are used.
At least that will let you keep a lot of options open. Free tools like http://www.xmlmind.com/xmleditor/ (personal edition) and other close to WYSIWYG editors have good support for DocBook. Large tables are a pain to edit in text editor form, wiki style tags help somewhat but are far from ideal. Just my $0.05. -- Bjørn
- Volodya
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 6/20/07, Vladimir Prus <ghost@cs.msu.su> wrote: Hi Vladimir,
Douglas Gregor wrote:
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
What options? Since you've authored Boostbook you must know better, but I still don't see the value in using home-grown documentation format.
Have you tried Quickbook? It is an impressive tool. (I really think that it can be use for others things in the future beside boost). It is a lot easier to maintain, to read, to write, to share. Some of the options that are included in Quickbook and not in Boostbook are: * Support for code import. I will be very unhappy with out this feature. In the review of Boost.Bimap we find a lot of typos in docs examples. Every bit of code that appears in y docs now are in libs/bimap/example, and are tested with boost.build before I do any commit. You can not understand the value of this feature til you use it. * Support for macros and templates. * Simple markup for italics, bold, preformatted, blurbs, code samples, tables, URLs, anchors, images, etc. And there is a lot more... Best regards Matias
On Wed, 2007-06-20 at 13:13 -0300, Matias Capeletto wrote:
* Support for code import. I will be very unhappy with out this feature. In the review of Boost.Bimap we find a lot of typos in docs examples. Every bit of code that appears in y docs now are in libs/bimap/example, and are tested with boost.build before I do any commit. You can not understand the value of this feature til you use it.
BoostBook actually has some support for literate programming, which is the opposite of the approach you're describing. Basically, you can name the code samples you write in BoostBook, then later on have it produce real example files by weaving together snippets of code with other support code. The Function library used this at one point to create its test suite (see libs/function/doc/tests.xml and libs/function/doc/tutorial.xml). But, without good integration into the build system, this feature never really got used. Granted, I'm not recommending that you use this part of BoostBook... Quickbook could do the same, probably better, but it is there. - Doug
Douglas Gregor wrote:
On Wed, 2007-06-20 at 13:13 -0300, Matias Capeletto wrote:
* Support for code import. I will be very unhappy with out this feature. In the review of Boost.Bimap we find a lot of typos in docs examples. Every bit of code that appears in y docs now are in libs/bimap/example, and are tested with boost.build before I do any commit. You can not understand the value of this feature til you use it.
BoostBook actually has some support for literate programming, which is
It has? Darn! I didn't know that. Where can I know more about it? What we have now is reverse-lit. Dave has been advocating for a full-Lit which I havent' done yet (me slap in head!).
the opposite of the approach you're describing. Basically, you can name the code samples you write in BoostBook, then later on have it produce real example files by weaving together snippets of code with other support code. The Function library used this at one point to create its test suite (see libs/function/doc/tests.xml and libs/function/doc/tutorial.xml). But, without good integration into the build system, this feature never really got used.
Granted, I'm not recommending that you use this part of BoostBook...
Why? I can imagine exposing this part of the interface to quickbook somehow. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Matias Capeletto wrote:
On 6/20/07, Vladimir Prus <ghost@cs.msu.su> wrote:
Hi Vladimir,
Douglas Gregor wrote:
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
What options? Since you've authored Boostbook you must know better, but I still don't see the value in using home-grown documentation format.
Have you tried Quickbook? It is an impressive tool. (I really think that it can be use for others things in the future beside boost). It is a lot easier to maintain, to read, to write, to share.
Some of the options that are included in Quickbook and not in Boostbook are:
* Support for code import. I will be very unhappy with out this feature. In the review of Boost.Bimap we find a lot of typos in docs examples. Every bit of code that appears in y docs now are in libs/bimap/example, and are tested with boost.build before I do any commit. You can not understand the value of this feature til you use it.
Such a support can be added to BoostBook via a tiny script or a tiny C++ program that takes code and produces XML corresponding to it.
* Support for macros
XML entities work just fine.
and templates.
Is it actually that much needed?
* Simple markup for italics, bold, preformatted, blurbs, code samples, tables, URLs, anchors, images, etc.
I guess this is not "option" that quickbook provides, since Docbook allows this too, and "simple" is subjective. - Volodya
Vladimir Prus wrote:
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
What options? Since you've authored Boostbook you must know better, but I still don't see the value in using home-grown documentation format.
Automatic syntax highlightling of source code for one. Quickbook is also much easier to read, write and maintain than Docbook. To give you an example, when I originally did the TR1 docs, I invested quite a bit of time to learn Docbook, and authored the docs using that. About a month later quickbook came along, and my first reaction was much like yours: I certainly didn't want to have to learn "yet another format". However, I gave it a try, and liked it so much that I immediately rewrote the TR1 docs in quickbook format: the quickbook source is just so much easier to read and maintain than Docbook XML, which frankly I wouldn't wish on my worst enemy these days. Anyway that's my experience. Regards, John.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of John Maddock Sent: 20 June 2007 18:24 To: boost@lists.boost.org Subject: Re: [boost] Help request, boost docs
Vladimir Prus wrote:
I would strongly advise that everything go into Quickbook format. It's far easier to write documentation in Quickbook than Boostbook, and Quickbook gives us more options.
What options? Since you've authored Boostbook you must know better, but I still don't see the value in using home-grown documentation format.
Quickbook is also much easier to read, write and maintain than Docbook.
To give you an example, when I originally did the TR1 docs, I invested quite a bit of time to learn Docbook, and authored the docs using that. About a month later quickbook came along, and my first reaction was much like yours: I certainly didn't want to have to learn "yet another format".
FWIW, having spent some time working on the Math Tool docs, I was also reluctant to earn "yet another format" (my brain is full!), and feared a custom tool, but I also found it *really* easy to use, and revise - once the experts had ironed out some of the wrinkles for me. As must be clear, there are still plenty of wrinkles to flatten, but the results are most pleasing. If we can add MathML editing, even the hated math equations infested with greek and symbols will be much easier. SVG graphs from C++, currently under development by Jake Voytko, will make simple (and complex) graphs a doddle to include. Finally the ability to search the pdf, and Google the html will make it user-friendly. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
participants (13)
-
Bjørn Roald -
Cédric Venet -
Douglas Gregor -
Glyn Matthews -
Janek Kozicki -
Joel de Guzman -
John Maddock -
Matias Capeletto -
Matt Doyle -
Michael Marcin -
Paul A Bristow -
Robert Ramey -
Vladimir Prus