Agustín K-ballo Bergé
On 1/7/2016 7:53 AM, Louis Dionne wrote:
[...]
That might address one of the reasons given for banning it, namely:
- Incompatible with some older browsers and some text based browsers.
Just like we drop support for old compilers when it's time to move on, perhaps it's time to do the same for documentation.
What's your take on the remaining ones?
- Makes printing docs pages difficult.
Printing documentation? Really? I didn't even know it was a use case, and I'd say change your workflow instead of changing the documentation.
- Often results in really bad user interface design.
This seems subjective. Plus, I'm not saying people should sprinkle JavaScript all over their docs when it's not needed and end up with a complicated mess. But some things are inherently dynamic, and JavaScript is currently the right way to do these things.
- "It's just annoying in general."
This, too, seems subjective. I've personally never been annoyed by JavaScript.
- Would require Boost to test web pages for ECMAScript/JavaScript compliance.
This seems like an academic argument. Sure, we could push things as far as to test that, but is it really an issue in practice? I don't think so. FWIW, I'd rather see proper CI being set up for the actual libraries than testing the documentation.
- Makes docs maintenance by other than the original developer more difficult.
Based on my current experience, I would say people are much more likely to contribute documentation fixes that change the content, not the build system or the way the documentation is laid out. In other words, most people submit PRs fixing the actual Doxygen comments, and they would never know that the documentation uses JavaScript anyway. So most contributors wouldn't be affected by JavaScript. Apart from that, it is true that JavaScript adds a layer of complexity on top of straight HTML, which could make maintenance slightly harder. Bottom line (IMO): Banning JavaScript from the Boost documentation is overkill, outdated, and not in line with existing practice. Instead, we should soften the ban to a simple warning like: JavaScript is OK, but don't get all crazy with it. Your documentation must still make sense when browsed with JavaScript disabled. Regards, Louis