=head1 Priorities

Larry Wall suggests, ``In the absence of other considerations, I'd
encourage you to provide the cleanest interface from the user's
standpoint, and let the implementer worry about the details.''

=head1 Naming

B<Still Undecided:>

All method names use lower-case, `C<_>' seperated names.

B<or>

All method names match their Java counterparts.

All options, parameters, and property names use mixed case names, with
an initial upper case character.  This eliminates a certain amount of
potential confusion with reserved words, which, for the most part, are
lower case.

The following words are abbreviated in method names and parameters:

 Declaration     decl     Decl
 Reference       ref      Ref
 Identifier      id       Id

=head1 Object Instantiation and Options

For creating new parser or handler objects, the `new' methods accept a
list of key-value pairs (C<=E<gt>>) or a hash containing the options.
The key names are derived from the SAX positional parameter names
(`C<Source>' and `C<SystemId>' in Parser's `C<parse()>') or the name of
option setting methods (`C<DocumentHandler>', `C<DTDHandler>',
`C<EntityResolver>', `C<ErrorHandler>', and `C<Locale>' in Parser).

Callers may get and set options directly in the object, for example:

    $parser = SAX::Parser->new( Source => { ByteStream => $fh },
                                DocumentHandler => $doc_handler );

    $parser->{Locale} = 'el_GR.ISO-8859-7';

There are no set/get methods in the Perl SAX API.

=head1 Handler Calls

Handler calls all take hashes instead of positional parameters.  Key
names are derived from SAX positional parameter names.  This allows
parsers and filters to provide additional parameters if they can or
the user requests it.

=head1 Extending Handler Interfaces

Developers of event-generators can extend the handler interface as
they need to.  Event-generators that use an extended interface should
accept generator options or use `C<can>' to test whether a handler can
support their extended interface.

For example, a C<DocumentHandler> that wants to receive internal
entity events instead of having them resolved and passed in to the
`C<characters>' method would define a `C<internal_entity>' method
and/or set a parser option to pass or not pass internal entity events.

=head1 Helper Classes

Perl SAX avoids helper classes (like SAXException and InputSource)
where those classes only hold information and have no behavior.  In
those cases, simple hashes are used instead.

B<It is still undecided> if these should be implemented anyway for
easier portability.

=head1 Contributors

 Eduard (Enno) Derksen
 Ken MacLeod
 Eric Prud'hommeaux
 Larry Wall