🚀 go-pugleaf

Again, thanks to everyone for your overwhelmingly positive response to  
Anderson Financial Systems' offer to maintain the c.s.n.programmer FAQ.  
Here are some preliminary ideas about how to organize this information.

There should be separate FAQs for the following broad topics:

	1. Programming tools and utilities (including IB, PB, gcc, etc.)

	2. The main appkit - standard classes we know and love

	3. DBKit - This is going to be confusing, buggy, and HotHotHot
	
	4. Other kits (SoundKit, IndexingKit, PhoneKit, etc.) - over time,  
this may get broken down further as individual sections grow

	5. PostScript and Renderman

	6. Application development issues - integrating this pile of Lego  
into interesting, functional programs. IMHO, this is the least well  
documented topic in the standard sources, and the one from which we can  
all benefit the most.

Ideas for each FAQ are presented in the following sections. Our overriding  
goal is to provide useful, integrated information that does not overlap  
commonly available sources, such as NeXT's published documentation.

-------------------------------
Programming tools and utilities
-------------------------------
Separate sections for IB, ProjectBuilder, HelpBuilder, compiler, gdb,  
other programs in /NextDeveloper/Apps. Known bugs, common pitfalls.

Objective-C - common questions, NeXT vs StepStone implementation, issues  
relating to the runtime system

Palettes - how to build them, implementing the right read/write/awake/init  
methods, common pitfalls, debugging, 2.x vs 3.0.

Makefile maintenance

Localization issues

-----------
Main appkit
-----------
The main appkit FAQ looks like the most complicated. The hardest part is  
how to make it useful without restating a lot of information that is  
already available in the NeXT docs. We propose to subdivide the main  
appkit FAQ by object class, with the following possible topics in each  
subsection:

	1. Typical uses, alternatives, tricks
	2. Common pitfalls and shortcomings
	3. Known bugs
	4. New or fixed in 3.0
	4. A short inline example, or location in /NextDeveloper/Examples
	6. Available ObjectWare - published or PD subclasses

To keep the size of this FAQ under control, only objects for which FAQs  
are required, and within each object listing only subtopics which have  
significant commentary, will be included.

Here's an example, with notes in []:
-------------------------------------------------------------------------
Button (Control : View : Responder : Object)

Typical uses, alternatives, tricks: 
	Uses: Push buttons, for signaling user actions; checkboxes, for  
reflecting the current state of yes/no and on/off choices. 
	Alternatives: Radio buttons or pop-up buttons should be used for  
other multiple-state choices, even two-state choices which are not clearly  
yes/no or on/off.
	Tricks: Unbordered Buttons can be used in place of static  
TextField labels to trigger 'hidden UI' actions on mouse clicks. For  
example, clicking on the label (which is actually a Button) next to an  
editable TextField might bring up a find panel specific to that field.
	[other cool stuff]
	
Common pitfalls and shortcomings:
	Checkboxes do not have a keyboard equivalent to toggle the state  
and cannot be Tabbed into (and out of) from TextFields.
	[Other common gotchas that show up on the Net all the time. For  
PopUpList, talk about how IB is a little braindead in the way it handles  
popups. Then the Example subtopic would show some code of how to  
circumvent.]
	
Known bugs:
	None
	[These would be from NeXTanswers or user reports on the Net]
	[In reality, if there were no known bugs 8^), this subtopic would  
be omitted to save space]
	
New or fixed in 3.0: 
	Nothing, but see ButtonCell for a fix about icon placement.
	[This would be a quick synopsis of new or replaced methods]
	
Example: 
	/NextDeveloper/Examples/BusyBox
	[Actual cut-and-paste code might appear here for common problems,  
or if there are no /NextDeveloper/Examples]

Available ObjectWare:
	AfsButton (Anderson Financial Systems), adds nextText and  
previousText instance variables so that push buttons and checkboxes can be  
included in the text editing loop; when first responder, listens for  
spacebar as the equivalent of a mouse click.
	Afs3DButton (AFS), remembers the coordinates of the last mouse  
click to pass as 3D viewpoint
	NiftyButton (NightShade Software), draw in freeform shapes
	[Other published or PD objects which derive from this class -  
sorry this one reads like a commercial]
-------------------------------------------------------------------------

-----------
DatabaseKit
-----------
Similar to the main appkit approach.
Sections about adaptors - writing and using
DBModeler

----------
Other kits
----------
Similar to the main appkit approach.

------------------------
PostScript and Renderman
------------------------
For specific operators, as needed:
	Known bugs
	Performance hints
	Common pitfalls
	
-----------------------
Application Development
-----------------------
	Designing stable, modular apps and object kits
	User interface issues (forms-based apps, for example)
	Subclassing decisions
	Delegates/controllers vs subclasses
	Dynamic class loading
	Resources - books, articles, tutorials
	API issues/clearinghouse - This is a particular favorite for me.  
I'd like for all active NeXT developers to have a clearinghouse for  
inter-app functionality, with a forum for the best ways to  
inter-communicate. Remember, apps are just complex objects!


Whew! Tired of reading yet? An unresolved question is whether to keep this  
in plain ASCII text, or RTF for nicer displays in DigitalLibrarian. I only  
want to maintain this in one format, so the answer is important. I  
personally vote for RTF unless enough people would feel disenfranchised.

I'm going to pull c.s.n.programmer off the archives and start sifting  
through the common threads. If you have anything to contribute that has  
not been on the Net, I'd love to include it. All contributions will be  
credited in place.

As usual, your comments are eagerly anticipated. In particular, I'd like  
to know if there is general agreement about the six FAQ subdivisions and  
the list of subtopics within each one.

greg@afs.com


--
Gregory H. Anderson          | "We're very tolerant around here,
Benevolent Dictator-for-Life |  being only amateurs ourselves."
Anderson Financial Systems   | - Tortoise (Godel, Escher, Bach)
greg@afs.com  (Nextmail OK)  |