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
rendering system and and not do so when when it's some other
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.
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.
to say - "Documents should be readable with browsers
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk