Tango quibbles - please write tickets so we can track them

[Matti Niemenmaa]

kris wrote:
> Lutger wrote:
>> kris wrote:
>>> Yes, the doc could be better overall. Some of it is just awesome,
>>> whilst some of it kinda sucks (my writing skills, for example). 
>>
>> [OT] No, your writing skills don't suck at all, but I think you did
>> place the bar a bit high with that io chapter. Mainly by assuming
>> readers are familiar with this kind of terminology.
> 
> OK, thank you. We'll get that fixed :)

I agree. In particular because Tango uses different terminology than just about
all other languages/libraries (streams vs conduits, almost everything is a
buffer instead of the stream doing the buffering), the I/O chapter should start
from the very basics and have useful examples.

It took me a long time to figure out the idioms around Tango I/O to the point
that I could write generic I/O code for a library, for example. For the C++ STL,
use std::istream and std::ostream. For Phobos, use std.stream.InputStream and
OutputStream.

After reading the (original version of the) Tango reference manual, I had no
clue. "Conduits, presumably, but what about Buffers? Do they need separate
support, or should I just take the Conduit the Buffer is wrapped around? But
won't that bypass the buffering?" Things like that.

Of course, it helps that the system has undergone a few redesigns in its short
life (the additions of InputStream + OutputStream, for instance). The reference
manual seems to have improved, too.

There's still some stuff I don't quite get, though. For instance, IConduit and
IBuffer: everything seems to inherit from Conduit or Buffer, so why have the
basic interfaces? Expanding on the reasons behind the whole design (and the
terminology) might be a good idea.

-- 
E-mail address: matti.niemenmaa+news, domain is iki (DOT) fi