Re: [boost] Re: Re: Property_map docs

From: Christoph Kögl (christoph_at_[hidden])
Date: 2002-11-11 20:05:27

Hi Jeremy (and Edward),

I am just now reading that unfortunate Edward Diener thread. Normally I
am a quiet Boost
list/code consumer, but this is the time, I think, to speak up (a
little), just to let you know
that there are guys out here that very much appreciate Jeremy's
contributions to Boost.
Edward may have let his frustration take the better of him, and I really
would like him
to read through the BGL (Boost Graph Library) docs, because that's where
property maps
are used in abundance and where enough example code lives to make the
concept
clear. Hey, there even is a book on the BGL which probably (I have not
read it) talks
about property maps as well. So, please, Edward, refrain from
prematurely posting harsh
remarks about seemingly unsuitable documentation (and note: I am not
saying anything about
your not being able to grasp the concept of property maps, I instead
suppose that you did not
devote enough time to trying to do so). I, for my part, have been using
the BGL (along with property
map implementations) extensively of late, and I cannot say that I
encountered undue difficulties with
the BGL/PM docs.

Good night.

PS. Edward, you may want to let us know what exactly your envisioned
area of application of the property map concept is. Then we may be able
to help you with
your specific problem(s). Here are some short answers to some of your
questions:

> I am disappointed in the doc. The concept sounds interesting but I
have no
> idea how it is implemented or used in a real situation.

Well, the mathematical concept underlying property maps are maps (in the
mathematical
sense): let A, B be two sets, then a map m from A to B (denoted m: A->B)
is a subset of
AxB (the direct product of A and B) such that for ordered pairs (a,b),
(a,c) of m we have that
b=c holds (i.e. maps are left-unique binary relations). If you do not
understand the concept
of mathematical maps I am afraid you are out of luck (you =/= Edward
here, just the anonymous
"you"). Boost's property maps are one method to model mathematical maps
in C++ that mandates
not the use of one specific implementation (like some predefined
class(es) of function(s)), rather they
are "merely" a set of assumptions. Every C++ software artifact that
fulfills these assumptions (read:
abides by the specified syntactic and semantic requirements of the
property map concept) is a
property map. Software that in its code only uses the assumptions that
the property map concept
mandates (and not more) is guaranteed to work with /every/ artifact
implementing the property map
concept. A more familiar case might be the concept of Input Iterator.
The std::find algorithm works
for every C++ artifact that implements the Input Iterator concept; you
are not confined to use
std::list::const_iterator, std::map::iterator etc., /any/ Input Iterator
works (not just those from the
standard library). So, actually, contrary to what Jeremy says, the
property map concept in itself
is not at all vague. It /could/ be defined more rigorously (read:
formally, which inevitably means
mathematically, because mathematics really is the only precise language
humankind currently has).
But this is not necessary nor would greatly support its understanding
for the average developer
(simply because the average developer is not trained in reading precise
formal specifications like
algebraic data types, modal/temporal logic, process algebras, whatever).
The understanding therefore
must come from practice and from reading existing code. The BGL provides
plenty of it. Read it
and learn from it.

> OK, why not explain that in the doc and how it is done.

Explanation is already there; read the code example right on the
introductory doc page and follow
the links to the (const_)associative_property_map pages a bit further
down. Perhaps there is less
of a problem than you (Edward) expect, the
(const_)associative_property_map is really just a simple
adapter (read the GOF book about the Adapter pattern if you haven't
already done so).

> You didn't answer the first question.

There is no need to, the get/put/operator[] semantics are described in
the docs. Look at the Valid
Expressions boxes on the ReadablePropertyMap, WriteablePropertyMap, and
LvaluePropertyMap
pages. If you understand the SGI STL docs you understand the
get/put/operator[] description as well.

> Example of this in the doc please, with some function template showing
this
> technique as practical usage within your "concept".

I am afraid this is a standard technique by now and the property map
docs are not the right nor
adequate place for talking about it in any detail. Several published
articles (on the web, in CUJ
etc.) or the SGI STL source code itself are available for perusal. And,
again, for examples on how
to use PMs you may always read the BGL sources or the BGL book. 

> I find it unbelievable that any college would accept your
> documentation as adequate explanation of your concept. Either colleges
have
> deteriorated from what they were when I went there, or you don't
perceive
> the need for the same amount of professionalism in dealing with other
> programmers as you would in dealing with college standards.

Have you ever seen the C++ standard document? It is full of vague
language, contradictory
statements, false code, missing or invalid assumptions, omissions, you
name it, despite it
having been perpared by many knowledgeable people. Perhaps this might
prompt you to
switch to another language, not being able to cope with such a low
degree of professionalism.
OTOH, you might perhaps agree that not everything can be perfect right
from the start. The
PM docs certainly are terse and not tutorial-like, but then they never
pretended to be. They
IMO adequately (and thankfully non-verbosely) manage to state the core
facts and details.
Any complementary documentation still has to be written. I anyone feels
he known how to
fill the perceived gaps, please feel invited to contribute.

Jeremy Siek wrote:

> Hi Edward,
> 
> Since you feel so strongly about this, please write a new version of
the
> property map docs and send them to me.
> 
> In future emails, I would appreciate it if you refrained from using
such
> an accusatory tone. At this point I'm feeling hurt by your words and
> discouraged about volunteering my time to boost.
> 
> Sincerely,
> Jeremy