ari@eleazar.dartmouth.edu (Ari Halberstadt) (11/02/89)
In article <1989Nov1.232424.8861@agate.berkeley.edu> silverio@brahms.berkeley.edu (C J Silverio) writes: >I am sick to death of trying to code Mac applications with the >existing documentation. > >Consider, for example, the case of TextEdit. It was originally >documented in IM-I, then there were a few tech notes on it, then it >was revised in IM-IV and again in IM-V, with a spate of additional >tech notes following. One needs to obtain, read, and piece together >all of these bits of info to use TextEdit with maximum effect. Why >hasn't anybody done this piecing together already? > >What I want is a set of three-ring binders that contains one chapter >per manager. Whenever Apple adds more documentation affecting that >manager (a tech note, a new IM chapter, etc.), I want a revised >version of the entire chapter, as well as a short, succinct >notification of what changed. (I won't ask for "change bars" since >everyone knows they were invented by IBM.) Yes yes...the project I've been working on took me 1/4 times longer cause of lousy docs. At least Apple cleaned up their mess in AU/X...they have about 20 manuals, ring bound, small, and the binder rings are ROUND!!! Yes, you don't have to push 600 pagesto get to the index!!! (or maybe I'm fantasizing, maybe in fact the binder rings are rectangular...). Each manual actually deals with what it says: there's one about text editing, one about games (ya, they put rogue on the mac :-), etc. BTW, who on earth invented square binder rings with 500 page manuals? He/she should be left out to dry in the Sahara desert! And, to keep this evil person company, we should send the people who have been maintaining Apple documentation (I like the first three manuals, we'll be nice to the original team). >(Of course, if this information was to also be available as an >updateable, monster Hypercard stack, I wouldn't complain, but frankly, >I can read printed pages much more easily than computer monitors, so >I'd also insist on paper copies.) It is, but only the tech notes. Besides, I can't run Hypercard and my debugger and program at same time, even on 4 and 5 meg machines... The best things to date: 1. Inside Mac DA. The version I have goes up to vol IV, which is most of what you need. Saves endless trips to the bookshelf. It's amazing how 4 volumes can be shrunk to 6x5 inches. 2. OnBase. When you need a prototype, or the name of a field in some obscure structure, OnBase is the one! 3. HyperCard technotes stack. Just the regular tech's, but in stack form. 4. MAC DTS sample code. Virtually useless to me, since I've had to learn all that junk myself...oh well. The examples just aren't terribly serious. And even on Phil and Dave's excellent CD I could find no sample DA code, so again I had to plow through three very poorly documented sections of IM. Turned out, writing a DA is simpler than an application, once you know how. Maybe we could have a frequently asked questions posting, a sample code posting, a "where to get help" and "you're not alone" posting, etc. Seems nearly everyone (including myself) starts out with just about the same problems, asks the same questions, breaks their heads on the same problems...what's the point??? We just need to find someone who will be willing to repost every, 2-3 weeks, and who will take submissions and include them (if deemed worthy or demanded by the net). If possible, people could help him/her out by sending copies of things that appeared on the net, just in case they were missed by our volunteer (keep this last idea to a minimum, don't want to swamp the mailer). That's about it. Oh, someone asked about handles, but I couldn't get through to him. If you're still out there: **hndl = SomethingThatFoolsWithMemory(); Don't do that: THINK C evaluates the pointer first, then calls the function, so if memory moves, you're in trouble. Similarly, don't do SomethingThatFoolsWithMemory(&(**struct_hndl).element); For the same reason. -- -- Ari Halberstadt '91, "Long live succinct signatures" E-mail: ari@eleazar.dartmouth.edu Disclaimer: "Live Free or Die"
d88-jwa@nada.kth.se (Jon Watte) (11/06/89)
In article <16467@dartvax.Dartmouth.EDU> ari@eleazar.dartmouth.edu (Ari Halberstadt) writes: >bound, small, and the binder rings are ROUND!!! Yes, you don't have >to push 600 pagesto get to the index!!! (or maybe I'm fantasizing, I agree wholeheartedly on the "One updated section per manager" idea. >Maybe we could have a frequently asked questions posting, >on the same problems...what's the point??? We just need to find someone I * MIGHT * be able to do this. I think it requires setting up a mail alias, and the sysops at THIS system might not feel the need for this as badly as the Net seems to :-) I might be able to do this on another system, though then with one-day type of delays... Mail me (as h+@nada.kth.se or h+@proxxi.se) if you NEED this, and come with suggestions ! >That's about it. Oh, someone asked about handles, but I couldn't >get through to him. If you're still out there: > **hndl = SomethingThatFoolsWithMemory(); >Don't do that: THINK C evaluates the pointer first, then calls the >function, so if memory moves, you're in trouble. Similarly, don't do > SomethingThatFoolsWithMemory(&(**struct_hndl).element); >For the same reason. Of course you can do: HLock(hndl); **hndl = SomeThingThatMessesWithMemory(); HUnlock(hndl); That's what those calls are for... Happy Hacking ! h+ -- This .signature is longer than 4 lines. If you'd like to see it in whole, please send a note to me. I'm h+@nada.kth.se and also h+@proxxi.se 8')
awd@dbase.UUCP (Alastair Dallas) (11/09/89)
Really, people, a 3-ring binder? Why not get one of those 6-foot-long metal catalog binders they use at auto parts stores? Microfiche, anyone? I mean, let's bring the solutions up to the 1960s at least. I'm just amazed. Apple doesn't put out a CD-ROM that does the job, and the Inside Mac DA is not up to date (apparently), so let's go back to paper! This is the 1990s. Sheesh. The answer is, re-write one Inside Mac that is up to date and which includes the tech notes and sample code and make it available on CD-ROM. If you want, you can publish it, too--three-hole-punch it if you like. (BTW, many places have equipment to slice the binding off the soft-cover IMs and whump! punch 3 holes at once--it takes no time.) I would rather see a more full-blown, Think C-oriented Chernicoff series, personally, even though it will be outdated eventually. There's not a mass-market, but I made some money in the early 80s self-publishing a "book" of details about the CBASIC compiler. Maybe what we need here is a series of pamphlets (Joel West on printing, etc.) that are periodically updated. That way, instead of TN 160, TN 183 and TN210 you could just turn to the MultiFinder pamphlet. All this complaining says two things: the current solutions aren't working, and there's money to be made here. /alastair/
silverio@brahms.berkeley.edu (C J Silverio) (11/09/89)
Alastair Dallas writes:
Really, people, a 3-ring binder? Why not get one of those 6-foot-long
metal catalog binders they use at auto parts stores? Microfiche, anyone?
I mean, let's bring the solutions up to the 1960s at least. I'm just
amazed.
Don't forget that even in this modern age it is still difficult to
beat the convenience and quality of paper and ink technology.
Electronic Publishing isn't hardly in its infancy, but rather a sort of
gestation period. CD-ROMs seem to be supplying the necessary nutrient
mass, but it will still be a long time until Electronic Hiliting,
Electronic Marginal Notes, Electronic Dog Eared Corners, and
Electronic Coffee Stains are correctly implemented. Nevermind the
fine resolution, easy perceptibility, and light weight of paper as
well. By the time the software is done, Hyper-twist LCDs should cost
pennies per pound.
Meanwhile, you won't catch me reading 600 pages of textbook in
Monaco-9.
Right now I am once again going over TextEdit, and cursing the fact
that I don't have all the appropriate Tech Notes (and the brain big
enough to digest all of them simultaneously).
And right you are, there is plenty of money to be made here. There is
no law preventing some other company from replacing Inside Mac et al.
(providing, of course, that plagiarism is not an issue).