[boost] Re: Some remarks on PP docs

From: David Abrahams (dave_at_[hidden])
Date: 2004-06-10 14:43:46

"Vesa Karvonen" <vesa_karvonen_at_[hidden]> writes:

> David B. Held:
>>It's hard enough getting one's head around the PP lib without having to
>>be an expert in it already.
> [...]
>>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.
>
> Learning Boost.Preprocessor is like learning a rather verbose and
> intricate programming language. It is not really surprising that it
> can be difficult to learn, although the documentation, at least the
> parts that I wrote, could certainly be improved. 

When did he write that?  Not in this thread.

I'm writing an appendix on the PP lib for the MPL book today.  I think
that'll demonstrate that it's possible to provide a reasonable gentle
and high-level introduction without exposing too many ugly details.

The basic outline I'm following is below.  If anyone would like to
suggest changes, I'd be grateful.

- Motivation

  - Example

  - Alternatives

    - Handcoded: error-prone
    - External Program Generated: not configurable

- Fundamental PP Abstractions

  - Macros
    - Non function
    - Function macros

  - Tokens

  - Sequences of tokens not including un-parenthesized commas

  Note issues with commas and templates

- How to read PP docs

  - BOOST_PP_ prefix

  - Header file convention

  - Z, R, D suffixes 

    [We're not going to cover anything but automatic recursion in
     detail, but we need to explain these things so that people know
     how to ignore them in the PP docs ;->, and because their presence
     leaks into the macros they write for passing to higher-order PP
    lib macros]

- PP library abstractions

  - Iteration

    - Horizontal:
    
      - Examples:

          BOOST_PP_ENUM_PARAMS...

      - Problems: Debuggability, Readability

    - Vertical
      - Local Iteration
      - File Iteration

  - Control structures

    - BOOST_PP_IF / BOOST_PP_IDENTITY / BOOST_PP_EMPTY
    - BOOST_PP_EXPR_IF
    - BOOST_PP_COMMA_IF

  - Data structures

    - sequences

    - tuples

    - arrays

    - lists

> It is possible to
> implement a language using the C99 (or even the less capable C++97)
> preprocessor that would be much less verbose and intricate and would
> be significantly easier to use (see
> http://groups.yahoo.com/group/boost/files/Order/ for details), but
> it would come at some cost in efficiency (on some compilers the cost
> would probably be prohibitive and on some compilers the cost is
> insignificant).

Well, if you really have a conforming C99 preprocessor, you could use
Paul M's Chaos, which I think is both easier to use and *way* more
efficient than the current Boost PP.

-- 
Dave Abrahams
Boost Consulting
http://www.boost-consulting.com