Boost logo

Boost :

From: Gregory Colvin (gregory.colvin_at_[hidden])
Date: 2003-10-14 09:18:03

On Tuesday, Oct 14, 2003, at 04:27 America/Denver, Paul Mensonides

>> From: boost-bounces_at_[hidden]
>> [mailto:boost-bounces_at_[hidden]] On Behalf Of Darren Cook
> I'll go into this in more detail:
>> I've been reviewing some code [1], and wondered if there was
>> something in
>> Boost to save having to write out the convenience functions
>> by hand. It
>> seems the Preprocessor library is what I need, but after
>> reading the docs
>> I'm confused as to how to go about using it.
> The library is effectively a programming language.

Right. And I would find it easier to understand if I could study its
BNF grammar.

> There is no simple
> answer for the question "how to use it." However, there are examples
> that use the library to do various things, but they, by no means, cover
> the gamut of possible uses. Hence, the documentation on each element
> of
> the library shows what each element of the library can do (there are
> many). How you put those together is up to you. However, the learning
> curve is inherent--just as it is with any programming language. You
> have to get to know (at least some of) the language through
> experimentation before you can use it to solve your real problems.
>> Here is some (hopefully constructive) feedback on the docs,
>> ranging from
>> important to petty:
>> 1. /libs/preprocessor/doc/index.html
>> There is no explanation or introductory text. In fact I
>> looked at this
>> page and thought the docs had not been written yet and just
>> the headers and
>> been placed ready. But just to see if it was a Mozilla issue
>> I checked the
>> source and discovered the they were actually links. Specifics:
> This is the what the documentation needs most--an introductory text.
>> a) Use conventional blue for links
>> b) Explain what will be found in each section, even
>> with just a sentence.
>> c) Paragraph at the top of this page explaining what
>> the preprocessor
>> library is.
> A relatively primitive and strange programming language built atop Cpp.
> :)
>> 2. /libs/preprocessor/doc/topics.html
>> Should use same layout style as first page (i.e. first
>> page is black
>> text, this page is grey text with bullets; needs consistency).
>> 3. Generally for HTML titles, I think
>> "Boost.Preprocessor:Topics" is
>> better than "topics.html".
> It does have a consistent layout and style. Both of these two issues
> are the result of viewing the page outside of the frame where it
> normally goes. This is fine and doesn't harm anything, but then you
> get
> the title issue and the style may not appear as uniform.
>> 4. /libs/preprocessor/doc/topics/motivation.html. In the
>> "The Motivation
>> Example Revisited" section I wanted to know:
>> a) What feature each of the three headers is loading in.
> <inc.hpp> brings in BOOST_PP_INC, <comma_if.hpp> brings in
> BOOST_PP_COMMA_IF, and <repetition.hpp> brings in BOOST_PP_REPEAT and
> BOOST_PP_ENUM_PARAMS. These things should be self-evident though.
>> b) A breakdown of what each line is doing (or links to
>> the reference
>> docs for each Boost macro used)
> Yes.
>> c) If "MAX_IS_FUNCTION_TESTER_PARAMS" is required, or
>> if 15 can be
>> directly embedded, e.g.:
> Yes, it can be. However, the intent is to make the code expand to some
> arity specified elsewhere as a configuration option.
> MAX_IS_FUNCTION_TESTER_PARAMS is just used for a default value.
>> If the example had been built up in two or three steps
>> it would have
>> helped (I don't understand the library enough to know if any
>> intermediate
>> steps are possible however).
> There isn't much to the example. Especially if you look at the
> reference documentation for each primitive used--they are pretty
> straightforward. The library is simply too large to explain the
> meaning
> of everything used in examples inline. The intent of the example here
> is not to show how to do XYZ, but rather to show that XYZ can be done.
>> 5. /libs/preprocessor/doc/topics/incompatible.html
>> Refers to 1.28 as the previous release. Maybe this page
>> can be dropped now?
> Yes, probably.
>> 6. /libs/preprocessor/doc/topics/techniques.html
>> This page badly needs an introductory paragraph stating
>> what it is all
>> about. I assumed it was going to show me the various ways you
>> can use the
>> library to simplify your code. But it is defining macros that
>> start with
>> "BOOST_" so is this explaining how the library was written?
> This is an artifact from before my time. BOOST_PP_DEF is used as some
> arbitrary user-defined macro. Personally, I don't think anyone should
> ever define BOOST_PP_ prefixed macros unless it is specifically
> required
> by a library element. Also, I don't recommend using all-caps
> identifiers for *temporary* macro names--using all-caps here actually
> *increases* the likelihood of a name conflict.
>> The second example is supposed to show use of
>> "BOOST_PP_EMPTY" but the
>> example only uses (well, defines, not uses) BOOST_PP_DEF.
> I thought I fixed this one already. E.g. the idea is:
> #define MACRO(id, cv_qualifier) cv_qualifier() int id;
> MACRO(x, const BOOST_PP_EMPTY) // const int x;
> MACRO(y, BOOST_PP_EMPTY) // int y;
>> It would be helpful if all examples showed the code that
>> they generated
>> so the two can be compared side by side.
> Maybe in some cases, but the documentation also needs to encourage
> experimentation. There are literally hundreds of examples in the
> documentation.
>> 7. The reference page is intimidating - can it be broken
>> down into sections?
> I assume that you're referring the index of macros. It could be broken
> down a little bit, but that would decrease its utility. (It's just an
> alphabetical index of library primitives.) The headers section is
> broken down in a more logical fashion (though it is also a
> reference-like section).
>> 8. I think my comments for 4, 6, and 7 are because there
>> is no page that
>> leads me from "here is my old code" to "here is how you'd use
>> this library
>> to rewrite it".
> That is because the library is a programming language. It is not a
> simplistic input -> output tool--the primitives are too low-level for
> that. There is a learning curve, and there is a degree of lateral
> thinking involved. However, the library is powerful (despite the fact
> that it has its hands tied by buggy--but popular--preprocessors), but
> the learning process is not a simple sequence of linear steps. It
> isn't
> overly difficult to learn either. (I know because I did it myself at
> one point.) If you want to learn it, go through all of the macros in
> the reference section and experiment with them. This will give you a
> good idea of what's in the library and what you can do with it. It
> will
> also give you a degree of familiarity that just reading documentation
> won't. That degree of familiarity is the foundation for the lateral
> thinking required to actually solve real problems in the future rather
> than toy examples used to experiment.
> That said, the documentation definitely needs improvement. The most
> important things that it needs are a simple introductory section and a
> general outline of what broad categories of facilities are available.
> (I have a big list of improvements that I need to make.)
> Regards,
> Paul Mensonides
> _______________________________________________
> Unsubscribe & other changes:

Boost list run by bdawes at, gregod at, cpdaniel at, john at