[doc] Liven up Boost Documentation with Java Script?

newer
[serialization] Back Versioning...

older
[ublas]Contribute about Toeplitz...

Krzysztof Jusiak

24 Feb 2016 24 Feb '16

2:50 p.m.

Dear Boosters, I'm writing to ask about your opinion regarding more interactive documentation for Boost. I know already that some of you would like to see online documentation without Java Script and that's absolutely fine and I agree that documentation should be available for anyone and any configuration. Nevertheless, I would like to know what the Boost community thinks about having following features in the documentation... * Run the code online (allows to check library with one click) * Comments (allows commenting on the documentation) * Chats (allows discussing issues and solutions) Personally, I have found above features extremely useful when checking out other languages/libraries and therefore I have implemented solutions for C++ too. Please, check it out (JS is required)... http://boost-experimental.github.io/msm-lite http://boost-experimental.github.io/di If there is an interest I can provide generic solution to allow developers to write documentation using markdown (mkdocs) and simply integrate it with their libraries. Currently, theme is just slightly modified version of readthedocs, however Paul Fultz II has prepared a boost theme for Fit library ( https://github.com/pfultz2/mkdocs-boost) already and it might be easily integration with the JS facilities provided. Cheers, Kris

Show replies by date

Andrey Semashev

24 Feb 24 Feb

3:24 p.m.

On Wed, Feb 24, 2016 at 5:50 PM, Krzysztof Jusiak wrote:

...

Nevertheless, I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click)

I imagine this could be useful to some. But frankly, I'd unlikely to use this feature myself.

...

* Comments (allows commenting on the documentation) * Chats (allows discussing issues and solutions)

There's been a discussion about comments, but unfortunately I can't find a link now. AFAIR, the main concerns were dealing with spam, usefulness of the comments and terms of the service that provides the support for comments (license, traffic injection, etc.) IMO, comments and let alone chats are inappropriate for documentation, detrimental even. I wouldn't want these to be enabled for my docs.

Robert Ramey

4:06 p.m.

On 2/24/16 6:50 AM, Krzysztof Jusiak wrote:

...

Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost.

I know already that some of you would like to see online documentation without Java Script and that's absolutely fine and I agree that documentation should be available for anyone and any configuration.

Nevertheless, I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click) * Comments (allows commenting on the documentation) * Chats (allows discussing issues and solutions)

Personally, I have found above features extremely useful when checking out other languages/libraries and therefore I have implemented solutions for C++ too.

Please, check it out (JS is required)... http://boost-experimental.github.io/msm-lite http://boost-experimental.github.io/di

I've also had some experience using this while delving into PHP libraries. PHP as a language isn't interesting for us of course. But the documentation / documentation/comment I found very useful. I can't see chat working out well - but no harm in experimenting with it. This experience has influenced my decisions regarding the boost library incubator which strongly encourages comments and reviews by users on submitted libraries. Though the incubator has some modest success in some areas, it's been a disappointment in others. a) The comment facility isn't used much. One issue is that there are lots of other places where one can comment / ask questions about a library. StackOverflow, Boost Developer/Users lists, github issues for the library and maybe others. Comments tend to accumulate around fewer hubs. In retro spect this is not a surprise. I guess I should tweak the inclubator to point to one or another comment area rather than implement it's own. This would be inline with the incubators implementation philosophy to avoid doing anything already done. b) the ability to comment on documentation - posting clarifications, questions about the documentation, etc. Is worthy of consideration.

...

If there is an interest I can provide generic solution to allow developers to write documentation using markdown (mkdocs) and simply integrate it with their libraries. Currently, theme is just slightly modified version of readthedocs, however Paul Fultz II has prepared a boost theme for Fit library ( https://github.com/pfultz2/mkdocs-boost) already and it might be easily integration with the JS facilities provided.

But this is totally the wrong way to go about this. We have a documentation infrastructure which, for the most part, works quite well. I produces relatively high quality linked presentation which is consistent accross those boost library (the majority) which use it. I'm very familiar wiht Paul Fultz TICK library documentation and found it to be unworthy of the underlying package. Most of the problem is the text, reference, lack of examples, weak tutorial etc. But the presentation as a web page is quite different that the boost libraries. It's jaring and not as effective. There is also - as far as know anyway to produce a PDF version of the documentation. This last is something the Boost Documentation system can do - albiet reserved for those who prefer to do their own dentistry. But it's not at hopeless. A short time ago, someone present some javascript which would add disqus commenting to each page of the documentation. With the current boost book system, it would be quite easy to create an xslt script which could be included in the xml -> html transformation pipe which would add the javascript commenting to each page the library. I would guess that this would take between 10-50 lines of xslt script code. It would be the documentation authors choice as to whether he would want to include this or not. To summarize a) create the xslt script to add commenting to each page when html output of documentation is created. b) convince authors to try the new script they generate their documentation. They do not have to change one line of their xml documentation or it's generation. c) If they don't like it, they just go back the old script. d) If your idea "sells", you're done. If not, you're also done. In any case, you will have achieved everything you desire in only 50 lines of code. e) caveat - xslt script is the probably the second most annoying scripting language I've ever had to deal with. Sure, it's only 50 lines, but it probably takes a few days learn about the whole XML tool chain to get it right. Good Luck with this. Robert Ramey

Krzysztof Jusiak

5:02 p.m.

On Wed, Feb 24, 2016 at 4:06 PM, Robert Ramey wrote:

...

On 2/24/16 6:50 AM, Krzysztof Jusiak wrote:

...
Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost.

I know already that some of you would like to see online documentation without Java Script and that's absolutely fine and I agree that documentation should be available for anyone and any configuration.

Nevertheless, I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click) * Comments (allows commenting on the documentation) * Chats (allows discussing issues and solutions)

Personally, I have found above features extremely useful when checking out other languages/libraries and therefore I have implemented solutions for C++ too.

Please, check it out (JS is required)... http://boost-experimental.github.io/msm-lite http://boost-experimental.github.io/di

I've also had some experience using this while delving into PHP libraries. PHP as a language isn't interesting for us of course. But the documentation / documentation/comment I found very useful. I can't see chat working out well - but no harm in experimenting with it.

This experience has influenced my decisions regarding the boost library incubator which strongly encourages comments and reviews by users on submitted libraries. Though the incubator has some modest success in some areas, it's been a disappointment in others.

a) The comment facility isn't used much. One issue is that there are lots of other places where one can comment / ask questions about a library. StackOverflow, Boost Developer/Users lists, github issues for the library and maybe others. Comments tend to accumulate around fewer hubs. In retro spect this is not a surprise. I guess I should tweak the inclubator to point to one or another comment area rather than implement it's own. This would be inline with the incubators implementation philosophy to avoid doing anything already done.

