[albatross-users] more data tricks for the wiki

[Eric S. Johansson]

Gregory Bond wrote:

>  
> 
>><al-for iter="item" expr="list">
>>
>>where list is the list of sets and item is a single element from the list.
> 
> 
> No, better to think of it as: item is a ListIterator object, item.value() is
> a (reference to a) single element from the list.  

my question for you is: at what point does the distinction between ListIterator 
and a simple element created from the list contents confuse the user and 
enlighten the user.

There is a point that the early learning phase where this is not important and 
in fact detracts from the user's ability to masterthe basics.  There is some 
point later when it becomes important to have the concept of ListIterator firmly 
in one's mind.  Can you define that boundary?
> 
> Which implies "item" is not a great name for the iterator in an al-for loop!

true.  But what else works?  It's a singleton containing your precious data and 
it is your challenge to rip your data out of its evil clutches and cast the 
empty ListIterator husk into the depths below.  (I guess that shows my frame of 
mind)

seriously, from the user's perspective "item" is just that.  A single item.  The 
user shouldn't have to care that it's an iterator when the surrounding structure 
looks like a simple for loop.  if appearances are deceiving, the user will 
resent being deceived.

> 
> (And it is a real reference to the actual object, too, so you can do things
> like "item.value().use_count += 1" and it will do the Right Thing.)

that's information for the advanced category of the documentation

> 
> Personally, I don't find "i.value().field" to be much of a problem, but that 
> may be because I grew up doing pointer arithmetic in C.

when I was programming in C, I would regularly create structures of pointers 
that would make the other programmers on the team whimper in fear.  When c-front 
  1.2 was released and I got a chance to play with C++, I was able to understand 
the output of c-front well enough that I could tell the vendor what was wrong 
with the code generator and give them concrete examples to reproduce the bug. 
It's fun scary when you get to be on a first name basis with the development team...

in my dotage, I have come to appreciate simplicity.  anything.value().something 
is not simple.  :-)

so tomorrow, I will take your advice as well as others and try to rework my 
example.  By the way, commentary on what is already in the wiki is also important.

---eric