"Tobias Schwinger" wrote

Beth Jacobson wrote:

...

Initially, I'd just like to get some feedback on whether the page might merit consideration for inclusion in the Boost website and an idea of whether others would be willing to contibute to the effort.

What's wrong with "libraries by category" part of

http://www.boost.org/libs/libraries.htm

in the first place?!

hmm .. Having Spirit and Wave under "string and text processing" is a bit underwhelming for earth shattering libs like these isnt it? They sound so much coooler in the "bleeding-edge libraries" section ... Thats where I'd prefer to be anyway! cheers Andy Little

"Stefan Seefeld" wrote

Andy Little wrote:

...

"Tobias Schwinger" wrote

...

What's wrong with "libraries by category" part of

http://www.boost.org/libs/libraries.htm

in the first place?!

hmm .. Having Spirit and Wave under "string and text processing" is a bit underwhelming for earth shattering libs like these isnt it? They sound so much coooler in the "bleeding-edge libraries" section ... Thats where I'd prefer to be anyway!

While I agree that 'string and text processing' might not be the most accurate description for them, I don't think 'bleeding-edge libraries' isn't a very meaningful category to put anything in. What does it tell about the problem domain ? It seems more about marketing than information. IMO of course.

I should have put a smiley at the end of that. Nevertheless its a serious point. I do know about http://www.boost.org/libs/libraries.htm but I can never actually find what I'm looking for when I get there as everythings a bit arbitrarily categorised and its a bit miserable. I guess the true answer is semantic markup or whatever the latest html wizardry is. The short term alt option is an *Alphabetic* drop-down list of keywords which take you can put into the google box. Like you get with MS compiled Help files. The Google box works quite well though FWIW. regards Andy Little

"Andy Little" <andy@servocomm.freeserve.co.uk> writes:

"Tobias Schwinger" wrote

...

Beth Jacobson wrote:

...

Initially, I'd just like to get some feedback on whether the page might merit consideration for inclusion in the Boost website and an idea of whether others would be willing to contibute to the effort.

What's wrong with "libraries by category" part of

http://www.boost.org/libs/libraries.htm

in the first place?!

hmm .. Having Spirit and Wave under "string and text processing" is a bit underwhelming for earth shattering libs like these isnt it? They sound so much coooler in the "bleeding-edge libraries" section ... Thats where I'd prefer to be anyway!

On the other hand we don't want to make any of the libraries sound experimental. -- Dave Abrahams Boost Consulting www.boost-consulting.com

Tobias Schwinger wrote:

What's wrong with "libraries by category" part of

http://www.boost.org/libs/libraries.htm

in the first place?!

Nothing. This would be in addition to, not in place of.

Quick set of comments: ======================

Library names should start with an uppercase character because of

http://www.boost.org/more/discussion_policy.htm#lib_names

Ok.

"C++ Tweak" doesn't quite cut it right for all what's listed in this section, I think.

Suggestions are welcome. I was looking for something that would communicate the idea of 'improvements to the language'. The group should contain libraries that most people will want to use most of the time.

BTW. is 'lexical_cast' really part of 'conversion'?

It's part of that library, but it would probably be better to list it as a replacement for atoi, atol, etc.

I can't make any sense of the description saying "Enums" for 'variant', did you perhaps actually want to write "Unions"?

I did.

It's strange that the meaning of the columns seems to swap after the first two entries (for "C++ tweaks" and "Simple utilities") and the authors' names should be listed for either all or for none of the entries.

In the final version, they would all be like the first two. The rest just aren't written yet.

What separates a "simple utility" from an "advanced utility"? Currently this separation seems tainted with a subjective guess of what might be inside.

My idea was to group them according to their appeal to different audiences, depending on the type of programming they do and how much of an investment they want to make in implementing something.

To just pick a few examples: 'enable_if' is (nearly) a one-liner while 'multi-index' is a complex library, 'call_traits' is quite simple compared to 'regex', and 'functional' and 'functional/hash' ending up in different categories seems quite odd to me too.

Further I can't really see what's "bleeding edge" about 'range' or 'in_place_factory'.

Some are misclassified. It might also be better to have a General Utilities section for things that are heavier than Simple Utilities, but are more applicable to traditional methodologies than Advanced Utilities.

"Misc" should probably read "Portability".

Sounds good. "Misc" isn't a useful name anyway.

- 'config': I'd just strike that "not intended for library users" sentence. Boost.Config gives a fine set of tools to write very portable code - it can be attractive to end-users as well. - 'compatibility' -- I'd probably use the word "normalize" in the description

I used the existing descriptions for both. Part of the idea of this page is to replace them with more helpful ones.

Hope it's of any help,

It is. Thanks.

...

...

"C++ Tweak" doesn't quite cut it right for all what's listed in this

On Sun, 19 Feb 2006 03:27:30 +0100, Tobias Schwinger wrote section, I think.

...

Suggestions are welcome.

OK, here's how I would structure what Boost's all about for someone who's new to it:

- components that are direct add-ons to the standard library Array, CompressedPair, DynamicBitset, IO State Savers, Iterators and MultiArray

- components that deal with functors Bind, Function, Functional, Lambda and Phoenix (currently part of Spirit)

- components that refine concepts that originally came from C Any, Optional and Variant

- components that provide abstractions for OS facilities Filesystem, Thread and Timer

- components that address typical programming problems Crc, MultiIndex, Pool, ProgramOptions and Serialization

- components for text processing Lexical Cast, Regex, Spirit, StringAlgo, Tokenizer and XPressive

- components that address mathematical problems everything under boost/math, Graph, Interval, MinMax, Random, Rational, TriBool and uBLAS

- components in the domain of programming languages Python and Wave

- utilities everything under boost/utility, InPlaceFactory, Ref SmartPtr and ValueInitialized

- components for addding syntactic sugar Assign, Format, Operators, Parameter and Range (well, sort of)

- components for generic programming / metaprogramming CallTraits, Concept Check, Enable If, MPL, Preprocessor, StaticAssert, Tuple and TypeTraits

- components for portability- and quality assurance Test, Config, Compatiblity and Integer

.

Not perfect, but it's a start.

