🚀 go-pugleaf

In article <861@mindlink.UUCP> a464@mindlink.UUCP (Bruce Dawson) writes:
>
>     Hmmm.  If I were an Amiga programmer (and I am) and I bought Lattice C 5.0
>(and I did) and I read the intuition.h include file (and I did) I would get the
>impression that the mutual exclude field is there, works, and should be used.

The impression would last only until you actually tried to run your program,
at which point the hard truth would make itself known.

>The include file spends ten lines explaining exactly how mutual exclude works,
>in excruciating detail, without ever mentioning that the function doesn't work
>at all.

Did you notice that the comment documentation for MutualExclude is simply in
the wrong place?  First - the comment immediately following the definition
in the Gadget structure is character-for-character IDENTICAL with that
following the definition of MutualExclude in the MenuItem structure.  Second,
the following line appears in the "explanation" comment:

"Intuition does the visual unselecting (with checkmarks) and leaves it up
 to the program to unselect internally"

Doesn't sound much like a Gadget MutualExclude, does it, now?  More like
a MenuItem MutualExclude, in which case it works perfectly.  Seems to me
that the screwup here was much more likely to have been a editor screwup -
"block move" instead of "block copy", followed by some very simplistic
editing, changing "menuitems" to "gadgets" throughout.  It seems pretty
clear that this is exactly what happened, since "MenuItems" has no 
explanatory text, and also since, if you substitute "menuitems" back in,
the spacing after periods becomes much more like what one would expect...

Besides - did any of you think to check the Intuition manual, which very
clearly states "Currently, Intuition ignores this field"?  Didn't that
give you cause to check the REAL situation with MutualExclude?

>     Back to the main issue:  Given the documentation in the include files
>(there may be more, but you're crazy if you think that all programmers read all
>of the documentation) it would seem to me that a significant percentage of
>programmers will use this field to implement there own mutual exclusion.

Only if they are incredibly dumb.  The point of structures defined in a
system file is that they are SYSTEM structures, used by the SYSTEM to do
SYSTEM-type things.  There is no license to use those structures in ANY
WAY except as specifically allowed by the system.  And if you use those
fields as the documentation demands, and things break, then ragging on
C/A to get them fixed is appropriate, but redefining the field to suit
your own purpose is not.  Using the field exactly as defined, but building
your own routines to handle the error is more appropriate, but damn stupid
programming practice - if it's broken, how do YOU know what it will take
to fix it?  And that DEFINITELY includes redefining the field, if necessary.
MOST especially in an area where the comment, as given and applied to 
Gadgets, could never have been correct in the first place, as several
people have eloquently pointed out.

No, one doesn't have to read all of the documentation.  But knowing the
general state of documentation quality (these comments were, after all,
written by engineers, who are notoriously variable in their language
skills :-), one _does_ have to read what documentation one does read
with care, and enough thought to be able to discover when things are
simply wrong.  And a programmer has a duty, having found a pit, to
step lightly around it until clarification is at hand.

-- 
Mike Farren 				     farren@well.sf.ca.usa