Re: [boost] ATTENTION: Library requirements..

Subject: Re: [boost] ATTENTION: Library requirements..
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-01-07 12:11:44

On 1/7/16 6:12 AM, Louis Dionne wrote:
> Agustín K-ballo Bergé <kaballo86 <at> hotmail.com> 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