Re: [boost] Boost documentation

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