b) the ability to comment on documentation - posting clarifications, questions about the documentation, etc. Is worthy of consideration.

If there is an interest I can provide generic solution to allow developers

...
to write documentation using markdown (mkdocs) and simply integrate it with their libraries. Currently, theme is just slightly modified version of readthedocs, however Paul Fultz II has prepared a boost theme for Fit library ( https://github.com/pfultz2/mkdocs-boost) already and it might be easily integration with the JS facilities provided.

But this is totally the wrong way to go about this. We have a documentation infrastructure which, for the most part, works quite well. I produces relatively high quality linked presentation which is consistent accross those boost library (the majority) which use it.

Yea, maybe you are right. I just like experimenting with the documentation. It gives me a needed kick to write it ;)

...

I'm very familiar wiht Paul Fultz TICK library documentation and found it to be unworthy of the underlying package. Most of the problem is the text, reference, lack of examples, weak tutorial etc. But the presentation as a web page is quite different that the boost libraries. It's jaring and not as effective. There is also - as far as know anyway to produce a PDF version of the documentation. This last is something the Boost Documentation system can do - albiet reserved for those who prefer to do their own dentistry.

But it's not at hopeless.

A short time ago, someone present some javascript which would add disqus commenting to each page of the documentation. With the current boost book system, it would be quite easy to create an xslt script which could be included in the xml -> html transformation pipe which would add the javascript commenting to each page the library. I would guess that this would take between 10-50 lines of xslt script code. It would be the documentation authors choice as to whether he would want to include this or not.

That would be me :) Boost.DI documentation used to be done using quickbook and I added disqus and run this code to it. However, I was struggling making it the way I wanted and I ended up having a lot scripts fixing generated html, which I didn't fancy to maintain and therefore I decided to try something different. I tried doxygen, but it wasn't working for me that well. On the other hand, I always liked the look of mkdocs and markdown, so I experimented with it and I have found it was really easy to achieve things I was struggling to do with quickbook. But, I'm not an expert, so I might be wrong. Anyway, I'm not really bothered whether we are using quickbook, markodown or anything else but I wonder more about the interactive features on their own.

...

To summarize

a) create the xslt script to add commenting to each page when html output of documentation is created.

b) convince authors to try the new script they generate their documentation. They do not have to change one line of their xml documentation or it's generation.

c) If they don't like it, they just go back the old script.

d) If your idea "sells", you're done. If not, you're also done. In any case, you will have achieved everything you desire in only 50 lines of code.

e) caveat - xslt script is the probably the second most annoying scripting language I've ever had to deal with. Sure, it's only 50 lines, but it probably takes a few days learn about the whole XML tool chain to get it right.

Good Luck with this.

Sounds reasonable, but I'm not sure whether the effort is worth it in the boost community and therefore this tread. hanks for you comments tho. You have a really valid points.

...

Robert Ramey

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Robert Ramey

6:02 p.m.

On 2/24/16 9:02 AM, Krzysztof Jusiak wrote:

...

...
A short time ago, someone present some javascript which would add disqus commenting to each page of the documentation. With the current boost book system, it would be quite easy to create an xslt script which could be included in the xml -> html transformation pipe which would add the javascript commenting to each page the library. I would guess that this would take between 10-50 lines of xslt script code. It would be the documentation authors choice as to whether he would want to include this or not.

That would be me :) Boost.DI documentation used to be done using quickbook and I added disqus and run this code to it.

...

However, I was struggling making it the way I wanted and I ended up having a lot scripts fixing generated html, which I didn't fancy to maintain and therefore I decided to try something different. I tried doxygen, but it wasn't working for me that well. On the other hand, I always liked the look of mkdocs and markdown, so I experimented with it and I have found it was really easy to achieve things I was struggling to do with quickbook. But, I'm not an expert, so I might be wrong. Anyway, I'm not really bothered whether we are using quickbook, markodown or anything else but I wonder more about the interactive features on their own.

I'm sympathetic here. I never warmed up to quickbook for a couple of reasons: a) it was a new markup language to learn b) as a boost tool I was concerned that it would be an overly elaborate/quirky program. c) Integrating DOxygen generated reference documentation seemed a little ad hoc d) There isn't and obvious way to produce good reference documentation with DOxygen. I know people think it's doable because there is a template parameter keyword - and maybe it is. I have yet to see DOxygen produced reference documentation which documents template parameter requirements in the commonly accepted way - SGI documention. I know some one is going to produce a counter example but the fact that either it doesn't exist shows that either it's non-obvious or not easy or that programmers don't know how to document templates. Admittedly, the popularity of quikbook demonstrates that I might be wrong on some of the above points.

...

...
To summarize

a) create the xslt script to add commenting to each page when html output of documentation is created.

b) convince authors to try the new script they generate their documentation. They do not have to change one line of their xml documentation or it's generation.

c) If they don't like it, they just go back the old script.

d) If your idea "sells", you're done. If not, you're also done. In any case, you will have achieved everything you desire in only 50 lines of code.

e) caveat - xslt script is the probably the second most annoying scripting language I've ever had to deal with. Sure, it's only 50 lines, but it probably takes a few days learn about the whole XML tool chain to get it right.

Good Luck with this.

Sounds reasonable, but I'm not sure whether the effort is worth it in the boost community and therefore this tread.