I've taken a shot at a different categorization once upon a time: http://www.crystalclearsoftware.com/cgi-bin/boost_wiki/wiki.pl?OOPSLA2004/Li... That said, I'm not sure I ever heard an answer why Beth considers the current categories insufficient: http://www.boost.org/libs/libraries.htm Jeff

Tobias Schwinger wrote:

OK, here's how I would structure what Boost's all about for someone who's new to it:

- components that are direct add-ons to the standard library Array, CompressedPair, DynamicBitset, IO State Savers, Iterators and MultiArray

- components that deal with functors Bind, Function, Functional, Lambda and Phoenix (currently part of Spirit)

- components that refine concepts that originally came from C Any, Optional and Variant

- components that provide abstractions for OS facilities Filesystem, Thread and Timer

- components that address typical programming problems Crc, MultiIndex, Pool, ProgramOptions and Serialization

- components for text processing Lexical Cast, Regex, Spirit, StringAlgo, Tokenizer and XPressive

- components that address mathematical problems everything under boost/math, Graph, Interval, MinMax, Random, Rational, TriBool and uBLAS

- components in the domain of programming languages Python and Wave

- utilities everything under boost/utility, InPlaceFactory, Ref SmartPtr and ValueInitialized

- components for addding syntactic sugar Assign, Format, Operators, Parameter and Range (well, sort of)

- components for generic programming / metaprogramming CallTraits, Concept Check, Enable If, MPL, Preprocessor, StaticAssert, Tuple and TypeTraits

- components for portability- and quality assurance Test, Config, Compatiblity and Integer

.

Not perfect, but it's a start.

I like your list. It's a novel way of grouping the libraries compared to both mine and the existing categories, and I wonder if it might be worth including as its own page, but it's not really what I'm trying to do here. I've avoided the word "selling", but this is really what the page is about. I'm not trying to sell the libraries (I think they can sell themselves), but I am trying to sell people on the idea that it's worth their time to read more about them. Looking only at the descriptions, the only one that really does that for me is "components that address typical programming problems".

David Abrahams wrote:

Beth Jacobson <bethj@bajac.com> writes:

...

I like your list. It's a novel way of grouping the libraries compared to both mine and the existing categories, and I wonder if it might be worth including as its own page, but it's not really what I'm trying to do here. I've avoided the word "selling", but this is really what the page is about. I'm not trying to sell the libraries (I think they can sell themselves), but I am trying to sell people on the idea that it's worth their time to read more about them.

I agree that your page does that better than prior efforts.

Seconded...

But I don't think we can afford to have two categorized pages,

My view is that the more categorisations the better. Beth's page deals with a scale of simple<->complex or concrete<->abstract. This one is classified by usage type. Both are valid and useful. The more signs we can post that say "Entrance", "Way In" or even "Ingress" the better (IMHO). Jim

David Abrahams wrote:

Beth Jacobson <bethj@bajac.com> writes:

...

Inspired by a recent discussion on the "Why Use Boost?" thread, I've started working on a new web page designed to briefly answer that question for each library.

It's a nice page, but I'd like to know what it accomplishes that isn't accomplished by the "libraries by category" list.

Let's remember that this intention of this information is to explain to the user who knows next to nothing about Boost why they should use it. "Libraries Listed by category" is tucked away halfway down the "Documentation" page. Imagine I am a casual user coming across the boost.org website for the first time. As Mr Casual User, I read "Welcome to Boost.org!" and that section suggests I should look at "Getting started". That allows me to download the libraries, but I have no desire to do that yet. I then look at the background information page and read a few testimonials. These sound like marketing talk to me. Fair enough, but everyone does that to promote their product. All well and good to say it's great, but how is it great? I still don't know at this point. I still haven't found any link to "what Boost can do for you" or something similar. There's a link to "Documentation", but I don't click on that because it's "obviously" for people who are already using the library. By this time, I haven't been convinced, so I go and look at someone else's product instead. I miss out on the information that I was looking for because it was hidden away somewhere I wouldn't have thought of looking. Let's suppose, however, I am a bit more persistent and dig deeper into the site. I find "Libraries Listed by Category". First line: "conversion/lexical_cast - lexical_cast class template". This doesn't catch my eye. Next: "format - Type-safe 'printf-like' format operations". OK, that might be a good thing. I read it, but by itself it's not enough to make me want to use Boost. "iostreams - Framework for defining streams, [etc]" How's that different from what C++ already gives me? Skip that one. Remember I'm just browsing, so I'm not going to read everything unless it looks it would be worthwhile. These descriptions are clearly intended to be used by the existing user as a reference guide, and they are fine in that respect. They don't, however, act as a lure to potential users. They don't tell me how each library could vastly improve the efficiency and reliably of my C++ programs. In short, they don't make me want to start using Boost this instant and wonder how I ever managed without it. On the other hand, the documentation Beth is proposing does get my interest about Boost. It points out what it can do for me and makes me want to use it, and it does it straight away. My view is that Beth's content (with appropriate revisions - it is clearly not yet complete or as good as it could be) should be adopted and linked to prominently from the main page. I commend the proposed documentation to the house :) Paul

Paul Giaccone <paulg@cinesite.co.uk> writes:

These descriptions are clearly intended to be used by the existing user as a reference guide, and they are fine in that respect. They don't, however, act as a lure to potential users. They don't tell me how each library could vastly improve the efficiency and reliably of my C++ programs. In short, they don't make me want to start using Boost this instant and wonder how I ever managed without it.

On the other hand, the documentation Beth is proposing does get my interest about Boost. It points out what it can do for me and makes me want to use it, and it does it straight away. My view is that Beth's content (with appropriate revisions - it is clearly not yet complete or as good as it could be) should be adopted and linked to prominently from the main page.

I agree with your analysis. It can be hard for those of use who've been around Boost forever to notice the deficiencies. It would be great if you and Beth could work with Rene on the new website structure, specifically addressing issues such as this. -- Dave Abrahams Boost Consulting www.boost-consulting.com

"Paul Giaccone" < wrote

Beth Jacobson wrote:

...

