From: johnsd2@jec314.its.rpi.edu.its1 (Daniel Norman Johnson)
Subject: Re: Windows, OS/2 and Mac APIs
Reply-To: johnsd2@jec314.its.rpi.edu.its1
Organization: Sun Microsystems, Inc.
Date: Sun, 15 Nov 1992 18:30:40 GMT

In article 24505@fcom.cc.utah.edu, brian@jaguar.cs.utah.edu (Brian Sturgill) writes:
>In article <dft1s_r@rpi.edu> johnsd2@vccsouth03.its.rpi.edu.its1 writes:
>>In article 13425@fcom.cc.utah.edu, brian@jaguar.cs.utah.edu (Brian Sturgill) writes:
>....
>>Be aware that what you say below is not about the rules
>>at all. If you wish to change topics, fine.
>
>But it is about the rules.  Essentially each new volume incorporates:

And here you go again, about DOCUMENTATION. Its all very fine
to complain about this, but it just isn't the same thing as the
rules.

>	1) The additions since the last volume.

Certainly.

>	2) The changes to usage of the old ones.

?? What do you mean by this. Apple doesn't change the way old routines
work- that would make existing apps crash.

>	3) Guidelines (new rules) to keep you out of trouble.

This is also true.

>A good example of 3... it used to be the case that it was considered quite
>proper for an app to write a private resource into it's resource fork...
>with the advent of AppleShare servers though, this was a problem as
>the app might not be writable, plus the data being written (such as
>options settings, window placement, etc.) would not be proper to make
>as a default for all using the same copy of the app. Even though you
>should not do this, one of the first three volumes still says you should...
>you only find out in one of the later ones that this is now considered
>a bad idea.

Do you really think any OS can avoid this sort of change? How? The problem
with the docs is real- they contain a lot of garbage; this is why apple
is releasing a new set of Inside Macintosh that fixes the problem.

>  The same holds true for the storage of font resources
>in a document... the original set III still say to do this, but do to
>problems getting the font passed to remote printers, this is now "against
>the rules", and one of the later volumes says this.
>(Actually unless this has been put in Volume 6, the font one may still
>be found only in the Tech Notes.)

This is very similar to the above problem with Appleshare.

[deletia- Inside Macintosh the Hard Way]
>This is precisely why there are so many buggy Mac apps, and so many that
>break between OS releases.

What buggy Mac apps are you thinking of?

>>>First read the 120+ page Apple Human Interface Guidlines to get a
>>>feel for the issues involved, then set out to meet the detailed
>>>guidelines: There are 47 pages in Volume I; 10 in Vol. IV; 15, in
>>>Vol. V; and 37 pages in Vol. VI.
>>
>>This is indeed the hard part; but I believe the Apple Human Interace
>>Guidlines contain the WHOLE interface; the rest is repetition.
>
>No, the Human Interface Guidlines is out of date, you would at the very
>least, have to read Volume VI.  Also the stuff in IM is much more detailed.

Well, that's annother documentation problem them. (tho its news to me)
Wonder when apple will fix that.

>>
>>>Basically even the most trivial of apps requires one to be familiar 
>>>with well over a thousand pages, in 10 different categories.
>>
>>It helps to do this, but you dont need to.
>
>Too many people don't bother to do this first, thus Mac shareware/freeware
>often have rather short lifespans.

Really? Can you justify this assertion, as it doesnt seem true to me.
Also, is this worse for the Mac than Windows?

>>
>>> The
>>>average category requires you to read and combine two sections if
>>>you want your app to run on System 7 -- three sections if you
>>>want it to run on System 6 and 7, but using the most modern
>>>features when possible.
>>
>>Making something system 6 AND system 7 compatiblke is a pain- but its
>>a pain you Windows folks will soon experience, when Microsofts makes
>>a siginificant upgrade beyond Win3. (say, Windows NT)
>
>I disagree strongly here... it is easy getting between Windows 3 and NT.
>If Apple had kept it's documentation up to date, and provided transition
>documents like MS does, then they would not have had all these problems.

