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

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

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