Inspired by a recent discussion on the "Why Use Boost?" thread, I've started working on a new web page designed to briefly answer that question for each library. The libraries arranged in groups meant to appeal to particular users and interests with an eye to encouraging browsing and making it easier for users to home in on the type of library appropriate to them.

Excellent, Beth, good job! This is just the sort of thing I had in mind and would have done if other constraints on my time had permitted. Thank you! I hope this or something very similar will be put somewhere prominently on the Boost website as I think it will be a very valuable asset for both potential and existing users.

My problem is that it just isnt Generic enough, but just someone elses grouping (nor is the current grouping any better) . Whats needed is some sort of generic grouping mechanism with a choice of grouping algorithms and /or keywords. That would be more in the spirit of boost. (The nearest thing currently is the Google box. ) Of course whether the technology a) exists b) is acceptable on the website.... is another matter. regards Andy little

"David Abrahams" wrote

"Andy Little" writes:

...

My problem is that it just isnt Generic enough, but just someone elses grouping (nor is the current grouping any better) . Whats needed is some sort of generic grouping mechanism with a choice of grouping algorithms and /or keywords. That would be more in the spirit of boost. (The nearest thing currently is the Google box. ) Of course whether the technology a) exists b) is acceptable on the website.... is another matter.

I think the inclination to use complex and unspecified (non-existent?) technology to attack the library browsability problem is really amusing.

I'm glad that I at least lightened your day ;-)

In my opinion, it's not at all in the spirit of Boost.

I was thinking about generic programming when I wrote that FWIW.

Operationally, many of the things we do are purposefully simple to avoid imposing lots of overhead on our volunteer structure. If *I* were a newbie asked to choose among grouping algorithms I would probably go back and read the list from beginning to end. The human ability to categorize blows what machines can do out of the water any day of the week, and I think exactly what Beth is doing -- with a little input from other participants -- is likely to produce far superior results.

FWIW Here are some algorithmic categories I thought of. Some you may recognise... Sort by Most popular Sort by least popular Sort by Most recent Sort by Oldest Choose Header only no linking reqd Choose Header only or Autolink Choose those that need building Choose only those with standardisation proposals Choose only those with equivalents in TR1. Alphabetical A-Z. Alphabetical Z-A. Rated excellent/good/medium/poor...

Just my 2c; if you feel like coding it up, we can always try it for comparison.

Basically a drop down box, which provides the above algorithms and similar that can be added as demanded/coded. On selecting one algorithm bring up a list of the relevant libraries. Ideally float mouse over a particular query result gives a popup with a bit more detailed info. Not sure whether Javascript is acceptable though? ( hmm if Javascript can do it.. havent used it for a long time ) (hmm......I wonder if he's still laughing ) ....... ;-) regards Andy Little

David Abrahams wrote:

"Andy Little" <andy@servocomm.freeserve.co.uk> writes:

...

Not sure whether Javascript is acceptable though? ( hmm if Javascript can do it.. havent used it for a long time )

(hmm......I wonder if he's still laughing ) ....... ;-)

No, this is deadly serious: if you feel like coding it up, we can always try it for comparison :). Last I checked, JavaScript is acceptable if not having JavaScript doesn't make the information inaccessible.

PHP is also acceptable, and as compared to JavaScript, more portable. The new library list, the alphabetical one, is a PHP page so that it shows the libraries available based on the release. And having a list with "columns" that can be sorted might be a reasonable way to manage it. It need not be displayed as columns, as that takes up more room. But having the various information available and sortable is very useful. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo

Andy Little wrote:

"Rene Rivera" wrote

...

David Abrahams wrote:

...

"Andy Little" writes:

...

Not sure whether Javascript is acceptable though? ( hmm if Javascript can do it.. havent used it for a long time )

(hmm......I wonder if he's still laughing ) ....... ;-) No, this is deadly serious: if you feel like coding it up, we can always try it for comparison :). Last I checked, JavaScript is acceptable if not having JavaScript doesn't make the information inaccessible. PHP is also acceptable, and as compared to JavaScript, more portable. The new library list, the alphabetical one, is a PHP page so that it shows the libraries available based on the release.

Currently I need to get my physical quantities library sorted out and make a formal review request, so I reckon I'll leave this until the new website is up. I've also got a vague idea to investigate a boost GUI... Meanwhile if anyone else feels inspired... please dont feel you'll be stepping on my toes ..... ;-)

Already working on it ;-)

...

And having a list with "columns" that can be sorted might be a reasonable way to manage it. It need not be displayed as columns, as that takes up more room. But having the various information available and sortable is very useful.

I suppose a full blown relational database is out of the question?

No.

Seriously isnt that the right way to do this?

Possibly. The fact that it's relational data doesn't require that it be stored in MySQL (the DB SourceForge provides). What I'm doing now is making an XML dataset of the libraries, to read in and display. The idea being that an XML file is easier for others to maintain than poking at MySQL directly (small example attached). Another benefit is that such a file could be used by others outside of Boost, possibly even for what you mention below.

Or is that the status quo? If one wanted to do a more modular boost then that data would also be used to generate modules or packages on demand, the regression results go in, etc, etc.

That would be considerably more work than just some tabular data display. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo

Rene Rivera wrote:

David Abrahams wrote:

...

No, this is deadly serious: if you feel like coding it up, we can always try it for comparison :). Last I checked, JavaScript is acceptable if not having JavaScript doesn't make the information inaccessible.

PHP is also acceptable, and as compared to JavaScript, more portable. The new library list, the alphabetical one, is a PHP page so that it shows the libraries available based on the release.

And having a list with "columns" that can be sorted might be a reasonable way to manage it. It need not be displayed as columns, as that takes up more room. But having the various information available and sortable is very useful.

PHP is server based. I guess the question again is: do we differentiate between "online" and "offline"? I, as a user, would surely want my offline boost distro to have that capabilities as well. Regards, -- Joel de Guzman http://www.boost-consulting.com http://spirit.sf.net

Joel de Guzman wrote:

I guess the question again is: do we differentiate between "online" and "offline"?

We do already. I can't google-search the documentation offline. Isn't sorting or filtering really just an extension of that?

I, as a user, would surely want my offline boost distro to have that capabilities as well.

