If you're going to hack on the inside of plum, please try to follow the
paradigm I'm currently using.  That means please use the same style of
variable names and function names.  ALL_CAPS are constant variables or
signal handler functions.  Capitalized variables are globals.  Lower
case are locals.   Things with leading or trailing underbars are
package statics or dynamically scoped variables respectively. Indention
is less important, but still nice.

You should familiarize yourself with the global data structures,
particularly things like %Scan_IDs and @Scan_Lines.  Per-folder
characteristics liek these are squirreled away into pseudo-anonymous
packages.  Check the &active_folder routine for details.

Plum uses delayed compilation through autoloading from disk for user
functions and autoloading (postcompiling) from its own DATA segment.  This
is probably the heaviest wizardry in plum -- blame Larry. :-)

Almost any function you want to use and be autoloaded instead of
included in plum proper, even replacements for existing functions.  If
it's a function you're not always going to use and don't want to
autoload, put it below the __END__ marker and add a &postcompile line.
Now, some functions you can't put below the __END__ marker.  I don't
know why, but it tends to screw up if you do.

If you're going to try debugging this, you'll need to remove the
__END__ marker entirely.   You'll also need to do so if autoloading and
postcompiling don't work on your system.  While I haven't seen such a
system yet, there are some hardcoded ideas about how big a C pointer is
in the &swapnload routine that might bite you.

Remove __END__ if you're going to undump or unexec() plum.

Plum takes a lot of memory.  You can probably save on some of this
by not worrying about folder resizes and only asking scan for lines
big enough for your current screen width, instead of the 200 I use right now.
I believe that the leaks are out of it now, however.  But reading
in 1000 messages from comp.lang.perl will surely make you grow, 
and I can't give that memory back.

I'm pretty fork-happy.  We've got the folder daemon that runs in the
background at first to help with completion.  There's also a gratuitous
fork or two in the two pagers.  If you don't have a copy-on-write VM
system, you may not be happy about these things.

If you do add more functions, please put in #%%# documentation as I've
begun to do.  This will help in the long run.

Above all, read the source.  Good luck.

Following is the tool I currently use to debug plum.  It calls "splum"
which is just "slow plum", eg. one without the __END__ and postcompilation.
Actually, it's just a bunch of requires, but you can achieve a similar
effect by removing the __END__ line.  

--tom

#!/usr/local/bin/perl

system("stty -echo");
&jam("b main\n");
&jam("b debugger_escape\n");
&jam("c\n");
system("stty echo");

open(TMP, ">/tmp/plumdebug.$$");

print TMP <<EOF;
    tty > /tmp/plumdebugtty.$$ 
    stty intr undef
    echo DEBUGGING
    sleep 77777777
EOF
close TMP;

system "xterm -WE +ls -ut -n plumbug -e sh /tmp/plumdebug.$$  2>/dev/null &";

sleep 1 until -e "/tmp/plumdebugtty.$$";

chop($bugtty = `cat /tmp/plumdebugtty.$$`);

print "slave tty is $bugtty\n";

$SIG{INT} = 'done';

system "perl -d splum -t $bugtty +inbox 2>&1 >$bugtty";

&done; 

sub done {
    print "\n";
    unlink </tmp/plumdebug*>;
    exit 0;
} 


sub jam {
    $TIOCSTI = 0x80017472;
    for (split(//, $_[0])) {
	ioctl(STDERR, $TIOCSTI, $_) || die "bad TIOCSTI: $!";
    } 
}