Cytheric XML README Introduction ------------ Cytheric XML is a static library that implements an event-based XML parser for Palm OS, inspired by SAX and Expat. Features: * Callbacks: StartElement, ElementCharacters, and EndElement. * Handles predefined entity references (lt/gt/apos/quot/amp); passes others through. * Handles character references in the ASCII range; passes others through. * Footprint: 12k in code section (including 2k imported from cytheric-util). No globals. * Able to parse a single document in separate chunks; well-suited to network data sources. * Well-documented; includes PalmUnit unit tests. * Implements character handling as a state machine for modularity and clarity. Limitations: * Accepts ASCII character encoding only. * Ignores comments and XML declaration. * Cannot read a DTD, processing instruction, or CDATA section. Results undefined. * Does not support namespaces. * Whitespace handling is minimal; not normalized. The most recent version of this package is available from http://cytheric.net/palm-xml/index.shtml. Contents -------- Important directories and files within this package: doc Directory for source files used by Doxygen to generate HTML documentation. Includes UML diagram source in XMI 1.1 format in doc/uml-design.xml. doc/html contains prebuilt documentation. src Directory for source files that build the archive, libCythericXml.a. test Directory for PalmUnit unit test generation. common.mk Make file that includes common definitions for other Makefiles. COPYING The MIT License that governs use of this package. Makefile Summary Make file that can recursively run subdirectory Makefiles. NEWS Describes updates to this package. Includes latest version number. README This file. Building -------- I develop with PRC-Tools, and the build instructions are designed for that environment. I do not have access to CodeWarrior; however, if you update the build process for that environment, I would be happy to incorporate those changes. * PRC-Tools 2.2 * Palm OS SDK 5. 4 should work too. Designed to run on Palm OS 3.5 or later. * Cytheric Utilities 0.2 * PilRC 2.9 (for unit tests only) * PalmUnit 0.1.2-cytheric1 (for unit tests only) * Doxygen (I use 1.2.8.) (for documentation rebuild only) Minimal build steps: (Just build the library) 1. If you changed any defaults when you installed cytheric-util, review the instructions in the Makefile in the src directory. This defines where to locate the include files for cytheric-util. By default cytheric-xml expects these files in ../../include/cytheric-util. 2. Run "make src" to build the library. Technically, this is all you *must* do to build the library. You may then reference the include files and the library file, in the src directory, in your work. 3. Optionally, run "make install" to install the library and include files. By default these files are copied to ../../lib/cytheric and ../../include/cytheric-xml respectively. See the instuctions in common.mk to change these defaults. Complete build steps: (Build the library and documentation, and run unit tests) 1. If you changed any defaults when you installed cytheric-util: a. Review the instructions in the Makefile in the src directory. This defines where to locate the include files for cytheric-util. By default cytheric-xml expects these files in ../../include/cytheric-util. b. Review the instructions in the Makefile in the test directory. This defines where to locate the include and library files for cytheric-util. By default cytheric-xml expects these files in ../../include/cytheric-util and ../../lib/cytheric respectively. 2. If you changed any defaults when you installed PalmUnit, review the instructions in the Makefile in the test directory. This defines where to locate the include and library files for PalmUnit. By default cytheric-xml expects these files in ../../include/palmunit and ../../lib/palmunit respectively. 3. Run "make" to build the library, unit tests, and documentation. This command simply runs make in the src, test, and doc subdirectories. You may build these modules individually using "make src", "make test", and "make doc". 4. Run the executable for the PalmUnit unit tests to verify the build. The executable is found in the test directory. 5. Run "make install" to install the library and include files. By default these files are copied to ../../lib/cytheric and ../../include/cytheric-xml respectively. See the instuctions in common.mk to change these defaults. Using the Library ----------------- Once you've installed the library, you're ready to include it in your project. The Doxygen HTML documentation shows how to use the library. You can find example code in the unit test classes. Acknowledgements ---------------- * The many contributors to the Palm Developer Forum, especially John Marshall, Ben Combee, Aaron Ardiri, and Keith Rollin for their tool/vendor support. There's a lot more signal than noise there. * Julie McKeehan and Neil Rhodes for _Palm OS Programming_, and Greg Winton for _Palm OS Network Programming_. They are excellent introductions to practical Palm development. * My colleagues CJ Villa and Larry O'Brien for their encouragement. Feedback -------- Let me know if you run into any problems, want to share your experience, or have some code/ideas to contribute. I hope this helps your project! Ken Bannister kbee@rcn.com http://cytheric.net