I'd think it would be appropriate to use PHP to add functionality to the online docs as long as it follows the same principle as javascript: it doesn't make information inaccessable when it doesn't work (in this case, when browsing offline). Of course, it would be great to have sorting capability offline too, but I don't see why that must be a prerequisite for implementing it in the online docs.

Joel de Guzman wrote:

I fear that over reliance on PHP will either 1) make the offline docs virtually useless or 2) fork a different online and offline version of the docs, hence double the effort and scatter the focus.

...

I'd think it would be appropriate to use PHP to add functionality to the online docs as long as it follows the same principle as javascript: it doesn't make information inaccessable when it doesn't work (in this case, when browsing offline). Of course, it would be great to have sorting capability offline too, but I don't see why that must be a prerequisite for implementing it in the online docs.

That would be ideal, but in reality is difficult to achieve. I'd hate to see pages that are disabled because it requires a server. While it's fun to have all the bells and whistles, a keep-it-simple design can also potentially give you much of the needed functionality with less fat and less fuss. The thing to keep in mind is that in our case (boost docs) information is mostly static.

It shouldn't really be that difficult to avoid the pitfalls. When the website is updated for a new release, just run wget (http://www.gnu.org/software/wget/) on it. It will hit each page (or the pages you select) and save the results to an identical directory structure. That way the dynamic, online pages produce the static, offline ones, so there's no risk of forking and no double work.

Jeff Garland wrote:

On Fri, 17 Feb 2006 13:35:19 -0500, David Abrahams wrote

...

...

Choose Header only no linking reqd Useful, though could be handled with an icon.

...

Choose Header only or Autolink I don't know what that means.

...

Choose those that need building Useful.

Small glitch with these categories -- 90% of date-time can be used without building the library now. Large percentage of the users probably don't need the lib. Same with graph. Last I knew only the graphviz feature required building a library. So not sure how you deal with these kind of complications...

Simple. You leave it to the very capable human brains to decide what the seemingly conflicting information is by providing as much detail as possible. For example the graph lib would be described as header-only, needs-building, and autolink. In other words, we are not giving any guarantees as to the level of functionality based on what parts of a library one uses. For example the threads lib is usable in both static and dynamic lib modes, yet you may get different functionality based on the platform you are on. So I say don't worry about it, and just give users the info and let them use the info. -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo

Andy Little wrote:

"Rene Rivera" wrote in message

...

So I say don't worry about it, and just give users the info and let them use the info.

Its a shame this couldnt use a fuzzy logic approach.

http://plato.stanford.edu/entries/logic-fuzzy/

Library X - DOESNT need building Library Y - MAY need building Library Z - POSSIBLY needs building Library E - PARTLY needs building Librarry J n- REALLY needs building Library K - STRONGLY needs building Library W - REALLY STRONGLY needs building Library A - POSSIBLY PARTLY needs building.

Similarly for compilers status.

hmmm I can hear David Abrahams laughing again ...!

I'm laughing... Since I think you just volunteered to write the code that does that :-D -- -- Grafik - Don't Assume Anything -- Redshift Software, Inc. - http://redshift-software.com -- rrivera/acm.org - grafik/redshift-software.com -- 102708583/icq - grafikrobot/aim - grafikrobot/yahoo

"Andy Little" <andy@servocomm.freeserve.co.uk> writes:

It would also be interesting to try to present the regression test data in a user friendly way as an alternative to raw regression tests, which are fine for the library author, but information overload for a potential user. Again just some dummy client side data embedded in a JavaScript file to start with and see if it is worth pursuing or not.

You really slay me! Considering the lengths to which we've gone to make the regression results accessible for users, this sounds like another one of your killer jokes. "The raw regression tests" look like a bunch of textual gobbledygook printed when running Jam; we supply nicely formatted tables. Users even get a distinct view from the developers, emphasizing the things users should care about.

Its only fair to say that its really only just doodling. Even assuming the interface arouses interest, which is a complete unknown yet, there would obviously need to be a deal of discussion about any implications before doing anything more of course.

Sounds like you're making it much more complicated than it needs to be... again(?) -- Dave Abrahams Boost Consulting www.boost-consulting.com

"Andy Little" wrote

Looks like theres a bug. My path from boost.org/index.html is

General Info --> Compiler status summary -->User report. At which point I am redirected to

http://engineering.meta-comm.com/boost-regression/CVS-HEAD/developer/

Also once in there I see "For user-level report, see user summary."

But I have No idea what that is actually referring to ? Couldnt that be a hyper-link.

Aaah Now I see a link to User view. Unfortunately I'm getting

HTTP 404 - File not found Internet Explorer

Example link is

http://engineering.meta-comm.com/boost-regression/CVS-HEAD/user/assign.html

Hmm maybe theres a problem in IE6 ?

Happens in Firefox too FWIW. regards Andy Little

"Andy Little" <andy@servocomm.freeserve.co.uk> writes:

OK. I have found one of the pages that I think you are referring too.

I think its:

http://engineering.meta-comm.com/boost-regression/CVS-RC_1_33_0/user/summary...

We should talk about why you had such a hard time finding that page, to begin with.

Now an interesting excercise is too first set your desktop to 1024 x 768 (assuming its bigger)... A reasonable size, then assume you have just discovered boost numeric interval and youre compiler is VC8.

I've put up a snapshot of the type of screen of "accessible for users" information that you are now presented with. This is the Summary BTW!

http://www.servocomm.freeserve.co.uk/boost/regression_snap.html

Best seen in Full screen mode! BTW You might think the list of libraries on the left is related to the data on the right. But you would be mistaken, because the grey line between is a scroll bar for the list, thus neatly removing your last desperate hope of having the least possible clue as where you are in the table and what those boxes are referring too. Useful isnt it! .. ;-)

I know it's not ideal, but it's a far, far cry from "the raw regression results." In FireFox, hit alt-minus until you can see roughly what's going on. -- Dave Abrahams Boost Consulting www.boost-consulting.com

On Sat, 18 Feb 2006 12:34:22 -0500, David Abrahams wrote

Rene Rivera <grafik.list@redshift-software.com> writes:

...

Jeff Garland wrote:

