
License:
========

iksemel is developed and released under GNU Lesser General Public License.
A copy of the license can be found in the file COPYING. You should read it
before sending patches to the iksemel, since it is implicitly assumed that
your patches are also submitted under the LGPL license.


Design Goals:
=============

Historically iksemel is designed for jabber protocol, but it can be used as a
general XML parser if you only need a subset of XML technologies.

Main goal of the iksemel is removing complexity from programs using the
library and the library itself. This is the reason why only a subset of XML
is supported. Some things like UTF16, entity definitons, DTDs will be eventually
implemented when we found ways to implement them without adding
too much complexity to the iksemel code. Somewhat external standarts
(XQuery, XSLT, vs) will probably not make it into the iksemel.

We don't want to end up like libxml. That library supports many XML standarts
(if not all) but become very big and complex. There are .c files with 100kb+
sizes and implementations of http, ftp and similar highly-complex-on-their-own
protocols inside its code.

Keeping programming API simple is easier. All we need to do is making everything
consistent, providing good documentation, and getting feedback from programs
using the library.

Second goal is providing a full test suite covering all aspects of library.
Having good test programs is more important for us then having actual code
correct. Fixing bugs is always easy, detecting them is hard.

Third goal is making iksemel secure. Since Jabber is a network protocol and
user have no control over incoming data, iksemel must check validity of
incoming data wherever possible. Crashes or buffer overflows on invalid
data is not tolerable.

Fourth goal is keeping library portable. ANSI C and autoconf is choosed for this
reason. GCC and glibc extensions are either avoided or only used where available.
CPU endianness and memory access alignment issues are carefully implemented
and tested.

Fifth goal is keeping memory usage low and performance fast. We will keep
Knuth's "premature optimization is root of all evil" saying in our mind though.
This is why having a good test suit and memory and speed measurement
tools is important.

Last goal is keeping source code organized and modular. It is possible to take
sax.c from iksemel and use it in a program only needs a sax parser. It is also
possible to take stream.c and use it with another parser (e.g. libxml, libexpat)
with a few changes.


Roadmap:
========

* validation

I think easiest way to add this feature is writing another parser based on the
sax parser which parses a dtd (either from sax parser's markup callback which
needs to be implemented or from an external source via iks_vsax_set_dtd() call)
and checks the arguments of sax callbacks. Using it via dom or stream parsers
can require some clever tricks.

* utf16

There are two sides of this. Improving parser to accept utf16 can be relatively
easy. But on the client side things can get confusing. What will be the default
character set used by iks_new(), iks_insert_cdata() and similar functions? and
how they will allow other charsets to be used. Supporting more than utf8 and
utf16 is more difficult. Hopefully there is no immediate need for this. Jabber
uses only utf8 and you can use iconv if you are using another charset in your
application. Btw, there is also byte order issue which is silly. Inventor of BOM
crap must be killed.

* jabber roster

Roster handling generally depends on the UI system used. But I think a generic
roster handler which parses roster result, pushes, presence changes and
allows application to access and display this data can be useful. Challenge
here is making it UI independent and extensible by the application.


Resources:
==========

* http://www.ietf.org/rfc/rfc2279.txt
RFC 2279, UTF-8 format

* http://www.w3.org/TR/REC-xml
W3C Recommendation, Extensible Markup Language 1.0

* http://www.jabber.org/protocol/
Jabber Protocol Documents


File Layout:
============

doc/
* iksemel.texi                Documentation in texinfo format.
include/
* common.h                    Internal header for some common definitions.
* iksemel.h                   Library API
* finetune.h                  Default memory allocation sizes.
src/
* ikstack.c                   Memory management functions.
* utility.c                   Small string utility functions.
* iks.c                       XML tree management.
* sax.c                       SAX parser.
* dom.c                       DOM parser.
* stream.c                    Stream parser.
* sha.c                       SHA1 hash functions.
* jabber.c                    Jabber utilities.
* filter.c                    Packet filter for Jabber.
test/
(self test programs)
tools/
(varius utility programs)


Coding Style:
=============
Here is a short list describing preferred coding style for iksemel.
Please keep in mind when sending patches.

* Indentation is done with tabs. Aligning is done with spaces.
* Placement of braces is K&R style.
* Function names are put at the start of line.
* Function names are lowercase.
* Words of the function names are separated with underscore character.
* Structure and variable names are lowercase.
* Macro and enumarations names are uppercase.
* Exported library API is contained in the single iksemel.h file.
* Exported function names start with iks_
* Exported structure and type names start with iks
* Exported macro and enumaration names start with IKS_

Here is an example:

int
iks_new_func (char *text)
{
	int i;

	i = a_static_func (text);
	if (IKS_SOME_VALUE == i) {
		iks_some_func (text);
		i++;
	}
	return i;
}