Oh nooooo... - we're the ground troops in the battle defending lost causes. You can't give up!!! I'm suggesting you're got the right idea - but you got off on the wrong foot by getting discouraged with the Boost book tool chain which is hard to figure out. If you can find some time you invest in this, I believe that you can achieve what you / I want just by writing this script. I know it's a pain. But you'll have something to sell that will not be disrupative. It will be easily includable / excludable by library authors. No one will have to alter their markup or their personal tool chain. (the xml -> html filter is the last stage in the chain which produces the html documentation. It's independent of how the boost book xml has been produced. You'll limit your investment to making this one script. You'll get all you desire with the smallest amount of effort. Also once it works - it's quite painless and robust - though admittedly, quite opaque. Robert Ramey

Paul Fultz II

6:16 p.m.

...

...
If there is an interest I can provide generic solution to allow developers to write documentation using markdown (mkdocs) and simply integrate it with their libraries. Currently, theme is just slightly modified version of readthedocs, however Paul Fultz II has prepared a boost theme for Fit library ( https://github.com/pfultz2/mkdocs-boost) already and it might be easily integration with the JS facilities provided.

But this is totally the wrong way to go about this. We have a documentation infrastructure which, for the most part, works quite well. I produces relatively high quality linked presentation which is consistent accross those boost library (the majority) which use it.

Boost documentation infrastructure works quite well with much weeping and gnashing of teeth. With mkdocs, its easy for users to generate the documentation and it integrates with other tools(the documentation is regenerated on push at readthedocs.org).

...

I'm very familiar wiht Paul Fultz TICK library documentation and found it to be unworthy of the underlying package. Most of the problem is the text, reference, lack of examples, weak tutorial etc. But the presentation as a web page is quite different that the boost libraries. It's jaring and not as effective. There is also - as far as know anyway to produce a PDF version of the documentation. This last is something the Boost Documentation system can do - albiet reserved for those who prefer to do their own dentistry.

The Tick library is "unworthy" of a formal review currently, and the documentation is lacking because I have been working on preparing the Boost.Fit library for formal review(which starts next week). You can see the documentation for Boost.Fit here: http://pfultz2.github.io/Fit/doc/html/ It is much more complete with the boost look and feel, while being generated using the same "underlying package" that both Boost.Tick and Boost.DI uses. Also a PDF can be generated using `mkdocs2pandoc` tool. Paul

Robert Ramey

7:05 p.m.

On 2/24/16 10:16 AM, Paul Fultz II wrote:

...

...
I'm very familiar wiht Paul Fultz TICK library documentation and found it to be unworthy of the underlying package. Most of the problem is the text, reference, lack of examples, weak tutorial etc. But the presentation as a web page is quite different that the boost libraries. It's jaring and not as effective. There is also - as far as know anyway to produce a PDF version of the documentation. This last is something the Boost Documentation system can do - albiet reserved for those who prefer to do their own dentistry.

The Tick library is "unworthy" of a formal review currently, and the documentation is lacking because I have been working on preparing the Boost.Fit library for formal review(which starts next week).

Fine, I like the TICK package and I think it will be much better if more time can be invested in the documentation.

...

You can see the documentation for Boost.Fit here:

http://pfultz2.github.io/Fit/doc/html/

It is much more complete with the boost look and feel, while being generated using the same "underlying package" that both Boost.Tick and Boost.DI uses.

Also a PDF can be generated using `mkdocs2pandoc` tool.

My point is that there are two ways to go: a) convince boost library developers to create a whole new markup for their documentation so they can test/use your proposed infrastructure to add commenting to their documentation. b) make a small optional add-on to boost book using xslt which would work with the markup they already have. Now step back and consider which of the two strategies is more likely to result in convincing boost library authors to experiment with including commenting with their documentation? Robert Ramey

Paul Fultz II

7:59 p.m.

On Wednesday, February 24, 2016 at 1:05:39 PM UTC-6, Robert Ramey wrote:

...

On 2/24/16 10:16 AM, Paul Fultz II wrote:

...
...
I'm very familiar wiht Paul Fultz TICK library documentation and found it to be unworthy of the underlying package. Most of the problem is the text, reference, lack of examples, weak tutorial etc. But the presentation as a web page is quite different that the boost libraries. It's jaring and not as effective. There is also - as far as know anyway to produce a PDF version of the documentation. This last is something the Boost Documentation system can do - albiet reserved for those who prefer to do their own dentistry.

The Tick library is "unworthy" of a formal review currently, and the documentation is lacking because I have been working on preparing the Boost.Fit library for formal review(which starts next week).

Fine, I like the TICK package and I think it will be much better if more time can be invested in the documentation.

Yes, of course, but I only have so much time right now. I do plan to invest more time after the review of Boost.Fit, but it doesn't have to be a one-man show. If you would like to contribute examples or tutorials, like what you have in boost library incubator(or it could be original content), I would be more than happy to integrate them into the documentation.

...

...
You can see the documentation for Boost.Fit here:

http://pfultz2.github.io/Fit/doc/html/

It is much more complete with the boost look and feel, while being generated using the same "underlying package" that both Boost.Tick and Boost.DI uses.

Also a PDF can be generated using `mkdocs2pandoc` tool.

My point is that there are two ways to go:

a) convince boost library developers to create a whole new markup for their documentation so they can test/use your proposed infrastructure to add commenting to their documentation.

b) make a small optional add-on to boost book using xslt which would work with the markup they already have.

Now step back and consider which of the two strategies is more likely to result in convincing boost library authors to experiment with including commenting with their documentation?

I am not proposing using some new markup nor I am not proposing that all boost libraries jump ship to mkdocs either. There should be plenty of room for more documentation tools for boost libraries.

...

Robert Ramey

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Robert Ramey

25 Feb 25 Feb

10:10 p.m.

On 2/24/16 11:59 AM, Paul Fultz II wrote:

...

...
My point is that there are two ways to go:

a) convince boost library developers to create a whole new markup for their documentation so they can test/use your proposed infrastructure to add commenting to their documentation.

b) make a small optional add-on to boost book using xslt which would work with the markup they already have.

Now step back and consider which of the two strategies is more likely to result in convincing boost library authors to experiment with including commenting with their documentation?

I am not proposing using some new markup nor I am not proposing that all boost libraries jump ship to mkdocs either.

Then exactly what ARE you proposing?

...

There should be plenty of room for more documentation tools for boost libraries.

More tools in order to ... what exactly. The demos are pretty cool - but what are you trying to convince the rest of us to do? Robert Ramey

Paul Fultz II

26 Feb 26 Feb

2:38 p.m.

On Thursday, February 25, 2016 at 4:10:38 PM UTC-6, Robert Ramey wrote:

...

On 2/24/16 11:59 AM, Paul Fultz II wrote:

...
...
My point is that there are two ways to go:

a) convince boost library developers to create a whole new markup for their documentation so they can test/use your proposed infrastructure to add commenting to their documentation.

b) make a small optional add-on to boost book using xslt which would work with the markup they already have.

Now step back and consider which of the two strategies is more likely to result in convincing boost library authors to experiment with including commenting with their documentation?

I am not proposing using some new markup nor I am not proposing that all boost libraries jump ship to mkdocs either.

Then exactly what ARE you proposing?

I am proposing to use mkdocs to generate the documentation, but by no means am I proposing that ever boost library switch over to mkdocs. If other developers prefer quickbooks than thats great.

...

...
There should be plenty of room for more documentation tools for boost libraries.

More tools in order to ... what exactly.

The demos are pretty cool - but what are you trying to convince the rest of us to do?

For me, consume the documentation. However, Krzysztofmay who has started this thread is proposing something much larger.

...

Robert Ramey

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Kris

4:20 p.m.

Paul Fultz II wrote

...

On Thursday, February 25, 2016 at 4:10:38 PM UTC-6, Robert Ramey wrote:

...
On 2/24/16 11:59 AM, Paul Fultz II wrote:

...
...
My point is that there are two ways to go:

