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