Re: [boost] Re: IOStreams formal review

From: Rob Stewart (stewart_at_[hidden])
Date: 2004-09-07 12:00:31

From: "Jonathan Turkanis" <technews_at_[hidden]>
> "John Torjo" <john.lists_at_[hidden]> wrote in message:
> 
> > I'm not sure if mixing streambuf and stream concepts is such a good idea.
> > As I've seen in your examples, you only use streams. Tnus, you don't use
> > streambufs directly.
> >
> > While having streambuf_facade is DEFINITELY a good idea, I think you
> > should have an  "Advanced" section, where you talk about the streambufs.
> > The rest of us are quite happy with having and using stream_facade.

Many of "us" are happy using streambufs to do work and use
streams only when we want the formatting.  Still, pushing the
streambuf discussion into an Advanced Topics section wouldn't be
so bad, so long as there was a brief description pointing folks
directly to it to get information on streambufs.

> I think I need to add -- very early in the documentation -- a brief overview of
> the standard iostreams library, in which I
> 
> 1. indroduce the types streamsize and streamoff
> 
> 2. mention that basic_streambuf is the component which represent a connection to
> a data source/sink
> 
> 3. explain that streams represent the formatting layer of standard i/o, and that
> each stream contains a pointer to a streambuf to which its i/o functions and
> operators delegate.
> 
> I can then explain that streambuf_facade is the principle component provided by
> the library, that stream_facade and filtering streams are really only
> convenience wrappers, but that the tutorial and examples will mostly use the
> wrappers since these are more familiar to existing users of the standard library
> and will probably be used most in practice.

If you can write the documentation around streams and defer
streambufs to an Advanced Topics section, it might reduce
confusion, will reduce main-line documentation complexity, and
should make the library more approachable.

Either way, what you've proposed would be terrific.

-- 
Rob Stewart                           stewart_at_[hidden]
Software Engineer                     http://www.sig.com
Susquehanna International Group, LLP  using std::disclaimer;