[boost] Re: Namespaces vs. directory placement

From: Jonathan Turkanis (technews_at_[hidden])
Date: 2004-12-29 13:54:42

David Abrahams wrote:
>> Jonathan Turkanis wrote:
>>> I would greatly prefer to use the namespace  "boost::io" because:
>>>
>>>    (i) it is much shorter than "boost::iostreams"; while it is
>>> possible to use an alias to shorten it, I'd hate to make users do
>>> this when there is a perfectly suitable short name available.

>> (i) is particularly important, since the documentation will contain
>> a lot of tutorial material in which the namespace qualification
>> can't be omitted, e.g.,
>>
>>     template<typename Sink>
>>     void put(Sink& dest, int c)
>>     {
>>         if (c == '\n')
>>             col_no_ = 0;
>>         else {
>>             if (col_no_ >= line_length_)
>>                 this->put(dest, '\n');
>>             ++col_no_;
>>         }
>>         boost::io::put(dest, c);
>>     }
>
> Pshaw.

Huzzah!

> After a few pages C++ Template Metaprogramming has an example
> that begins with:
>
>   namespace mpl = boost::mpl; // namespace alias
>
> which it then follows with a note that says
>
>   "Many examples in this book will use ``mpl::`` to indicate
>   ``boost::mpl::``, but will omit the alias that makes it legal
>   C++."

I know how I would explain the convention; I'm just afraid people won't notice
it, and will copy and paste from the examples and find they don't work. It's a
bit easier in a printed book, in which there's some expectation that the
material will be read from the beginning, than in a heavily hyperlinked web
document, where reader are known to skip immediately to somewhere in the middle.

>> The occurence of boost::io::put in the above example has to be
>> qualified, since otherwise it will refer to the member function
>> being defined. I worry that having to use a long namespace name or
>> to introduce a namespace alias in a high percentage of the examples
>> will make the documentation harder to follow, and the library harder
>> to learn.
>
> So use the technique described above.  And if you really can't stand
> that, do as I suggested originally and introduce the alias in Boost:
>
> namespace boost { namespace iostreams{} namespace io = iostreams; }

Sorry, I didn't read your first post carefully enough. I though you were saying
that users should perform the aliasing.

>> If I have to choose, then, I would much rather use the namespace io
>> and move the library back to boost/io than use the namespace
>> iostreams.
>
> You don't _have_ to choose, but then you could do better than the
> status quo.

Okay, I'll hold off adding iostreams to CVS while I think about it some more.

Jonathan