Boost logo

Boost :

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

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