Re: [boost] Re: Boost preprocessor library

From: Paul Mensonides (pmenso57_at_[hidden])
Date: 2003-01-14 02:52:16

----- Original Message -----
From: "Edward Diener" <eddielee_at_[hidden]>

> I see many pre-processor macros in the reference section of the
> documentation but I don't see any good overview explaining the various
> macros or groups of macros and the ideas behind them.

The directory groupings of the library's headers are a pretty obvious clue
for most of the preprocessor library (e.g. directory names such as
"arithmetic" and "repetition").  While there is no "general overview" for
the time being, you can look at the directory structure (which is included
in the documentation) and get a pretty good idea of what is in the library.
The library includes facilities for arithmetic, logical, and comparison
operations, repetition constructs (horizontal and vertical), control
structures (such as "if" and "while"), manipulation of several data types
with unique properties, and a myriad of miscellaneous tools and facilities
to help with using the afore mentioned groups.

> What I am looking for
> is a good overview of what macros are in the library. One section shows
> examples, but they seem very random and don't seem to explain
functionality
> or ideas very well.

Nearly every reference document for a particular macro includes a simple
example.  The examples in those parts don't usually do anything incredibly
useful.  They just exist to show how the respective macro *can* be used.
There is no set group of domains to which the pp-lib caters.  You use it to
do whatever it is that you want to do.  (The pp-lib does, however, excel at
repetition.)  Many of the facilities in the library are similar to the
low-level capabilities of a regular old "if" or "while".  Discussing at
length what constructs like this are good for would only complicate the
documentation even more than it already is.  The documentation provides a
reference of all macros (etc.) in the library and shows how to use them.
How you use them and what you use them for is up to you.

If you have a specific question or a general idea of what you want to
accomplish, you can always ask me.  I can point you in the right direction,
give you advice, and tell you if it can or cannot be done.

Dealing with the preprocessor as a programming environment is like learning
a whole new language--one that doesn't even have many language features that
are taken for granted (i.e. arithmetic, looping, flow control, etc.), so you
have to expect that it takes some experimentation and experience to
understand it.  I will help you in every way that I can.

> The preprocessor library would be much more understandable if the ideas
> behind the macros were discussed and if an overview allowed end users to
> understand what is in the library.

The fundamental reason that the library is inaccessable and has such a step
learning curve is that the library is not written in C++ (or even C).  It is
written in Cpp.  Furthermore, it is like any other library written to be
used by a specific language.  You must have a reasonable understanding of
the language in order to use the library.  This requires more than a minimal
conceptual understanding of Cpp, but a nitty-gritty
"what-happens-when-and-what-doesn't-happen-and-why".  That is what makes it
steep.

I agree that the documentation can be improved considerably, but that is
also a massive undertaking.  Consider the available documentation on C++
idioms.  The literature is spread over thousands of books, articles, and
decades of algorithmic lore.  The available literature for programming in
Cpp is largely confined to one place (that I know of), and that is the
documentation for Boost's pp-lib.  I am certainly not saying that Cpp is on
par with a general purpose programming language (such as C++) as far as the
raw number of unique idioms, but it has great many nonetheless, and the
primary purpose of the documentation is to describe the library, not the
language.

> I have a feeling there are some valuable
> techniques there, as the library has been muched praised, but I can't
> discern how they macros are organized to provide functionality.

I'm not sure what you mean here.  Are you saying that the docs should
discuss the implementation of the library as well as what the library can
do?  The internal implementation of the library uses some fairly advanced
techniques, and it is hacked into incomprehensibility to support extremely
buggy preprocessors (such as Metrowerks and Microsoft).  The high-precision
arithmetic support, which I have working on everything but Metrowerks, uses
more advanced techniques than the entire rest of the library combined (which
is what makes Metrowerks such a pain in the ***), not to mention the amount
of tricks involving C99's variadic macros and placeholder arguments that I
have up my sleve.  (BTW, Dave, any word on the "work" Metrowerks is
supposedly doing on their preprocessor?)  The documentation does have some
significant articles on the library facilities that require the user to use
more advanced techniques, but the discussion is limited to the use of the
library rather than the techniques themselves.

As I mentioned previously, feel free to contact me personally, via the Boost
list, or via the Boost-Users list if you need help, and I will be happy to
help as I am able.

Paul Mensonides