...

On Fri, 17 Feb 2006 13:35:19 -0500, David Abrahams wrote

...

...

Choose Header only no linking reqd Useful, though could be handled with an icon.

...

Choose Header only or Autolink I don't know what that means.

...

Choose those that need building Useful.

Small glitch with these categories -- 90% of date-time can be used without building the library now. Large percentage of the users probably don't need the lib. Same with graph. Last I knew only the graphviz feature required building a library. So not sure how you deal with these kind of complications...

Simple. You leave it to the very capable human brains to decide what the seemingly conflicting information is by providing as much detail as possible. For example the graph lib would be described as header-only, needs-building, and autolink.

Ok, I'm not sure how putting a library in all 3 categories will work -- it will at least require explanation of how this can happen, but mostly I would think it would be confusing to new users.

Nothing in the graph lib needs building.

From http://www.boost.org/libs/graph/doc/read_graphviz.html Building the GraphViz Readers To use the GraphViz readers, you will need to build and link against the "bgl-viz" library. The library can be built by following the Boost Jam Build Instructions for the subdirectory libs/graph/build. Jeff

Paul Giaccone wrote:

Excellent, Beth, good job! This is just the sort of thing I had in mind and would have done if other constraints on my time had permitted. Thank you! I hope this or something very similar will be put somewhere prominently on the Boost website as I think it will be a very valuable asset for both potential and existing users.

Thanks, Paul. Any chance that we could pool our limited time resources to get this done? I'm still hoping that if we could get the groupings nailed down with good names and descriptions and the libraries properly sorted among them, others would contribute individual library descriptions. Without that additional help, I'm afraid the job would just be too large. With some of the libraries -- particularly the ones I listed under "Advanced Utilities" and "Bleeding Edge" -- it would take some time just to get up to speed on the concepts behind them, not to mention learning enough about the library itself to describe it intelligently. Others like threading or the BGL, I'm somewhat familiar with, but someone with more experience with those types of libraries could better judge which features are most important to potential users. The groupings should probably be done first, because different types of descriptions are appropriate to different groups. For example, descriptions for "Tweaks" (or "Enhancements", if people prefer), should describe the problem they solve (memory leaks, bad casts, etc), while Simple Utilities would just describe what the functions do, and General Libraries would be mostly a features list to help people quickly decide whether the Boost implementation is worth investigating. The more clearly we can specify the types of descriptions we need, the more forthcoming contributions are likely to be. Asking someone to describe the serialization library in a few sentences can be a little intimidating. Listing its major features doesn't seem so hard.

Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:

Beth Jacobson writes:

...

I've put a very preliminary page up at http://bajac.com/boost/byType.html. The libraries are arranged by group, and a few include new descriptions appropriate to this type of listing (those are the ones with black 'headings' in the left column).

All other issues aside, I find the "Cutting-Edge Libraries" group ill-conceived and bordering on the edge of offensive (for the library author).

I agree, but I think we've all decided that category is going away (right?) -- Dave Abrahams Boost Consulting www.boost-consulting.com

Beth Jacobson <bethj@bajac.com> writes:

David Abrahams wrote:

...

Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:

...

All other issues aside, I find the "Cutting-Edge Libraries" group ill-conceived and bordering on the edge of offensive (for the library author).

I agree, but I think we've all decided that category is going away (right?)

I thought the objections were to the original name (bleeding edge), which I changed to cutting edge to sound less experimental.

I didn't notice the change. You're right that it sounds slightly less experimental, but it is reminiscent of and still suggests "bleeding edge." More importantly, it's a misleading distinction for most people. The description # If words like "generic" and "metaprogramming" get your blood racing, this is the place for you. These libraries provide a framework for trying out the latest programming techniques, and like all Boost Libraries are stable enough for use in production code. basically is useful for the programmer who's looking at Boost as a learning experience, but is likely to put off the production programmer who doesn't want her blood racing. The last bit doesn't provide much reassurance; it sounds defensive and unconvincing. This category also suggests that anything you haven't put there is somehow less sophisticated. The whole idea of a "simple/advanced/cutting-edge" hierarchy doesn't seem to work, to me. I'm looking at Boost.Random in the simple category, for example. From my point of view, understanding what that library provides requires a deep understanding of numerical issues that's out of reach for most programmers. Is the parameter library "cutting edge?" I think so. Does using it require great sophistication? No. In fact, it belongs in the "C++ Enhancements" category, because it provides, essentially, a language extension in library form. As does lambda.n

Is the problem still with the name, or is it with the category description, or the category itself?

Well, I guess I don't like the categories.

The intent of the page is to encourage people to explore the Boost libraries. I tried to create categories that would appeal to various interests and ability levels

Good idea; the execution isn't there yet, though.

and that would give a broad overview of the sorts of things Boost has to offer.

Also good. If you list all the libraries you can't help but do that :)

I thought that support for the latest programming concepts and techniques would have been of real interest to some.

Yes, it's of interest to those who are here for an educational experience. That's an important role of Boost, but let's not suggest that the other libraries have less education or innovation to offer.

If that's a mistake, I could eliminate that category altogether and move its contents to "Specialized Libraries". If the categorization is sound but the name/description is bad, perhaps someone could suggest something better. Most of the libraries in that group are beyond my own skill level and experience, so it's difficult for me to describe the group well.

