=head1 contributing to tcl/parrot

a brief overview on how to help out, if you're interested. In general, 
it's ok to send patches for tcl to the RT system for anything that isn't
"BIG STUFF" - those, please bounce off me first. I'd prefer C<diff -u>
patches, but am happy to take complete files as well.

Most of this is mentioned in the TODO - in fact, this document probably
should merge with the TODO to avoid redundancy.

=head1 BIG STUFF

=over 4

=item speed

We're currently a bit slow, compared to tclsh. Switching over to a compiler
instead of an interpreter might help here, though I'm having a hard time
envisioning a compiler that doesn't have to do all the things we already do
as an interpreter. 

We could rewrite parse/interpret/compile in C, either as an NCI or behind
a PMC object - this would I<possibly> give us an improvement in speed also.

=item features

We're currently missing a lot of stuff that requires support from parrot
before we can continue, like Unicode for the C<\u> escapes. I've tried to
start documenting these in the TODO with sections like C<given Unicode>, 
then listing the things that we can do once we have that. 

=back

=head1 DOCUMENTATION

=over 4

=item pod 

Every PIR .sub that's defined should probably have some POD to go along
with it to document the arguments and return values.

=item big picture docs.

Are the docs in C<docs/> useful? Could use someone to proof them, and
verify that there are no missing chunks (if missing, write them, or 
get them added to the C<TODO>), and that they are coherent.

=back

=head1 PIR

=over 4

=item Missing Commands

Every builtin command corresponds to a file with an appropriately named
sub in C<lib/commands> - Each of these subs takes some number of PMCs
as arguments. For those commands that take a fixed number of parameters,
we declare them with C<.param>. For those that take a variable number,
we use the C<foldup> opcode.

Note that there are two return values for each command, an int and a PMC.
The integer contains the Tcl return value for that command (OK, BREAK,
RETRUN, etc.). The PMC is usually a string at this point, but could be
any valid PMC. Note - right now, if there's an error condition, create
a new string-like PMC and put the error condition in it. Eventually this
will be some kind of structure.

Once you write a command (or add a subcommand), you need to add a test file (
or a test in an existing) file in C<t/> - tests for C<puts>, for example,
go in C<t/cmd_puts.t> - we use the C<Test::Harness> framework, via 
C<Parrot::Test>. To run your test, just say C<make test> in the top level
tcl directory. Be sure to test each of the subcommands. While our eventual
goal is to pass the tcl test suite, we really need to maintain a good one
on our own in the meantime.

To find a command to work on, just check out the TODO - several commands
are currently not implemented, and others are missing various subcommands.

=back

=cut