Windows NT will be compatible with Windows 3, so if you stick to the
rules well enough it will be able to run old programs- but to use
new features will be just as much fun as doing it on the Mac.

Also, I seem to recall there being some bitching and moaning about how
a significant number of apps from 3.0 did not work in 3.1; a pretty
small upgrade should not cause such problems.

Similarly, when Windows 3.0 came out it didn't support Windows 2.0
apps very well- you had to update virtually all of them. (at least,
that the impression the magazines gave me at the time)

What if this is a trend?

>>
>>>Is it any wonder Apple is having trouble keeping ISV's?
>>
>>I would say it had more to do with market share.
>
>Why would this be true?  Macintoshes have gained market share for the
>last two years.  While they have not grown nearly as fast as Windows, they
>definitely have shown 

Windows has a much larger market share, plain and simple. More money is
tempting to anyone.

>>
>>>....
>>>>
>>>>Incidentally, I dont recall anything important in the Tech notes about
>>>>it. What are you think of?
>>>
>>>This is the typical problem... without going and looking how do
>>>you know?
>>
>>I do not assume that there is something there, if the info is present
>>in Inside Macintosh. Occasionally there are bugs but they are not common,
>>and you can usually get away with just IM. (if something crashes
>>inexplicitly you perhaps could check out the notes and they may help,
>>tho)
>
>I have trouble believing that this is a proper attitude on a non-protect
>mode OS, that often doesn't bother to check the parameters you pass it.
>(And doesn't even have a debug version of the OS like Windows 3.X does.)

I agree; they should check their parameters whenever reasonable to do so,
despite the cost in speed. The Mac doesn't do this enough.

>>
>>The Tech Notes mostly provide info that is absent from Inside Macintosh.
>>
>>>>
>>>>>To do file I/O you need to look in 2 volumes plus all the Tech notes.
>>>>
>>>>Once again, it depends on what versions of the system you want.
>>>>IM-VI is sufficient, if you only want to program system 7.
>>>
>>>Wrong, If you look on page P-17 of Volume VI it clearly says that
>>>you need to read in Volume IV, V, and VI to program for System 7.
>>
>>It is wrong. Really. Im not making this up. If you use nothing but the
>>FSp routines, you need nothing but IM-VI. (well, there are some routines
>>in IM-II (duplicated in IM-IV) that you also need, but I presume
>>you can remember FSClose(refnum).
>
>Well first of all I think I'll just take Apple's word for it.

As you like.

>But even if it is true,  there are plenty of other "Managers" that require
>you to look in 2 or 3 IM volumes.

I dont know about that. There ARE some sections that have been wholly
replaced (the sound stuff for isntance) and you need to know that;
presumably the new IM will just drop the outdated stuff. But in most
areas the old stuff will still work, and if thats all you need to do
you dont need to search elsewhere. If you need newer features, you need
to look in more volumes. Its bad organization, but its not as bad as you
are making it sound.

>>
>>>>
>>>>I dont recall the tech notes saying anything critical about this
>>>>either.
>>>
>>>You'd better look again then, there are several Tech Notes on
>>>File Manager issues.
>>
>>Ive seen them too, but they are rarely needed.
>
>Really? :-)

Really. Why, did I miss the tech note that sez you have to call
FSRead with the square root of pi as teh refnum before any other
file manager routines, or your program wil crash on system 7.2? :)

>>
>>>....
>>>>>Some people will tell you that the Mac is easy to program for... I
>>>>>invariably find that people that say this did not realize that the
>>>>>code they were producing violated many of the guidelines.
>>>>
>>>>Such as?
>>>
>>>I tell you what, write the equivalent of Petzold's "hellowin"
>>>program and I'll audit it for you.
>>
>>Hmm? What's Petzold's "hellowin" program?
>
>Ah... here you are arguing about the ease of Macintosh programming, and
>you don't know about Windows programming?