I'm not sure they should be grouped. Okay, let me take a shot at this. The category I'm least sure about is "system-level." It feels right, but I can't justify it. This is an attempt to fit everything into a single category, unlike Boost's current list. I don't feel as though any of the library is being badly shortchanged or pigeonholed, but others may disagree. I copied the libs from Beth's list, but it seems short; Beth, are you sure you didn't miss anything? * Class definition utilities operators, noncopyable, base_from_member, compressed_pair * Language Enhancements - libraries that make the standard C++ core language easier and safer to use, or extend its capabilities in "language-like" ways. Many relieve common frustrations of programmers with the C++ language. Datatypes: variant, optional/in-place-factories, tribool, integer Language extensions: foreach, enable_if, parameter, ref Safety: conversion, value_initialized, checked_delete, * Standard Library Enhancements - libraries that make the standard C++ library easier and safer to use or extend its capabilities in evolutionary ways. Many relieve frustrations commonly encountered when using the standard library (see also Functional Programming) IO: io state saver, iostreams, format Containers/data structures: assign, pointer container, array, bitset, multi_index, multi-array, tuple Iterators: iterators, next/prior, range Algorithms: minmax * Functional Programming - libraries for working with functions and function objects. Especially useful in conjunction with STL algorithms, but any program can benefit from functional programming idioms. lambda (see also bind), bind/mem_fn (see also lambda), functional (deprecated), function * Numerics, number crunching, high-performance computing. CRC, functional/hash, random, rational, graph/property map, interval, math, ublas * Testing and debugging timer, static_assert (see also MPL assert), concept check, test, * Parsing and Text Processing Regex, XPressive, Spirit, tokenizer, string_algo * System-level libraries Program options, date-time, filesystem, threads, serialization, signals, pool, Python * Code Generation Preprocessor, wave * Type information, synthesis, and computation Type Traits, Call Traits, MPL * Portability compatibility, config -- Dave Abrahams Boost Consulting www.boost-consulting.com

David Abrahams writes:

Okay, let me take a shot at this. The category I'm least sure about is "system-level." It feels right, but I can't justify it. This is an attempt to fit everything into a single category, unlike Boost's current list.

With a specific rational in mind, or just because it seemed doable? Personally, I agreed with Beman at the time and still do (http://article.gmane.org/gmane.comp.lib.boost.devel/54545/): Incidentally, there is no law that says a library couldn't appear in more than one category. Remember that the objective isn't the categories themselves, but to help users locate libraries which might meet their need. -- Aleksey Gurtovoy MetaCommunications Engineering

David Abrahams writes:

Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:

...

David Abrahams writes:

...

Okay, let me take a shot at this. The category I'm least sure about is "system-level." It feels right, but I can't justify it. This is an attempt to fit everything into a single category, unlike Boost's current list.

With a specific rational in mind, or just because it seemed doable?

Yeah, it seemed doable without really shortchanging any libraries.

...

Personally, I agreed with Beman at the time and still do (http://article.gmane.org/gmane.comp.lib.boost.devel/54545/):

Incidentally, there is no law that says a library couldn't appear in more than one category. Remember that the objective isn't the categories themselves, but to help users locate libraries which might meet their need.

I agree, but as it turns out, with the right categories I don't think the cross-listing is helpful overall.

I disagree, please see below.

I actually think it makes things a little more confusing. Too much information.

How is it "too much information", specifically, in the typical usage scenario the list tries to cover (user searching for a library in a particular domain)?

* Class definition utilities

operators, noncopyable, base_from_member, compressed_pair

Wouldn't you like to have Iterators library here well?

* Language Enhancements - libraries that make the standard C++ core language easier and safer to use, or extend its capabilities in "language-like" ways. Many relieve common frustrations of programmers with the C++ language.

Datatypes: variant, optional/in-place-factories, tribool, integer

Language extensions: foreach, enable_if, parameter, ref

Safety: conversion, value_initialized, checked_delete,

* Standard Library Enhancements - libraries that make the standard C++ library easier and safer to use or extend its capabilities in evolutionary ways. Many relieve frustrations commonly encountered when using the standard library (see also Functional Programming)

IO: io state saver, iostreams, format

What about Serialization?

Containers/data structures: assign, pointer container, array, bitset, multi_index, multi-array, tuple

Graph library, no?

Iterators: iterators, next/prior, range

Algorithms: minmax

What about String Algorithms?

* Functional Programming - libraries for working with functions and function objects. Especially useful in conjunction with STL algorithms, but any program can benefit from functional programming idioms.

lambda (see also bind), bind/mem_fn (see also lambda), functional (deprecated), function

* Numerics, number crunching, high-performance computing.

CRC, functional/hash, random, rational, graph/property map, interval, math, ublas

* Testing and debugging

timer, static_assert (see also MPL assert), concept check, test,

* Parsing and Text Processing

Regex, XPressive, Spirit, tokenizer, string_algo

* System-level libraries

Program options, date-time, filesystem, threads, serialization, signals, pool, Python

I don't see the logic behind putting all these together (nor does the name speak for any of them). What's common between Threads and Date-time, or, for that matter, Signals and Python? Or Filesystem and Pool? IMO "Concurrent Programming", "Memory" and "Inter-language support" were perfect names for their corresponding content (which you've all bundled here).

* Code Generation

Preprocessor, wave

* Type information, synthesis, and computation

Type Traits, Call Traits, MPL

A bit too abstract for my taste, but I don't have better suggestions at the moment.

* Portability

compatibility, config

-- Aleksey Gurtovoy MetaCommunications Engineering

David Abrahams writes:

...

...

* Class definition utilities

operators, noncopyable, base_from_member, compressed_pair

Wouldn't you like to have Iterators library here well?

Not particularly. I might look here for iterator definition tools but I'd also be inclined to look in a category for stuff related to the standard library.

Well, yeah, but do we really want to pretened that the library doesn't fit here when it clearly does, and make the user with whom the category "clicked" go rounds just because she will probably be willing to?

...

...

* Standard Library Enhancements - libraries that make the standard C++ library easier and safer to use or extend its capabilities in evolutionary ways. Many relieve frustrations commonly encountered when using the standard library (see also Functional Programming)

IO: io state saver, iostreams, format

What about Serialization?

Yeah, maybe.

Wouldn't it be the first place you'd look for it in?

...

...

Containers/data structures: assign, pointer container, array, bitset, multi_index, multi-array, tuple

Graph library, no?

IMO, there's no huge advantage in using the BGL if all you're looking for is a graph data structure. Coding one up by hand will probably give you something that's easier to work with. The strong reason to use the BGL is the algorithms.

I'd say that's up to the user to decide, but in any case you are right, having it listed in Algorithms as well is IMO a must.

...

...

Iterators: iterators, next/prior, range

Algorithms: minmax

What about String Algorithms?

Okay, you have a point there.

[..]

...

...

* System-level libraries

Program options, date-time, filesystem, threads, serialization, signals, pool, Python

I don't see the logic behind putting all these together (nor does the name speak for any of them). What's common between Threads and Date-time,

time :^)

...

or, for that matter, Signals and Python?

Often used to glue together large systems while keeping parts decoupled.

...

Or Filesystem and Pool?

Management of system resources.

Well, OK, I'm sure we can find _something_ common between any two libraries :). The question is, is this categorization helpful to people who are looking for, say, a date-time library? IMO, no. At least I would have never guessed to look for it under this category.

...

IMO "Concurrent Programming", "Memory" and "Inter-language support" were perfect names for their corresponding content (which you've all bundled here).

The problem is that categories with only one library in them are no help to the navigator.

FWIW, "Memory" currently has three entries: pool, smart_ptr, and utility/checked_delete. Perhaphs more importantly, a category can be helpful even if it only contains a single entry: it adds context to the library name. "Pool" might not necessarily have something to do with memory, but place it under a telling category and it's enough information to save the user from diving in just to find out that it's not what she thought it is. Same with the just accepted "Shmem". And then there is the factor of precedent: put Python on the list without categorizing it, and hardly anybody will give it a second thought beyond "Hmm, interesting". Put it as a single entry under "Inter-language support", and you've got people thinking about other language binding libraries they've used/developed/heard about and why they are not in Boost.

We might as well just move these libraries up to the top level. As I said, I was least convinced by this category, but I'm still not sure there's a better grouping.

I would: 1) Put Program Options and Serialization under "Standard Library Enhancements" / "Input/Output" and Program Options alone under "Standard Library Enhancements" / "Operating System Services" (see below). 2) Put Signals under "Functional Programming" (they _really_ should be present in the same category as Function). 3) Put Pool under "Standard Library Enhancements" / "Memory Management". 4) Put Threads under "Standard Library Enhancements" / "Concurrent Programming" and "Standard Library Enhancements" / "Operating System Services". 5) Put Date-time and Filesystem under "Standard Library Enhancements" / "Operating System Services" (admittedly borrowed from Python docs here: http://docs.python.org/lib/lib.html) 6) Put Python under "Inter-language support". 7) Get rid of the "System-level libraries" category. -- Aleksey Gurtovoy MetaCommunications Engineering

Aleksey Gurtovoy <agurtovoy@meta-comm.com> writes:

David Abrahams writes:

...

...

...

* Class definition utilities

operators, noncopyable, base_from_member, compressed_pair

Wouldn't you like to have Iterators library here well?

Not particularly. I might look here for iterator definition tools but I'd also be inclined to look in a category for stuff related to the standard library.

Well, yeah, but do we really want to pretened that the library doesn't fit here when it clearly does, and make the user with whom the category "clicked" go rounds just because she will probably be willing to?

Yeah, I sorta do. It fits here about as well as oil paints belong in a category called "things that come in colors." Yeah, it is accurate, but everything else in the category is completely general-purpose, and this one has a very specific purpose. If someone else had written the library I would have no problem allowing them to put it in as many categories as they wanted, but my sense is that the library and its users will be best served by putting it in one category that's closely associated with its purpose.

...

...

...

* Standard Library Enhancements - libraries that make the standard C++ library easier and safer to use or extend its capabilities in evolutionary ways. Many relieve frustrations commonly encountered when using the standard library (see also Functional Programming)

IO: io state saver, iostreams, format

What about Serialization?

Yeah, maybe.

Wouldn't it be the first place you'd look for it in?

If IO were a top-level category, yes, but no, I wouldn't look in "standard library enhancements/IO" for serialization.

...

...

...

Containers/data structures: assign, pointer container, array, bitset, multi_index, multi-array, tuple

Graph library, no?

IMO, there's no huge advantage in using the BGL if all you're looking for is a graph data structure. Coding one up by hand will probably give you something that's easier to work with. The strong reason to use the BGL is the algorithms.

I'd say that's up to the user to decide,

Absolutely. I don't object to cross-listing it here, but I am averse to "maximal cross-listing," at least for people trying to get a sense of what's in Boost.

...

...

...

* System-level libraries

Program options, date-time, filesystem, threads, serialization, signals, pool, Python

I don't see the logic behind putting all these together (nor does the name speak for any of them). What's common between Threads and Date-time,

time :^)

