Re: [boost] [doc] Liven up Boost Documentation with Java Script?

Subject: Re: [boost] [doc] Liven up Boost Documentation with Java Script?
From: Krzysztof Jusiak (krzysztof_at_[hidden])
Date: 2016-02-24 12:02:17

On Wed, Feb 24, 2016 at 4:06 PM, Robert Ramey <ramey_at_[hidden]> 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
>