From: Chewy@cup.portal.com (Paul Frederick Snively)
Newsgroups: comp.sys.mac.programmer
Subject: Re: Gestalt glue is redundant!
Date: Mon, 20 Jul 92 21:56:46 PDT
Organization: The Portal System (TM)
  <1992Jul11.063540.11834@usenet.ins.cwru.edu>
  <5cWy03MV36Pd00@amdahl.uts.amdahl.com> <BrEo5w.Bt4@world.std.com>
  <c6n403hY3dcZ00@amdahl.uts.amdahl.com>

jsp@uts.amdahl.com (James Preston) writes:

>siegel@world.std.com (Rich Siegel) writes:
>
>}In article <5cWy03MV36Pd00@amdahl.uts.amdahl.com> jsp@pls.amdahl.com writes:
>
>}>The glue is not documented anywhere in the THINK C documentation.  Symantec
>}>makes great compilers, but the completeness of their documentation is sadly
>}>lacking.
>
>}In defense of the guys who wrote the doc, it's not their responsibility (nor
>}is it Symantec's) to document the Macintosh toolbox interface, particularly
>}since it's a moving target. The Gestalt glue (and the rest of the components
>}of MacTraps and MacTraps2) are supplied by Apple.
>
>}It's also not their responsibility to teach people how to program the Macinto
sh
>}or how to program in C; there are reference materials already extant that
>}do a very complete job at both tasks, including, but not limited to,
>}Kernighan & Ritchie's "The C Programming Language" and Apple Computer's
>}"Inside Macintosh" (along with associated technical notes and other related
>}materials).
>
>Well, this is getting a little off topic, but since I feel strongly that
>the THINK products' documentation is a very large blemish on otherwise
>excellent products, I'd like to followup a little.
>
>I disagree when you say that it is not the responsibility of the THINK C
>documentation to talk about something like the Gestalt glue code.  In the
>first place (and I'm sure I don't need to remind Rich of this), THINK C
>is not just a C compiler, it is a Macintosh development environment.
>Therefore, its documentation certainly should talk about the interface
>between the application program and the Mac toolbox.

The THINK C documentation _does_ talk about the interface between the
application program and the Mac toolbox, to the extent that it documents
how to use #include files and libraries in your projects.  There is nothing
magical about the Toolbox/OS interface viz-a-viz interfacing to any other
kind of library that you have library/header files for.

>More importantly,
>in this particular case, calling the glue code is something that the compiler
>does _behind the programmer's back_.  It doesn't matter where that glue
>code comes from, be it Apple or anywhere else; the point is that the code
>generator does not see my call to Gestalt and emit a call to directly to
>Gestalt.  It emits code to call the glue code.  I agree that it is a good
>thing to do, but certainly any such behind the back calling must be
>documented by the product that does so, which in this case is THINK C.

I have to disagree.  As has been pointed out before, the interfaces and
libraries that the THINK products ship with are licensed from Apple and
are a moving target.  Not only is Symantec not under the obligation to
reiterate Apple documentation regarding Apple interfaces and libraries,
it would be, IMHO, irresponsible of them to do so, since maintaining
parallel versions of such documentation would be a herculean effort
replete with the potential for the most egregious sorts of errors to
occur.

>I don't see how something like this can be put in the category of "teaching"
>Mac or C programming; what I'm saying is that the documentation left out
>a feature _of the code generator_ (i.e. that it calls glue code rather than
>the Gestalt routine directly), and I therefore ended up doing an hour or
>so of unecessary work.

Your assertion that the inclusion of the Gestalt glue in your code is `a
feature _of the code generator_' is in error.  The Gestalt call is defined
in ":Mac #includes:Apple #includes:GestaltEqu.h" (from the THINK C folder)
and is conditionalized on whether the compiler variable SystemSevenOrLater is
defined or not.  If it is defined, then the trap is used, otherwise the
function declaration is left unresolved, in which case it's up to the linker
to cope with it.  Note that all of these machinations--#include files,
compiler variables, preprocessor directives, etc.--are documented in the
THINK C documentation.  Apple's particular use of these features in their
interfaces and libraries, however, are not, and this is what I claim is as
it should be.

>--James Preston

Paul Snively
Dissolute Wandering Hacker
chewy@apple.com