...

or, for that matter, Signals and Python?

Often used to glue together large systems while keeping parts decoupled.

...

Or Filesystem and Pool?

Management of system resources.

Well, OK, I'm sure we can find _something_ common between any two libraries :). The question is, is this categorization helpful to people who are looking for, say, a date-time library? IMO, no. At least I would have never guessed to look for it under this category.

Yeah, maybe this goes to what Beth meant about "browsing vs. searching." My page is oriented toward browsing. And, IMO, if we don't do too much cross-listing there are still few enough libraries that the searcher can do all his work fairly efficiently with a browsing-oriented page. Once the list grows a lot, that will no longer be true.

...

...

IMO "Concurrent Programming", "Memory" and "Inter-language support" were perfect names for their corresponding content (which you've all bundled here).

The problem is that categories with only one library in them are no help to the navigator.

FWIW, "Memory" currently has three entries: pool, smart_ptr, and utility/checked_delete. Perhaphs more importantly, a category can be helpful even if it only contains a single entry: it adds context to the library name. "Pool" might not necessarily have something to do with memory, but place it under a telling category and it's enough information to save the user from diving in just to find out that it's not what she thought it is. Same with the just accepted "Shmem".

And then there is the factor of precedent: put Python on the list without categorizing it, and hardly anybody will give it a second thought beyond "Hmm, interesting". Put it as a single entry under "Inter-language support", and you've got people thinking about other language binding libraries they've used/developed/heard about and why they are not in Boost.

Good points.

...

We might as well just move these libraries up to the top level. As I said, I was least convinced by this category, but I'm still not sure there's a better grouping.

I would:

1) Put Program Options and Serialization under "Standard Library Enhancements" / "Input/Output" and Program Options alone under "Standard Library Enhancements" / "Operating System Services" (see below).

Huh, program options a standard library enhancement? Serialization an OS service? I guess, if you see it that way, it must fit for some fraction of people, but I don't get it.