a) convince boost library developers to create a whole new markup for their documentation so they can test/use your proposed infrastructure to add commenting to their documentation.

b) make a small optional add-on to boost book using xslt which would work with the markup they already have.

Now step back and consider which of the two strategies is more likely to result in convincing boost library authors to experiment with including commenting with their documentation?

I am not proposing using some new markup nor I am not proposing that all boost libraries jump ship to mkdocs either.

Then exactly what ARE you proposing?

...
I am proposing to use mkdocs to generate the documentation, but by no means am I proposing that ever boost library switch over to mkdocs. If other developers prefer quickbooks than thats great.

...
There should be plenty of room for more documentation tools for boost libraries.

More tools in order to ... what exactly.

The demos are pretty cool - but what are you trying to convince the rest of us to do?

...
For me, consume the documentation. However, Krzysztofmay who has started this thread is proposing something much larger.

Actually, I started this thread to discuss what boost community think about interactive documentation in general. Just wanted to get feedback whether there is interest in such approach or not and if yes what exactly would be most useful.

I wasn't planning to talk about implementation details at all. Honestly, I don't really mind whether doc will be written in quickbook, markdown or doxygen. I have tried all of them and found markdown to be the easiest to achieve what I wanted, but it's just my opinion. I'm not trying to convince anyone here.

...
Robert Ramey

_______________________________________________ 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/doc-Liven-up-Boost-Documentation-with-Jav... Sent from the Boost - Dev mailing list archive at Nabble.com.

Rob Stewart

25 Feb 25 Feb

11:38 a.m.

On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak wrote:

...

Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost. [snip] I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click)

I see no value in that. The library is supposed to be in good working order and I wouldn't care to verify that from the docs. Instead, I'd expect a link to where such things can be viewed and managed. I just looked at the DI docs and I now see that you meant being able to run sample code shown in the docs. If the sample program was somehow interactive or the code was editable such that one could experiment with it, then I can see the value. Your "Run this code!" button hides some of the code!

...

* Comments (allows commenting on the documentation)

I can understand that comments would permit quick notes on what's lacking or unclear, but I also wouldn't want comment loading to slow page loading or for their display to detract from the information. Thus, having a means to display them, on demand, probably with a sticky bit, would be a reasonable compromise.

...

* Chats (allows discussing issues and solutions)

I don't think a documentation page is the place for that, though I have seen some value in such commentary on some MSDN pages. Still, a link to such discussions should suffice. Your floating chat button is actually rather annoying, especially when viewing the content on a small screen.

...

Please, check it out (JS is required)... http://boost-experimental.github.io/msm-lite http://boost-experimental.github.io/di

Perhaps I'm just too staid, but that page is horribly busy. My screen was filled with large blocks of color and all sorts of distractions. I had to scroll down a good bit before I even saw the word "Introduction". Add the ever-present "Chat" button, the run this, run that buttons, etc. and it's much too busy. ___ Rob (Sent from my portable computation engine)

Krzysztof Jusiak

3:18 p.m.

On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart wrote:

...

On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < krzysztof@jusiak.net> wrote:

...
Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost. [snip] I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click)

I see no value in that. The library is supposed to be in good working order and I wouldn't care to verify that from the docs. Instead, I'd expect a link to where such things can be viewed and managed.

I just looked at the DI docs and I now see that you meant being able to run sample code shown in the docs. If the sample program was somehow interactive or the code was editable such that one could experiment with it, then I can see the value.

Your "Run this code!" button hides some of the code!

Yea, that was my point for the user to be able to easily experiment before really trying the library. A lot of users won't download the library and check it out, but IMHO, some of them may actually click the button and check what will happen. Moreover, some users (me, for example) when see code example are curious what will happen if... Documentation will not cover all cases, but if user can quickly check it might be beneficial, I think. If it comes to interaction itself, I was thinking of creating an interactive tutorial for the users. For example, a lot of people do not see benefits in dependency injection and having a quick exercise to adopt code with or without DI could have changed their mind. One of the examples where user can interact a bit more... http://boost-experimental.github.io/di/extensions/index.html#types-dumper

...

...
* Comments (allows commenting on the documentation)

I can understand that comments would permit quick notes on what's lacking or unclear, but I also wouldn't want comment loading to slow page loading or for their display to detract from the information. Thus, having a means to display them, on demand, probably with a sticky bit, would be a reasonable compromise.

Point taken. Therefore, I have prepared 3 themes for the users. * Boost-Experimental - the fancy one - http://boost-experimental.github.io/di * Boost-Modern - more like Boost but still interactive - http://boost-experimental.github.io/di/boost-modern/ * Boost - classic Boost (no Java Script) - http://boost-experimental.github.io/di/boost/ Boost themes are based on Paul's great work. They are not perfect yet, but, I guess, they show the point. User can even change the theme with a button provided on the top right corner.

...

...
* Chats (allows discussing issues and solutions)

I don't think a documentation page is the place for that, though I have seen some value in such commentary on some MSDN pages. Still, a link to such discussions should suffice.

Your floating chat button is actually rather annoying, especially when viewing the content on a small screen.

Fair point, therefore, on mobile you may want to change the theme to http://boost-experimental.github.io/di/boost/ I actually find out that chats seems to be more useful than comments as people are more willing to use them. Hana's chat it's quite active and useful. * https://gitter.im/boostorg/hana * https://gitter.im/boost-experimental/di

...

...
Please, check it out (JS is required)... http://boost-experimental.github.io/msm-lite http://boost-experimental.github.io/di

Perhaps I'm just too staid, but that page is horribly busy. My screen was filled with large blocks of color and all sorts of distractions. I had to scroll down a good bit before I even saw the word "Introduction". Add the ever-present "Chat" button, the run this, run that buttons, etc. and it's much too busy.

I agree, that for mobile it might be a bit to much and, therefore the http://boost-experimental.github.io/di/boost/ theme. I may also add detection in order to choose the most suitable theme for the user. Depending on JS enabled/disabled screen size, etc. Thanks for you feedback. ___

...

Rob

(Sent from my portable computation engine)

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Paul Fultz II

6:08 p.m.

On Thursday, February 25, 2016 at 9:18:28 AM UTC-6, Krzysztof Jusiak wrote:

...

On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart javascript:> wrote:

...
On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < krzy...@jusiak.net javascript:> wrote:

...
Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost. [snip] I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click)

I see no value in that. The library is supposed to be in good working order and I wouldn't care to verify that from the docs. Instead, I'd expect a link to where such things can be viewed and managed.

I just looked at the DI docs and I now see that you meant being able to run sample code shown in the docs. If the sample program was somehow interactive or the code was editable such that one could experiment with it, then I can see the value.

Your "Run this code!" button hides some of the code!