Dont be TOO stupid if you can help it. (a) the ease of Macintosh
programming is independant of the ease of Windows programming. (b)
Petzold's "hellowin" program is not relevant to that anyway.

And watch those ad-hominem attacks. I am not going to go away
just because you don't think much of me.

>Trust me, I've programmend numerous GUI environments (Windows 3.X and NT, X11
>and Motif, a small amount of OS/2 PM, as well as the Mac), and the Macintosh
>environment is the hardest to deal with of them all.

That may be true, but it is not as hard as you are making it sound.

>
>>
>>>See the 550 page Vol. I, 429 page Vol II, 279 Page Vol II, 326
>>>page Vol IV, 625 page Vol V, 1500+ (not a typo!) Vol VI, plus
>>>200+ Tech Notes at more than 5 pages per, for details on what I
>>>will base the audit on. :-) BTW, That's nearly 5000 pages of
>>>documentation, and don't think that "more is better", IMO Windows
>>>is better documented than the Macintosh.
>>>(The Windows 3.1 SDK is also about 5,000 pages too, but the books
>>>have much smaller pages than Inside Macintosh, it is probably
>>>the equivalent of about 3,000 Inside Macintosh pages.)
>>
>>This seems to be the crux of your argument- you dont like Apples
>>documentation. But what does this have to do with it? Use someone
>>elses docs if you like, or get the New Improved Inside Macintosh,
>>which fixed the organization problem you are having.
>
>It's not so much a matter of the documentation as it is the complexity
>of what you have to know.  Improving the docs would help things alot,
>but the Macintosh interface does almost nothing automatically for you.

This just isn't so.

>The number of things a programmer must get right on their own on a Mac
>is much larger than under any other environment I've programmed for.

This probably is true. The Mac requries you to do things in several
steps that should just HAPPEN.

That does not = almost nothing done automatically for you.

>>
>>>>
>>>>>Another problem with the Macintosh API is that it consists of calls
>>>>>that take HUGE data structures, and you have to understand every
>>>>>item in the data structure to initialize it properly.
>>>>
>>>>Except they don't. This just isn't true. Most routines just take
>>>>parameters, not paramater blocks.
>>>
>>>How can you possibly say this?  I agree that e.g. QuickDraw don't
>>>take parameter blocks, but many of the FileManager Routines do,
>>
>>all of which have normal parameter equivalents!
>
>Really how do you do a directory tree search with no parameter blocks?

Dont have my manuals here now; I cant look this up. But I have 
a clue for you: you dont do this. There's no reason to do this
is the vast majority of cases.

>>
>>>and the AppleTalk stuff quite defintely does.
>>
>>This is true. I assure you very few Mac programs need to ever
>>touch this stuff.
>
>Uh... I think I would rather say that the reason there is a dearth of such
>programs is that it is so hard to make them.

Hmm, no. You can do it other ways, with the PPC toolbox or with apple
events. Its doing it in THAT particular way thats hard.

>....
>>
>>My info comes from a Tech Note, which says nulls are permissable
>>in filenames but not wise.
>
>Damn!  despite my best efforts to know for certain, I'm wrong!
>See how hard this is?

See how irrelevant? Or do you really think it matters?

>>
>>And, as you have noticed, the MacOS _does_ allow them, even if
>>they are not Officially Sactioned (and will mess up some programs)
>>You were complaining above that the file manager let you use them,
>>so dont try to say now that they are not usable.
>
>I know... I am the author of a program that messed up on this!
>I mean who'd have thought they'd be stupid enough to allow a null?

Why would you give it one? Even if allowed it will trip other
programs up.

