[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!
Dear Boosters, I have just released version 1.0.0 of experimental Boost.DI library. Your C++14 header only Dependency Injection library with no dependencies. Library entered Boost Formal Review Queue some time ago and right now, IMHO, is ready to be reviewed. http://www.boost.org/community/review_schedule.html Therefore, I'm looking for a Review Manager, so if you think that Boost.DI is good enough to be reviewed and you would like to help with it, please let me know. Thank you! In the mean time check out the library yourself online! http://boost-experimental.github.io/di/examples/index.html Or read the interactive documentation... http://boost-experimental.github.io/di Or check out the source code... https://github.com/boost-experimental/di Why Boost.DI? * Boost.DI has none or minimal run-time overhead * Boost.DI compiles fast / Faster than Java-Dagger2! * Boost.DI gives short diagnostic messages * Boost.DI is non-intrusive * Boost.DI reduces boilerplate code * Boost.DI reduces testing effort * Boost.DI gives better control of what and how is created * Boost.DI gives better understanding about objects hierarchy Read more why here -> http://boost-experimental.github.io/di/index.html Any feedback is more than welcome! Cheers, Kris
AMDG A few documentation nits: * The examples often overflow the window and there is no horizontal scroll bar. * What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too. * I find the tables without any borders hard to read. * "But what about values? renderer requires device, which, by default, was zero initialized." Are you sure that you don't mean /value/-initialized? (Yes, I know they're equivalent in this case.) * When I follow the link to constructible in "If you want change the default behaviour and be sure that all required dependencies are bound and not zero initialized take a look at constructible policy." which goes here: http://boost-experimental.github.io/di/user_guide/index.html#di_constructibl..., it doesn't give any clue about how I'm supposed to use constructible. In Christ, Steven Watanabe
On Tue, Feb 23, 2016 at 3:43 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG
Thanks for you feedback.
A few documentation nits: * The examples often overflow the window and there is no horizontal scroll bar.
Can you tell me which browser are you using, please? I tested it on newest versions of Chrome/Firefox and IE and looks fine.
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test online. However, you have to have Java Script enabled in order to see the documentation properly.
* I find the tables without any borders hard to read.
There are borders on the tables. I really would like to know your configuration, please?
* "But what about values? renderer requires device, which, by default, was zero initialized." Are you sure that you don't mean /value/-initialized? (Yes, I know they're equivalent in this case.)
Fair point, thanks for that. I have updated the doc accordingly.
* When I follow the link to constructible in "If you want change the default behaviour and be sure that all required dependencies are bound and not zero initialized take a look at constructible policy." which goes here:
http://boost-experimental.github.io/di/user_guide/index.html#di_constructibl... , it doesn't give any clue about how I'm supposed to use constructible.
I think it's because you can't see examples and code due to lack of Java Script as most information is described using it.
In Christ, Steven Watanabe
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
AMDG On 02/23/2016 10:43 AM, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 3:43 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
A few documentation nits: * The examples often overflow the window and there is no horizontal scroll bar.
Can you tell me which browser are you using, please? I tested it on newest versions of Chrome/Firefox and IE and looks fine.
Firefox w/ javascript disabled.
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test online.
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting (though I'm not really happy about that), but it makes no sense at all for the code to require javascript to display at all.
However, you have to have Java Script enabled in order to see the documentation properly.
* I find the tables without any borders hard to read.
There are borders on the tables. I really would like to know your configuration, please?
It's because you're using javascript to do something that ought to be handled by css. In Christ, Steven Watanabe
On Tue, Feb 23, 2016 at 10:19 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG On 02/23/2016 10:43 AM, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 3:43 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test online.
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting
I can't. Highlighting is static content, there is no need for JS for that.
On Tue, Feb 23, 2016 at 10:23 PM, Andrey Semashev <andrey.semashev@gmail.com
wrote:
On Tue, Feb 23, 2016 at 10:19 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG On 02/23/2016 10:43 AM, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 3:43 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test online.
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting
I can't. Highlighting is static content, there is no need for JS for that.
I created a ticket do display the code without JS -> https://github.com/boost-experimental/di/issues/208. However, highlighting will require JS to be enabled. I get your point that it might be done statically, however, mkdocs is using JS for it and I don't see a huge reason to change it. Anyway, on this note, I really do not understand why requirement of Java Script is such a big thing? Data shows that only 1-2% of people don't have it enabled either way, so it's a really small number of people affected. Almost all pages are using Java Script in some way either way, so why Boost can't take advantage of it as others languages do? IMHO, maybe a bit controversial, not being more aggressive with the web tools available is one of the reasons why C++ is still considered old fashioned and so hard to work with. These days we can do so much better, Modern C++ allow us to code in a more productive way than even before, but it's hard to show all these benefits for new/old users with a boring/old fashion documentation. Therefore, Boost.DI doc is so interactive... * You can comment on the page * You have a chat to discuss issues * Finally you can run the code in your browser! IMHO this type of documentation is more appealing to the average users as they can easily see how the library works and how good modern C++ becomes. What I mean by that, is that they can easily spot that the library... * Compiles quickly -> you can change it online and see! * Error messages are short and nice -> again, You can tryi 5 sec and seen the result! * Can be integrated easily -> it's done on the web, how hard it can be? (Boost.DI therefore is just one header and no dependencies) * Has support via comments/chats -> You don't have to subscribe to lists etc... I think Boost and C++ can win a lot by showing how good Modern C++ is, especially right now, when languages like Rust/Nim/Go/D are already showing how easily they are in comparison to OLD C++! It will come with a bit of cost, like enabling JS, but I think it's the cost worth taking! BTW. I would really appreciate comments about the library too. Cheers, Kris
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Wed, Feb 24, 2016 at 3:39 PM, Krzysztof Jusiak <krzysztof@jusiak.net> wrote:
On Tue, Feb 23, 2016 at 10:23 PM, Andrey Semashev <andrey.semashev@gmail.com
wrote:
On Tue, Feb 23, 2016 at 10:19 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting
I can't. Highlighting is static content, there is no need for JS for that.
I created a ticket do display the code without JS -> https://github.com/boost-experimental/di/issues/208. However, highlighting will require JS to be enabled. I get your point that it might be done statically, however, mkdocs is using JS for it and I don't see a huge reason to change it.
Well, to me the JS-only markup would be a reason enough...
Anyway, on this note, I really do not understand why requirement of Java Script is such a big thing?
There are two aspects to this. First is conceptual. Using JS where static content can and should be used is just wasteful in terms of client performance and battery life. I'm sad to see that JS is often viewed as a hammer for every nail and we can see JS projects that should have never existed in the first place. I hate to see web pages that load CPU, are difficult to scroll and cause closing the tab take seconds. Second is practical. Boost docs are also built into pdf, and JS cannot be used there. Also there are people who disable JS in web browsers. Whether these people are 1% or not I cannot tell, but I don't think you want to deny them reading your docs. Then there's some people who'd like to have the docs offline. This is certainly the case for Boost packagers. Don't misunderstand me, I don't mind using JS for interactive stuff you mentioned - when the docs are online. But all these bells and whistles should be strictly optional and the docs should be viewable without them. You could say the code snippets are viewable without highlighting and that is true, but I can't say such docs are comfortable to read. And since static highlighting is easy with Doxygen or QuickBook, I think it should be done.
On Wed, Feb 24, 2016 at 2:19 PM, Andrey Semashev <andrey.semashev@gmail.com> wrote:
On Wed, Feb 24, 2016 at 3:39 PM, Krzysztof Jusiak <krzysztof@jusiak.net> wrote:
On Tue, Feb 23, 2016 at 10:23 PM, Andrey Semashev < andrey.semashev@gmail.com Anyway, on this note, I really do not understand why requirement of Java Script is such a big thing?
There are two aspects to this. First is conceptual. Using JS where static content can and should be used is just wasteful in terms of client performance and battery life.
OTOH, statically styled code is bigger, sometimes quite a bit. So assuming the JS to style it is both small and cached, dynamically styled code can lead to less network IO overall. My $0.02. --DD
On Wed, Feb 24, 2016 at 1:19 PM, Andrey Semashev <andrey.semashev@gmail.com> wrote:
On Tue, Feb 23, 2016 at 10:23 PM, Andrey Semashev < andrey.semashev@gmail.com
wrote:
On Tue, Feb 23, 2016 at 10:19 PM, Steven Watanabe <watanabesj@gmail.com
wrote:
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting
I can't. Highlighting is static content, there is no need for JS for
On Wed, Feb 24, 2016 at 3:39 PM, Krzysztof Jusiak <krzysztof@jusiak.net> wrote: that.
I created a ticket do display the code without JS -> https://github.com/boost-experimental/di/issues/208. However, highlighting will require JS to be enabled. I get your point that it might be done statically, however, mkdocs is
using
JS for it and I don't see a huge reason to change it.
Well, to me the JS-only markup would be a reason enough...
Anyway, on this note, I really do not understand why requirement of Java Script is such a big thing?
There are two aspects to this. First is conceptual. Using JS where static content can and should be used is just wasteful in terms of client performance and battery life. I'm sad to see that JS is often viewed as a hammer for every nail and we can see JS projects that should have never existed in the first place. I hate to see web pages that load CPU, are difficult to scroll and cause closing the tab take seconds.
Second is practical. Boost docs are also built into pdf, and JS cannot be used there. Also there are people who disable JS in web browsers. Whether these people are 1% or not I cannot tell, but I don't think you want to deny them reading your docs. Then there's some people who'd like to have the docs offline. This is certainly the case for Boost packagers.
Don't misunderstand me, I don't mind using JS for interactive stuff you mentioned - when the docs are online. But all these bells and whistles should be strictly optional and the docs should be viewable without them. You could say the code snippets are viewable without highlighting and that is true, but I can't say such docs are comfortable to read. And since static highlighting is easy with Doxygen or QuickBook, I think it should be done.
I agree that there should be an option to see it without JS, however, I don't think it's a priority these days. As I mentioned before I'm going to fix visibility of code when JS is disabled ( https://github.com/boost-experimental/di/issues/208). I don't see much problem in generating pdf from markdown and JS either. I would even say it might be done with one-liner ;) Furthermore, If it comes to JS you can change the style/theme online. Imagine someone doesn't like the highlighting provided and would like a different one. With the static solution, another version of the website would have to be provided. JS + CSS let you change it dynamically. IMHO it's a great timing for all C++ developers to appreciate JS/HTML5 as we have tools like Emscripten/Cheerp to our disposition now. I predict that more and more stuff will be written or ported this way as you can write one code for all platforms including Web and Mobile.
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
AMDG On 02/24/2016 07:07 AM, Krzysztof Jusiak wrote:
Furthermore, If it comes to JS you can change the style/theme online. Imagine someone doesn't like the highlighting provided and would like a different one. With the static solution, another version of the website would have to be provided. JS + CSS let you change it dynamically.
I have a hard time imagining anyone bothering to fiddle with the highlighting settings like this. In any case, if your static html includes a fixed color scheme, you're doing it wrong. The actual colors should be set in CSS regardless of whether you're using JS or not. In Christ, Steven Watanabe
On Thu, Feb 25, 2016 at 12:06 AM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG
On 02/24/2016 07:07 AM, Krzysztof Jusiak wrote:
Furthermore, If it comes to JS you can change the style/theme online. Imagine someone doesn't like the highlighting provided and would like a different one. With the static solution, another version of the website would have to be provided. JS + CSS let you change it dynamically.
I have a hard time imagining anyone bothering to fiddle with the highlighting settings like this. In any case, if your static html includes a fixed color scheme, you're doing it wrong. The actual colors should be set in CSS regardless of whether you're using JS or not.
Yea, most of the stuff will be handled by CSS, however, you have to add tags for the keywords in the code. Either way it's not giving you a possibility to change it, so it doesn't really from the user perspective, I guess. Anyway, I have prepared a Boost-like version of the documentation (based on Paul's boost theme) which does not require JS, so please check it out. http://boost-experimental.github.io/di/boost/ It still require some tweaks, but it's usable already.
In Christ, Steven Watanabe
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On 2/25/2016 10:25 AM, Krzysztof Jusiak wrote:
On Thu, Feb 25, 2016 at 12:06 AM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG
On 02/24/2016 07:07 AM, Krzysztof Jusiak wrote:
Furthermore, If it comes to JS you can change the style/theme online. Imagine someone doesn't like the highlighting provided and would like a different one. With the static solution, another version of the website would have to be provided. JS + CSS let you change it dynamically.
I have a hard time imagining anyone bothering to fiddle with the highlighting settings like this. In any case, if your static html includes a fixed color scheme, you're doing it wrong. The actual colors should be set in CSS regardless of whether you're using JS or not.
Yea, most of the stuff will be handled by CSS, however, you have to add tags for the keywords in the code. Either way it's not giving you a possibility to change it, so it doesn't really from the user perspective, I guess.
Anyway, I have prepared a Boost-like version of the documentation (based on Paul's boost theme) which does not require JS, so please check it out. http://boost-experimental.github.io/di/boost/
It still require some tweaks, but it's usable already.
In your Tutorial 2. section 'view' becomes 'iview'. But doesn't your example hierarchy for controller now have to be ?: class controller { public: controller(model&, iview&) {} };
On Thu, Feb 25, 2016 at 5:20 PM, Edward Diener <eldiener@tropicsoft.com> wrote:
On 2/25/2016 10:25 AM, Krzysztof Jusiak wrote:
On Thu, Feb 25, 2016 at 12:06 AM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG
On 02/24/2016 07:07 AM, Krzysztof Jusiak wrote:
Furthermore, If it comes to JS you can change the style/theme online. Imagine someone doesn't like the highlighting provided and would like a different one. With the static solution, another version of the website would have to be provided. JS + CSS let you change it dynamically.
I have a hard time imagining anyone bothering to fiddle with the highlighting settings like this. In any case, if your static html includes a fixed color scheme, you're doing it wrong. The actual colors should be set in CSS regardless of whether you're using JS or not.
Yea, most of the stuff will be handled by CSS, however, you have to add
tags for the keywords in the code. Either way it's not giving you a possibility to change it, so it doesn't really from the user perspective, I guess.
Anyway, I have prepared a Boost-like version of the documentation (based on Paul's boost theme) which does not require JS, so please check it out. http://boost-experimental.github.io/di/boost/
It still require some tweaks, but it's usable already.
In your Tutorial 2. section 'view' becomes 'iview'. But doesn't your example hierarchy for controller now have to be ?:
class controller { public: controller(model&, iview&) {} };
Yea, it should and I think it does? https://github.com/boost-experimental/di/blob/cpp14/example/tutorial/basic_f...
However, your point is absolutely valid as it's not visible in the doc. Thanks! Fixed with this commit, should be updated in a few minutes.. https://github.com/boost-experimental/di/commit/30702a9898de74acc00f69d4abdc...
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Wednesday, February 24, 2016 at 6:39:52 AM UTC-6, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 10:23 PM, Andrey Semashev <andrey....@gmail.com <javascript:>
wrote:
On Tue, Feb 23, 2016 at 10:19 PM, Steven Watanabe <watan...@gmail.com <javascript:>> wrote:
AMDG On 02/23/2016 10:43 AM, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 3:43 PM, Steven Watanabe <watan...@gmail.com <javascript:>> wrote:
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test online.
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting
I can't. Highlighting is static content, there is no need for JS for that.
I created a ticket do display the code without JS -> https://github.com/boost-experimental/di/issues/208. However, highlighting will require JS to be enabled. I get your point that it might be done statically, however, mkdocs is using JS for it and I don't see a huge reason to change it.
Mkdocs can use pygments to highlight code blocks statically. However, I've found that highlight.js does a much better job at highlighting. It seems pygments would get confused by C++ syntax easily.
Anyway, on this note, I really do not understand why requirement of Java Script is such a big thing? Data shows that only 1-2% of people don't have it enabled either way, so it's a really small number of people affected. Almost all pages are using Java Script in some way either way, so why Boost can't take advantage of it as others languages do?
IMHO, maybe a bit controversial, not being more aggressive with the web tools available is one of the reasons why C++ is still considered old fashioned and so hard to work with.
These days we can do so much better, Modern C++ allow us to code in a more productive way than even before, but it's hard to show all these benefits for new/old users with a boring/old fashion documentation.
Therefore, Boost.DI doc is so interactive... * You can comment on the page * You have a chat to discuss issues * Finally you can run the code in your browser!
But how does the documentation deal with versioning? When you go back to a previous version how does all the interaction work then? Also, how does it work with offline documentation browsing such as Dash/Zeal?
IMHO this type of documentation is more appealing to the average users as they can easily see how the library works and how good modern C++ becomes.
What I mean by that, is that they can easily spot that the library... * Compiles quickly -> you can change it online and see! * Error messages are short and nice -> again, You can tryi 5 sec and seen the result! * Can be integrated easily -> it's done on the web, how hard it can be? (Boost.DI therefore is just one header and no dependencies) * Has support via comments/chats -> You don't have to subscribe to lists etc...
I think Boost and C++ can win a lot by showing how good Modern C++ is, especially right now, when languages like Rust/Nim/Go/D are already showing how easily they are in comparison to OLD C++! It will come with a bit of cost, like enabling JS, but I think it's the cost worth taking!
BTW. I would really appreciate comments about the library too.
Cheers, Kris
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Wednesday, February 24, 2016 at 6:39:52 AM UTC-6, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 10:23 PM, Andrey Semashev <andrey....@
> <javascript:>
wrote:
On Tue, Feb 23, 2016 at 10:19 PM, Steven Watanabe <watan...@ > <javascript:>> wrote:
AMDG On 02/23/2016 10:43 AM, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 3:43 PM, Steven Watanabe <watan...@ > <javascript:>> wrote:
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test online.
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting
I can't. Highlighting is static content, there is no need for JS for that.
I created a ticket do display the code without JS -> https://github.com/boost-experimental/di/issues/208. However, highlighting will require JS to be enabled. I get your point that it might be done statically, however, mkdocs is using JS for it and I don't see a huge reason to change it.
Mkdocs can use pygments to highlight code blocks statically. However, I've found that highlight.js does a much better job at highlighting. It seems pygments would get confused by C++ syntax easily.
Anyway, on this note, I really do not understand why requirement of Java Script is such a big thing? Data shows that only 1-2% of people don't have it enabled either way, so it's a really small number of people affected. Almost all pages are using Java Script in some way either way, so why Boost can't take advantage of it as others languages do?
IMHO, maybe a bit controversial, not being more aggressive with the web tools available is one of the reasons why C++ is still considered old fashioned and so hard to work with.
These days we can do so much better, Modern C++ allow us to code in a more productive way than even before, but it's hard to show all these benefits for new/old users with a boring/old fashion documentation.
Therefore, Boost.DI doc is so interactive... * You can comment on the page * You have a chat to discuss issues * Finally you can run the code in your browser!
But how does the documentation deal with versioning? When you go back to a previous version how does all the interaction work then? Also, how does it work with offline documentation browsing such as Dash/Zeal?
Thanks. It's a really valid point. Well, chats and comments do not refer to any version so, I guess, they are okay. Code to be ran is taken from github and is using a specific version, so it's not an issue too. Actually, everything is prepared to add a button next to compile button with all versions available where user can change the version and verify the behavior. I haven't added it yet, because I have really one version of the library so far. Other option is to maintain different versions of the documentation for different releases as Boost is doing either way. The only thing which would be different is the fact that code examples will point to a specific release. If it comes to offline browsing, I'm not sure actually. I will check it out tho. Either way for offline browsing either via pdf or dash/zeal a static version would have to be generated, which is not a big deal and I can provide that.
IMHO this type of documentation is more appealing to the average users as they can easily see how the library works and how good modern C++ becomes.
What I mean by that, is that they can easily spot that the library... * Compiles quickly -> you can change it online and see! * Error messages are short and nice -> again, You can tryi 5 sec and seen the result! * Can be integrated easily -> it's done on the web, how hard it can be? (Boost.DI therefore is just one header and no dependencies) * Has support via comments/chats -> You don't have to subscribe to lists etc...
I think Boost and C++ can win a lot by showing how good Modern C++ is, especially right now, when languages like Rust/Nim/Go/D are already showing how easily they are in comparison to OLD C++! It will come with a bit of cost, like enabling JS, but I think it's the cost worth taking!
BTW. I would really appreciate comments about the library too.
Cheers, Kris
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost -- View this message in context: http://boost.2283326.n4.nabble.com/Experimental-Boost-DI-v1-0-0-released-Loo... Sent from the Boost - Dev mailing list archive at Nabble.com.
On 25/02/2016 06:50, Kris wrote:
On Wednesday, February 24, 2016 at 6:39:52 AM UTC-6, Krzysztof Jusiak wrote:
But how does the documentation deal with versioning? When you go back to a previous version how does all the interaction work then? Also, how does it work with offline documentation browsing such as Dash/Zeal?
Thanks. It's a really valid point. Well, chats and comments do not refer to any version so, I guess, they are okay. Code to be ran is taken from github and is using a specific version, so it's not an issue too. Actually, everything is prepared to add a button next to compile button with all versions available where user can change the version and verify the behavior. I haven't added it yet, because I have really one version of the library so far.
Other option is to maintain different versions of the documentation for different releases as Boost is doing either way. The only thing which would be different is the fact that code examples will point to a specific release.
Boost does already maintain separate snapshots of the documentation for different releases of Boost. Which I think was part of Krzysztof's point -- what happens when someone browsing the v1.59 docs adds a comment that something is wrong in the doc, while people looking at the v1.61 docs see something completely different (possibly already fixed) and then get confused?
On Fri, Feb 26, 2016 at 4:36 AM, Gavin Lambert <gavinl@compacsort.com> wrote:
On 25/02/2016 06:50, Kris wrote:
On Wednesday, February 24, 2016 at 6:39:52 AM UTC-6, Krzysztof Jusiak wrote:
But how does the documentation deal with versioning? When you go back to a previous version how does all the interaction work then? Also, how does it work with offline documentation browsing such as Dash/Zeal?
Thanks. It's a really valid point. Well, chats and comments do not refer to any version so, I guess, they are okay. Code to be ran is taken from github and is using a specific version, so it's not an issue too. Actually, everything is prepared to add a button next to compile button with all versions available where user can change the version and verify the behavior. I haven't added it yet, because I have really one version of the library so far.
Other option is to maintain different versions of the documentation for different releases as Boost is doing either way. The only thing which would be different is the fact that code examples will point to a specific release.
Boost does already maintain separate snapshots of the documentation for different releases of Boost. Which I think was part of Krzysztof's point -- what happens when someone browsing the v1.59 docs adds a comment that something is wrong in the doc, while people looking at the v1.61 docs see something completely different (possibly already fixed) and then get confused?
Yea, exactly. It's a really valid question about comments tho. I was wondering myself about that and disqus (by default) generates comments per URL, which means that Boost separate snapshots would solve that as well because v_1.59 will have separate comments to version v_1.60, which, I guess, it's what we really want. Chat, on the other hand, would the same throughout all versions as its flow, usually, looks like that: - User: What about feature A? - Dev: Implemented in v1.62 ...
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Tue, Feb 23, 2016 at 7:19 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
AMDG
On 02/23/2016 10:43 AM, Krzysztof Jusiak wrote:
On Tue, Feb 23, 2016 at 3:43 PM, Steven Watanabe <watanabesj@gmail.com> wrote:
A few documentation nits: * The examples often overflow the window and there is no horizontal scroll bar.
Can you tell me which browser are you using, please? I tested it on newest versions of Chrome/Firefox and IE and looks fine.
Firefox w/ javascript disabled.
* What does CPP(SPLIT) mean? CPP, CPP(BTN), and CPP(SHOW) too.
CPP uses Java Script to show the code, highlight it and let it test
online.
I can understand needing javascript to test the code online and I can sort of justify using it for higlighting (though I'm not really happy about that), but it makes no sense at all for the code to require javascript to display at all.
Fair do's. I created a ticket to support code displaying without js enabled. You can check it found here -> https://github.com/boost-experimental/di/issues/208
However, you have to have Java Script enabled in order to see the documentation properly.
* I find the tables without any borders hard to read.
There are borders on the tables. I really would like to know your configuration, please?
It's because you're using javascript to do something that ought to be handled by css.
It's actually done via CSS. Documentation using markdown and mkdocs to display with slightly modified readthedocs theme.
In Christ, Steven Watanabe
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 23 February 2016 12:41 To: boost@lists.boost.org Subject: [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!
Dear Boosters,
I have just released version 1.0.0 of experimental Boost.DI library. Your C++14 header only Dependency Injection library with no dependencies.
Library entered Boost Formal Review Queue some time ago and right now, IMHO, is ready to be reviewed. http://www.boost.org/community/review_schedule.html
Therefore, I'm looking for a Review Manager, so if you think that Boost.DI is good enough to be reviewed and you would like to help with it, please let me know. Thank you!
In the mean time check out the library yourself online! http://boost-experimental.github.io/di/examples/index.html
Or read the interactive documentation... http://boost-experimental.github.io/di
Or check out the source code... https://github.com/boost-experimental/di
Why Boost.DI? * Boost.DI has none or minimal run-time overhead * Boost.DI compiles fast / Faster than Java-Dagger2! * Boost.DI gives short diagnostic messages * Boost.DI is non-intrusive * Boost.DI reduces boilerplate code * Boost.DI reduces testing effort * Boost.DI gives better control of what and how is created * Boost.DI gives better understanding about objects hierarchy
Read more why here -> http://boost-experimental.github.io/di/index.html
Any feedback is more than welcome!
This documentation looks very swish and sexy and has obviously received a lot of thoughtful work. I'm not needing injections at present (apart from monkey glands perhaps ;-) but you told a plausible story with good graphics (though I was left with a bit of a Huh? feeling). I'm not at all convinced that it's really worth making it all interactive. Without going all NIH (Not Invented Here), I feel there are some big things missing. 1 Versioning - each released Boost version needs its own version of the docs - or people will get really confused. 2 Not standalone - we aren't all always online. HTML version is vital, single PDF is neatest. 3 Unfamiliar. For a 'simple' (in what it offers, rather than its internal complexity) library like this, this is not so important, but the toolchain doesn't scale IMO. 4 Difficult to find what you are looking for. This start with the library name Boost.DI - how are you going to know that you might want it in the first place? (There are lots of other 'pet' library names that will not draw users unless they know what they are looking for). And it gets worse when you fail to find a detailed table of contents and class, macro, function, concept and general index. For me 'how to find' is an major documentation problem that we haven't cracked yet. 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. 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. 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. 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. So nice try, but no banana. Paul PS The one thing that we could do is to use the CSS to make it easy for users to impose their own syntax color scheme onto Boost libraries. I'm really sensitive to this (and for chromatically challenged it will be a major readability issue). I feel person CSS should be a quick win. --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On Fri, Feb 26, 2016 at 12:55 PM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 23 February 2016 12:41 To: boost@lists.boost.org Subject: [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!
Dear Boosters,
I have just released version 1.0.0 of experimental Boost.DI library. Your C++14 header only Dependency Injection library with no dependencies.
Library entered Boost Formal Review Queue some time ago and right now, IMHO, is ready to be reviewed. http://www.boost.org/community/review_schedule.html
Therefore, I'm looking for a Review Manager, so if you think that Boost.DI is good enough to be reviewed and you would like to help with it, please let me know. Thank you!
In the mean time check out the library yourself online! http://boost-experimental.github.io/di/examples/index.html
Or read the interactive documentation... http://boost-experimental.github.io/di
Or check out the source code... https://github.com/boost-experimental/di
Why Boost.DI? * Boost.DI has none or minimal run-time overhead * Boost.DI compiles fast / Faster than Java-Dagger2! * Boost.DI gives short diagnostic messages * Boost.DI is non-intrusive * Boost.DI reduces boilerplate code * Boost.DI reduces testing effort * Boost.DI gives better control of what and how is created * Boost.DI gives better understanding about objects hierarchy
Read more why here -> http://boost-experimental.github.io/di/index.html
Any feedback is more than welcome!
This documentation looks very swish and sexy and has obviously received a lot of thoughtful work.
I'm not needing injections at present (apart from monkey glands perhaps ;-) but you told a plausible story with good graphics (though I was left with a bit of a Huh? feeling).
I'm not at all convinced that it's really worth making it all interactive.
Without going all NIH (Not Invented Here), I feel there are some big things missing.
1 Versioning - each released Boost version needs its own version of the docs - or people will get really confused.
Don't see any problem here. It's pretty much them same as any other spec. 1. Code is versioned so there is no issue with 'Run this code' will refer to a proper version 2. Comments are versioned as they depends on URL 3. Chat is common for all versions
2 Not standalone - we aren't all always online. HTML version is vital, single PDF is neatest.
I will provide pdf version, it's really easy to generate pdf from markdown. I will do it from http://boost-experimental.github.io/di/boost/ so it will have boost look and feel.
3 Unfamiliar. For a 'simple' (in what it offers, rather than its internal complexity) library like this, this is not so important, but the toolchain doesn't scale IMO.
Therefore, http://boost-experimental.github.io/di/boost/ theme which has the same look and feel as any other Boost library using quickbook. Generated from the same markdown, not fancy stuff, no java script, etc.
4 Difficult to find what you are looking for. This start with the library name Boost.DI - how are you going to know that you might want it in the first place? (There are lots of other 'pet' library names that will not draw users unless they know what they are looking for). And it gets worse when you fail to find a detailed table of contents and class, macro, function, concept and general index.
For me 'how to find' is an major documentation problem that we haven't cracked yet.
I'm not sure whether I do understand your point. IMHO developers are not browsing boost libraries trying to check whether a library might be useful to them or not. It's rather the opposite way. They have a problem and they are trying to check whether there is a library solving it. DI is a design pattern and really popular in other languages and therefore it would be easy to find by them.
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...
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.
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. Quickbook doesn't have support for doxygen either way and any try caused a LOT of pain.
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.
So nice try, but no banana.
Paul
PS The one thing that we could do is to use the CSS to make it easy for users to impose their own syntax color scheme onto Boost libraries. I'm really sensitive to this (and for chromatically challenged it will be a major readability issue).
I feel person CSS should be a quick win.
--- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
On Fri, Feb 26, 2016 at 1:56 PM, Krzysztof Jusiak <krzysztof@jusiak.net> wrote:
On Fri, Feb 26, 2016 at 12:55 PM, Paul A. Bristow <pbristow@hetp.u-net.com
wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 23 February 2016 12:41 To: boost@lists.boost.org Subject: [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!
Dear Boosters,
I have just released version 1.0.0 of experimental Boost.DI library. Your C++14 header only Dependency Injection library with no dependencies.
Library entered Boost Formal Review Queue some time ago and right now, IMHO, is ready to be reviewed. http://www.boost.org/community/review_schedule.html
Therefore, I'm looking for a Review Manager, so if you think that Boost.DI is good enough to be reviewed and you would like to help with it, please let me know. Thank you!
In the mean time check out the library yourself online! http://boost-experimental.github.io/di/examples/index.html
Or read the interactive documentation... http://boost-experimental.github.io/di
Or check out the source code... https://github.com/boost-experimental/di
Why Boost.DI? * Boost.DI has none or minimal run-time overhead * Boost.DI compiles fast / Faster than Java-Dagger2! * Boost.DI gives short diagnostic messages * Boost.DI is non-intrusive * Boost.DI reduces boilerplate code * Boost.DI reduces testing effort * Boost.DI gives better control of what and how is created * Boost.DI gives better understanding about objects hierarchy
Read more why here -> http://boost-experimental.github.io/di/index.html
Any feedback is more than welcome!
This documentation looks very swish and sexy and has obviously received a lot of thoughtful work.
I'm not needing injections at present (apart from monkey glands perhaps ;-) but you told a plausible story with good graphics (though I was left with a bit of a Huh? feeling).
I'm not at all convinced that it's really worth making it all interactive.
Without going all NIH (Not Invented Here), I feel there are some big things missing.
1 Versioning - each released Boost version needs its own version of the docs - or people will get really confused.
Don't see any problem here. It's pretty much them same as any other spec. 1. Code is versioned so there is no issue with 'Run this code' will refer to a proper version 2. Comments are versioned as they depends on URL 3. Chat is common for all versions
2 Not standalone - we aren't all always online. HTML version is vital, single PDF is neatest.
I will provide pdf version, it's really easy to generate pdf from markdown. I will do it from http://boost-experimental.github.io/di/boost/ so it will have boost look and feel.
3 Unfamiliar. For a 'simple' (in what it offers, rather than its internal complexity) library like this, this is not so important, but the toolchain doesn't scale IMO.
Therefore, http://boost-experimental.github.io/di/boost/ theme which has the same look and feel as any other Boost library using quickbook. Generated from the same markdown, not fancy stuff, no java script, etc.
4 Difficult to find what you are looking for. This start with the library name Boost.DI - how are you going to know that you might want it in the first place? (There are lots of other 'pet' library names that will not draw users unless they know what they are looking for). And it gets worse when you fail to find a detailed table of contents and class, macro, function, concept and general index.
For me 'how to find' is an major documentation problem that we haven't cracked yet.
I'm not sure whether I do understand your point. IMHO developers are not browsing boost libraries trying to check whether a library might be useful to them or not. It's rather the opposite way. They have a problem and they are trying to check whether there is a library solving it. DI is a design pattern and really popular in other languages and therefore it would be easy to find by them.
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...
Moreover, https://raw.githubusercontent.com/isocpp/CppCoreGuidelines/master/CppCoreGui... is using markdown too. I think that means something.
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.
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. Quickbook doesn't have support for doxygen either way and any try caused a LOT of pain.
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.
So nice try, but no banana.
Paul
PS The one thing that we could do is to use the CSS to make it easy for users to impose their own syntax color scheme onto Boost libraries. I'm really sensitive to this (and for chromatically challenged it will be a major readability issue).
I feel person CSS should be a quick win.
--- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 13:57 To: boost@lists.boost.org 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...
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.
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.
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! Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On Fri, Feb 26, 2016 at 2:48 PM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 13:57 To: boost@lists.boost.org 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...
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/d97ee097ff32123ff9242d39629595... 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. I also have seen Niall Douglas effort trying to generate doxygen for AFIO which was quite painful.
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.
Paul
--- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 15:21 To: boost@lists.boost.org 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!
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've missed the Boost.Math library which has nearly as much documentation as other libraries together.
I would say with markdown whatever is possible with Quickbook is also possible just in an easier way.
How does markdown handle code snippets? Code snippets seem like a 'must have' feature, but you just seem to be pasting code in. Experience shows that this is a recipe for mistakes. What You See is What Compiles and Runs (WYSWCR) is what we need. Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On 2016-02-26 21:23, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 15:21 To: boost@lists.boost.org 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!
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've missed the Boost.Math library which has nearly as much documentation as other libraries together.
There's a rough list: $ for file in `find libs -name Jamfile.v2`; do grep -q "doxygen" "$file" && grep -q "quickbook" "$file" && echo "$file" ; done libs/core/doc/Jamfile.v2 libs/move/doc/Jamfile.v2 libs/test/doc/Jamfile.v2 libs/numeric/odeint/doc/Jamfile.v2 libs/chrono/doc/Jamfile.v2 libs/tti/doc/Jamfile.v2 libs/local_function/doc/Jamfile.v2 libs/scope_exit/doc/Jamfile.v2 libs/sync/doc/Jamfile.v2 libs/algorithm/doc/Jamfile.v2 libs/type_index/doc/Jamfile.v2 libs/heap/doc/Jamfile.v2 libs/dll/doc/Jamfile.v2 libs/property_tree/doc/Jamfile.v2 libs/lockfree/doc/Jamfile.v2 libs/sort/doc/Jamfile.v2 libs/random/doc/Jamfile.v2 libs/xpressive/doc/Jamfile.v2 libs/mpi/doc/Jamfile.v2 libs/log/doc/Jamfile.v2 libs/crc/doc/Jamfile.v2 libs/accumulators/doc/Jamfile.v2 libs/compute/doc/Jamfile.v2 libs/units/doc/Jamfile.v2 libs/ratio/doc/Jamfile.v2 libs/icl/doc/Jamfile.v2 libs/intrusive/doc/Jamfile.v2 libs/interprocess/doc/Jamfile.v2 libs/container/doc/Jamfile.v2 libs/utility/identity_type/doc/Jamfile.v2 libs/functional/overloaded_function/doc/Jamfile.v2
On Fri, Feb 26, 2016 at 8:45 PM, Andrey Semashev <andrey.semashev@gmail.com> wrote:
On 2016-02-26 21:23, Paul A. Bristow wrote:
-----Original Message-----
From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 15:21 To: boost@lists.boost.org 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!
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've missed the Boost.Math library which has nearly as much documentation as other libraries together.
There's a rough list:
$ for file in `find libs -name Jamfile.v2`; do grep -q "doxygen" "$file" && grep -q "quickbook" "$file" && echo "$file" ; done libs/core/doc/Jamfile.v2 libs/move/doc/Jamfile.v2 libs/test/doc/Jamfile.v2 libs/numeric/odeint/doc/Jamfile.v2 libs/chrono/doc/Jamfile.v2 libs/tti/doc/Jamfile.v2 libs/local_function/doc/Jamfile.v2 libs/scope_exit/doc/Jamfile.v2 libs/sync/doc/Jamfile.v2 libs/algorithm/doc/Jamfile.v2 libs/type_index/doc/Jamfile.v2 libs/heap/doc/Jamfile.v2 libs/dll/doc/Jamfile.v2 libs/property_tree/doc/Jamfile.v2 libs/lockfree/doc/Jamfile.v2 libs/sort/doc/Jamfile.v2 libs/random/doc/Jamfile.v2 libs/xpressive/doc/Jamfile.v2 libs/mpi/doc/Jamfile.v2 libs/log/doc/Jamfile.v2 libs/crc/doc/Jamfile.v2 libs/accumulators/doc/Jamfile.v2 libs/compute/doc/Jamfile.v2 libs/units/doc/Jamfile.v2 libs/ratio/doc/Jamfile.v2 libs/icl/doc/Jamfile.v2 libs/intrusive/doc/Jamfile.v2 libs/interprocess/doc/Jamfile.v2 libs/container/doc/Jamfile.v2 libs/utility/identity_type/doc/Jamfile.v2 libs/functional/overloaded_function/doc/Jamfile.v2
Fair point. I wasn't aware more libraries is using it. Still way more not using doxygen but that's not the point as having doxygen documentation has a lot benefits. The problem with generated quickbook doxygen the standard way is that it's not that useful because, AFAIK, its a reference with leasted headers and functions. http://www.boost.org/doc/libs/1_60_0/doc/html/property_tree/reference.html#h... Unless, I'm wrong?
_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 22:02 To: boost@lists.boost.org 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!
On Fri, Feb 26, 2016 at 8:45 PM, Andrey Semashev <andrey.semashev@gmail.com> wrote:
On 2016-02-26 21:23, Paul A. Bristow wrote:
The problem with generated quickbook doxygen the standard way is that it's not that useful because, AFAIK, its a reference with leasted headers and functions. http://www.boost.org/doc/libs/1_60_0/doc/html/property_tree/reference.html#h... hpp
No - you are absolutely correct that this isn't much help and is why Doxygen has a bad reputation with some. People have the totally misguided impression that just running Doxygen on the header files is a 'job done'. That's entirely wrong - they haven't even started the job! You have to document what the classes, functions, macros, templates and files actually do! describing their preconditions, post conditions, throws or not ... and for this there is a de facto standard that I call the Doxygen syntax. It provides categories like \pre \post \return \param \tparam \throw ... and a simple mark-up language, including code sections with syntax coloring etc. Soon, the Clang compiler will be able to process these comments for Doxygen (rather than using its own struggling-with-fancy-C++-templates parser) and emit the results in a useful way. When this is done, the C++ reference section immediately becomes invaluable because you can click on each item like a function or class and read what is does. Index(es) also takes you straight to the item. (And you can read the comments as you go if you are reduced to reading the header file itself). All this is hard work (and very tedious if done retrospectively) so few people have done it properly yet. For future-proofing, the vital information is stored in a standard-ish way, so it can be processed by other tools to give your preferred look'n'feel, SGI-ish if you like that (or not, if like me, you hate it). HTH Paul --- Paul A. Bristow Prizet Farmhouse Kendal UK LA8 8AB +44 (0) 1539 561830
On Sat, Feb 27, 2016 at 10:28 AM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
No - you are absolutely correct that this isn't much help and is why Doxygen has a bad reputation with some.
People have the totally misguided impression that just running Doxygen on the header files is a 'job done'.
That's entirely wrong - they haven't even started the job!
You have to document what the classes, functions, macros, templates and files actually do!
describing their preconditions, post conditions, throws or not ... and for this there is a de facto standard that I call the Doxygen syntax. It provides categories like \pre \post \return \param \tparam \throw ... and a simple mark-up language, including code sections with syntax coloring etc.
Soon, the Clang compiler will be able to process these comments for Doxygen (rather than using its own struggling-with-fancy-C++-templates parser) and emit the results in a useful way.
When this is done, the C++ reference section immediately becomes invaluable because you can click on each item like a function or class and read what is does. Index(es) also takes you straight to the item. (And you can read the comments as you go if you are reduced to reading the header file itself).
All this is hard work (and very tedious if done retrospectively) so few people have done it properly yet.
For future-proofing, the vital information is stored in a standard-ish way, so it can be processed by other tools to give your preferred look'n'feel, SGI-ish if you like that (or not, if like me, you hate it).
I couldn't agree more with you comment.
On 2/26/2016 3:45 PM, Andrey Semashev wrote:
On 2016-02-26 21:23, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 15:21 To: boost@lists.boost.org 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!
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've missed the Boost.Math library which has nearly as much documentation as other libraries together.
There's a rough list:
$ for file in `find libs -name Jamfile.v2`; do grep -q "doxygen" "$file" && grep -q "quickbook" "$file" && echo "$file" ; done libs/core/doc/Jamfile.v2 libs/move/doc/Jamfile.v2 libs/test/doc/Jamfile.v2 libs/numeric/odeint/doc/Jamfile.v2 libs/chrono/doc/Jamfile.v2 libs/tti/doc/Jamfile.v2 libs/local_function/doc/Jamfile.v2 libs/scope_exit/doc/Jamfile.v2 libs/sync/doc/Jamfile.v2 libs/algorithm/doc/Jamfile.v2 libs/type_index/doc/Jamfile.v2 libs/heap/doc/Jamfile.v2 libs/dll/doc/Jamfile.v2 libs/property_tree/doc/Jamfile.v2 libs/lockfree/doc/Jamfile.v2 libs/sort/doc/Jamfile.v2 libs/random/doc/Jamfile.v2 libs/xpressive/doc/Jamfile.v2 libs/mpi/doc/Jamfile.v2 libs/log/doc/Jamfile.v2 libs/crc/doc/Jamfile.v2 libs/accumulators/doc/Jamfile.v2 libs/compute/doc/Jamfile.v2 libs/units/doc/Jamfile.v2 libs/ratio/doc/Jamfile.v2 libs/icl/doc/Jamfile.v2 libs/intrusive/doc/Jamfile.v2 libs/interprocess/doc/Jamfile.v2 libs/container/doc/Jamfile.v2 libs/utility/identity_type/doc/Jamfile.v2 libs/functional/overloaded_function/doc/Jamfile.v2
You missed 'vmd' for whatever reason I do not know.
AMDG On 02/26/2016 04:41 PM, Edward Diener wrote:
On 2/26/2016 3:45 PM, Andrey Semashev wrote:
<snip> There's a rough list:
$ for file in `find libs -name Jamfile.v2`; do grep -q "doxygen" "$file" && grep -q "quickbook" "$file" && echo "$file" ; done <snip>
You missed 'vmd' for whatever reason I do not know.
His search for Jamfile.v2 was case sensitive. In Christ, Steven Watanabe
On 2/26/2016 9:22 PM, Steven Watanabe wrote:
AMDG
On 02/26/2016 04:41 PM, Edward Diener wrote:
On 2/26/2016 3:45 PM, Andrey Semashev wrote:
<snip> There's a rough list:
$ for file in `find libs -name Jamfile.v2`; do grep -q "doxygen" "$file" && grep -q "quickbook" "$file" && echo "$file" ; done <snip>
You missed 'vmd' for whatever reason I do not know.
His search for Jamfile.v2 was case sensitive.
That is a wrong thing to do AFAICS. There are 6 doc 'jamfile.v2' which I am seeing.
On Friday, February 26, 2016 at 12:23:22 PM UTC-6, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-...@lists.boost.org <javascript:>] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 15:21 To: bo...@lists.boost.org <javascript:> 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!
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've missed the Boost.Math library which has nearly as much documentation as other libraries together.
I would say with markdown whatever is possible with Quickbook is also possible just in an easier way.
How does markdown handle code snippets?
Code snippets seem like a 'must have' feature, but you just seem to be pasting code in. Experience shows that this is a recipe for mistakes.
What You See is What Compiles and Runs (WYSWCR) is what we need.
Well with the Fit library it uses two phases to build the documentation. So the first phase will either paste in the snippets from cpp files or it will extract snippets from markdown and put them in a cpp file. I use a similar technique to build by my presentations for C++Now or CppCon. I write my presentation in markdown with reveal.js, and then a separate tool pastes my code snippets into the markdown. Zach Laine is the one who wrote the tool for the presentations. I just took it from him. So markdown is very capable of What You See is What Compiles and Runs (WYSWCR). Paul
On 2/26/2016 10:20 AM, Krzysztof Jusiak wrote:
On Fri, Feb 26, 2016 at 2:48 PM, Paul A. Bristow <pbristow@hetp.u-net.com> wrote:
-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Krzysztof Jusiak Sent: 26 February 2016 13:57 To: boost@lists.boost.org 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...
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/d97ee097ff32123ff9242d39629595... 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.
On Friday, February 26, 2016 at 7:57:14 AM UTC-6, Krzysztof Jusiak wrote:
On Fri, Feb 26, 2016 at 12:55 PM, Paul A. Bristow <pbri...@hetp.u-net.com <javascript:>> wrote:
-----Original Message----- From: Boost [mailto:boost-...@lists.boost.org <javascript:>] On
Krzysztof Jusiak
Sent: 23 February 2016 12:41 To: bo...@lists.boost.org <javascript:> Subject: [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!
Dear Boosters,
I have just released version 1.0.0 of experimental Boost.DI library. Your C++14 header only Dependency Injection library with no dependencies.
Library entered Boost Formal Review Queue some time ago and right now, IMHO, is ready to be reviewed. http://www.boost.org/community/review_schedule.html
Therefore, I'm looking for a Review Manager, so if you think that Boost.DI is good enough to be reviewed and you would like to help with it,
Behalf Of please
let me know. Thank you!
In the mean time check out the library yourself online! http://boost-experimental.github.io/di/examples/index.html
Or read the interactive documentation... http://boost-experimental.github.io/di
Or check out the source code... https://github.com/boost-experimental/di
Why Boost.DI? * Boost.DI has none or minimal run-time overhead * Boost.DI compiles fast / Faster than Java-Dagger2! * Boost.DI gives short diagnostic messages * Boost.DI is non-intrusive * Boost.DI reduces boilerplate code * Boost.DI reduces testing effort * Boost.DI gives better control of what and how is created * Boost.DI gives better understanding about objects hierarchy
Read more why here -> http://boost-experimental.github.io/di/index.html
Any feedback is more than welcome!
This documentation looks very swish and sexy and has obviously received a lot of thoughtful work.
I'm not needing injections at present (apart from monkey glands perhaps ;-) but you told a plausible story with good graphics (though I was left with a bit of a Huh? feeling).
I'm not at all convinced that it's really worth making it all interactive.
Without going all NIH (Not Invented Here), I feel there are some big things missing.
1 Versioning - each released Boost version needs its own version of the docs - or people will get really confused.
Don't see any problem here. It's pretty much them same as any other spec. 1. Code is versioned so there is no issue with 'Run this code' will refer to a proper version 2. Comments are versioned as they depends on URL 3. Chat is common for all versions
2 Not standalone - we aren't all always online. HTML version is vital, single PDF is neatest.
I will provide pdf version, it's really easy to generate pdf from markdown. I will do it from http://boost-experimental.github.io/di/boost/ so it will have boost look and feel.
3 Unfamiliar. For a 'simple' (in what it offers, rather than its internal complexity) library like this, this is not so important, but the toolchain doesn't scale IMO.
Therefore, http://boost-experimental.github.io/di/boost/ theme which has the same look and feel as any other Boost library using quickbook. Generated from the same markdown, not fancy stuff, no java script, etc.
4 Difficult to find what you are looking for. This start with the library name Boost.DI - how are you going to know that you might want it in the first place? (There are lots of other 'pet' library
names
that will not draw users unless they know what they are looking for). And it gets worse when you fail to find a detailed table of contents and class, macro, function, concept and general index.
For me 'how to find' is an major documentation problem that we haven't cracked yet.
I'm not sure whether I do understand your point. IMHO developers are not browsing boost libraries trying to check whether a library might be useful to them or not. It's rather the opposite way. They have a problem and they are trying to check whether there is a library solving it. DI is a design pattern and really popular in other languages and therefore it would be easy to find by them.
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...
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.
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. Quickbook doesn't have support for doxygen either way and any try caused a LOT of pain.
Actually for the Fit library, I have inline comments in the header file. I do this by using a two phase doc generation. So, first I extract the documentation from the header files, and then extract the example code into a cpp file so the examples can be built and ran as well. Then I generate the docs with mkdocs. Paul
On Friday, February 26, 2016 at 6:56:00 AM UTC-6, Paul A. Bristow wrote:
-----Original Message----- From: Boost [mailto:boost-...@lists.boost.org <javascript:>] On Behalf Of Krzysztof Jusiak Sent: 23 February 2016 12:41 To: bo...@lists.boost.org <javascript:> Subject: [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!
Dear Boosters,
I have just released version 1.0.0 of experimental Boost.DI library. Your C++14 header only Dependency Injection library with no dependencies.
Library entered Boost Formal Review Queue some time ago and right now, IMHO, is ready to be reviewed. http://www.boost.org/community/review_schedule.html
Therefore, I'm looking for a Review Manager, so if you think that Boost.DI is good enough to be reviewed and you would like to help with it, please let me know. Thank you!
In the mean time check out the library yourself online! http://boost-experimental.github.io/di/examples/index.html
Or read the interactive documentation... http://boost-experimental.github.io/di
Or check out the source code... https://github.com/boost-experimental/di
Why Boost.DI? * Boost.DI has none or minimal run-time overhead * Boost.DI compiles fast / Faster than Java-Dagger2! * Boost.DI gives short diagnostic messages * Boost.DI is non-intrusive * Boost.DI reduces boilerplate code * Boost.DI reduces testing effort * Boost.DI gives better control of what and how is created * Boost.DI gives better understanding about objects hierarchy
Read more why here -> http://boost-experimental.github.io/di/index.html
Any feedback is more than welcome!
This documentation looks very swish and sexy and has obviously received a lot of thoughtful work.
I'm not needing injections at present (apart from monkey glands perhaps ;-) but you told a plausible story with good graphics (though I was left with a bit of a Huh? feeling).
I'm not at all convinced that it's really worth making it all interactive.
Without going all NIH (Not Invented Here), I feel there are some big things missing.
1 Versioning - each released Boost version needs its own version of the docs - or people will get really confused.
For Fit, readthedocs.org takes care of that for me and generates documentation for each versions(as well as the latest off of master). If I was using quickbooks I wouldn't be able take advantage of third-party tools like this.
2 Not standalone - we aren't all always online. HTML version is vital, single PDF is neatest.
From HTML, it can be integrated into Dash/Zeal which is the neatest.
3 Unfamiliar. For a 'simple' (in what it offers, rather than its internal complexity) library like this, this is not so important, but the toolchain doesn't scale IMO.
4 Difficult to find what you are looking for. This start with the library name Boost.DI - how are you going to know that you might want it in the first place? (There are lots of other 'pet' library names that will not draw users unless they know what they are looking for). And it gets worse when you fail to find a detailed table of contents and class, macro, function, concept and general index.
For me 'how to find' is an major documentation problem that we haven't cracked yet.
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.
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.
With mkdocs, the users can make changes with plain text. Plus, its written in markdown(which almost every developer on github or stackoverflow knows) unlike Quickbooks mark-up which is only known by core boost developers.
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.
Same with mkdocs.
Anyone can change the indexing by changing the source code (or the index.idx plain text-file that controls Boost auto-indexing).
Another not so well known configuration.
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.
And thats one major advantage of mkdocs, its easy for the user to generate the docs on their own as well as integrate easily with third-party tools. This is important, especially, if the user is contributing a feature that requires sizable documentation(they will definitely want to preview the docs). Having easier tools makes will help improve community contribution. Paul F.
participants (9)
-
Andrey Semashev -
Dominique Devienne -
Edward Diener -
Gavin Lambert -
Kris -
Krzysztof Jusiak
-
Paul A. Bristow -
Paul Fultz II -
Steven Watanabe