Boost logo

Boost :

Subject: Re: [boost] [doc] Liven up Boost Documentation with Java Script?
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-02-24 11:06:39

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)...

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 (
> 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

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