Yea, that was my point for the user to be able to easily experiment before really trying the library. A lot of users won't download the library and check it out, but IMHO, some of them may actually click the button and check what will happen. Moreover, some users (me, for example) when see code example are curious what will happen if... Documentation will not cover all cases, but if user can quickly check it might be beneficial, I think. If it comes to interaction itself, I was thinking of creating an interactive tutorial for the users. For example, a lot of people do not see benefits in dependency injection and having a quick exercise to adopt code with or without DI could have changed their mind.

One of the examples where user can interact a bit more... http://boost-experimental.github.io/di/extensions/index.html#types-dumper

...
...
* Comments (allows commenting on the documentation)

I can understand that comments would permit quick notes on what's lacking or unclear, but I also wouldn't want comment loading to slow page loading or for their display to detract from the information. Thus, having a means to display them, on demand, probably with a sticky bit, would be a reasonable compromise.

Point taken. Therefore, I have prepared 3 themes for the users. * Boost-Experimental - the fancy one - http://boost-experimental.github.io/di * Boost-Modern - more like Boost but still interactive - http://boost-experimental.github.io/di/boost-modern/ * Boost - classic Boost (no Java Script) - http://boost-experimental.github.io/di/boost/

BTW, my boost theme still uses javascript for syntax highlighting. I would like to add a variable to disable javascript highlighting(or perhaps pick a different highlighting theme). This way the user could highlight using pygments instead if they wanted to. Also, the theme can be installed using `pip install mkdocs-boost`. And then the docs can be built by setting the theme to `boost` either on the command line or in the yaml file: mkdocs build -t boost This way you don't have to drag around the boost theme directory. Paul

Kris

9:07 p.m.

...

On Thursday, February 25, 2016 at 9:18:28 AM UTC-6, Krzysztof Jusiak wrote:

On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart <rob.s...@ > javascript:> wrote:

...
On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < krzy...@ javascript:> wrote:

...
Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost. [snip] I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click)

I see no value in that. The library is supposed to be in good working order and I wouldn't care to verify that from the docs. Instead, I'd expect a link to where such things can be viewed and managed.

I just looked at the DI docs and I now see that you meant being able to run sample code shown in the docs. If the sample program was somehow interactive or the code was editable such that one could experiment with it, then I can see the value.

Your "Run this code!" button hides some of the code!

Yea, that was my point for the user to be able to easily experiment before really trying the library. A lot of users won't download the library and check it out, but IMHO, some of them may actually click the button and check what will happen. Moreover, some users (me, for example) when see code example are curious what will happen if... Documentation will not cover all cases, but if user can quickly check it might be beneficial, I think. If it comes to interaction itself, I was thinking of creating an interactive tutorial for the users. For example, a lot of people do not see benefits in dependency injection and having a quick exercise to adopt code with or without DI could have changed their mind.

One of the examples where user can interact a bit more... http://boost-experimental.github.io/di/extensions/index.html#types-dumper

...
...
* Comments (allows commenting on the documentation)

I can understand that comments would permit quick notes on what's lacking or unclear, but I also wouldn't want comment loading to slow page loading or for their display to detract from the information. Thus, having a means to display them, on demand, probably with a sticky bit, would be a reasonable compromise.

Point taken. Therefore, I have prepared 3 themes for the users. * Boost-Experimental - the fancy one - http://boost-experimental.github.io/di * Boost-Modern - more like Boost but still interactive - http://boost-experimental.github.io/di/boost-modern/ * Boost - classic Boost (no Java Script) - http://boost-experimental.github.io/di/boost/

...

BTW, my boost theme still uses javascript for syntax highlighting. I would like to add a variable to disable javascript highlighting(or perhaps pick a different highlighting theme). This way the user could highlight using pygments instead if they wanted to.

That would be great!

...

Also, the theme can be installed using `pip install mkdocs-boost`. And then the docs can be built by setting the theme to `boost` either on the command line or in the yaml file:

mkdocs build -t boost

This way you don't have to drag around the boost theme directory.

Wow, that's cool. However, I have made quite a few modifications to the original theme in order to support tables, theme selection and added (optionally) all Java Script magic. Moreover, I have removed a lot of not needed files from the theme. When the look and feel of the spec will be approved by the boost users I will create a pull request so that you can check what I have changed. Thanks again for a great job on the boost-theme!

...

Paul

-- View this message in context: http://boost.2283326.n4.nabble.com/doc-Liven-up-Boost-Documentation-with-Jav... Sent from the Boost - Dev mailing list archive at Nabble.com.

Paul Fultz II

26 Feb 26 Feb

3:35 p.m.

On Thursday, February 25, 2016 at 3:34:22 PM UTC-6, Kris wrote:

...

...
On Thursday, February 25, 2016 at 9:18:28 AM UTC-6, Krzysztof Jusiak wrote:

On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart <rob.s...@ > javascript:> wrote:

...
On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < krzy...@ javascript:> wrote:

...
Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost. [snip] I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click)

I see no value in that. The library is supposed to be in good working order and I wouldn't care to verify that from the docs. Instead, I'd expect a link to where such things can be viewed and managed.

I just looked at the DI docs and I now see that you meant being able to run sample code shown in the docs. If the sample program was somehow interactive or the code was editable such that one could experiment with it, then I can see the value.

Your "Run this code!" button hides some of the code!

Yea, that was my point for the user to be able to easily experiment before really trying the library. A lot of users won't download the library and check it out, but IMHO, some of them may actually click the button and check what will happen. Moreover, some users (me, for example) when see code example are curious what will happen if... Documentation will not cover all cases, but if user can quickly check it might be beneficial, I think. If it comes to interaction itself, I was thinking of creating an interactive tutorial for the users. For example, a lot of people do not see benefits in dependency injection and having a quick exercise to adopt code with or without DI could have changed their mind.

One of the examples where user can interact a bit more...

http://boost-experimental.github.io/di/extensions/index.html#types-dumper

...
...
...
* Comments (allows commenting on the documentation)

I can understand that comments would permit quick notes on what's lacking or unclear, but I also wouldn't want comment loading to slow page loading or for their display to detract from the information. Thus, having a means to display them, on demand, probably with a sticky bit, would be a reasonable compromise.

Point taken. Therefore, I have prepared 3 themes for the users. * Boost-Experimental - the fancy one - http://boost-experimental.github.io/di * Boost-Modern - more like Boost but still interactive - http://boost-experimental.github.io/di/boost-modern/ * Boost - classic Boost (no Java Script) - http://boost-experimental.github.io/di/boost/

...
BTW, my boost theme still uses javascript for syntax highlighting. I would like to add a variable to disable javascript highlighting(or perhaps pick a different highlighting theme). This way the user could highlight using pygments instead if they wanted to.

