On 1/7/16 6:12 AM, Louis Dionne wrote:
Agustín K-ballo Bergé
writes: On 1/7/2016 7:53 AM, Louis Dionne wrote:
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.
You're on the wrong track here. Documentation should be factored into two parts: a) Semantic content - which contains the information and the "meta data" which describes what the information is. This is what BoostBook does. b) Rendering - which displays the information in a way which is most convenient to the task. The current system was set up according to this model and it's for this reason that it's survived so well the test of time. As far as supporting printing via PDF - this is not the end in itself so much as proof that the documentation has been properly factored in the first place. (Although more people than you think are enamored with the PDF version of the docs.) The document preparation system should be able to inject javascript when appropriate into html when it is the target rendering system and and not do so when when it's some other system. Injecting javascript "by hand" into one's documents would conflict with the "factoring" idea described above. So I would not be a fan of this idea. Document maintenance should be focused on the semantic content rather than the rendering - so there should be no motivation for library authors to do this. Useful applications of javascript that occur to me are: a) ability to run code examples online. b) syntax coloring for code examples c) separate and optional "navigator" window as used by the serialization and io streams libraries. d) possible others that I don't know about. So I think the javascript admonition should be softened to say - "Documents should be readable with browsers which have javascript disabled" or something to that effect. Robert Ramey