About
-----

Exemplar is a program designed to make it easier to work with XML. It began
life as a program to generate the smallest possible parser for a given
vocabulary of XML. While it still retains the capability to do this, it is now
a more general program intended to support conversion of specifications of XML
vocabularies (DTDs, Schemas, etc) into useful code.

Exemplar is designed to support plug-in moduless to implement input
translators, output producers and user/application interfaces. This should make
it easier to add features to Exemplar and/or integrate it with third-party
products.

How To Build
------------

If you got Exemplar as a source distribution, you have to build it before you
can use it. If you can't or don't want to build Exemplar, then go back to where
you got the source distribution and fetch the binary version instead.

Building a JAR should be as easy as typing `ant jar' in the directory that you
found this README file. The resulting Exemplar.jar can be found in the `dist'
directory.

Of course, sometimes it just isn't that easy. :-) You must have the following:

1) A Java compiler
2) Ant
3) JFlex
4) CUP

The JFlex and CUP JAR files must be in your classpath.

How to Use
----------

Read the documentation. :-) OK, here's a quick intro.

As a command line app:

java -jar /path/to/Exemplar.jar --input /path/to/vocabulary.dtd
	--output-language Java --output-api SAX2 --vocabulary vocabulary

As an Ant task:

<taskdef name="exemplar" classname="com.mcdermottroe.exemplar.ui.ant.Task" />
<exemplar	input="/path/to/vocabulary.dtd"
			output-language="Java"
			output-api="SAX2"
			vocabulary="vocabulary"
/>

Now read the documentation. :-)

Licensing
---------

The license for Exemplar is found in the LICENSE file and in every source file.

The following are NOT covered by the license for Exemplar:
 * Everything under lib/

   Details of the licensing of these files may be found in lib/LICENSING

 * All files under dtds/docbook-xml-42

   The license for these files can be found in the
   dtds/docbook-xml-42/docbookx.dtd file.

   This directory is only needed for testing and can be removed without
   affecting the functionality of Exemplar. None of the files in this directory
   appear in the binary packages.

 * All files under dtds/docbook-xml-44

   The license for these files can be found in the
   dtds/docbook-xml-44/docbookx.dtd file.

   This directory is only needed for testing and can be removed without
   affecting the functionality of Exemplar. None of the files in this directory
   appear in the binary packages.

 * dtds/w3cschema/XMLSchema.dtd and dtds/w3cschema/datatypes.dtd

   Those files were originally referenced from appendix G of the XML Schema
   Recommendation (http://www.w3.org/TR/xmlschema-1/#nonnormative-schemaDTD)
   and are copies of http://www.w3.org/2001/XMLSchema.dtd and
   http://www.w3.org/2001/datatypes.dtd and have been modified only as
   described below.

   There was no copyright notice on either file and in accordance with the
   documents http://www.w3.org/Consortium/Legal/2002/ipr-notice-20021231 and
   http://www.w3.org/Consortium/Legal/IPR-FAQ-20000620 and clarification from
   the W3C I am treating both files as being covered by the W3C software
   license. The full text of the license is reproduced below.

	W3C SOFTWARE NOTICE AND LICENSE
	Copyright (C) 1994-2002 World Wide Web Consortium, (Massachusetts Institute
	of Technology, Institut National de Recherche en Informatique et en
	Automatique, Keio University). All Rights Reserved.
	http://www.w3.org/Consortium/Legal/

	This W3C work (including software, documents, or other related items) is
	being provided by the copyright holders under the following license. By
	obtaining, using and/or copying this work, you (the licensee) agree that
	you have read, understood, and will comply with the following terms and
	conditions:

	Permission to use, copy, modify, and distribute this software and its
	documentation, with or without modification,  for any purpose and without
	fee or royalty is hereby granted, provided that you include the following
	on ALL copies of the software and documentation or portions thereof,
	including modifications, that you make:

	1. The full text of this NOTICE in a location viewable to users of the
	   redistributed or derivative work.
	2. Any pre-existing intellectual property disclaimers, notices, or terms
	   and conditions. If none exist, a short notice of the following form
	   (hypertext is preferred, text is permitted) should be used within the
	   body of any redistributed or derivative code: "Copyright (C)
	   [$date-of-software] World Wide Web Consortium, (Massachusetts Institute
	   of Technology, Institut National de Recherche en Informatique et en
	   Automatique, Keio University).  All Rights Reserved.
	   http://www.w3.org/Consortium/Legal/"
	3. Notice of any changes or modifications to the W3C files, including the
	   date changes were made. (We recommend you provide URIs to the location
	   from which the code is derived.)

	THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS
	MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT
	NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR
	PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE
	ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.

	COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR
	CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR
	DOCUMENTATION.

	The name and trademarks of copyright holders may NOT be used in advertising
	or publicity pertaining to the software without specific, written prior
	permission. Title to copyright in this software and any associated
	documentation will at all times remain with copyright holders.

   This directory is only needed for testing and can be removed without
   affecting the functionality of Exemplar. None of the files in this directory
   appear in the binary packages.

 * The file res/skeleton.nested

   This file is from the JFlex distribution and is licensed as follows:

	Copyright (c) 2006, Gerwin Klein
	All rights reserved.

	Redistribution and use in source and binary forms, with or without
	modification, are permitted provided that the following conditions are met:

	* Redistributions of source code must retain the above copyright notice,
	  this list of conditions and the following disclaimer.
	* Redistributions in binary form must reproduce the above copyright notice,
	  this list of conditions and the following disclaimer in the documentation
	  and/or other materials provided with the distribution.

	THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
	AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
	LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
	CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
	SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
	INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
	CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
	ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
	POSSIBILITY OF SUCH DAMAGE.
 
   This file is required and Exemplar will not build correctly without it.

 * All files under java_cup in the generated JAR file

   When Exemplar is built, it copies portions of the CUP parser runtime into
   the Exemplar JAR file. All of these files are under the CUP license which is
   as follows:

	Copyright 1996-1999 by Scott Hudson, Frank Flannery, C. Scott Ananian

	Permission to use, copy, modify, and distribute this software and its
	documentation for any purpose and without fee is hereby granted, provided
	that the above copyright notice appear in all copies and that both the
	copyright notice and this permission notice and warranty disclaimer appear
	in supporting documentation, and that the names of the authors or their
	employers not be used in advertising or publicity pertaining to
	distribution of the software without specific, written prior permission.

	The authors and their employers disclaim all warranties with regard to this
	software, including all implied warranties of merchantability and fitness.
	In no event shall the authors or their employers be liable for any special,
	indirect or consequential damages or any damages whatsoever resulting from
	loss of use, data or profits, whether in an action of contract, negligence
	or other tortious action, arising out of or in connection with the use or
	performance of this software. 

   These files are required and Exemplar will not run correctly without them.

Any software produced by Exemplar is not covered by the license, even those
parts which are copied from files that *are* covered by the license. If you
need something clearer legally, then contact me and we can work something out.

If the license for Exemplar is not suitable for your needs I am open to
supplying the program to you under a different license. If you or your company
refuses to use the default license, please contact me and describe why you
can't use it and I'll try to accomodate you. I can't guarantee that we'll come
to an agreement, but I'll try to be as flexible as possible.