-----Original Message----- From: Boost [mailto:boost-bounces@lists.boost.org] On Behalf Of Agustín K-ballo Bergé Sent: 07 January 2016 12:41 To: boost@lists.boost.org Subject: Re: [boost] ATTENTION: Library requirements..
On 1/7/2016 7:53 AM, Louis Dionne wrote:
Robert Ramey
writes: A few observations
[...]
f) javescript.
I thing the admonitions agains java script should be softened. Most of the concerns existent when the document was originally written don't apply to day. I would like to see our html documentation support thinks like syntax coloring, running example code online, and the like. These things are often supported via injected javascript.
+1
I think JavaScript should be allowed, and even encouraged when it makes the documentation much superior. For example, Hana uses JavaScript to integrate performance benchmarks to the documentation in a nice way.
I'm one of those that used to disable javascript by default. I wouldn't mind its use when it results in a superior documentation, as long as it's optional and I can still get at least a mediocre documentation with the basic information, and possibly some hint that I need to enable javascript for this site to see more (not just to navigate differently).
Plus, all major browsers support JavaScript now, so I see this restriction as being outdated.
That might address one of the reasons given for banning it, namely:
- Incompatible with some older browsers and some text based browsers.
What's your take on the remaining ones?
- Makes printing docs pages difficult. - Often results in really bad user interface design. - "It's just annoying in general." - Would require Boost to test web pages for ECMAScript/JavaScript compliance. - Makes docs maintenance by other than the original developer more difficult.
Isn't necessary? Paul PS In discussing documentation, we seem to be focussing only the 'printed page' documentation. Perhaps we should be looking forward to providing more 'documentation' that appears when using an IDE? You get this already to some extent with Visual Studio when hovering over a function or parameter name - the information about the function provided as a comment shows. This is much more helpful than reams of C++ reference documentation. To get this to work well, we need to have a *syntax* to the comments that could only show the relevant information, or a choice perhaps. The existing defecto standard of Doxygen, like \function a_function Does something Really Useful. \param thingys How many thingys to do something with. might serve this purpose. (At present, if you have a big Doxygen comment, you get everything, perhaps more than you want). Of course you still need tutorial-style examples with code snippets that will be web browsable.