Boost documentation
Hi, I've been offline for a bit. But I was able to spend several weeks learning DocBook. I must say I was really impressed with quality of this project. I also tried to get a grasp of BoostBook and gave perfunctory look on quickbook. Here I would like to share my thoughts on recent "doc update" movement. I. quickbook as documentation media. Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format. DocBook is very mature, well supported project. It's based on widely accepted/supported technologies. It's powerful and configurable to implement essentially anything one need. I personally don't see much valid reasons to look in home grown format direction. Here some specific points: 1. Simplicity Some people argues that it's easier to type quickbook I might argue that it's actually opposite. Granted if you use vi XML editing is not fun. But myriads of modern XML editors simplify the process marginally. There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. In addition you get immediate format validation and presentation (using assigned stylesheets) 2. Any change in DocBook have to be reflected in quickbook terms 3. Someone need to maintain quickbook parser/transformer 4. quickbook will never be as flexible as DocBook 5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters. 6. Source code highlighting My understanding is that quickbook presents some source code highlighting automation. IMO this can be either implemented as standalone C++ based tool that docs writers can use when required or even better it can be implemented in JavaScript. I believe I've seen it done. All in all I believe using this format is going to be a maintenance problem in a long term and should be avoided. We should stick with industry standard DocBook IMO instead. II. BoostBook 1. Complexity The BoostBook being an extension to DocBook seems to be doing too much. IMO any useful generic innovations should be proposed to the DocBook developers and eventually removed. All in all we should strive to make this layer as thin as possible. 2. Test suites support. I did not really grasp the idea behind this feature completely, but from what I understand this is "misfeature" and should be removed 3. Tight coupling with Boost.Build This is major problem I believe. Especially in documentation. BoostBook should be presented as independent project. It should be explained how to use it, configure it without any reference to Boost.Build at all. At the very last chapter of documentation we may refer that if you want you docs to be automatically generated on some remote host (if let's say you don't have all the tools set up locally for all the formats) this is what you need to do ..... 4. Documentation I found documentation to be largely unacceptable (funny thing for the project dedicated to writing documentation) a) No explanation how to use BoostBook without Boost.Build (see above) b) all he elements description are without examples c) most critical: no description whatsoever of all the modification done in comparison with DocBook. All the updated parameter need to be listed, all the updated templates need to be explained. General approach should be what the person familiar with DocBook (standard) need to know/expect to use BoostBook d) No explanation on how to extend the BoostBook (especially in comparison with DocBook) As I mentioned before we should try to limit our extensions to the most necessary only and strive to stick with standard DocBook. Also all extensions should be made optional. III. What should we do? IMO the standardization efforts need to target DocBook/BoostBook. On the other hand each developer should be allowed to extend/twick standard L&F. Usually differences should be only cosmetic. Following are general observations about common L&F 1. JS Menu support. I believe it should be implemented but made optional. I personally don't like it (I believe it's just wait of space for this menu to stay on all the time) and prefer "location path" kinda navigation Boost.Test currently using. 2. Header on top. I don't believe it's necessary. Neither in a form of boost|libraries|more|... nor what is currently proposed. This information is accessible from boost main page. No need to duplicate it on every page of every library. 3. Frames I personally need frames support for the reference like pages (like in preprocessor and test libraries). I am open to the alternative that presents similar L&F. 4. Portability This is major requirement for all the features we implement. They should work on at least set of predefined "major" browsers. Please make this as discouraging comments to overall documentation efforts movements. I just don't believe we move in right direction. Regards, Gennadiy
Gennadiy Rozental wrote:
Hi,
I've been offline for a bit. But I was able to spend several weeks learning DocBook. I must say I was really impressed with quality of this project. I also tried to get a grasp of BoostBook and gave perfunctory look on quickbook. Here I would like to share my thoughts on recent "doc update" movement.
I. quickbook as documentation media.
Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format.
It is my business :-). As much as I like writing libraries, I also like writing tools. And it *is* easy to support. It is merely a very thin layer on top of docbook. It is very easy to understand, extend and maintain. I am not the sole maintainer. It's being maintained by some folks and I do get some contributions from a few more. IOTW, it's not a one-man-show. And, it is not a new toy. It's been with us since 2002.
DocBook is very mature, well supported project. It's based on widely accepted/supported technologies. It's powerful and configurable to implement essentially anything one need.
quickbook *is* docbook. What's the worry? If you get paranoid, you can just dump into xml and forget about quickbook. Nothing lost!
I personally don't see much valid reasons to look in home grown format direction.
Well, you can't please everybody ;) The good thing is, you don't need to use it if you don't want to. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
"Joel de Guzman" <joel@boost-consulting.com> wrote in message news:f5j3pq$ba4$1@sea.gmane.org...
Gennadiy Rozental wrote:
Hi,
I've been offline for a bit. But I was able to spend several weeks learning DocBook. I must say I was really impressed with quality of this project. I also tried to get a grasp of BoostBook and gave perfunctory look on quickbook. Here I would like to share my thoughts on recent "doc update" movement.
I. quickbook as documentation media.
Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format.
It is my business :-). As much as I like writing libraries, I also like writing tools.
I am sure you are. But Boost should use industry standard formats for it's documentation: html before, DocBook now. Boost can't be everything in one bottle: we produce c++ libraries, we don't invent documentation formats. If you believe you very good at it and your format is better, try to convince guys who actually know something about it (I mean they are experts). I am not the one.
And it *is* easy to support.
It's easy now, when you've got very limited number of users. This will change with widespread application of this format. And to be completely frank with you how easy it is to support the tools for you is comparatively minor part of my concern. After all it's your own decision. The fact remains: someone need to support it. Someone need to test it. Someone need to documents it. And what about these: Do you support quickbook documents validation? Do you plan to invent schema language? Do you run unit tests? How flexible is it in comparison with DocBook from extension standpoint? Is there a single editor out there that understands this format?
It is merely a very thin layer on top of docbook.
It's not a thin layer. This is completely different markup language. Even BoostBook is not thin enough IMO.
It is very easy to understand, extend and maintain.
First of all it's subjective opinion: I personally don't like these magic char sequences and prefer explicit names in everything. And since you don't have many users yet you can't really state second and third. Let's say I want frames in my docs. Does quickbook is extendible to support it?
I am not the sole maintainer. It's being maintained by some folks and I do get some contributions from a few more. IOTW, it's not a one-man-show.
I don't believe Boost.Build, for example, is one man show as well.
And, it is not a new toy. It's been with us since 2002.
Until someone is trying to make it de facto standard for Boost documentation and not just a convenience tool for HTML generation I don't care. Did it ever go through submission process and formal review?
DocBook is very mature, well supported project. It's based on widely accepted/supported technologies. It's powerful and configurable to implement essentially anything one need.
quickbook *is* docbook. What's the worry?
What do you mean? From where I stand it's completely different format.
If you get paranoid, you can just dump into xml and forget about quickbook. Nothing lost!
I am not paranoid. Above statement is pointless if I still required to maintain docs in this format and make no sense if I don't use it.
I personally don't see much valid reasons to look in home grown format direction.
Well, you can't please everybody ;) The good thing is, you don't need to use it if you don't want to.
This one is clear. The only reason for my post is to make sure the community is moving in right direction. Which is not IMO. Gennadiy
Gennadiy Rozental wrote:
"Joel de Guzman" <joel@boost-consulting.com> wrote in message
I. quickbook as documentation media.
And it *is* easy to support.
It's easy now, when you've got very limited number of users. This will change with widespread application of this format. And to be completely frank with you how easy it is to support the tools for you is comparatively minor part of my concern. After all it's your own decision. The fact remains: someone need to support it. Someone need to test it. Someone need to documents it.
So what? All tools need documentation and support. It just so happens that this tool is homegrown. You can argue that we are not in this business. Fine. That's your opinion. I find Quickbook useful. I will continue to support it. Many more find it useful too. I'm glad to be of service. It just so happens that I am a booster, but I would have done the same even if I was an outsider, if boost finds my tool useful.
And what about these:
Do you support quickbook documents validation?
Does a car have wings?
Do you plan to invent schema language?
Does a bike have turbo-chargers?
Do you run unit tests?
Oh man, sure we do!
How flexible is it in comparison with DocBook from extension standpoint?
Gennadiy, you are clearly missing the point of what quickbook is. I do not want to argue this any longer. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
on Sun Jun 24 2007, Joel de Guzman <joel-AT-boost-consulting.com> wrote:
Gennadiy Rozental wrote:
"Joel de Guzman" <joel@boost-consulting.com> wrote in message
I. quickbook as documentation media.
And it *is* easy to support.
It's easy now, when you've got very limited number of users. This will change with widespread application of this format. And to be completely frank with you how easy it is to support the tools for you is comparatively minor part of my concern. After all it's your own decision. The fact remains: someone need to support it. Someone need to test it. Someone need to documents it.
So what? All tools need documentation and support. It just so happens that this tool is homegrown. You can argue that we are not in this business. Fine. That's your opinion. I find Quickbook useful. I will continue to support it. Many more find it useful too. I'm glad to be of service. It just so happens that I am a booster, but I would have done the same even if I was an outsider, if boost finds my tool useful.
The only places I can imagine a conclusion that "we're not in the tools business" leading are: * we don't start any new tool projects * we remove the tools we do have from boost. They can still be supported elsewhere by the same people. I'm not suggesting we do either of these things. I'm just pointing out that whether or not Boost is in the tool business ultimately has no bearing on which tools we end up using.
And what about these:
Do you support quickbook documents validation?
Does a car have wings?
Do you plan to invent schema language?
Does a bike have turbo-chargers?
His questions seem reasonable to me, and I think QuickBook has reasonable answers for them. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com
David Abrahams wrote:
on Sun Jun 24 2007, Joel de Guzman <joel-AT-boost-consulting.com> wrote:
Gennadiy Rozental wrote:
"Joel de Guzman" <joel@boost-consulting.com> wrote in message
And what about these:
Do you support quickbook documents validation? Does a car have wings?
Do you plan to invent schema language? Does a bike have turbo-chargers?
His questions seem reasonable to me
IMO, they are not. Quickbook is not designed to include everything but the kitchen sink. If one reads even partially through the docs, you'll see that it is a wiki style tool. Simplicity is a very important requirement. Those are the wrong questions to ask for evaluating the usefulness of quickbook. IOTW, I do not need to answer them.
, and I think QuickBook has reasonable answers for them.
Yes, and Cédric answered them. What irks me is that Gennadiy could have done the research first. Such questions show his unfamiliarity with the tool and IMO, you can't just gather such sweeping statements from a collection of small snippets of information here and there and form conclusions based on what little you have, which he did in his original post. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
"Joel de Guzman" <joel@boost-consulting.com> wrote in message news:f5l6q0$i6n$1@sea.gmane.org...
Gennadiy, you are clearly missing the point of what quickbook is.
It looks this way. But what important here for me is not what it is, but how do you position it. Gennadiy
And it *is* easy to support.
It's easy now, when you've got very limited number of users. This will change with widespread application of this format. And to be completely frank with you how easy it is to support the tools for you is comparatively minor part of my concern. After all it's your own decision. The fact remains: someone need to support it. Someone need to test it. Someone need to documents it.
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.
And what about these:
Do you support quickbook documents validation? Do you plan to invent schema language?
You can run the schema validation on the docbook, it should be easy to find the corresponding part of the quickbook
Do you run unit tests? How flexible is it in comparison with DocBook from extension standpoint?
If you don't fin dit extensible enough, go back to boostbook
Is there a single editor out there that understands this format?
Simple enough to use with lightweight text editor: vim, emacs, kde (someone developed a syntax colorizer for it)
It is very easy to understand, extend and maintain.
First of all it's subjective opinion: I personally don't like these magic char sequences and prefer explicit names in everything. And since you don't have many users yet you can't really state second and third.
For those which don't use xml wisiwig editor, it is useful. If you don't need it, don't use it.
Gennadiy
I just emphasised the point of Matias, that you don't need to use it. And if you start using it, you can easily go back. -- Cédric Venet
On 6/23/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
Hi,
I've been offline for a bit. But I was able to spend several weeks learning DocBook. I must say I was really impressed with quality of this project.
100% Agree with you. I have spend last two weeks learning Docbook, his history and where it is heading and I have to said I am really impressed too. Docbook 5 will rock, they are starting to use RelaxNG instead of DTD and will apply all the power of xsl 2. We should be really happy to have such an amazing and supported project as our backend.
I also tried to get a grasp of BoostBook and gave perfunctory look on quickbook. Here I would like to share my thoughts on recent "doc update" movement.
Ok, thanks for taking the time to comment on it.
I. quickbook as documentation media.
Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format.
As Joel said it is *my* business too. And IMHO you are too. We could use a different thing than Boost.Test, but I am very happy with it and I really appreciate such a wonderful project is maintained by a boost developer.
DocBook is very mature, well supported project. It's based on widely accepted/supported technologies. It's powerful and configurable to implement essentially anything one need. I personally don't see much valid reasons to look in home grown format direction.
First of all. I will be proposing to use Quickbook even if it is not inside Boost. I really think that Quickbook (plus the necessary backend) is a hell of a documenting tool and IMHO in the future other projects will start to using it (Yesterday I spend part of the day working on a boost agnostic version of boostbook to better support outsiders) Also there is a big difference between our homegrown build system. As Joel state it we are proposing dockbook as our documentation format backend, this allow us to be sure we have a lot of support from the outside (there are tools, documentation, a community, etc). Quickbook and boostbook is very small (but yet powerful) layer that IMHO works better for us. If you want to write in docbook, it is ok. I really think you will change your opinion when you use both tools for a while. You can not make strong statements without trying them.
Here some specific points:
1. Simplicity Some people argues that it's easier to type quickbook I might argue that it's actually opposite. Granted if you use vi XML editing is not fun. But myriads of modern XML editors simplify the process marginally. There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. In addition you get immediate format validation and presentation (using assigned stylesheets)
I have use these tools and they are very good indeed. The same thing happens to latex, the LyX project allows you to write almost WYSWYG and it is a handy tool to know but if you asked around, almost everybody will tell you that they prefer and are far more productive writing directly in latex. It is the same with Quickbook, once you use it for a while you will be very productive and happy as is. The only aid I need is something like this: http://tinyurl.com/2ll5tk
2. Any change in DocBook have to be reflected in quickbook terms
IMHO this is not the idea.
3. Someone need to maintain quickbook parser/transformer
There are a lot of people interested in maintained it and we have Joel with us ;) I am really interested in offer my help to maintain the boost docs tools.
4. quickbook will never be as flexible as DocBook
We are not looking for more flexibility, we are aiming at simplicity. If you need the extra complexity just write docbook, it is compatible with the current efforts. But please first tell us what have you fail to do in quickbook, it may be that you just do not have enough experience with it. Moreover... quickbook templates rocks and in the feature quickbook will be even thinner.
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Believe me that I am working very hard to low the barrier.
II. BoostBook
1. Complexity The BoostBook being an extension to DocBook seems to be doing too much. IMO any useful generic innovations should be proposed to the DocBook developers and eventually removed. All in all we should strive to make this layer as thin as possible.
Docbook is a very slow changing project. It has to be. I have been hacking boostbook internals for the last two weeks. I have simplify a lot of things. I am currently working on documentation. I hope to have it ready soon.
2. Test suites support. I did not really grasp the idea behind this feature completely, but from what I understand this is "misfeature" and should be removed
I have never used it, no strong opinion here.
3. Tight coupling with Boost.Build This is major problem I believe. Especially in documentation. BoostBook should be presented as independent project. It should be explained how to use it, configure it without any reference to Boost.Build at all. At the very last chapter of documentation we may refer that if you want you docs to be automatically generated on some remote host (if let's say you don't have all the tools set up locally for all the formats) this is what you need to do .....
I am working to make boostbook a boost agnostic tool.
4. Documentation I found documentation to be largely unacceptable (funny thing for the project dedicated to writing documentation)
a) No explanation how to use BoostBook without Boost.Build (see above)
Good point, I will add a page about this.
c) most critical: no description whatsoever of all the modification done in comparison with DocBook. All the updated parameter need to be listed, all the updated templates need to be explained. General approach should be what the person familiar with DocBook (standard) need to know/expect to use BoostBook
I spend a big part of yesterday doing this :) Just give me a few more hours to polish it.
d) No explanation on how to extend the BoostBook (especially in comparison with DocBook)
Ok, this may be a good thing to add in the future. It is not a priority now.
As I mentioned before we should try to limit our extensions to the most necessary only and strive to stick with standard DocBook. Also all extensions should be made optional.
All extensions are optional, input a docbook source to boostbook and it will work.
III. What should we do?
IMO the standardization efforts need to target DocBook/BoostBook. On the other hand each developer should be allowed to extend/twick standard L&F. Usually differences should be only cosmetic.
This is exactly what we are doing. I think that is fair to say that I spend last two weeks in: 40% boostbook 20% css 15% sending mails to boost-docs 10% javascript 10% learning 5% quickbook (no sleep :P)
Following are general observations about common L&F
1. JS Menu support. I believe it should be implemented but made optional. I personally don't like it (I believe it's just wait of space for this menu to stay on all the time) and prefer "location path" kinda navigation Boost.Test currently using.
It is optional.
2. Header on top. I don't believe it's necessary. Neither in a form of boost|libraries|more|... nor what is currently proposed. This information is accessible from boost main page. No need to duplicate it on every page of every library.
They are optional (I have work on this yesterday)
3. Frames I personally need frames support for the reference like pages (like in preprocessor and test libraries). I am open to the alternative that presents similar L&F.
Frames are bad friend of the new web. They are not embrace by standards. I am working in an optional sidebar that will let you do the same.
4. Portability This is major requirement for all the features we implement. They should work on at least set of predefined "major" browsers.
Have you seen this: http://svn.boost.org/trac/boost/wiki/BrowserTestingChart
Please make this as discouraging comments to overall documentation efforts movements. I just don't believe we move in right direction.
I hope we can work together to move things in the right direction. IMO your direction is a lot more similar from the current "Improving Boost Docs" project that you think. Regards Matias
Matias Capeletto wrote:
Here some specific points:
1. Simplicity Some people argues that it's easier to type quickbook I might argue that it's actually opposite. Granted if you use vi XML editing is not fun. But myriads of modern XML editors simplify the process marginally. There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. In addition you get immediate format validation and presentation (using assigned stylesheets)
I have use these tools and they are very good indeed. The same thing happens to latex, the LyX project allows you to write almost WYSWYG and it is a handy tool to know but if you asked around, almost everybody will tell you that they prefer and are far more productive writing directly in latex.
Do you have any real data to support your claim? I trust that your friends prefer latex; but in my experience LyX comes as a clear winner. I'm not sure this point is important in your reasonable, but wanted to note that it's weak ;-) - Volodya
On 6/23/07, Vladimir Prus <ghost@cs.msu.su> wrote:
Matias Capeletto wrote:
Here some specific points:
1. Simplicity Some people argues that it's easier to type quickbook I might argue that it's actually opposite. Granted if you use vi XML editing is not fun. But myriads of modern XML editors simplify the process marginally. There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. In addition you get immediate format validation and presentation (using assigned stylesheets)
I have use these tools and they are very good indeed. The same thing happens to latex, the LyX project allows you to write almost WYSWYG and it is a handy tool to know but if you asked around, almost everybody will tell you that they prefer and are far more productive writing directly in latex.
Do you have any real data to support your claim? I trust that your friends prefer latex; but in my experience LyX comes as a clear winner.
No formal study, I just asked around. Please have in mind that I really like LyX and other related tools. But I really appreciate that it is just a front end for LaTeX and I can grab that in a text editor on whatever platform I am and enjoy editing it. Also, compare the size of the docs source: Boost.Bimap docs in docbook: 1.1 MB Boost.Bimap docs in quickbook: 0.3 MB It is a real difference.
I'm not sure this point is important in your reasonable, but wanted to note that it's weak ;-)
Fair enough. As you said, It was not really important in my post anyway :) Best regards Matias
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706230826od2db317ic2cb90f1bfdb561@mail.gmail.com...
Also, compare the size of the docs source:
Boost.Bimap docs in docbook: 1.1 MB Boost.Bimap docs in quickbook: 0.3 MB
It is a real difference.
The real difference would be the comparison of non WS chars (and exclude all quickbook related artifacts from DocBook) Gennadiy
Gennadiy Rozental wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706230826od2db317ic2cb90f1bfdb561@mail.gmail.com...
Also, compare the size of the docs source:
Boost.Bimap docs in docbook: 1.1 MB Boost.Bimap docs in quickbook: 0.3 MB
It is a real difference.
The real difference would be the comparison of non WS chars (and exclude all quickbook related artifacts from DocBook)
You do know that XML is one of the most verbose data formats in existence, right? I would bet that even compressing a docbook file and corresponding quickbook file would yield quickbook the winner. -- -- 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
"Rene Rivera" <grafikrobot@gmail.com> wrote in message news:467F1339.9050302@gmail.com...
Gennadiy Rozental wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706230826od2db317ic2cb90f1bfdb561@mail.gmail.com...
Also, compare the size of the docs source:
Boost.Bimap docs in docbook: 1.1 MB Boost.Bimap docs in quickbook: 0.3 MB
It is a real difference.
The real difference would be the comparison of non WS chars (and exclude all quickbook related artifacts from DocBook)
You do know that XML is one of the most verbose data formats in existence, right?
So what? Above comparison still prove nothing.
I would bet that even compressing a docbook file and corresponding quickbook file would yield quickbook the winner.
yes. I see ~30%. Again, what is the point of this comparison? Gennadiy
Gennadiy Rozental wrote:
"Rene Rivera" <grafikrobot@gmail.com> wrote in message news:467F1339.9050302@gmail.com...
Gennadiy Rozental wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706230826od2db317ic2cb90f1bfdb561@mail.gmail.com...
Also, compare the size of the docs source:
Boost.Bimap docs in docbook: 1.1 MB Boost.Bimap docs in quickbook: 0.3 MB
It is a real difference. The real difference would be the comparison of non WS chars (and exclude all quickbook related artifacts from DocBook) You do know that XML is one of the most verbose data formats in existence, right?
So what? Above comparison still prove nothing.
Who said there was anything to prove? Matias suggested that you might consider the size of equivalent documents when thinking about the effectiveness of writing in Quickbook. And you said it was an invalid comparison because you should remove white-space before comparing. I was just asking if you knew where XML stands in the verbosity scale of data formats. Do you?
I would bet that even compressing a docbook file and corresponding quickbook file would yield quickbook the winner.
yes. I see ~30%. Again, what is the point of this comparison?
Simple... That you *type* less when writing _Quickbook_, than when writing with <emphasis role="underline">DocBook</phrase> <emphasis>directly</emphasis>. -- -- 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 6/25/07, Rene Rivera <grafikrobot@gmail.com> wrote:
Gennadiy Rozental wrote:
"Rene Rivera" <grafikrobot@gmail.com> wrote in message news:467F1339.9050302@gmail.com...
Gennadiy Rozental wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706230826od2db317ic2cb90f1bfdb561@mail.gmail.com...
Also, compare the size of the docs source:
Boost.Bimap docs in docbook: 1.1 MB Boost.Bimap docs in quickbook: 0.3 MB
I would bet that even compressing a docbook file and corresponding quickbook file would yield quickbook the winner.
yes. I see ~30%. Again, what is the point of this comparison?
Simple... That you *type* less when writing _Quickbook_, than when writing with <emphasis role="underline">DocBook</phrase> <emphasis>directly</emphasis>.
[*That was my point] Regards Matias
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Matias Capeletto Sent: 25 June 2007 15:34 To: boost@lists.boost.org Subject: Re: [boost] Boost documentation
On 6/25/07, Rene Rivera <grafikrobot@gmail.com> wrote:
Gennadiy Rozental wrote:
"Rene Rivera" <grafikrobot@gmail.com> wrote in message news:467F1339.9050302@gmail.com...
Gennadiy Rozental wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706230826od2db317ic2cb90f1bfdb561@mail.gmail.com...
Also, compare the size of the docs source:
Boost.Bimap docs in docbook: 1.1 MB Boost.Bimap docs in quickbook: 0.3 MB
I would bet that even compressing a docbook file and corresponding quickbook file would yield quickbook the winner.
yes. I see ~30%. Again, what is the point of this comparison?
Simple... That you *type* less when writing _Quickbook_, than when writing with <emphasis role="underline">DocBook</phrase> <emphasis>directly</emphasis>.
[*That was my point]
AND it is not "Write-only" either - you can read it more easily too! I think the weight of opinion is firmly behind keeping Quickbook as a favoured, but not exclusive, Boost docs tool. Paul --- Paul A Bristow Prizet Farmhouse, Kendal, Cumbria UK LA8 8AB +44 1539561830 & SMS, Mobile +44 7714 330204 & SMS pbristow@hetp.u-net.com
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:002301c7b741$0798cc40$0200a8c0@hetp7...
I think the weight of opinion is firmly behind keeping Quickbook as a favoured, but not exclusive, Boost docs tool.
Let me clarify again my point: Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release Boost shouldn't require what tools are used to generate BoostBook documents. Whether it's QuickBook, XML editor, any other facility is irrelevant and libraries authors are free to use any of them (and keep some intermediate files under source control if necessary) Gennadiy
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:002301c7b741$0798cc40$0200a8c0@hetp7...
I think the weight of opinion is firmly behind keeping Quickbook as a favoured, but not exclusive, Boost docs tool.
Let me clarify again my point:
Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release Boost shouldn't require what tools are used to generate BoostBook documents. Whether it's QuickBook, XML editor, any other facility is irrelevant and libraries authors are free to use any of them (and keep some intermediate files under source control if necessary)
This is one of the objectives of the "Improving Boost Docs" project.
From my very first answer to your post:
I hope we can work together to move things in the right direction. IMO your direction is a lot more similar from the current "Improving Boost Docs" project that you think. ------------------------------------------------------------------------------------------- I really hope that you think that our current direction is right now. Please try not to sparse FUD, people can get confused by it. Best regards Matias
Matias Capeletto wrote:
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
Boost shouldn't require what tools are used to generate BoostBook documents.
I really hope that you think that our current direction is right now. Please try not to sparse FUD, people can get confused by it.
But the argument has nothing to do with the quality of the tool you are working on ! Let me put this into a broader context: The concern I have about even the fact that we have this discussion is basically the same I have about people spending weeks arguing about the best version control tool for boost, or build system. (And, as far as the build system is concerned, I was worried about David pushing people to use boost.build even for their own projects. It seems he is quite a bit less aggressive about that, these days, luckily. ;-) ) It sounds like an imbalance between academic concerns (getting things Right), as opposed to pragmatism (focus on the important stuff, and not getting stuck in things outside what should be boost's scope). At least there seems to be a consensus about what boost's scope / focus should be. That's a good starting point. :-) Thanks, Stefan -- ...ich hab' noch einen Koffer in Berlin...
On 6/25/07, Stefan Seefeld <seefeld@sympatico.ca> wrote:
Matias Capeletto wrote:
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
Boost shouldn't require what tools are used to generate BoostBook documents.
I really hope that you think that our current direction is right now. Please try not to sparse FUD, people can get confused by it.
But the argument has nothing to do with the quality of the tool you are working on ! Let me put this into a broader context:
The concern I have about even the fact that we have this discussion is basically the same I have about people spending weeks arguing about the best version control tool for boost, or build system. (And, as far as the build system is concerned, I was worried about David pushing people to use boost.build even for their own projects. It seems he is quite a bit less aggressive about that, these days, luckily. ;-) )
It sounds like an imbalance between academic concerns (getting things Right), as opposed to pragmatism (focus on the important stuff, and not getting stuck in things outside what should be boost's scope).
IMHO opinion the current project to boost docs is well balanced. We are trying to get things right because it is Boost tradition to pursue excellence in all aspects. The important thing to note is that this discussion is healthy an do not slow down the project. Two weeks ago there was no such project, and now there are at least six volunteers working in different parts of it.
At least there seems to be a consensus about what boost's scope / focus should be. That's a good starting point. :-)
Having a common look & feel for docs and good tools for navigate them should be part of boost scope. Best regards Matias
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706250954m11a04762mc5c1cfc6d7429ebe@mail.gmail.com...
On 6/25/07, Stefan Seefeld <seefeld@sympatico.ca> wrote:
At least there seems to be a consensus about what boost's scope / focus should be. That's a good starting point. :-)
Having a common look & feel for docs and good tools for navigate them should be part of boost scope.
If you want this to become part of boost scope, submit it for review. You can't just develop staff and make everyone start using it. Please don't take this statement as diminishing your efforts - it's just how boost work (or I thought it is). Gennadiy
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706250954m11a04762mc5c1cfc6d7429ebe@mail.gmail.com...
On 6/25/07, Stefan Seefeld <seefeld@sympatico.ca> wrote:
At least there seems to be a consensus about what boost's scope / focus should be. That's a good starting point. :-)
Having a common look & feel for docs and good tools for navigate them should be part of boost scope.
If you want this to become part of boost scope, submit it for review. You can't just develop staff and make everyone start using it. Please don't take this statement as diminishing your efforts - it's just how boost work (or I thought it is).
I am not forcing anyone to do nothing. I am working in this project because I think it will be very good for boost future. Others seem to think that way too, because now there are a bunch of people working behind scene. I will very happy to submit all this work for review when it is ready. I am working hard so the review process will be painless. You can take a look at our wiki page: http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs We are taking this project very seriously (while having a fair amount of fun) Best regards Matias
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706251340v7132cad1sc95d2122e36b16d9@mail.gmail.com...
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706250954m11a04762mc5c1cfc6d7429ebe@mail.gmail.com...
On 6/25/07, Stefan Seefeld <seefeld@sympatico.ca> wrote:
At least there seems to be a consensus about what boost's scope / focus should be. That's a good starting point. :-)
Having a common look & feel for docs and good tools for navigate them should be part of boost scope.
If you want this to become part of boost scope, submit it for review. You can't just develop staff and make everyone start using it. Please don't take this statement as diminishing your efforts - it's just how boost work (or I thought it is).
I am not forcing anyone to do nothing. I am working in this project because I think it will be very good for boost future. Others seem to think that way too, because now there are a bunch of people working behind scene.
I will very happy to submit all this work for review when it is ready. I am working hard so the review process will be painless. You can take a look at our wiki page: http://svn.boost.org/trac/boost/wiki/ImprovingBoostDocs
We are taking this project very seriously (while having a fair amount of fun)
Well. Maybe we can ask review wizard for some priority handling. It shouldn't be difficult to find review manager. Gennadiy
Gennadiy Rozental wrote:
You can't just develop staff and make everyone start using it.
You mean like this <http://tinyurl.com/2b46b8>? -- -- 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
"Rene Rivera" <grafikrobot@gmail.com> wrote in message news:46802E62.80402@gmail.com...
Gennadiy Rozental wrote:
You can't just develop staff and make everyone start using it.
You mean like this <http://tinyurl.com/2b46b8>?
I am not sure I understand your point. Gennadiy
Gennadiy Rozental wrote:
"Rene Rivera" <grafikrobot@gmail.com> wrote in message news:46802E62.80402@gmail.com...
Gennadiy Rozental wrote:
You can't just develop staff and make everyone start using it. You mean like this <http://tinyurl.com/2b46b8>?
I am not sure I understand your point.
There was no point. I was asking if what I did to present your docs in the beta web site an instance of developing stuff and making everyone use it? -- -- 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
"Rene Rivera" <grafikrobot@gmail.com> wrote in message news:468033ED.1080306@gmail.com...
Gennadiy Rozental wrote:
"Rene Rivera" <grafikrobot@gmail.com> wrote in message news:46802E62.80402@gmail.com...
Gennadiy Rozental wrote:
You can't just develop staff and make everyone start using it. You mean like this <http://tinyurl.com/2b46b8>?
I am not sure I understand your point.
There was no point. I was asking if what I did to present your docs in the beta web site an instance of developing stuff and making everyone use it?
I don't know since it's your own playground and (I hope) is not going to be pushed to the release. Genandiy
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706250930l7842da82je74ba8b7ff9876bc@mail.gmail.com...
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:002301c7b741$0798cc40$0200a8c0@hetp7...
I think the weight of opinion is firmly behind keeping Quickbook as a favoured, but not exclusive, Boost docs tool.
Let me clarify again my point:
Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release Boost shouldn't require what tools are used to generate BoostBook documents. Whether it's QuickBook, XML editor, any other facility is irrelevant and libraries authors are free to use any of them (and keep some intermediate files under source control if necessary)
This is one of the objectives of the "Improving Boost Docs" project.
Hmm. I never got this fealing. At least I do not see .dokbook files in libraries maintaining it's docs as quickbook.
From my very first answer to your post:
I hope we can work together to move things in the right direction. IMO your direction is a lot more similar from the current "Improving Boost Docs" project that you think. -------------------------------------------------------------------------------------------
I really hope that you think that our current direction is right now. Please try not to sparse FUD, people can get confused by it.
What particular part is FUD? I still believe that most (if not all) the point in original post are valid. These facilities were never submitted, reviewed and accepted. Essentially it's a someone toy within bounds of boost (might be quite useful, but the fact remains). BUT, Unless you position it as boost documentation format, I personally don't really care. Gennadiy
Gennadiy Rozental wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706250930l7842da82je74ba8b7ff9876bc@mail.gmail.com... Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release Boost shouldn't require what tools are used to generate BoostBook documents. Whether it's QuickBook, XML editor, any other facility is irrelevant and libraries authors are free to use any of them (and keep some intermediate files under source control if necessary)
This is one of the objectives of the "Improving Boost Docs" project.
Hmm. I never got this fealing. At least I do not see .dokbook files in libraries maintaining it's docs as quickbook.
The DocBook or BoostBook XML will be generated via Quickbook when needed. Or do you want the DocBook/BoostBook XML to always be in the source tree, even if it can be regenerated? - Doug
"Douglas Gregor" <dgregor@osl.iu.edu> wrote in message news:468025D2.4050102@osl.iu.edu...
Gennadiy Rozental wrote:
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706250930l7842da82je74ba8b7ff9876bc@mail.gmail.com... Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release Boost shouldn't require what tools are used to generate BoostBook documents. Whether it's QuickBook, XML editor, any other facility is irrelevant and libraries authors are free to use any of them (and keep some intermediate files under source control if necessary)
This is one of the objectives of the "Improving Boost Docs" project.
Hmm. I never got this fealing. At least I do not see .dokbook files in libraries maintaining it's docs as quickbook.
The DocBook or BoostBook XML will be generated via Quickbook when needed. Or do you want the DocBook/BoostBook XML to always be in the source tree, even if it can be regenerated?
Yes. Essentially I should be able to generate docs for any library and know nothing about quickbook and it's tools whatsoever. And how you make this file - you own business. Gennadiy
Gennadiy Rozental wrote:
"Douglas Gregor" <dgregor@osl.iu.edu> wrote in message news:468025D2.4050102@osl.iu.edu...
The DocBook or BoostBook XML will be generated via Quickbook when needed. Or do you want the DocBook/BoostBook XML to always be in the source tree, even if it can be regenerated?
Yes. Essentially I should be able to generate docs for any library and know nothing about quickbook and it's tools whatsoever.
I think that a well-placed 'bjam' command can do that since QuickBook can bootstrap itself (if it supports an HTML target directly). In contrast, it is not possible to generate docs knowing nothing about DocBook and its tools. But I may be misunderstanding something.
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:01fa01c7b76c$4287de60$6407a80a@pdimov2...
Gennadiy Rozental wrote:
"Douglas Gregor" <dgregor@osl.iu.edu> wrote in message news:468025D2.4050102@osl.iu.edu...
The DocBook or BoostBook XML will be generated via Quickbook when needed. Or do you want the DocBook/BoostBook XML to always be in the source tree, even if it can be regenerated?
Yes. Essentially I should be able to generate docs for any library and know nothing about quickbook and it's tools whatsoever.
I think that a well-placed 'bjam' command can do that since QuickBook can bootstrap itself (if it supports an HTML target directly).
I personally would prefer to keep Boost.Build away from docs generation. IOW I shouldn't be required to know/have bjam to do it.
In contrast, it is not possible to generate docs knowing nothing about DocBook and its tools. But I may be misunderstanding something.
1. It will be true for cvs users only 2. If we decide Boost.Book to be documentation format it should be expected 3. It can be avoided with assigned publicly available stylesheets. For example library A developer may put stylesheet as <lib>/doc/html.xsl and assign it as default in XML file. That any user may just open this file using browser and see HTML. Gennadiy
Gennadiy, On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
I personally would prefer to keep Boost.Build away from docs generation. IOW I shouldn't be required to know/have bjam to do it.
I think that the inherent problem with this is from the view of someone else generating your documentation when trying out your library (say, for instance, when you come to the review). When an individual pulls down an individual library that has ANY kind of documentation that has to be built (presuming you are not distributing the library with the HTML sources), you're asking the end-user to go through a two step process instead of a one step process. This complicates the build process, IMO. The user runs Boost.Build if sources need to be built for any of the tests, etc, and then the user goes through a second step to generate the docs. It seems like we have three options at this point. One, have the end user make a script that takes care of the library build process and the documentation build process (and if they have to build sources + documentation separately enough times, they will). Two, create a different script that invokes Boost.Build as well as the documentation build, and third, just stick with bjam and have it all taken care of at once. I personally think that the third option makes the most sense.
"Jake Voytko" <jakevoytko@gmail.com> wrote in message news:16c2caba0706260845k5206304eq19154773a71db9d1@mail.gmail.com...
Gennadiy,
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
I personally would prefer to keep Boost.Build away from docs generation. IOW I shouldn't be required to know/have bjam to do it.
I think that the inherent problem with this is from the view of someone else generating your documentation when trying out your library (say, for instance, when you come to the review).
I don't think this is valid example. Library submitted for review will have bot hxml and html version of docs in review package
When an individual pulls down an individual library that has ANY kind of documentation that has to be built (presuming you are not distributing the library with the HTML sources), you're asking the end-user to go through a two step process instead of a one step process.
The released version of the library will have at least xml and HTML. Users willing to go over our head and access cvs directly will have to deal with doc generation. At this point it assumed one knows how to do this. Gennadiy
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
"Douglas Gregor" <dgregor@osl.iu.edu> wrote in message news:468025D2.4050102@osl.iu.edu...
Gennadiy Rozental wrote: The DocBook or BoostBook XML will be generated via Quickbook when needed. Or do you want the DocBook/BoostBook XML to always be in the source tree, even if it can be regenerated?
Yes. Essentially I should be able to generate docs for any library and know nothing about quickbook and it's tools whatsoever. And how you make this file - you own business.
I agree with Gennady. It is better for now to separate quickbook from dockbook. We may ask authors to provide: libs/{lib_name}/doc/{lib_name}.xml libs/{lib_name}/doc/--stringparam I like .xml over .docbook but I have no strong opinions about this. The --stringparam contains parameters that affects the chunker, that have to be library independent. Best regards Matias
Matias Capeletto wrote:
libs/{lib_name}/doc/{lib_name}.xml libs/{lib_name}/doc/--stringparam
I like .xml over .docbook but I have no strong opinions about this. The --stringparam contains parameters that affects the chunker, that have to be library independent.
Chunking is a styling issue, and thus shouldn't be part of the sources. And, if you really want library authors to be able to customize the process, I think it would be better to allow for them to provide a custom xsl stylesheet (that presumably imports the global boost stylesheet). '--stringparam' is not flexible enough, and specific to xsltproc. Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
On 6/25/07, Stefan Seefeld <seefeld@sympatico.ca> wrote:
Matias Capeletto wrote:
libs/{lib_name}/doc/{lib_name}.xml libs/{lib_name}/doc/--stringparam
I like .xml over .docbook but I have no strong opinions about this. The --stringparam contains parameters that affects the chunker, that have to be library independent.
Chunking is a styling issue, and thus shouldn't be part of the sources. And, if you really want library authors to be able to customize the process, I think it would be better to allow for them to provide a custom xsl stylesheet (that presumably imports the global boost stylesheet). '--stringparam' is not flexible enough, and specific to xsltproc.
I stand corrected. Just wanted to point out what we need. Your solution is far more flexible. libs/{lib_name}/doc/{lib_name}.xml libs/{lib_name}/doc/{lib_name}.xsl I will be writing docs soon about boostbook parameters (params that are not in docbook), but you can look at them here if you can not wait: http://svn.boost.org/trac/boost/browser/sandbox/boost_docs/trunk/tools/boost... Best regards Matias
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706251415s483a5189yc2ea30625254d52f@mail.gmail.com...
On 6/25/07, Stefan Seefeld <seefeld@sympatico.ca> wrote:
Matias Capeletto wrote:
libs/{lib_name}/doc/{lib_name}.xml libs/{lib_name}/doc/--stringparam
I like .xml over .docbook but I have no strong opinions about this. The --stringparam contains parameters that affects the chunker, that have to be library independent.
Chunking is a styling issue, and thus shouldn't be part of the sources. And, if you really want library authors to be able to customize the process, I think it would be better to allow for them to provide a custom xsl stylesheet (that presumably imports the global boost stylesheet). '--stringparam' is not flexible enough, and specific to xsltproc.
I stand corrected. Just wanted to point out what we need. Your solution is far more flexible.
libs/{lib_name}/doc/{lib_name}.xml libs/{lib_name}/doc/{lib_name}.xsl
Nope. <output>.xsl is more flexible Gennadiy
"Stefan Seefeld" <seefeld@sympatico.ca> wrote in message news:46802F38.7060307@sympatico.ca...
Matias Capeletto wrote:
libs/{lib_name}/doc/{lib_name}.xml libs/{lib_name}/doc/--stringparam
I like .xml over .docbook but I have no strong opinions about this. The --stringparam contains parameters that affects the chunker, that have to be library independent.
Chunking is a styling issue, and thus shouldn't be part of the sources. And, if you really want library authors to be able to customize the process, I think it would be better to allow for them to provide a custom xsl stylesheet (that presumably imports the global boost stylesheet). '--stringparam' is not flexible enough, and specific to xsltproc.
Hear, hear Gennadiy
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706251404s599262cw309916b3dedc1633@mail.gmail.com...
On 6/25/07, Gennadiy Rozental <gennadiy.rozental@thomson.com> wrote:
"Douglas Gregor" <dgregor@osl.iu.edu> wrote in message news:468025D2.4050102@osl.iu.edu...
Gennadiy Rozental wrote: The DocBook or BoostBook XML will be generated via Quickbook when needed. Or do you want the DocBook/BoostBook XML to always be in the source tree, even if it can be regenerated?
Yes. Essentially I should be able to generate docs for any library and know nothing about quickbook and it's tools whatsoever. And how you make this file - you own business.
I agree with Gennady. It is better for now to separate quickbook from dockbook.
We may ask authors to provide:
libs/{lib_name}/doc/{lib_name}.xml libs/{lib_name}/doc/--stringparam
I like .xml over .docbook but I have no strong opinions about this. The --stringparam contains parameters that affects the chunker, that have to be library independent.
I would prefer developers wishing to twick output parameters for any output to generate <output>.xsl in corresponding doc directory. Gennadiy
Gennadiy Rozental wrote:
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:002301c7b741$0798cc40$0200a8c0@hetp7...
I think the weight of opinion is firmly behind keeping Quickbook as a favoured, but not exclusive, Boost docs tool.
Let me clarify again my point:
Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release.
I don't disagree with the above; it's OK to have a Boost-wide requirements for documentation, and I personally have no opinion on which one it should be. However I should stress that *neither the current form of .xml nor .qbk is documentation* as far as I'm concerned. Both are intermediate formats that are of no practical use without further processing. I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be. CVS users of Boost should not be considered second-class citizens; they should have access to human-readable documentation as well.
On 6/25/07, Peter Dimov <pdimov@mmltd.net> wrote:
Gennadiy Rozental wrote:
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:002301c7b741$0798cc40$0200a8c0@hetp7...
I think the weight of opinion is firmly behind keeping Quickbook as a favoured, but not exclusive, Boost docs tool.
Let me clarify again my point:
Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release.
I don't disagree with the above; it's OK to have a Boost-wide requirements for documentation, and I personally have no opinion on which one it should be.
However I should stress that *neither the current form of .xml nor .qbk is documentation* as far as I'm concerned. Both are intermediate formats that are of no practical use without further processing.
In my opinion release version must include both xml and html versions of the docs. We should store only the xml in the svn repository so the project size is more user friendly.
I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be. CVS users of Boost should not be considered second-class citizens; they should have access to human-readable documentation as well.
Good point. But I think we should not bloat the repository. What about a adding a boost_docs tree with the last snapshot of the documentation. Best regards Matias
Matias Capeletto wrote:
I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be. CVS users of Boost should not be considered second-class citizens; they should have access to human-readable documentation as well.
Good point. But I think we should not bloat the repository. What about a adding a boost_docs tree with the last snapshot of the documentation.
It appears to be down now, but MetaComm typically generates HTML from BoostBook nightly at http://engineering.meta-comm.com/boost-boostbook/BoostBook-RC_1_34_0/index.h... (for the 1.34.x branch) This is the right solution: generate documentation from active branches nightly and have them available on boost.org. It would be wasteful to put this information in any repository, since it can all be regenerated. - Doug
"Peter Dimov" <pdimov@mmltd.net> writes:
Gennadiy Rozental wrote:
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:002301c7b741$0798cc40$0200a8c0@hetp7...
I think the weight of opinion is firmly behind keeping Quickbook as a favoured, but not exclusive, Boost docs tool.
Let me clarify again my point:
Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release.
I don't disagree with the above; it's OK to have a Boost-wide requirements for documentation, and I personally have no opinion on which one it should be.
However I should stress that *neither the current form of .xml nor .qbk is documentation* as far as I'm concerned. Both are intermediate formats that are of no practical use without further processing. I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be. CVS users of Boost should not be considered second-class citizens; they should have access to human-readable documentation as well.
In general it is not a very good idea to use a version control system to store generated files, because they will waste space, and they must not be edited anyway. It seems that what is really needed is an easy way for anyone to generate the documentation (in any of the supported formats, like HTML, PDF, etc.) from the source files (boostbook or docbook or quickbook files, or source code in the case of doxygen). If there is not already a command in the build system to do this either for all of boost or for an individual project, then there should be one. If special tools not distributed with Boost are needed, they should be noted in an easy to find place on the Boost website. -- Jeremy Maitin-Shepard
Peter Dimov wrote:
I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be.
By using http://www.badgers-in-foil.co.uk/projects/docbook-css/ it's possible to view DocBook XML. Not particularly pretty, but beats looking at the raw XML. There seem to be other CSS stylesheets for DocBook as well. http://wiki.docbook.org/topic/DocBookCssStylesheets
On 6/25/07, Peter Dimov <pdimov@mmltd.net> wrote:
Peter Dimov wrote:
I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be.
By using
http://www.badgers-in-foil.co.uk/projects/docbook-css/
it's possible to view DocBook XML. Not particularly pretty, but beats looking at the raw XML. There seem to be other CSS stylesheets for DocBook as well.
Great! Once we settled down with a particular look & feel we can easily hack this stylesheet to look similar to it. I have download the this css and this seems pretty easy. Best regards Matias
Hi, I am experimenting with QuickBook to produce HTML docs. I found that in the build directory, some .xml and a .docbook file are created. If a *.docbook file is a DOCBOOK, then I succeeded in opening a Docbook with the program Yelp (which should be a GNOME documentations viewer). It looks fine, like a CHM doc... Regards, Manuel Fiorelli
Manuel Fiorelli wrote:
Hi, I am experimenting with QuickBook to produce HTML docs. I found that in the build directory, some .xml and a .docbook file are created. If a *.docbook file is a DOCBOOK, then I succeeded in opening a Docbook with the program Yelp (which should be a GNOME documentations viewer). It looks fine, like a CHM doc...
Yes, Yelp seems to be able to display DocBook. It claims to use the gnome-doc-utils XSL stylesheets for that: http://www.linuxfromscratch.org/blfs/view/svn/gnome/gnome-doc-utils.html I wasn't able to get them to work in IE7 or Firefox 2, though, and the error messages are uninformative. :-/
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:018a01c7b752$26407bf0$6407a80a@pdimov2...
Peter Dimov wrote:
I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be.
By using
Hmm. Why not regular single or multi chunk HTML output stylesheet? You open XML file with browser and see regular HTML. Gennadiy
Gennadiy Rozental wrote:
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:018a01c7b752$26407bf0$6407a80a@pdimov2...
Peter Dimov wrote:
I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be.
By using
Hmm. Why not regular single or multi chunk HTML output stylesheet?
No idea. Given that the XML->HTML conversion is done via XSLT, I'd have expected the XML files to already come with an associated XSLT stylesheet, but they do not. The above was what I found in the limited time I spent looking for a DocBook stylesheet. Apparently, the XmlMind editor also contains a CSS stylesheet for DocBook. The exact method is not important. What matters is that the user should be able to view the documentation in at least Firefox, and hopefully IE7 as well. It might be reasonable to require a 'bjam' invocation for libraries that need building anyway, but a requirement to install a BoostBook toolchain seems a bit steep (in this light I view QuickBook as an improvement as it can - IIUC - produce HTML docs from a single 'bjam' command given a fresh Boost tree). For header-only libraries that don't even require bjam to be present, everything besides readily-accessible HTML would be a regression.
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:01f901c7b76b$b3f46330$6407a80a@pdimov2...
Gennadiy Rozental wrote:
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:018a01c7b752$26407bf0$6407a80a@pdimov2...
Peter Dimov wrote:
I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet, but currently they don't seem to be.
By using
Hmm. Why not regular single or multi chunk HTML output stylesheet?
No idea. Given that the XML->HTML conversion is done via XSLT, I'd have expected the XML files to already come with an associated XSLT stylesheet,
You can do this in general sinbce there are different stylesheets you can apply to produce different outputs.
but they do not. The above was what I found in the limited time I spent looking for a DocBook stylesheet. Apparently, the XmlMind editor also contains a CSS stylesheet for DocBook.
Using xml-stylesheet processing instruction allows you to assign stylesheet to the XML file and see it accordingly.
The exact method is not important. What matters is that the user should be able to view the documentation in at least Firefox, and hopefully IE7 as well.
Boost release version users - yes. CVS version users - I don't think so.
It might be reasonable to require a 'bjam' invocation for libraries that need building anyway, but a requirement to install a BoostBook toolchain seems a bit steep
It's not nesseserily required. We can do what DocBook does and provide an access to the current release stylesheets online. (in this light I view QuickBook as an
improvement as it can - IIUC - produce HTML docs from a single 'bjam' command given a fresh Boost tree). For header-only libraries that don't even require bjam to be present, everything besides readily-accessible HTML would be a regression.
In released version there should be both XML and HTML (at least). In cvs - I don't think so. But with stylesheet available only it can be done with the single xml-stylesheet processing instruction. Gennadiy
Gennadiy Rozental wrote:
Using xml-stylesheet processing instruction allows you to assign stylesheet to the XML file and see it accordingly.
Sure. Have you tried, and does it work for you? Can you share the stylesheet you used?
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:022901c7b76e$ad1b1fb0$6407a80a@pdimov2...
Gennadiy Rozental wrote:
Using xml-stylesheet processing instruction allows you to assign stylesheet to the XML file and see it accordingly.
Sure. Have you tried, and does it work for you?
I did that at work for configuration files I use.
Can you share the stylesheet you used?
You don't understand. You will use regular BoostBook stylesheets. Gennadiy
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> wrote in message news:f5r7el$jr6$1@sea.gmane.org...
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:022901c7b76e$ad1b1fb0$6407a80a@pdimov2...
Gennadiy Rozental wrote:
Using xml-stylesheet processing instruction allows you to assign stylesheet to the XML file and see it accordingly.
Sure. Have you tried, and does it work for you?
I did that at work for configuration files I use.
Can you share the stylesheet you used?
You don't understand. You will use regular BoostBook stylesheets.
I just recalled that IE XSLT processor is too dumb/buggy. But you might can use some other. Genandiy
Gennadiy Rozental wrote:
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:022901c7b76e$ad1b1fb0$6407a80a@pdimov2...
Gennadiy Rozental wrote:
Using xml-stylesheet processing instruction allows you to assign stylesheet to the XML file and see it accordingly.
Sure. Have you tried, and does it work for you?
I did that at work for configuration files I use.
Can you share the stylesheet you used?
You don't understand. You will use regular BoostBook stylesheets.
What did you do to get them to work in a browser? What is your xml-stylesheet PI?
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:001701c7b804$dd9f40d0$6407a80a@pdimov2...
Gennadiy Rozental wrote:
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:022901c7b76e$ad1b1fb0$6407a80a@pdimov2...
Gennadiy Rozental wrote:
Using xml-stylesheet processing instruction allows you to assign stylesheet to the XML file and see it accordingly.
Sure. Have you tried, and does it work for you?
I did that at work for configuration files I use.
Can you share the stylesheet you used?
You don't understand. You will use regular BoostBook stylesheets.
What did you do to get them to work in a browser? What is your xml-stylesheet PI?
abc.xml <?xml version="1.0" encoding="utf-8" standalone="no" ?> <?xml-stylesheet href="<output>.xsl" type="text/xsl"?> Gennadiy
Peter: Can you share the stylesheet you used?
Gennady: You don't understand. You will use regular BoostBook stylesheets.
Peter: What did you do to get them to work in a browser? What is your xml-stylesheet PI?
Gennady: abc.xml
I think you are being too sarcastic. It makes me feel uncomfortable Gennady. We are not web experts, but we are eager to learn and work to make boost better. Best regards Matias
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706260845u6635ec1dqc50db9232f087b37@mail.gmail.com...
Peter: Can you share the stylesheet you used?
Gennady: You don't understand. You will use regular BoostBook stylesheets.
Peter: What did you do to get them to work in a browser? What is your xml-stylesheet PI?
Gennady: abc.xml
I think you are being too sarcastic. It makes me feel uncomfortable Gennady. We are not web experts, but we are eager to learn and work to make boost better.
I am not sure where did you find a trace of sarcasm in what I wrote. I am not a web expect by any standards as well and still learning this staff as well. Gennadiy
Gennadiy Rozental wrote:
What did you do to get them to work in a browser? What is your xml-stylesheet PI?
abc.xml <?xml version="1.0" encoding="utf-8" standalone="no" ?> <?xml-stylesheet href="<output>.xsl" type="text/xsl"?>
Works in neither IE7 nor Firefox 2, even after a bit of fiddling (like removing the DTD to appease IE7 and downloading the DocBook XSLs locally to appease Firefox).
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:005801c7b80b$4dff8190$6407a80a@pdimov2...
Gennadiy Rozental wrote:
What did you do to get them to work in a browser? What is your xml-stylesheet PI?
abc.xml <?xml version="1.0" encoding="utf-8" standalone="no" ?> <?xml-stylesheet href="<output>.xsl" type="text/xsl"?>
Works in neither IE7 nor Firefox 2, even after a bit of fiddling (like removing the DTD to appease IE7 and downloading the DocBook XSLs locally to appease Firefox).
Heh, I had some hopes for Firefox at least. Well, it should (theoretically). It just docbook stylesheets are way too complicated. What errors does it produce? Gennadiy
Gennadiy Rozental wrote:
Heh, I had some hopes for Firefox at least.
Well, it should (theoretically). It just docbook stylesheets are way too complicated.
FWIW, I use this technique to display an rss changelog as part of a website (http://synopsis.fresco.org/changelog.rss), and it works fine. But docbook stylesheets are indeed quite a different ball game. They aren't meant to be used on the client side (but they still should work, I believe). Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
"Peter Dimov" <pdimov@mmltd.net> wrote in message news:014b01c7b748$f2894840$6407a80a@pdimov2...
Gennadiy Rozental wrote:
"Paul A Bristow" <pbristow@hetp.u-net.com> wrote in message news:002301c7b741$0798cc40$0200a8c0@hetp7...
I think the weight of opinion is firmly behind keeping Quickbook as a favoured, but not exclusive, Boost docs tool.
Let me clarify again my point:
Boost should require BoostBook as a documentation format. This is the format documentation should be kept in source control and delivered with release.
I don't disagree with the above; it's OK to have a Boost-wide requirements for documentation, and I personally have no opinion on which one it should be.
However I should stress that *neither the current form of .xml nor .qbk is documentation* as far as I'm concerned.
It is. If we call it this way ;)
Both are intermediate formats that are of no practical use without further processing.
Not nesseserily. but this is beyond the point.
I admit that it would be possible to make the .xml files viewable in a browser by using a stylesheet,
and it should be
but currently they don't seem to be. CVS users of Boost should not be considered second-class citizens; they should have access to human-readable documentation as well.
I don't agree. There multiple different formats we can produce from DocBook. HTML in chunks, HTML in one chunk, PDF, HTML help and so on. Which one do you believe we need to keep under source control. I don't consider CVS users of boost first class citizen. They are kinda upper class. If you opted to deal with cvs version of boost, deal with doc generation in your favorite format. And I don't think this is a problem under regular circumstances. The fact that 1.34 took so long should be an exclusion. With regular - every 3 month - releases the need for direct cvs access by users should be minimal. Gennadiy
"Matias Capeletto" <matias.capeletto@gmail.com> wrote in message news:e9b043a10706230726t49a5b8e7k7fa5ae49bb3ae10a@mail.gmail.com...
I. quickbook as documentation media.
Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format.
As Joel said it is *my* business too. And IMHO you are too. We could use a different thing than Boost.Test, but I am very happy with it and I really appreciate such a wonderful project is maintained by a boost developer.
This is not exactly the same thing. Boost.Test is c++ library to be used by c++ developers. Documentation format is used by writers to write a book/article etc (in our specific case developers are writers, but this doesn't change a thing). Boost as a community (and I don't mean any particular person) should concentrate on first domain (C++ libraries development) IMO and should use existing formats for documentation writing. That doesn't mean that any one particular booster can't work on something else outside the bounds of boost.
DocBook is very mature, well supported project. It's based on widely accepted/supported technologies. It's powerful and configurable to implement essentially anything one need. I personally don't see much valid reasons to look in home grown format direction.
First of all. I will be proposing to use Quickbook even if it is not inside Boost.
And I would object as much. Boost should use accepted standards for anything beyond our expertise.
I really think that Quickbook (plus the necessary backend) is a hell of a documenting tool and IMHO in the future other projects will start to using it (Yesterday I spend part of the day working on a boost agnostic version of boostbook to better support outsiders)
Also there is a big difference between our homegrown build system. As Joel state it we are proposing dockbook as our documentation format
You might as well claim HTML or PDF as your backend. They both well standardized and supported. That doesn't change the fact that quickbook format has nothing to do with them (as well as with DocBook one)
backend, this allow us to be sure we have a lot of support from the outside (there are tools, documentation, a community, etc).
How DocBook tools are going to help write quickbook? Does DocBook community is going to answer quickbook related questions? How reading DocBook docs helps me in any way other than confuse me?
Quickbook and boostbook is very small (but yet powerful) layer that IMHO works better for us. If you want to write in docbook, it is ok. I really think you will change your opinion when you use both tools for a while. You can not make strong statements without trying them.
I am using XML based solution in my everyday development.
Here some specific points:
1. Simplicity Some people argues that it's easier to type quickbook I might argue that it's actually opposite. Granted if you use vi XML editing is not fun. But myriads of modern XML editors simplify the process marginally. There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. In addition you get immediate format validation and presentation (using assigned stylesheets)
I have use these tools and they are very good indeed. The same thing happens to latex, the LyX project allows you to write almost WYSWYG and it is a handy tool to know but if you asked around, almost everybody will tell you that they prefer and are far more productive writing directly in latex. It is the same with Quickbook, once you use it for a while you will be very productive and happy as is. The only aid I need is something like this: http://tinyurl.com/2ll5tk
Well our needs and preferences are different.
2. Any change in DocBook have to be reflected in quickbook terms
IMHO this is not the idea.
Meaning? So I can't use any new feature introduced in DocBook?
3. Someone need to maintain quickbook parser/transformer
There are a lot of people interested in maintained it and we have Joel with us ;) I am really interested in offer my help to maintain the boost docs tools.
It still require support. And I am sure the workload will grow once it usage is widespread.
4. quickbook will never be as flexible as DocBook
We are not looking for more flexibility, we are aiming at simplicity. If you need the extra complexity just write docbook, it is compatible
I am not looking for complexity. I am looking for flexibility.
with the current efforts. But please first tell us what have you fail to do in quickbook, it may be that you just do not have enough experience with it. Moreover... quickbook templates rocks and in the feature quickbook will be even thinner.
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Believe me that I am working very hard to low the barrier.
I believe you ;) It's still going to be there, unless you are ready to accept the responsibility of writing the documentation for everyone submitting new library.
II. BoostBook
1. Complexity The BoostBook being an extension to DocBook seems to be doing too much. IMO any useful generic innovations should be proposed to the DocBook developers and eventually removed. All in all we should strive to make this layer as thin as possible.
Docbook is a very slow changing project. It has to be. I have been hacking boostbook internals for the last two weeks. I have simplify a lot of things. I am currently working on documentation. I hope to have it ready soon.
2. Test suites support. I did not really grasp the idea behind this feature completely, but from what I understand this is "misfeature" and should be removed
I have never used it, no strong opinion here.
3. Tight coupling with Boost.Build This is major problem I believe. Especially in documentation. BoostBook should be presented as independent project. It should be explained how to use it, configure it without any reference to Boost.Build at all. At the very last chapter of documentation we may refer that if you want you docs to be automatically generated on some remote host (if let's say you don't have all the tools set up locally for all the formats) this is what you need to do .....
I am working to make boostbook a boost agnostic tool.
Are you going to go through formal review? Did you submit review request? How should we ask to review XSLT based solution?
3. Frames I personally need frames support for the reference like pages (like in preprocessor and test libraries). I am open to the alternative that presents similar L&F.
Frames are bad friend of the new web. They are not embrace by standards. I am working in an optional sidebar that will let you do the same.
What I am looking for is 4 area solution(header, footer, list, concrete page)
I hope we can work together to move things in the right direction. IMO your direction is a lot more similar from the current "Improving Boost Docs" project that you think.
My position is that we do need to improve the documentation. But we should use recommended standards for this. Even if it means a bit more work for some people. Gennadiy
Gennady, I will let other people participate in the discussion. But I want to state one more time that the current effort to achieve a common look & feel for Boost docs needs that the standard format for boost documentation be "docbook", we are not trying to impose the quickbook format. Please do not forget that. We want xml docs because they are wonderful to work with. Please separate the discussion of whether to use docbook as the standard docs from using Quickbook. A lot of people have started to love Quickbook and when translating the old docs we are writing in it because it is far more easy to maintain for us. We then use quickbook to convert this .qbk docs into docbook that (if things go right) will be the standard format required by boost. Do not mix things, we both want to see Boost going into the docbook format. If you do not want to use quickbook, just do not use it. Accept that what may be a bad tool for you can be a very productive, fun and just amazing tool for a lot of other people. Best regards Matias
Matias Capeletto wrote:
100% Agree with you. I have spend last two weeks learning Docbook, his history and where it is heading and I have to said I am really impressed too. Docbook 5 will rock, they are starting to use RelaxNG instead of DTD and will apply all the power of xsl 2. We should be really happy to have such an amazing and supported project as our backend.
That's good to learn. Docbook is finally going to start being good.
Gennadiy Rozental wrote:
1. Simplicity Some people argues that it's easier to type quickbook I might argue that it's actually opposite. Granted if you use vi XML editing is not fun. But myriads of modern XML editors simplify the process marginally. There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. In addition you get immediate format validation and presentation (using assigned stylesheets)
First, I would like to say that I do know a lot about XML and related technologies, at least enough to write XSL Stylesheets. While XML can be nice to structure textual data, I think XML is just plain horrible to author documents. Of course, I'm not talking of using a WYSIWYG editor, simply because I hate those, especially XML-related ones (actually, LyX is almost decent, but I'd rather use LaTeX directly). Editing a document with a wiki-like syntax just requires a regular text editor (syntax highlighting can be a nice addon though), and it already looks nice in the text editor. You're not lost with deep indentations of XML nodes. With wiki-like syntax, a table just looks like a table, to emphasize a word you actually emphasize it with special obvious characters, etc. Meaning you can quickly read and understand the document while editing it, unlike with XML where you have to figure out what the node tree is and what it does. I'm not the only one who likes that. Wiki syntaxes exist for a reason. Quickbook certainly isn't the best Wiki syntax ever, but it's still pretty good.
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
Hi,
I've been offline for a bit. But I was able to spend several weeks learning DocBook. I must say I was really impressed with quality of this project. I also tried to get a grasp of BoostBook and gave perfunctory look on quickbook. Here I would like to share my thoughts on recent "doc update" movement.
I. quickbook as documentation media.
Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format.
That's a concern for me, I must admit.
DocBook is very mature, well supported project. It's based on widely accepted/supported technologies. It's powerful and configurable to implement essentially anything one need. I personally don't see much valid reasons to look in home grown format direction. Here some specific points:
1. Simplicity Some people argues that it's easier to type quickbook
It is. And it's easier to read, too, which is even more important.
I might argue that it's actually opposite.
Really?
Granted if you use vi XML editing is not fun.
Nor XML reading!
But myriads of modern XML editors simplify the process marginally.
A marginal simplification is hardly enough to make it palatable.
There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow.
Yeah, but we need to represent semantic information (e.g. Concepts) that are outside the builtin representational abilities of DocBook. How well will these WYSIWYG editors handle BoostBook's special tags? Which editors are these, BTW?
In addition you get immediate format validation and presentation (using assigned stylesheets)
2. Any change in DocBook have to be reflected in quickbook terms
Problem, but minor. They're not going to fundamentally break backward compatibility.
3. Someone need to maintain quickbook parser/transformer
Problem.
4. quickbook will never be as flexible as DocBook
Disagree. It's far more flexible, because it has a whole macro language builtin.
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
6. Source code highlighting
My understanding is that quickbook presents some source code highlighting automation. IMO this can be either implemented as standalone C++ based tool that docs writers can use when required or even better it can be implemented in JavaScript. I believe I've seen it done.
I'm not sure I want to do that job on the browser, but I understand the appeal, especially if end-users can tune the colors.
All in all I believe using this format is going to be a maintenance problem in a long term and should be avoided. We should stick with industry standard DocBook IMO instead.
I don't think it's necessarily that clear-cut. However, there *are* other broadly-accepted tools, supported by others, (e.g. docutils) that we can use to produce DocBook, so it doesn't necessarily mean we're stuck with XML as our input format if we don't want to have to support our own front-end.
II. BoostBook
1. Complexity The BoostBook being an extension to DocBook seems to be doing too much. IMO any useful generic innovations should be proposed to the DocBook developers and eventually removed. All in all we should strive to make this layer as thin as possible.
I *seriously* doubt DocBook is going to accept C++-specific tags such as we use for concept documentation.
2. Test suites support. I did not really grasp the idea behind this feature completely, but from what I understand this is "misfeature" and should be removed
Well, before you jump the gun you should Google up "literate programming." Having an integrated way of testing code examples is critical to getting them right. We did that with Boost.Parameter (using a different system than QuickBook) and it made a huge difference. We also used that to test the examples in C++ Template Metaprogramming.
3. Tight coupling with Boost.Build
Huh?
This is major problem I believe. Especially in documentation. BoostBook should be presented as independent project. It should be explained how to use it, configure it without any reference to Boost.Build at all. At the very last chapter of documentation we may refer that if you want you docs to be automatically generated on some remote host (if let's say you don't have all the tools set up locally for all the formats) this is what you need to do .....
That's a documentation issue, not an intrinsic one. BoostBook is not coupled with Boost.Build at all.
4. Documentation I found documentation to be largely unacceptable (funny thing for the project dedicated to writing documentation)
a) No explanation how to use BoostBook without Boost.Build (see above)
That's a problem.
b) all he elements description are without examples
That's a problem.
c) most critical: no description whatsoever of all the modification done in comparison with DocBook. All the updated parameter need to be listed, all the updated templates need to be explained. General approach should be what the person familiar with DocBook (standard) need to know/expect to use BoostBook
That's a problem.
d) No explanation on how to extend the BoostBook (especially in comparison with DocBook)
That's a problem.
As I mentioned before we should try to limit our extensions to the most necessary only and strive to stick with standard DocBook. Also all extensions should be made optional.
Aren't they, currently?
III. What should we do?
IMO the standardization efforts need to target DocBook/BoostBook. On the other hand each developer should be allowed to extend/twick standard L&F. Usually differences should be only cosmetic.
Major cosmetic differences will keep Boost looking fractured.
Following are general observations about common L&F
1. JS Menu support. I believe it should be implemented but made optional.
Why not just let the user show/hide it?
I personally don't like it (I believe it's just wait of space for this menu to stay on all the time) and prefer "location path" kinda navigation Boost.Test currently using.
Breadcrumbs are nice.
2. Header on top. I don't believe it's necessary. Neither in a form of boost|libraries|more|... nor what is currently proposed. This information is accessible from boost main page. No need to duplicate it on every page of every library.
3. Frames I personally need frames support for the reference like pages (like in preprocessor and test libraries). I am open to the alternative that presents similar L&F.
Frames don't interact well with bookmarks and sending people links into the documentation.
4. Portability This is major requirement for all the features we implement. They should work on at least set of predefined "major" browsers.
Yep. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com
David Abrahams wrote:
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format.
That's a concern for me, I must admit.
I'm glad to hear that.
There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow.
Yeah, but we need to represent semantic information (e.g. Concepts) that are outside the builtin representational abilities of DocBook.
DocBook is designed for extensibility. That's becoming even more true with the new DocBook 5. It is possible to refine the document type (e.g. add custom vocabulary), as well as add custom (xslt) templates to be used in the processing pipeline when generating html, pdf, etc.
How well will these WYSIWYG editors handle BoostBook's special tags?
I'm not aware of fany DocBook editors, only XML editors. And these don't notice 'special tags'. You feed them a document type (DTD, RelaxNG, XSchema, etc.), and they Just Work.
Which editors are these, BTW?
The one I have run across is xxe (http://www.xmlmind.com/xmleditor/). But I'm mostly using (x)emacs, which has its own xml-editing modes that will happily accept any customization layer, too. [...]
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
There are other standard languages that could be used as a mixin, such as ReST. The point is not only syntactical ease. But having independent development / maintainence, documentation, etc., is invaluable. That's essentially the first argument above.
1. Complexity The BoostBook being an extension to DocBook seems to be doing too much. IMO any useful generic innovations should be proposed to the DocBook developers and eventually removed. All in all we should strive to make this layer as thin as possible.
I *seriously* doubt DocBook is going to accept C++-specific tags such as we use for concept documentation.
I had some discussions with Norman Walsh over the years, when I realized that DocBook was a bit inconsistent in its support for language-specific artifacts. The tricky thing is that DocBook is a documentation language, not a modeling language. I do believe it would be good to be able to represent more language artifacts (I have a hard time deciding what kind of DocBook to generate with my Synopsis reference manual generator), but I understand the concern about language bloat that may incur, at least if these changes got into the core vocabulary. Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Stefan Seefeld wrote:
David Abrahams wrote:
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
Why, oh, why don't we learn from our own mistakes. We just started to realize the problem we got ourselves into with makesystem. And immediately find new toy to play with. However fun it is, however cool it might look on first sight, THIS IS NOT OUR BUSENESS to invent/support documentation format. That's a concern for me, I must admit.
I'm glad to hear that.
I was the one who re-targeted Joel's QuickDoc/HTML to generate BoostBook/XML, added the Doxygen integration and re-christened it QuickBook. It was a quick hack so that I could write xpressive's docs. I needed something that would let me write docs fast in a plain text editor, with cross-links to a reference section generated by Doxygen. I wasn't aware of any tool that fit that description. I'm still not. I see a lot of talk about XML editors. I don't want to edit XML, fancy editor or not. My personal preference is for plain text editors and simple mark-up. I'm all for standardizing on DocBook. I'm also all for unifying the look-and-feel of the docs across all of boost. If we decide that all Boost docs must be in DocBook XML, that's peachy. But unless someone shows me a better way, I'll probably continue using QuickBook and Doxygen to generate the DocBook XML. I don't see why that's any cause for concern. After all, QuickBook is just a dumb translator. We can convert any QuickBook file into DocBook at any time -- no harm done. I would be concerned if I saw a lot of people wasting time struggling with QuickBook. But the reality is quite the opposite -- I think it has been a real time-saver for people. So what is the problem? <snip>
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters. Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
There are other standard languages that could be used as a mixin, such as ReST. The point is not only syntactical ease. But having independent development / maintainence, documentation, etc., is invaluable. That's essentially the first argument above.
I'm very sympathetic to this argument. I've never used ReST. I know Dave has. Can I cross-link to a Doxygen-generated section? I can point Doxygen to a C++ header foo.hpp that has a class foo and create a foodoc.xml reference section. In my QuickBook file I can [xinclude foodoc.xml] and then link to the auto-generated reference for class foo simply by saying [classref foo]. How would I do that with ReST? Incidentally, I'm not opposed to someone else using ReST. I'm also not opposed to Matias offering to help people move their docs to QuickBook. Users can decide for themselves whether to accept Matias' (very generous) offer. Nobody is forcing anything on anybody. -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
Incidentally, I'm not opposed to someone else using ReST. I'm also not opposed to Matias offering to help people move their docs to QuickBook. Users can decide for themselves whether to accept Matias' (very generous) offer. Nobody is forcing anything on anybody.
And we should at the very least be thankful to Matias (and folks helping him). He's (and of course those helping him) doing all the work -- and that's an enormous task ahead of him (them). I don't see any reason why we shouldn't give him the prerogative to choose whichever path he thinks is best for the task at hand. It just so happens that he feels quickbook is the easiest path. But really, I don't see any of the FUD against it have any bearing at all. As many have hinted, you can always throw away the qbk intermediate files and use straight docbook if it's not to your likings. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Eric Niebler wrote: I'm barely following this discussion b/c I'm in a time crunch, but as an avid Quickbook fan I think I should chime in...
I was the one who re-targeted Joel's QuickDoc/HTML to generate BoostBook/XML, added the Doxygen integration and re-christened it QuickBook. It was a quick hack so that I could write xpressive's docs. I
And thx for doing so, Quickbook has saved me much time over the last couple years especially writing standards proposals.
needed something that would let me write docs fast in a plain text editor, with cross-links to a reference section generated by Doxygen. I wasn't aware of any tool that fit that description. I'm still not. I see a lot of talk about XML editors. I don't want to edit XML, fancy editor or not. My personal preference is for plain text editors and simple mark-up.
Nor I. I've looked at various XML editors and always been bitterly disappointed -- they all stink as far as I'm concerned. I always wind up back at emacs. But even emacs with XML modes can't really overcome the problems with with XML. And trust me, I know, all the date-time docs are in BoostBook. It's really painful to edit them because the signal/noise ratio of XML is so low. And it's really hard to get nice looking C++ examples with richly colored text. What makes Quickbook so attractive is to me is that 1) it's signal to noise ratio is high (that is, little distraction from the actual content caused by the 'required structure'), 2) C++ code examples can be copied and pasted directly into text, 3) it supports easy hypertext linking, 4) since it's all simple text it means that regular version control and diff is very powerful for tracking changes, 5) it's editable in anything that can edit plain text, 6) I can get both html and pdf out the back.
I'm all for standardizing on DocBook. I'm also all for unifying the look-and-feel of the docs across all of boost. If we decide that all
Me too -- the irony being that it's mostly the DocBook toolchain that causes problems for people...
Boost docs must be in DocBook XML, that's peachy. But unless someone shows me a better way, I'll probably continue using QuickBook and Doxygen to generate the DocBook XML. I don't see why that's any cause for concern. After all, QuickBook is just a dumb translator. We can convert any QuickBook file into DocBook at any time -- no harm done.
I would be concerned if I saw a lot of people wasting time struggling with QuickBook. But the reality is quite the opposite -- I think it has been a real time-saver for people. So what is the problem?
Exactly...QuickBook is trivial to learn and use (partially because of it's simplicity and partially because the docs rock)...it's DocBook that took most of the struggle for me -- setting up the tools, writing a perl script to get rid of boost build and BoostBook xslt crud, etc. I agree that we can't can't/shouldn't force anyone to move to Quickbook and I even worry about BoostBook/DocBook. That said, so far our standard has been html. But html creates lots of problems in getting similar looking documentation (and pdf, of course) -- and I really think that's a big problem we (Boost) should solve. I think half of what makes PHP viable is good looking consistent docs - some Java docs really stink, but the common look and feel helps developers navigate large collections of libraries. Perl/Python...the list goes on -- all these languages/libraries have standard documentation systems to handle large sets of libraries. This lack of common feel in the docs I do think holds back C++ in comparison. For that reason alonge, as the premier place for C++ library development I think it's quite reasonable that Boost would push this envelope and set the standard. Anyway, I really think most developers that actually do the work of documenting something non-trivial in html or DocBook and then try Quickbook (Rest is likely similar) will be converts to Quickbook. And I think we should seriously consider upping the ante and requiring BoostBook/DocBook going forward so that we can get a unified look and feel. Jeff
Stefan Seefeld wrote:
David Abrahams wrote:
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters. Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
There are other standard languages that could be used as a mixin, such as ReST.
ReST nor DocBook are any more standard than Quickbook, AFAIK. If you want standard stick to HTML (ISO/IEC 15445:2000), ODA (ISO 8613), or perhaps OpenDocument (ISO/IEC 26300:2006). ReST and DocBook are more widely used than Quickbook though. -- -- 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
Rene Rivera wrote:
ReST nor DocBook are any more standard than Quickbook, AFAIK.
By what metric ? I'm not talking about ISO, ECMA, or other standardization bodies. I'm talking about widespread use, a vibrant developer community that is quick to help or fix bugs, and everything else that makes such tools healthy. And, as far as standardization is concerned, docbook is part of the club, too (see http://www.oasis-open.org/docbook/). Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Note, Stefan I'm not really directing these at you. They are just arguments in regards to the mistaken, and self contradictory, idea that we should only use "standard" tools, formats, whatever. Stefan Seefeld wrote:
Rene Rivera wrote:
ReST nor DocBook are any more standard than Quickbook, AFAIK.
By what metric ? I'm not talking about ISO, ECMA, or other standardization bodies.
I was; to indirectly make the point that standards start out not being standard ;-)
I'm talking about widespread use, a vibrant developer community that is quick to help or fix bugs, and everything else that makes such tools healthy.
Then why use the word "standard"? And why try and squelch attempts to build such a community?
And, as far as standardization is concerned, docbook is part of the club, too (see http://www.oasis-open.org/docbook/).
OK. -- -- 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
Rene Rivera wrote:
ReST nor DocBook are any more standard than Quickbook, AFAIK. By what metric ? I'm not talking about ISO, ECMA, or other standardization bodies.
I was; to indirectly make the point that standards start out not being standard ;-)
That's a fair point.
I'm talking about widespread use, a vibrant developer community that is quick to help or fix bugs, and everything else that makes such tools healthy.
Then why use the word "standard"? And why try and squelch attempts to build such a community?
Because, as others have phrased it, this is not (or at least, shouldn't be) boost.org's business. Nothing speaks against trying to develop new languages, infrastructure bits, etc. However, with all due appreciation for perfectionism, it is a very common mistake to ignore or underestimate the importance of well established know-how. It's really a sad story. Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Stefan Seefeld wrote:
Rene Rivera wrote:
Then why use the word "standard"? And why try and squelch attempts to build such a community?
Because, as others have phrased it, this is not (or at least, shouldn't be) boost.org's business.
But no one has said Quickbook is Boost's business. It is specifically Joel, Eric, mine, and anyone else who wants to contribute or participate by the use of Quickbook.
Nothing speaks against trying to develop new languages, infrastructure bits, etc. However, with all due appreciation for perfectionism, it is a very common mistake to ignore or underestimate the importance of well established know-how. It's really a sad story.
Indeed. But then again people assume that because it's not "old" or "established" that it's not taking advantage of established know-how. Or that it's not based on previous success of other documentation facilities. We all stand on shoulders of giants, and I refuse to be trampled on the ground by apathy. And in case people don't know, probably because they haven't read the Quickbook docs, Quickbook is based on the populous Wiki formats (which also happens to borrow from a long tradition of email formatting). -- -- 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
Stefan Seefeld wrote:
DocBook is designed for extensibility. That's becoming even more true with the new DocBook 5. It is possible to refine the document type (e.g. add custom vocabulary), as well as add custom (xslt) templates to be used in the processing pipeline when generating html, pdf, etc.
[snip]
I had some discussions with Norman Walsh over the years, when I realized that DocBook was a bit inconsistent in its support for language-specific artifacts. The tricky thing is that DocBook is a documentation language, not a modeling language. I do believe it would be good to be able to represent more language artifacts (I have a hard time deciding what kind of DocBook to generate with my Synopsis reference manual generator), but I understand the concern about language bloat that may incur, at least if these changes got into the core vocabulary.
I started BoostBook precisely because of this problem. DocBook was (is) a decent, well-supported standard format for documentation, but it's support for C++ was non-existent. BoostBook was meant to be DocBook extended to support the description of C++ interfaces/declarations so that we could build good reference documentation manually and merge that with documentation extracted from source code (currently, via Doxygen). You mentioned that DocBook 5 is meant to be more extensible... might it possible for our C++ markup to be introduced into DocBook 5 as some kind of custom vocabulary? I'd love to minimize the distance between BoostBook and DocBook, but the need for Boost- and C++-specific features pushed them apart further than one would like. Perhaps with a more extensible DocBook 5, and Matias et. al.'s new work on the BoostBook/Quickbook toolchain, we can simplify things and move back closer to DocBook. But make no mistake: DocBook alone is insufficient for Boost, and standards are only useful when they solve your problems. - Doug
Douglas Gregor wrote:
You mentioned that DocBook 5 is meant to be more extensible... might it possible for our C++ markup to be introduced into DocBook 5 as some kind of custom vocabulary? I'd love to minimize the distance between BoostBook and DocBook, but the need for Boost- and C++-specific features pushed them apart further than one would like. Perhaps with a more extensible DocBook 5, and Matias et. al.'s new work on the BoostBook/Quickbook toolchain, we can simplify things and move back closer to DocBook. But make no mistake: DocBook alone is insufficient for Boost, and standards are only useful when they solve your problems.
The reason I'm saying extensions will be easier to generate is that docbook 5 is specified by means of RelaxNG, not DTD. I have no idea about how hard / sensible it is to attempt to either make such changes get approval of the docbook technical commitee, or to keep it in a separate profile. Such questions are best asked on the docbook list (docbook@lists.oasis-open.org). Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
on Sun Jun 24 2007, Stefan Seefeld <seefeld-AT-sympatico.ca> wrote:
David Abrahams wrote:
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow.
Yeah, but we need to represent semantic information (e.g. Concepts) that are outside the builtin representational abilities of DocBook.
DocBook is designed for extensibility.
I know. That's why I said *builtin*. BoostBook is just an extension of DocBook, using expressly-designed hooks in DocBook for that purpose. I don't consider that an NIH move on our part; quite the contrary.
How well will these WYSIWYG editors handle BoostBook's special tags?
I'm not aware of fany DocBook editors, only XML editors. And these don't notice 'special tags'. You feed them a document type (DTD, RelaxNG, XSchema, etc.), and they Just Work.
Yeah, well Gennadiy cited WYSIWYG.
Which editors are these, BTW?
The one I have run across is xxe (http://www.xmlmind.com/xmleditor/). But I'm mostly using (x)emacs, which has its own xml-editing modes that will happily accept any customization layer, too.
Yeah, that's fine too; I use emacs. It's just not quite WYSIWYG... not that it's a problem for me.
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
There are other standard languages that could be used as a mixin, such as ReST.
Yes. Big fan here. C++ TMP and the MPL reference and Boost.Parameter docs and the new getting started guide were all written in ReST.
The point is not only syntactical ease. But having independent development / maintainence, documentation, etc., is invaluable. That's essentially the first argument above.
Yes, it's huge. Someone else wrote an emacs editing mode for ReST that works great. I had to try to write a qbk-mode. It took a long time. It doesn't work great. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com
David Abrahams wrote:
on Sun Jun 24 2007, Stefan Seefeld <seefeld-AT-sympatico.ca> wrote:
David Abrahams wrote:
There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. Yeah, but we need to represent semantic information (e.g. Concepts)
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote: that are outside the builtin representational abilities of DocBook. DocBook is designed for extensibility.
I know. That's why I said *builtin*.
BoostBook is just an extension of DocBook, using expressly-designed hooks in DocBook for that purpose. I don't consider that an NIH move on our part; quite the contrary.
Yes, understood. With NIH I'm not referring to BoostBook, but to QuickBook, which is neither an extension to DocBook, nor ReST. Thus, no existing parser will work with it, no existing documentation will help, and no existing community can answer questions and help resolve issues. (For the record: I did bring up the BoostBook extension on the #docbook IRC channel, and people, including Norman Walsh, where quite favorable to the idea of getting BoostBook or a variant thereof integrated into DocBook, if only as a 'C++ profile'. That would make it easier to let it evolve together with DocBook, and would help boost developers focus on the Real Stuff. ;-) )
How well will these WYSIWYG editors handle BoostBook's special tags? I'm not aware of fany DocBook editors, only XML editors. And these don't notice 'special tags'. You feed them a document type (DTD, RelaxNG, XSchema, etc.), and they Just Work.
Yeah, well Gennadiy cited WYSIWYG.
Which editors are these, BTW? The one I have run across is xxe (http://www.xmlmind.com/xmleditor/). But I'm mostly using (x)emacs, which has its own xml-editing modes that will happily accept any customization layer, too.
Yeah, that's fine too; I use emacs. It's just not quite WYSIWYG... not that it's a problem for me.
There are (as you surely know) long discussions about the WYSIWYG paradigm, and by what that could be replaced in the context of structured documents. However, for all practical purposes, I do consider the above editor (xxe) to be WYSIWYG. People do have a choice, if they really want. FWIW, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Stefan Seefeld wrote:
David Abrahams wrote:
on Sun Jun 24 2007, Stefan Seefeld <seefeld-AT-sympatico.ca> wrote:
David Abrahams wrote:
There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. Yeah, but we need to represent semantic information (e.g. Concepts)
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote: that are outside the builtin representational abilities of DocBook. DocBook is designed for extensibility. I know. That's why I said *builtin*.
BoostBook is just an extension of DocBook, using expressly-designed hooks in DocBook for that purpose. I don't consider that an NIH move on our part; quite the contrary.
Yes, understood. With NIH I'm not referring to BoostBook, but to QuickBook, which is neither an extension to DocBook, nor ReST. Thus, no existing parser will work with it, no existing documentation will help, and no existing community can answer questions and help resolve issues.
Let me repeat the point about QuickBook I made earlier, since you seem to have missed it:
I needed something that would let me write docs fast in a plain text editor, with cross-links to a reference section generated by Doxygen. I wasn't aware of any tool that fit that description. I'm still not.
And later I asked:
I've never used ReST. I know Dave has. Can I cross-link to a Doxygen-generated section?
I never saw a response. I'm all for using ReST, as long as it does what I need it to do. So does it? -- Eric Niebler Boost Consulting www.boost-consulting.com
Eric Niebler wrote:
Let me repeat the point about QuickBook I made earlier, since you seem to have missed it:
I didn't. I hoped David would jump in, as he seems to be the ReST expert here.
I needed something that would let me write docs fast in a plain text editor, with cross-links to a reference section generated by Doxygen. I wasn't aware of any tool that fit that description. I'm still not.
And later I asked:
I've never used ReST. I know Dave has. Can I cross-link to a Doxygen-generated section?
I never saw a response. I'm all for using ReST, as long as it does what I need it to do. So does it?
I believe ReST can be configured to do that. David ? Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Stefan Seefeld wrote:
Eric Niebler wrote:
Let me repeat the point about QuickBook I made earlier, since you seem to have missed it:
I didn't. I hoped David would jump in, as he seems to be the ReST expert here.
I needed something that would let me write docs fast in a plain text editor, with cross-links to a reference section generated by Doxygen. I wasn't aware of any tool that fit that description. I'm still not. And later I asked:
I've never used ReST. I know Dave has. Can I cross-link to a Doxygen-generated section? I never saw a response. I'm all for using ReST, as long as it does what I need it to do. So does it?
I believe ReST can be configured to do that. David ?
Yes, docutils could pretty easily be extended to do that. It doesn't handle it by default, naturally, since it's way outside the scope of the project, but docutils has very well defined extension points that can be used for these kinds of things. -- Daniel Wallin Boost Consulting www.boost-consulting.com
on Sun Jul 01 2007, Stefan Seefeld <seefeld-AT-sympatico.ca> wrote:
I needed something that would let me write docs fast in a plain text editor, with cross-links to a reference section generated by Doxygen. I wasn't aware of any tool that fit that description. I'm still not.
And later I asked:
I've never used ReST. I know Dave has. Can I cross-link to a Doxygen-generated section?
I never saw a response. I'm all for using ReST, as long as it does what I need it to do. So does it?
I believe ReST can be configured to do that. David ?
I don't know enough about what we mean by "cross-link to a Doxygen-generated section" to answer. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com
Stefan Seefeld wrote:
David Abrahams wrote:
on Sun Jun 24 2007, Stefan Seefeld <seefeld-AT-sympatico.ca> wrote:
David Abrahams wrote:
Which editors are these, BTW? The one I have run across is xxe (http://www.xmlmind.com/xmleditor/). But I'm mostly using (x)emacs, which has its own xml-editing modes that will happily accept any customization layer, too. Yeah, that's fine too; I use emacs. It's just not quite WYSIWYG... not that it's a problem for me.
There are (as you surely know) long discussions about the WYSIWYG paradigm, and by what that could be replaced in the context of structured documents. However, for all practical purposes, I do consider the above editor (xxe) to be WYSIWYG. People do have a choice, if they really want.
I'll likely get flamed for this, but can't help but point out... WYSIWYG text editors are a UI failure. They inadvertently put the burden on correct *visual* formatting on users overriding the more important aspect of correct *structural* formatting. So saying that documentation system X has a WYSIWYG editor Y doesn't impress me at all. People should concentrate on editors that help/enforce document structure and coherence. -- -- 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 01/07/07, Rene Rivera <grafikrobot@gmail.com> wrote:
I'll likely get flamed for this, but can't help but point out... WYSIWYG text editors are a UI failure. They inadvertently put the burden on correct *visual* formatting on users overriding the more important aspect of correct *structural* formatting. So saying that documentation system X has a WYSIWYG editor Y doesn't impress me at all. People should concentrate on editors that help/enforce document structure and coherence.
I always enjoy it when LyX yells at me for hitting space twice in a row :) ~ Scott
Stefan Seefeld wrote:
David Abrahams wrote:
on Sun Jun 24 2007, Stefan Seefeld <seefeld-AT-sympatico.ca> wrote:
David Abrahams wrote:
There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow. Yeah, but we need to represent semantic information (e.g. Concepts)
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote: that are outside the builtin representational abilities of DocBook. DocBook is designed for extensibility. I know. That's why I said *builtin*.
BoostBook is just an extension of DocBook, using expressly-designed hooks in DocBook for that purpose. I don't consider that an NIH move on our part; quite the contrary.
Yes, understood. With NIH I'm not referring to BoostBook, but to QuickBook, which is neither an extension to DocBook, nor ReST. Thus, no existing parser will work with it, no existing documentation will help, and no existing community can answer questions and help resolve issues.
I don't understand what you mean by "no existing". There is an existing parser, there is an existing documentation and there is an existing community. It just so happens that it is within the boost community. FWIW, QuickDoc/QuickBook was written in 2001. I wasn't aware of any similar tool. ReST was far from my radar screen. ReST was completed (according to the docs [http://tinyurl.com/2kthnf]) in 2001-2002. So, it is not NIH that drove me to write it, if your definition of NIH is (http://tinyurl.com/7oavz) "a persistent sociological, corporate or institutional culture that avoids using already existing products, research or knowledge because of its different origins." Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
Joel de Guzman wrote:
Yes, understood. With NIH I'm not referring to BoostBook, but to QuickBook, which is neither an extension to DocBook, nor ReST. Thus, no existing parser will work with it, no existing documentation will help, and no existing community can answer questions and help resolve issues.
I don't understand what you mean by "no existing". There is an existing parser, there is an existing documentation and there is an existing community. It just so happens that it is within the boost community.
Sorry for not phrasing it more carefully. Yes, I'v used "no existing" as "only exists within the bounds of boost". Regards, Stefan -- ...ich hab' noch einen Koffer in Berlin...
Stefan Seefeld wrote:
Joel de Guzman wrote:
Yes, understood. With NIH I'm not referring to BoostBook, but to QuickBook, which is neither an extension to DocBook, nor ReST. Thus, no existing parser will work with it, no existing documentation will help, and no existing community can answer questions and help resolve issues. I don't understand what you mean by "no existing". There is an existing parser, there is an existing documentation and there is an existing community. It just so happens that it is within the boost community.
Sorry for not phrasing it more carefully. Yes, I'v used "no existing" as "only exists within the bounds of boost".
And that makes it NIH? Boost is a large community. If you've seen the quickbook threads in the Boost.Docs list, it might give you a hint on how much it is being used now, after many years of deployment. I'd venture a guess that if we've gone public, it would be much larger than that. But then again, I'm sure you'll agree that the size of the user base does not define its being NIH or not. And its existence within Boost only does not too. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
On 7/1/07, Stefan Seefeld <seefeld@sympatico.ca> wrote:
(For the record: I did bring up the BoostBook extension on the #docbook IRC channel, and people, including Norman Walsh, where quite favorable to the idea of getting BoostBook or a variant thereof integrated into DocBook, if only as a 'C++ profile'.
Great! Thanks for this Stefan. We have change Boostbook a lot, and will continue to make it more simpler, and powerful. Once we settled down we can contact Docbook authors to put upstream as much as possible.
That would make it easier to let it evolve together with DocBook, and would help boost developers focus on the Real Stuff. ;-) )
Documentation and tools are "Real Stuff" for me. Very Real. Please give us a place between the Boost community, we will try to not distract you ;) Regards Matias
Matias Capeletto wrote:
On 7/1/07, Stefan Seefeld <seefeld@sympatico.ca> wrote:
That would make it easier to let it evolve together with DocBook, and would help boost developers focus on the Real Stuff. ;-) )
Documentation and tools are "Real Stuff" for me. Very Real. Please give us a place between the Boost community, we will try to not distract you ;)
And for me too. The tools that I write using Spirit makes the library stronger. And this does not distract me from my focus. It's just the way I work. I build tools to make tools and I test them using real tools; not just toys and examples bundled together adhoc. With this approach, I have authored 3 major libraries already. 2 of which are already accepted into boost. These tools are built on top of each other. For me, I see no distinction between tools and libraries. There may be for others, and perhaps for you, but please don't force that definition upon us. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net
On 6/24/07, David Abrahams <dave@boost-consulting.com> wrote:
on Sat Jun 23 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
Hi,
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
Totally agree.
6. Source code highlighting
My understanding is that quickbook presents some source code highlighting automation. IMO this can be either implemented as standalone C++ based tool that docs writers can use when required or even better it can be implemented in JavaScript. I believe I've seen it done.
I'm not sure I want to do that job on the browser, but I understand the appeal, especially if end-users can tune the colors.
Have you seen this: (firefox, safari, camino and knoqueror only for now) http://tinyurl.com/27ubvp Move the mouse to the upper-right corner of a code-block and select your preferred IDE.
II. BoostBook 4. Documentation I found documentation to be largely unacceptable (funny thing for the project dedicated to writing documentation)
c) most critical: no description whatsoever of all the modification done in comparison with DocBook. All the updated parameter need to be listed, all the updated templates need to be explained. General approach should be what the person familiar with DocBook (standard) need to know/expect to use BoostBook
That's a problem.
Almost solved in my local copy, will upload it soon.
As I mentioned before we should try to limit our extensions to the most necessary only and strive to stick with standard DocBook. Also all extensions should be made optional.
Aren't they, currently?
Yep.
III. What should we do?
IMO the standardization efforts need to target DocBook/BoostBook. On the other hand each developer should be allowed to extend/twick standard L&F. Usually differences should be only cosmetic.
Major cosmetic differences will keep Boost looking fractured.
100% agree.
Following are general observations about common L&F
1. JS Menu support. I believe it should be implemented but made optional.
Why not just let the user show/hide it?
I am working to provide this functionality. You have spoiled the surprise effect now ;)
4. Portability This is major requirement for all the features we implement. They should work on at least set of predefined "major" browsers.
Yep.
We are currently working on this. Best regards Matias Capeletto
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87vedd16z5.fsf@grogan.peloton...
There several WYSWYG editors producing DocBook (and I don't need to enter markup at all!) and this trend is going to grow.
Yeah, but we need to represent semantic information (e.g. Concepts) that are outside the builtin representational abilities of DocBook. How well will these WYSIWYG editors handle BoostBook's special tags?
Which editors are these, BTW?
see here: http://wiki.docbook.org/topic/DocBookAuthoringTools look for WYSWYG
4. quickbook will never be as flexible as DocBook
Disagree. It's far more flexible, because it has a whole macro language builtin.
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
I would guess that number of people familiar with DocBook would be much more in comparison with QuickBook
All in all I believe using this format is going to be a maintenance problem in a long term and should be avoided. We should stick with industry standard DocBook IMO instead.
I don't think it's necessarily that clear-cut. However, there *are* other broadly-accepted tools, supported by others, (e.g. docutils) that we can use to produce DocBook, so it doesn't necessarily mean we're stuck with XML as our input format if we don't want to have to support our own front-end.
I don't believe boost should regulate what people use to develop docs. What it should regulate is: what people need to use the docs. IOW what we should require is the presence of BoostBook file in a doc directory (under source control and in deliverables). At that point it's irrelevant how you got it (using XML editor, QuickBook or any other way). BoostBook document I can use to do whatever I want with it. Including producing my own personal form of documentation based on my company requirements or change a L&F if it matters for me. IOW we should state: Boost documentation is in BoostBook format and you need to know it (and corresponding tools) to work with it (well almost: release provides regular output in a form of HTML). The BoostBook document should be the one required during review. What we shouldn't do IMO is to require yet another tool to work with documentation. And HTML generation should be strait from BoostBook documents. Gennadiy
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> wrote in message news:f5nk9n$ktr$1@sea.gmane.org...
4. quickbook will never be as flexible as DocBook
Disagree. It's far more flexible, because it has a whole macro language builtin.
I meant to ask here: How macros will help you configure your HTML output? Gennadiy
On Mon, Jun 25, 2007 at 01:51:34AM -0400, Gennadiy Rozental wrote:
"Gennadiy Rozental" <gennadiy.rozental@thomson.com> wrote in message news:f5nk9n$ktr$1@sea.gmane.org...
4. quickbook will never be as flexible as DocBook
Disagree. It's far more flexible, because it has a whole macro language builtin.
I meant to ask here: How macros will help you configure your HTML output?
I'm not sure how HTML output came into this particular item, but I do have a good use case for quickbook macros: http://osdir.com/ml/lib.boost.documentation/2005-11/msg00020.html Seems pretty flexible to me... -t
on Mon Jun 25 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87vedd16z5.fsf@grogan.peloton...
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
I would guess that number of people familiar with DocBook would be much more in comparison with QuickBook
Granted. I would guess that the number of people familiar with neither is much much more. My point is that when you're starting from zero, QuickBook has a much shallower learning curve.
I don't believe boost should regulate what people use to develop docs. What it should regulate is: what people need to use the docs. IOW what we should require is the presence of BoostBook file
So you no longer object to BoostBook? Before, you seemed to insist on pure DocBook. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87d4zb7fm4.fsf@grogan.peloton...
on Mon Jun 25 2007, "Gennadiy Rozental" <gennadiy.rozental-AT-thomson.com> wrote:
"David Abrahams" <dave@boost-consulting.com> wrote in message news:87vedd16z5.fsf@grogan.peloton...
5. This is new *nonstandard* format any new developer will have to learn. I don't believe we can afford yet another barrier for new submitters.
Unless they already know DocBook, DocBook represents a much higher barrier for most people getting started.
I would guess that number of people familiar with DocBook would be much more in comparison with QuickBook
Granted. I would guess that the number of people familiar with neither is much much more. My point is that when you're starting from zero, QuickBook has a much shallower learning curve.
I don't believe boost should regulate what people use to develop docs. What it should regulate is: what people need to use the docs. IOW what we should require is the presence of BoostBook file
So you no longer object to BoostBook? Before, you seemed to insist on pure DocBook.
I never did (at least never intended, I midght've mistyped docbook instead of boostbook in some contexts) Gennadiy
participants (20)
-
Cédric Venet -
Daniel Wallin -
David Abrahams -
Douglas Gregor -
Eric Niebler -
Gennadiy Rozental -
Jake Voytko -
Jeff Garland -
Jeremy Maitin-Shepard -
Joel de Guzman -
Manuel Fiorelli -
Mathias Gaunard -
Matias Capeletto -
Paul A Bristow -
Peter Dimov -
Rene Rivera -
Scott McMurray -
Stefan Seefeld -
troy d straszheim -
Vladimir Prus