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