>>
>>>>
>>>>However, its true that the MacOS doesn't check its data enough. Even
>>>>a HLock(not_a_valid_handle) can muck up memory. :(
>>>>
>>
>>>At the very end of this message is an example of Macintosh code. It is sample
>>>code from Apple that I hacked on.
>>>What it does is call the Macintosh equivalent of the TCP/IP "gethostbyname()".
>>
>>Oh, gad, you think this is RELEVANT? You go and implement a function the
>>MacOS doesn't have and claim it says something?
>
>I do not implment that function, I load a code resource that performs that
>function.

No you dont; you would not need to have things like asynchronous
callback stuff if it just did it.

>>
>>>Under Windows or Win32 (using the WinSock API), IBM OS/2 TCP/IP,
>>>or Unix, the equivalent routine would be:
>>>#include <netdb.h>
>>>
>>>long
>>>hosttoaddr(char *hostname)
>>>{
>>>	struct hostent *h;
>>>
>>>	if ((h=gethostbyname(hostname)) == NULL)
>>>		return(0);
>>>	return(h->h_addr[0]);
>>>}
>>>
>>>Please understand that all the Macintosh code below does is _call_ the
>>>equivalent of gethostbyname, it is NOT an implementation of
>>>gethostbyname.
>>
>>No it ISN'T. Dont give me this, I went and read it. You implement
>>gethostbyname in terms of other existing functions. Its quite
>>absurd to imply that you are simply calling gethostbyname.
>
>Then I suggest you read it again.  All I do is load the code resource
>from the MacTCP init.  THE CODE RESOURCE IS THE DIRECT EQUIVALENT TO
>GETHOSTBYNAME!

It is NOT. It is asyncronous; that is why it needs the callback.
This is a big difference!

>>
>>>(In other words it takes 150+ lines to do what I did in 10 above.)
>>
>>Check. Perhaps the Mac isn't a good machine to do TCP/IP programming
>>on.
>>
>>>The example is a bad-case for a Macintosh, but I would not call
>>>it a worst-case.
>>
>>What can you think of that is actually worse?
>
>Just off the top of my head:
>
>Any non-trivial program that uses AppleTalk or MacTCP for data transfer.

MacTCP is the example you gave before, but expanded. Appletalk is not
harder; you use the higher level funtions and its easier. Heck, just send
AppleEvents if that'll serve. Of course, there are lots of alternatives
to that.

>Any "control panel" program.

Hmmm? I dont recall anything so amazingly difficult about this,
but I've never written one. What's so hard?

>Any program that does serial port communications.

You just open .<somenameIforgetsorry> and read and write to that.
Its not so hard.

Somehow it doesn't suprise me that a whole program is more difficult
that one function.

>>
>>>  It is indicative of the attitude that prevails
>>>throughout MacOS -- that all the work is left to the programmer.
>>
>>This just isn't so. I agree the MacOS should do more of the work,
>>but it hardly leaves it all to the programmer.
>>
>>One other point: you implement this so it will run on any mac at all.
>>Can you really put TCP/IP on a Mac 128k? Do you really CARE?
>
>It supports Macs down to 512K's, not 128K's.
>I did not write the bulk of the code, Apple did... see the copyright notices.
>I normally draw the line at MacPluses running system 6.0.

You said you hacked it; I have no way to know what you did so I assumed
you hacked it until it was the code you wanted.

I would also draw the line at MacPluses+system 6; so why didn't you?
Your comments definitely said it had extra code to support 512kes.
You wouldn't have done it that way, so why did you give us code that
does?

>>
>>Even apple no longer supports those things.
>
>Sorry, but that was Apple's code, so you are clearly wrong here.

Apple has said it no longer supports 64k ROM machines; it has
dropped the tech notes about them. When was the code written?

>....
>>			- Dan Johnson
>
>Brian
>
>P.S. go ahead and respond, but don't be surprised if I don't say anything
>back... I'll be gone (to Comdex) starting tomorrow, and I may not
>catch the message when I'm "catching up".  If you have a specific
>question, send me a copy via e-mail.

ok, Ill respond. Maybe somebody else will argue with me. :)

---
			- Dan Johnson
And God said "Jeeze, this is dull"... and it *WAS* dull. Genesis 0:0

These opinions have had all identifiying marks removed, and are untraceable.
You'll never know whose they are.
Newsgroups: comp.os.ms-windows.advocacy