Boost logo

Boost :

Subject: Re: [boost] [Experimental Boost.DI] [v1.0.0 released] [Looking for a Review Manager] Your C+14 Dependency Injection library with no overhead and compile time creation guarantee!
From: Edward Diener (eldiener_at_[hidden])
Date: 2016-02-26 18:37:32

On 2/26/2016 10:20 AM, Krzysztof Jusiak wrote:
> On Fri, Feb 26, 2016 at 2:48 PM, Paul A. Bristow <pbristow_at_[hidden]>
> wrote:
>>> -----Original Message-----
>>> From: Boost [mailto:boost-bounces_at_[hidden]] On Behalf Of
>> Krzysztof Jusiak
>>> Sent: 26 February 2016 13:57
>>> To: boost_at_[hidden]
>>> Subject: Re: [boost] [Experimental Boost.DI] [v1.0.0 released] [Looking
>> for a Review Manager] Your C+14 Dependency
>>> Injection library with no overhead and compile time creation guarantee!
>> > 4 Not maintainable. This is a BIG issue. We are already seeing a lot
>> of
>>>> Boost libraries where the documentation cannot be
>>>> maintained by anyone other than the original author (they all disappear
>>>> eventually). Some have been completely refactored (a lot of
>>>> rather tedious work) but in several cases we have effectively given up
>> on
>>>> making any changes to the documentation. This is really,
>>>> really BAD.
>>> I would disagree with this one. IMHO markdown is well known and way
>> easier
>>> then quickbook. Generating doc is trivial, might be even
>>> done online. Generates doc in 0.1 s. QuickBook is so really, really heavy
>>> in comparison. It's way easier to change markdonw.
>>>> Using the Quickbook mark-up language (for example because it is used
>> for
>>>> many libraries) anyone can make small changes with any
>>>> plain text editor, and there are many people who can make much bigger
>>>> revisions.
>>> The same apply to Markdown. Markdown is well known, really easy and very
>>> popular too.
>> OK - Markdown is less powerful than Quickbook, but Quickbook isn't rocket
>> science - if you had trouble getting started, you should
>> have asked for help on the Boost lists. Once working, Quickbook really
>> isn't difficult. It really comes into its own when dealing
>> with 'bigger' libraries.
> I didn't have problems to start with quickbook. Well, maybe it was painful
> to set it up, but oh well.
> I haven't found it really powerful tho. A lot of things I wanted were
> really hard to achieve.
> Anyway, I have done quickbook version of the spec in the beginning ->
> I started like that, but I ended up having plenty of hard to maintain
> scripts fixing
> quickbook generated code. Moreover, it was really slow to develop as well.
> I decided to try doxygen afterwards (like hana does). It was
> a bit clumsy too. Markdown, on the other hand, suits my needs perfectly.
>>>> Using Doxygen-syntax comments in the source code, anyone can easily
>> change
>>>> these comments with their preferred IDE or editor. All
>>>> changes will appear in documentation automatically.
>>> Don't see any reason why markdown might not be generated from Doxygen
>>> comments.
>> Indeed, I think this will happen, which is why having Doxygen-syntax
>> comments in the source and header code is the really important
>> thing.
>>> Quickbook doesn't have support for Doxygen either
>>> way and any try caused a LOT of pain.
>> They work very well together, as you will see from many libraries using
>> both.
> Many libraries? I see geometry, numeric and gil, its not a lot out of ~120
> libraries.

You haven't looked very hard, to say the least. Try again !

> I also have seen Niall Douglas effort trying to generate doxygen for AFIO
> which was quite painful.

That is Niall Douglas's problem and not doxygen's problem. I am not
claiming doxygen is perfect by a long shot but it is quite adequate for
generating documentation from source code. I am also pretty sure that
you know that doxygen has a very large user base in the programming world.

But the issue is not doxygen and I would be the first to agree that a
library developer should be able to use whatever he likes to generate
the documentation for his library, just as long as he realizes that
end-user's may want to view the docs both online and offline. What Boost
almost certainly doesn't want is for the end-user to have major
requirements just to view a library's documentation. If as the OP has
done different levels of the same documentation is part of a library,
depending on the end-user's preference, that's fine with me. But the
basic level of doc needs to be accessible for the end-user with the
least amount of outside requirements possible.
>>>> Anyone can change the indexing by changing the source code (or the
>>>> index.idx plain text-file that controls Boost auto-indexing).
>>>> Setting up the building tools is some hassle (like all other tools,
>>>> including getting endless Javascript updates!),
>>>> but these tools don't need to be used by the person who makes the
>>>> documentation changes - the build process will take care of that.
>>> I would say with markdown whatever is possible with Quickbook is also
>>> possible just in an easier way.
>> I doubt it.
>> You've just reinvented a fancy wheel!
> Well, its way easier to get support when using markdown as its used
> worldwide.
> Configuration is simpler too. You can even push your changed to
> and you done. With quickbook you have to check out boost compile it, set up
> all docutils/xlst, etc.. and as boost quickbook is used just by boost
> support is limited
> to boost mailing list, but it's just my opinion.

Boost list run by bdawes at, gregod at, cpdaniel at, john at