RE: [boost] Re: Some remarks on PP docs

From: Paul Mensonides (pmenso57_at_[hidden])
Date: 2004-06-11 00:50:01

> -----Original Message-----
> [mailto:boost-bounces_at_[hidden]] On Behalf Of David B. Held

> "David Abrahams" <dave_at_[hidden]> wrote in message 
> news:uaczb9y4f.fsf_at_boost-consulting.com...
> > [...]
> >   It is usually okay to reuse a single generic macro name like
> >   BOOST_PP_DEF throughout your code because the macro is
> >   both defined and undefined very close to its point of use.
> 
> Yeah, this would make a lot more sense.  I was just looking 
> over the docs the other day too, and gave up because it was 
> taking too long to grok.

It takes more than a day to get used to the pp-lib.  It takes much more than a
day to get used to preprocessor metaprogramming--which is what you are doing
every time that you use the pp-lib.  It is an entirely different form of
programming.

> > [...]
> > ?? Where is BOOST_PP_EMPTY used in this example?  I think I 
> know what 
> > you mean, but really, you need to show it!
> 
> Yup.  You did better than me.  I didn't even see the BOOST_PP_EMPTY.

This was an error, probably on my part, the example should be something like:

#define QUALIFIER(cv) cv()

QUALIFIER( BOOST_PP_EMPTY )           // nothing
QUALIFIER( BOOST_PP_IDENTITY(const) ) // const

That is what it is referring to--abstraction of "emptiness" and more
generally--programmatic emptiness.

> > [...]
> > The BOOST_PP_ENUM_PARAMS example could benefit greatly from a 
> > side-by-side format in a table showing the expansion on the 
> right.  In 
> > fact, that would help all the examples,
> 
> YES!  I could not agree with this more!!!  It's hard enough 
> getting one's head around the PP lib without having to be an 
> expert in it already.

All of the examples (except the ones in this page) do have the results.
Apparently, these did too, but I missed them when I copied the page.

> > [...]
> >   BOOST_PP_IF enables convenient generation of lists using
> >   BOOST_PP_REPEAT.
> >
> > This statement, without an example, is too vague to be helpful.
> 
> Yes, many more examples, please.

There are a great many examples.  For instance, almost all (if not all--I can't
remember) library primitives have accompanying examples.

> Also, am I the only one who 
> finds the sparse frame-based layout to be a little 
> counter-intuitive?

It is a reference tool intended to adequately support those developers that are
already familiar with the library--that is the purpose of the layout.

> Would it be possible to make the docs 
> look a little more Boost-like?

Frankly, I find the Boost-like format to be suboptimal both in style and
navigation--it achieves a lowest common denominator worthy of Netscape
Gold--which is unnecessary.  I'm not saying that the pp-lib docs look
good--because they don't without the fonts fixed--but navigation is much easier
and much more direct.  Other documentation, such as Spirit's docs and Python's
"Tutorial Introduction" are much more pleasing to the eye and much more
professional.  However, I know that some people's focus is on utilitarian
presentation.  The next iteration of the pp-lib's documentation will be entirely
generated and that format can be generated just as easily as any other.

> > [...]
> >   Example:  Use arithmetic, logical, and comparison operations
> >   when necessary.
> >
> > With no commentary, and no generated code, this example is really 
> > useless.  I mean, of course you'd use arithmetic, logical, and 
> > comparison operations "when neccessary".
> 
> I didn't get that either.  It's a shame, because there's a 
> lot of code that would benefit from the PP lib that almost 
> certainly isn't because of the difficult learning curve.

The difficult learning curve is never going to go away.  It is an alien
environment that is contrary to most forms of programming.  That takes time to
become familiar with.

> Good documentation would go a long way towards making it more usable.

More usable for what?  I ask this simply to determine perspective.  The
documentation is never going to tell you what you can and cannot do with the
preprocessor or what you should and should not do with the preprocessor--those
are all unbounded sets.  The most that the documentation can do is tell you what
the _library_ can do and give a few examples.  Take ENUM_PARAMS for example, an
extremely common use of this primitive is to generate stuff like "class T0,
class T1, class T2".  However, the library doesn't have a single primitive that
generates that string of preprocessing tokens--it only has the general form.  It
could just as easily generate "0.1, 0.2, 0.3".  The point is that the output is
a function of the combination of primitives, user-defined macros, and input.
The library takes the role of a programming language.  As such, it is never
going to answer questions like "what things can I do with 'if'?" and "what
things can I do with 'while'?".  The library really is that low-level.
ENUM_PARAMS is about the most underlying-language-oriented primitive in the
entire library.  There is definitely room for improvement, but I suspect that no
matter how much I improve the docs and no matter how many examples that I add,
I'm always going to hear the same old argument--the learning curve is too steep.
That argument is based on the assumption that documentation (etc.) is enough to
reduce every learning curve to a gentle slope--which is naive.  The library is
hard to learn because the library is different than anything that most
programmers have been exposed to and because the many of the techniques and
idioms used are different than those used in every other language and in
computer science in general.  It isn't simple, and it can't be made to be
simple.  *But* it can be better...

Regards,
Paul Mensonides