many of your questions are addressed in the following forms API quickstart guide:
 
http://cvs.drupal.org/viewcvs/*checkout*/drupal/contributions/docs/developer/topics/forms_api.html?content-type=text%2Fhtml
 
...and we're working on full documentation right now  :)
 
chad
-----Original Message-----
From: Kieran Lal [mailto:kieran@civicspacelabs.org]
Sent: Tuesday, October 18, 2005 02:43
To: Chad Phillips; Angie Byron
Subject: Fwd: [drupal-devel] RFC: Forms API Reference Draft

Please point out the other supporting documentation.

Kieran

Begin forwarded message:

From: David Carrington <david.carrington@gmail.com>
Date: October 18, 2005 1:27:41 AM PDT
Subject: Re: [drupal-devel] RFC: Forms API Reference Draft


On 18/10/05, Angie Byron <drupal-devel@webchick.net> wrote:

If you guys could have a look and throw me your 2 cents on this document overall
that would be awesome.


Should the same document cover a few fundamentals first? For example,
after reading it, I still have no idea how to create a simple form and
do anything with it.

Some example things I still don't know for certain:
* Do I create the $form array myself, or is there something which
initialises it for me?
* How important is the array key "preview", and what does it relate to?
* " $fields[$category][$field->name]" - it is not clear where this
fits in with everything else (or any other nested part of a $form)
* How do I put controls into a block?
* Can I put controls into a table?

I know I could answer all these questions myself by looking at
examples, I'm just curious if they should be part of the same
documentation.

--
David Carrington