That would be great!

...
Also, the theme can be installed using `pip install mkdocs-boost`. And then the docs can be built by setting the theme to `boost` either on the command line or in the yaml file:

mkdocs build -t boost

This way you don't have to drag around the boost theme directory.

Wow, that's cool. However, I have made quite a few modifications to the original theme in order to support tables, theme selection and added (optionally) all Java Script magic. Moreover, I have removed a lot of not needed files from the theme. When the look and feel of the spec will be approved by the boost users I will create a pull request so that you can check what I have changed. Thanks again for a great job on the boost-theme!

Ah yes, tables is something that needs improving. I was working with the boost CSS, and it doesn't seem to have anything for css tables. I think boost book styles the tables with HTML. I'll take a look at what you did for tables and try to integrate that in. Also, mkdocs will include automatically all javascripts files in the documentation source directory, plus additional files can be included using the `extra_javascript`. However, I don't know if the boost theme supports this yet(I haven't had a need for it yet), but it should be supported. Plus, I think this might be a good place for some of the javascript until it gets official approval in boost. Paul

Rene Rivera

3:46 p.m.

On Fri, Feb 26, 2016 at 9:35 AM, Paul Fultz II wrote:

...

Ah yes, tables is something that needs improving. I was working with the boost CSS, and it doesn't seem to have anything for css tables. I think boost book styles the tables with HTML. I'll take a look at what you did for tables and try to integrate that in.

https://github.com/boostorg/boost/blob/master/doc/src/boostbook.css#L234 -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Paul Fultz II

3:54 p.m.

On Friday, February 26, 2016 at 9:46:37 AM UTC-6, Rene Rivera wrote:

...

On Fri, Feb 26, 2016 at 9:35 AM, Paul Fultz II javascript:> wrote:

...
Ah yes, tables is something that needs improving. I was working with the boost CSS, and it doesn't seem to have anything for css tables. I think boost book styles the tables with HTML. I'll take a look at what you did for tables and try to integrate that in.

https://github.com/boostorg/boost/blob/master/doc/src/boostbook.css#L234

Yep, that exactly my point. I need to wrap the tables in divs with special classes to get things like borders and such. Tables should look good by default.

Kris

3:55 p.m.

Paul Fultz II wrote

...

On Friday, February 26, 2016 at 9:46:37 AM UTC-6, Rene Rivera wrote:

...
On Fri, Feb 26, 2016 at 9:35 AM, Paul Fultz II <

...

pfu...@

...

> javascript:

...
wrote:

...
Ah yes, tables is something that needs improving. I was working with

...
boost CSS, and it doesn't seem to have anything for css tables. I think boost book styles the tables with HTML. I'll take a look at what you did for

the tables

...
and try to integrate that in.

<https://github.com/boostorg/boost/blob/master/doc/src/boostbook.css#L234>;

...
Yep, that exactly my point. I need to wrap the tables in divs with special classes to get things like borders and such. Tables should look good by default.

As a wknd I extended the boostbook.css table support. I doesn't need to wrap tables in divs.