2) Put Signals under "Functional Programming" (they _really_ should be present in the same category as Function).

Really? This is another one of those "it fits technically, but doesn't speak to the purpose of the lib" things for me.

3) Put Pool under "Standard Library Enhancements" / "Memory Management".

Okay.

4) Put Threads under "Standard Library Enhancements" / "Concurrent Programming" and "Standard Library Enhancements" / "Operating System Services".

Okay.

5) Put Date-time and Filesystem under "Standard Library Enhancements" / "Operating System Services" (admittedly borrowed from Python docs here: http://docs.python.org/lib/lib.html)

Yep, good.

6) Put Python under "Inter-language support".

7) Get rid of the "System-level libraries" category.

Sounds like a good direction, though some of the individual choices don't make any sense to me. -- Dave Abrahams Boost Consulting www.boost-consulting.com

Beth Jacobson <bethj@bajac.com> writes:

** Text and Number Handling - These range from enhancements to improve accuracy and performance to full-featured libraries suitable for advanced text and mathematical processing.

I like everything but this one. In what way do text processing and numerics belong together? Feels arbitrary to me. -- Dave Abrahams Boost Consulting www.boost-consulting.com

Beth Jacobson <bethj@bajac.com> writes:

David Abrahams wrote:

...

Beth Jacobson <bethj@bajac.com> writes:

...

** Text and Number Handling - These range from enhancements to improve accuracy and performance to full-featured libraries suitable for advanced text and mathematical processing.

I like everything but this one. In what way do text processing and numerics belong together? Feels arbitrary to me.

Both of them, along with system-level, are different from the rest of the categories because the decision to use them has to do with the type of application you're writing. Any program could potentially benefit from language enhancements, code generation, etc, but there's not much use for text handling libraries unless your app handles text. Also, the other categories seem to naturally group libraries of similar complexity together, while text and numerics are all over the map.

I suppose the real reason I put those two together is that they both kind of bother me. The categories are too useful to consider eliminating them, but they don't quite fit the with rest of the list. That doesn't really justify expicitly grouping them though. Maybe it would be better just to put system-level, text, and numerics at the end of the list.

No strong opinions here. For once ;-) -- Dave Abrahams Boost Consulting www.boost-consulting.com

Aleksey Gurtovoy wrote:

Beth Jacobson writes:

...

I think this categorization is the best I've seen so far (mine included). I'd like to see no more than 7-8 major categories though, to make the list seem more accessable and browsable.

Seems like an arbitrary limit to me.

Not entirely. It's common wisdom that ~7 is a 'comfortable' size for a group of items (IIRC, the number was chosen because research that found that the average person can hold ~7 items in short-term memory). If you look around the internet, you'll see that the on the bulk of professionally designed sites, the main menus have ~7 items. (Rene's latest effort has 7 in the top menu.) When there are significantly more, they're usually arranged into no more than 7-8 groups with no more than 7-8 items in each. Scanning (e.g. looking down a list of categories for one that meets a specific criterion) is different from browsing. When scanning, the brain can just throw out items that don't match so the short-term limit doesn't apply. For the new page I'm envisioning though, the emphasis is not on looking for something specific, but looking around and seeing if there's anything of interest. In that situation, a shorter list will seem more inviting and be easier to deal with. This isn't an absolute rule (if someone came up with an ideal categorization with 9, or even 10 items, I'd go for it), but it's a good rule of thumb.

How does adding a level of hierarchy make things "more accessible"? For me, it's quite the opposite: it increases chances that I'll have to browse through insides of several categories because the top-level names are so generic that the library I'm looking for could be in half of them.

Remember, the page layout will be similar to the sample page I put up. Each major category will have a short descriptive paragraph attached to it. Also the page will be flatter than the number of levels suggests. When someone clicks on a top-level category, they'll go immediately to the list of libraries in that group arranged by sub- or sub-sub-category, so it will still only take one click to get to the good stuff. Most of your objections seem to be with the new page's usefulness in searching, and I agree that the arrangement I'm suggesting is less than ideal for that. Maybe the answer is to have separate pages: one for browsing and one for searching. If I understand correctly, David's objection is that that two category pages (or one 'by category' and one 'by type') will be confusing because people have no good way of choosing between them. David, could we avoid this just by changing the name of the new page from 'By Type' to 'Browse the Libraries' or something like that? If we try to make one page work for both browsing and searching, I'm afraid we'll end up compromising on both.

David Abrahams wrote:

Beth Jacobson <bethj@bajac.com> writes:

...

Most of your objections seem to be with the new page's usefulness in searching, and I agree that the arrangement I'm suggesting is less than ideal for that. Maybe the answer is to have separate pages: one for browsing and one for searching. If I understand correctly, David's objection is that that two category pages (or one 'by category' and one 'by type') will be confusing because people have no good way of choosing between them. David, could we avoid this just by changing the name of the new page from 'By Type' to 'Browse the Libraries' or something like that? If we try to make one page work for both browsing and searching, I'm afraid we'll end up compromising on both.

I'm afraid I don't understand the distinctions you're trying to draw. When I think of "searching" in conjunction with the web I'm thinking about using a search engine. Everything else is browsing to me. So, no, I don't think that would reduce confusion.

I guess both 'browse' and 'search' are poor choices for describing web pages. Let's try a low-tech example. Say you pick up a book on C++. If you want to read up on variable scoping, you'll probably go straight to the index and under the entry 'scoping' find listings for functions, classes, namespaces, etc. But maybe you just picked the book up because someone recommended it or the cover looked interesting. In that case, you'll probably flip through the table of contents to get an idea of the sort of things the book covers, and maybe the introduction to get feel for its purpose and direction. I see the category page as an index, a way to find a particular library or group of libraries. It should should be lean and mean with simple, straight-foward category names and a minumum of supporting text. The new page should be a sort of a cross between the table of contents and the introduction. It's intended for people who don't know much more about Boost than that it's a collection of C++ libraries. The page should spark people's interest and encourage them to spend a little time there. It's meant to introduce people to the various solutions Boost has to offer, not to help them find a particular one. Maybe the category page should be called something like "Category Index" and the new one something like "Explore the Libraries" or "Library Overview".