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!

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.
>>>
>> https://raw.githubusercontent.com/boost-experimental/di/cpp14/doc/user_guide.md
>>>
>>>
>>>> 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 ->
> https://github.com/boost-experimental/di/tree/d97ee097ff32123ff9242d396295954dab98a6ad/doc
> 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
> readthedocs.org
> 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.