table { table-layout: fixed; border:1px solid #C0C0C0; border-collapse:collapse; margin-bottom: 20px; padding:5px; width: 100%; font-size: 90%; }

IMHO looks pretty much the same, but you can check it yourself -> http://boost-experimental.github.io/di/boost/user_guide/index.html

BTW Support for note, tip, etc. will require some tweaks in css too.

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

-- View this message in context: http://boost.2283326.n4.nabble.com/doc-Liven-up-Boost-Documentation-with-Jav... Sent from the Boost - Dev mailing list archive at Nabble.com.

Rene Rivera

4:30 p.m.

On Fri, Feb 26, 2016 at 9:55 AM, Kris wrote:

...

Paul Fultz II wrote

...
On Friday, February 26, 2016 at 9:46:37 AM UTC-6, Rene Rivera wrote:

...
On Fri, Feb 26, 2016 at 9:35 AM, Paul Fultz II <

...
pfu...@

...
> javascript:

...
wrote:

...
Ah yes, tables is something that needs improving. I was working with

the

...
boost CSS, and it doesn't seem to have anything for css tables. I think

boost

...
...
...
book styles the tables with HTML. I'll take a look at what you did for tables and try to integrate that in.

< https://github.com/boostorg/boost/blob/master/doc/src/boostbook.css#L234> ;

...
Yep, that exactly my point. I need to wrap the tables in divs with special classes to get things like borders and such. Tables should look good by default.

As a wknd I extended the boostbook.css table support. I doesn't need to wrap tables in divs.

table { table-layout: fixed; border:1px solid #C0C0C0; border-collapse:collapse; margin-bottom: 20px; padding:5px; width: 100%; font-size: 90%; }

IMHO looks pretty much the same, but you can check it yourself -> http://boost-experimental.github.io/di/boost/user_guide/index.html

Warning.. It uses the divs in order to disambiguate documentation tables vs. regular web site tables. As the documentation tables appear embedded in the web site when browsed on-line. http://www.boost.org/doc/libs/1_60_0/doc/html/align.html vs. http://www.boost.org/development/exemplar.html -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Paul Fultz II

3:35 p.m.

On Thursday, February 25, 2016 at 3:34:22 PM UTC-6, Kris wrote:

...

...
On Thursday, February 25, 2016 at 9:18:28 AM UTC-6, Krzysztof Jusiak wrote:

On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart <rob.s...@ > javascript:> wrote:

...
On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < krzy...@ javascript:> wrote:

...
Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost. [snip] I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click)

I see no value in that. The library is supposed to be in good working order and I wouldn't care to verify that from the docs. Instead, I'd expect a link to where such things can be viewed and managed.

I just looked at the DI docs and I now see that you meant being able to run sample code shown in the docs. If the sample program was somehow interactive or the code was editable such that one could experiment with it, then I can see the value.

Your "Run this code!" button hides some of the code!

Yea, that was my point for the user to be able to easily experiment before really trying the library. A lot of users won't download the library and check it out, but IMHO, some of them may actually click the button and check what will happen. Moreover, some users (me, for example) when see code example are curious what will happen if... Documentation will not cover all cases, but if user can quickly check it might be beneficial, I think. If it comes to interaction itself, I was thinking of creating an interactive tutorial for the users. For example, a lot of people do not see benefits in dependency injection and having a quick exercise to adopt code with or without DI could have changed their mind.

One of the examples where user can interact a bit more...

http://boost-experimental.github.io/di/extensions/index.html#types-dumper

...
...
...
* Comments (allows commenting on the documentation)

I can understand that comments would permit quick notes on what's lacking or unclear, but I also wouldn't want comment loading to slow page loading or for their display to detract from the information. Thus, having a means to display them, on demand, probably with a sticky bit, would be a reasonable compromise.

Point taken. Therefore, I have prepared 3 themes for the users. * Boost-Experimental - the fancy one - http://boost-experimental.github.io/di * Boost-Modern - more like Boost but still interactive - http://boost-experimental.github.io/di/boost-modern/ * Boost - classic Boost (no Java Script) - http://boost-experimental.github.io/di/boost/

...
BTW, my boost theme still uses javascript for syntax highlighting. I would like to add a variable to disable javascript highlighting(or perhaps pick a different highlighting theme). This way the user could highlight using pygments instead if they wanted to.

That would be great!

...
Also, the theme can be installed using `pip install mkdocs-boost`. And then the docs can be built by setting the theme to `boost` either on the command line or in the yaml file:

mkdocs build -t boost

This way you don't have to drag around the boost theme directory.

Wow, that's cool. However, I have made quite a few modifications to the original theme in order to support tables, theme selection and added (optionally) all Java Script magic. Moreover, I have removed a lot of not needed files from the theme. When the look and feel of the spec will be approved by the boost users I will create a pull request so that you can check what I have changed. Thanks again for a great job on the boost-theme!

Krzysztof Jusiak

11:58 a.m.

On Thu, Feb 25, 2016 at 3:18 PM, Krzysztof Jusiak wrote:

...

On Thu, Feb 25, 2016 at 11:38 AM, Rob Stewart wrote:

...
On February 24, 2016 9:50:13 AM EST, Krzysztof Jusiak < krzysztof@jusiak.net> wrote:

...
Dear Boosters,

I'm writing to ask about your opinion regarding more interactive documentation for Boost. [snip] I would like to know what the Boost community thinks about having following features in the documentation...

* Run the code online (allows to check library with one click)

I see no value in that. The library is supposed to be in good working order and I wouldn't care to verify that from the docs. Instead, I'd expect a link to where such things can be viewed and managed.

I just looked at the DI docs and I now see that you meant being able to run sample code shown in the docs. If the sample program was somehow interactive or the code was editable such that one could experiment with it, then I can see the value.

Your "Run this code!" button hides some of the code!

Yea, that was my point for the user to be able to easily experiment before really trying the library. A lot of users won't download the library and check it out, but IMHO, some of them may actually click the button and check what will happen. Moreover, some users (me, for example) when see code example are curious what will happen if... Documentation will not cover all cases, but if user can quickly check it might be beneficial, I think. If it comes to interaction itself, I was thinking of creating an interactive tutorial for the users. For example, a lot of people do not see benefits in dependency injection and having a quick exercise to adopt code with or without DI could have changed their mind.

One of the examples where user can interact a bit more... http://boost-experimental.github.io/di/extensions/index.html#types-dumper

Another example of having online compilation handy is to show code performance. For example, with Boost.DI I claim that simple value bindings will generate following ASM-x86-64: // ASM x86-64 (same as `return 42`) mov $0x2a,%eax retq However, user can be curious what will happen if I do something else (like in https://gcc.godbolt.org/), with online compiler you can do that too for your library. Example here -> http://boost-experimental.github.io/di/overview/index.html#performance Sorry for replaying to myself, I was just thinking it might be useful sharing that.

...

...
...
* Comments (allows commenting on the documentation)

I can understand that comments would permit quick notes on what's lacking or unclear, but I also wouldn't want comment loading to slow page loading or for their display to detract from the information. Thus, having a means to display them, on demand, probably with a sticky bit, would be a reasonable compromise.

Point taken. Therefore, I have prepared 3 themes for the users. * Boost-Experimental - the fancy one - http://boost-experimental.github.io/di * Boost-Modern - more like Boost but still interactive - http://boost-experimental.github.io/di/boost-modern/ * Boost - classic Boost (no Java Script) - http://boost-experimental.github.io/di/boost/

Boost themes are based on Paul's great work. They are not perfect yet, but, I guess, they show the point. User can even change the theme with a button provided on the top right corner.

...
...
* Chats (allows discussing issues and solutions)

I don't think a documentation page is the place for that, though I have seen some value in such commentary on some MSDN pages. Still, a link to such discussions should suffice.

Your floating chat button is actually rather annoying, especially when viewing the content on a small screen.

Fair point, therefore, on mobile you may want to change the theme to http://boost-experimental.github.io/di/boost/ I actually find out that chats seems to be more useful than comments as people are more willing to use them. Hana's chat it's quite active and useful. * https://gitter.im/boostorg/hana * https://gitter.im/boost-experimental/di

...
...
Please, check it out (JS is required)... http://boost-experimental.github.io/msm-lite http://boost-experimental.github.io/di

Perhaps I'm just too staid, but that page is horribly busy. My screen was filled with large blocks of color and all sorts of distractions. I had to scroll down a good bit before I even saw the word "Introduction". Add the ever-present "Chat" button, the run this, run that buttons, etc. and it's much too busy.

I agree, that for mobile it might be a bit to much and, therefore the http://boost-experimental.github.io/di/boost/ theme. I may also add detection in order to choose the most suitable theme for the user. Depending on JS enabled/disabled screen size, etc.

Thanks for you feedback.

___

...
Rob

(Sent from my portable computation engine)

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Boris Schäling

5:53 p.m.

"Krzysztof Jusiak" wrote in message news:CALNnLfa+WCdCEcqAeX40ORfohCZ3UUnFyZgVicR=ZuDQwEhwNg@mail.gmail.com...

...

* Run the code online (allows to check library with one click)

The #1 request on http://theboostcpplibraries.com/ is to make the output of the sample programs available right after the examples. I like that this is what happens when I run code online. However it might be better if the output was always immediately available (without having to run code first)? (This is of course possible by embedding output into static webpages; no need for an online compiler.) I'm very much in favor of providing complete sample programs which users can build right away and use as a starting point to play around with libraries. However I'm not sure whether users would like to play around with examples in a browser (can't remember that I ever wanted to do this)? If they really want to, they could copy&paste code to http://melpon.org/wandbox. One could provide a button or link next to every example which opens Wandbox and copies&pastes code automatically. But I don't know whether there are enough users out there who need this?

...

* Comments (allows commenting on the documentation)

I think the most important advantage of comments is to interact with users who can't be reached otherwise (because they aren't subscribed to mailing lists for example). The biggest disadvantage is however that someone has to interact with users. If users add comments and nobody replies, it's better not to have comments at all. :)

...

* Chats (allows discussing issues and solutions)

I guess it's a bit similar as with comments. Personally I like to see social features being added to the website (and if only temporary for a test). For us who we are subscribed to mailing lists it may seem unnecessary. But I believe there are lots of users out there we could interact with more easily if there were social features on the website. My two cents, Boris

