[boost] Re: Re: Re: Boost preprocessor library

From: Edward Diener (eddielee_at_[hidden])
Date: 2003-01-14 14:14:16

"David Abrahams" <dave_at_[hidden]> wrote in message
news:ufzrv7lmw.fsf_at_boost-consulting.com...
> "Edward Diener" <eddielee_at_[hidden]> writes:
>
> >
> > My suggestion is not a programming primer on advanced techniques of
using
> > the preprocessor. It is rather an overview of the functionality in the
> > preprocessor library broken down into categories of usage so that
someone
> > first trying to understand the facilities of the library can absorb what
> > areas of functionality are there, and which groups of macros pertain to
each
> > area of functionality. That would make it easier looking at the
reference
> > section and understanding how any given macro relates to the library
> > functionality as a whole. I realize that many of the macros are general
> > purpose utility macros, but without a decent overview of functionality
and
> > organization it is really hard to understand why one should use areas of
the
> > preprocessor library in own's own code, whether one is a library
implementor
> > oneself or just a programmer writing modules and looking to use Boost.
> >
> > This is just a suggestion. I have had the same feelings regarding the
> > documentation of a few of the other Boost libraries in that a general
> > overview and categorization of functionality is lacking before the
> > documenter explains details. As someone who has worked on 3rd party
> > libraries myself, although not within the Boost framework, I know how
easy
> > it is not to realize that the functionality which the implementor
implicitly
> > understands is difficult for others to equally understand and use
without a
> > good preliminary explanation and breakdown of areas of usage.
>
> I agree that this would be very helpful. Something along the lines of:
>
>   "The Boost PP lib is a (mostly) functional programming system built
>   around the C/C++ preprocessor.  The result of evaluating a Boost PP
>   program is some new sequence of tokens, i.e. source code.
>
>   You can do simple integer arithmetic which generates new computed
>   preprocessor tokens. In other words, BOOST_PP_ADD(1,2) produces the
>   token "3" instead of "1+2"
>
>   You can do other computed generation of source code.
>
>   You can smooth over implementation errors in common preprocessors by
>   using macros such as BOOST_PP_CAT(a,b) instead of primitives such as
>   ##.
>
>   You can generate boilerplate source code repetition with computed
>   variations in each repeat.  There are two main category of
>   repetition, horizontal and vertical. The difference is blah, blah,
>   blah.  Many repetition primitives accept an argument which is the
>   name of a user-defined macro which is invoked with sequential
>   numbers as one of the arguments, so that you can change the code
>   generated for each repeat. You can read about horizontal repetition
>   primitives here: ..., and vertical repetition primitives here:
>   ... . A guide to choosing between the two idioms is here: ...
>   "
>
> This is very coarse, and also very short.  However, even something
> like that on the front page of the documentation would be a big help.
> I think the biggest missing piece in what's currently there is the
> section on repetition above.
>
> I would also suggest that if Edward has gotten a grip on some of the
> library, he could start a Wiki page based on this model which could
> eventually be turned into official library documentation.

I don't think there is a general model in all cases, but I think you have a
good idea above about what I was suggesting. I don't know anything about
Wiki but I will be glad to write something about my views of how Boost
documentation can be improved for the general users of the various libraries
along the lines of my suggestion above, and then someone can tell me who to
hand it off to or what I do with it. Please note that many, if not most,
Boost libraries have documentation which appears fine to me along the lines
of a good overview and explanation of functionality, and I am not trying to
pick on the preprocessor library or any other just to make a point. I will
readily admit that I place a much greater weight in the acceptance and use
of programming functionality on documentation than most people do, but a
great deal of my interest and background is in other fields where
intelligent written and verbal communication plays a large part.