"Paul Mensonides" <pmenso57@comcast.net> writes:
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.
Which begs the question of how anyone is supposed to get familiar in the first place without personal help from you. Speaking as one of those who followed that route and is now reasonably familiar, the layout isn't even very good for us. The big blank space at the beginning and the lack of lines around the frames are disconcerting, but more importantly, the reference pane lumps every macro together at the same level instead of categorizing them and progressively revealing detail. It would be a big help, for example, to have a view that simply hid all of the names with _Z _R or _D suffixes.
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 tend to agree.
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.
It's pretty good, but the reference is much too "flat". If you really want to help the familiar programmer, you'll use all of the hierarchical levels you have for a categorized reference. The parts that familiar programmers mostly don't need to look at are currently sucking up all those convenient navigational abilities.
Other documentation, such as Spirit's docs and Python's "Tutorial Introduction" are much more pleasing to the eye and much more professional.
I'd say they're very accessible but not particularly professional. They have a "chatty", almost dumbed-down (that's too pejorative a word, but couldn't find another) feel about them. They're also very "flat". Many people find the "original iMac case" background disconcerting.
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.
Mostly because you believe it can't.
It is an alien environment that is contrary to most forms of programming. That takes time to become familiar with.
That's absolutely true, but most people don't need to get far enough along on the curve to get to the part where it really *has* to be difficult. I didn't get started with C++ by studying the overload resolution rules, did you? I still don't know many of the subtleties, and yet I get plenty of useful work done; I even write and call overloaded functions on a daily basis.
Good documentation would go a long way towards making it more usable.
More usable for what?
Weren't you the one who was frustrated by people asking "what can the PP lib be used for?" ;-)
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.
Paul, your ability to move from the specific to the general is awesome; it's part of what makes you such a great programmer. Your unwillingness to go in the other direction is a liability, though, at least for your users. The PP lib is really only very well-suited to algorithmic and pattern-based C/C++ code generation. You probably could build a program that analyzes english sentences in PP language, but other languages are much better suited to AI research.
The most that the documentation can do is tell you what the _library_ can do and give a few examples.
It can describe the kinds of jobs the library is well-suited to.
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".
And you think that's hard to explain in a way that's simple, yet captures the generality of ENUM_PARAMS?
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'?".
I don't know why you obsess over questions like that. I don't think anyone expects anything other than a reasonable answer to them. For example, "BOOST_PP_IF selects between two sequences of preprocessing tokens based on an integral-valued argument" (roughly speaking).
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.
As long as you insist that it's impossible to (or people shouldn't) use the library without an in-depth understanding of the fundamental operation of the PP, that will be a self-fulfilling prophecy.
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
It doesn't matter whether the library is hard to learn. It matters whether it's hard to learn _to use_. Right now, that's the case. Most people learn much more effectively incrementally, and in layers. The current docs, for all intents and purposes, dump the whole library on you at once.
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.
Sure the whole picture can't be made simple, but enough of it can be made simple that people could get a whole lot more useful work done without handholding from you. With some sense of mastery under their belts on that basis, they would be much more inclined to delve deeper, not least because it would seem easier. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com