Krzysztof Jusiak

8:09 p.m.

On Fri, Feb 26, 2016 at 5:53 PM, Boris Schäling wrote:

...

"Krzysztof Jusiak" wrote in message news:CALNnLfa+WCdCEcqAeX40ORfohCZ3UUnFyZgVicR=ZuDQwEhwNg@mail.gmail.com...

...
* Run the code online (allows to check library with one click)

The #1 request on http://theboostcpplibraries.com/ is to make the output of the sample programs available right after the examples. I like that this is what happens when I run code online. However it might be better if the output was always immediately available (without having to run code first)? (This is of course possible by embedding output into static webpages; no need for an online compiler.)

I'm very much in favor of providing complete sample programs which users can build right away and use as a starting point to play around with libraries. However I'm not sure whether users would like to play around with examples in a browser (can't remember that I ever wanted to do this)? If they really want to, they could copy&paste code to http://melpon.org/wandbox. One could provide a button or link next to every example which opens Wandbox and copies&pastes code automatically. But I don't know whether there are enough users out there who need this?

Totally agree. Personally, I really like cpprefrence and their 'run this code'. My solution is based on the same idea -> http://en.cppreference.com/w/cpp/algorithm/sort. Yea, you can copy full example to wandbox, however, you won't have the library headers there and it won't compile. BTW. I'm using wandbox under the hood. I firstly started with generting a link to wandobx with the library and a basic example, but decided to go a step further with it as I have noticed that all new languages like rust/nim/go/d were using similar approach and because I have found it more convinent. Furthermore, I have noticed a huge potential in it to: * create an interactive tutorial with code excersies for the users * printing optimized code for users to experiment easily ( http://boost-experimental.github.io/di/overview/index.html#performance) * interact with online tools like plantuml to generate diagrams (for example with Boost.MSM-lite state machine)

...

* Comments (allows commenting on the documentation)

...
I think the most important advantage of comments is to interact with users who can't be reached otherwise (because they aren't subscribed to mailing lists for example). The biggest disadvantage is however that someone has to interact with users. If users add comments and nobody replies, it's better not to have comments at all. :)

Agree.

...

* Chats (allows discussing issues and solutions)

...
I guess it's a bit similar as with comments.

Personally I like to see social features being added to the website (and if only temporary for a test). For us who we are subscribed to mailing lists it may seem unnecessary. But I believe there are lots of users out there we could interact with more easily if there were social features on the website.

I think so too. Especially, users not familair with boost as much. Gitter for hana and di show that users are willing to use them which is great.

...

My two cents, Boris

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Boris Schäling

9:22 p.m.

"Krzysztof Jusiak" wrote in message news:CALNnLfaCy--cPAeC8vFyXRC1y0pSA2=TzYB0k+9gcc_g_0pzJA@mail.gmail.com...

...

[...] library headers there and it won't compile. BTW. I'm using wandbox under the hood.

I knew you know Wandbox - I had a brief look at your JavaScript code. :) By the way, do you or anyone else know how reliable Wandbox is? Is the website/online compiler up and running most of the time?

...

I firstly started with generting a link to wandobx with the library and a basic example, but decided to go a step further with it as I have noticed that all new languages like rust/nim/go/d were using similar approach and because I have found it more convinent. Furthermore, I have noticed a huge potential in it to:

When you look at the examples of these other programming languages, do you modify them and are happy you can run them in the browser? (Serious question; I wonder as I never did this and never missed such an option.) Given that you referred to other programming languages: I do wonder whether developers look at C++ as a programming language which is too difficult to get started with ("you can try out Rust/Nim/Go/D in the browser but not C++ - too much effort to try it out"). If this is the case, I would definitely want to see more C++ examples being interactive.

...

* create an interactive tutorial with code excersies for the users

Interactive tutorials sounds like a great idea to me!

...

* printing optimized code for users to experiment easily ( http://boost-experimental.github.io/di/overview/index.html#performance) * interact with online tools like plantuml to generate diagrams (for example with Boost.MSM-lite state machine)

Here I am not so sure anymore. :) Boris

...

[...]

Krzysztof Jusiak

10:17 p.m.

On Fri, Feb 26, 2016 at 9:22 PM, Boris Schäling wrote:

...

By the way, do you or anyone else know how reliable Wandbox is? Is the website/online compiler up and running most of the time?

It seems to be reliable, but I'm not sure about it. I guess wandbox is based in Asia somewhere. Nonethless, they provide the dialy snapshots of the compilers which is awesome!

...

When you look at the examples of these other programming languages, do you modify them and are happy you can run them in the browser? (Serious question; I wonder as I never did this and never missed such an option.)

Yea, I do experiment in the browser a bit. I just can't be asked going through the installation process as it's different for each compiler. Therefore, I'm checking it online. If I like i will give it ago and spend more efford installing and playing with it online. That's the way I experimented with Go and Rust. But it just me, no idea whether other developers have similar approach.

...

Given that you referred to other programming languages: I do wonder whether developers look at C++ as a programming language which is too difficult to get started with ("you can try out Rust/Nim/Go/D in the browser but not C++ - too much effort to try it out"). If this is the case, I would definitely want to see more C++ examples being interactive.

Well, I see it a bit like that, but again, it's just my view from my experience. A lot of developers I talk to (mostly Java,Python, C# or JS), still think that C++ is basically C with classes. Moreover, it compiles slowly, gives really long error messages and plenty of segfaults. It's hard to convenience them to modern C++ and that OO might be done the same way, that we can use dependency injection too, that we can compile quickly etc... Having an online way to show that, IMHO, may surprise them a bit and maybe encourage to try modern C++ a bit more.

Boris Schäling

1 Mar 1 Mar

11:25 a.m.

"Krzysztof Jusiak" wrote in message news:CALNnLfaCy--cPAeC8vFyXRC1y0pSA2=TzYB0k+9gcc_g_0pzJA@mail.gmail.com...

...

[...] Totally agree. Personally, I really like cpprefrence and their 'run this code'. My solution is based on the same idea -> http://en.cppreference.com/w/cpp/algorithm/sort.

Just for the record: I asked cppreference.com about their experience with their "Run this code" examples. They made their examples interactive because they want to encourage users to add/fix examples. As cppreference.com is a wiki, everything is edited in the browser. If you work in the browser anyway, it makes sense to me if you can test examples in the browser, too. Boris

3192

Age (days ago)

3198

Last active (days ago)

List overview

Download

26 comments

8 participants

participants (8)

Andrey Semashev
Boris Schäling
Kris
Krzysztof Jusiak
Paul Fultz II
Rene Rivera
Rob Stewart
Robert Ramey