From: Eric Niebler (eric_at_[hidden])
Date: 2007-06-24 20:09:11
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