GNU Enterprise - Module Guide Proposal
 
Reinhard Müller
GNU: Enterprise Core Development Team
Neil Tiffin
GNU: Enterprise Core Development Team
Edited by
Derek Neighbors

GNU Enterprise - Module Guide Proposal
by Reinhard Müller and Neil Tiffin
by 
Edited by Derek Neighbors
Published Tue May 23 12:30:23 MST 2000
Copyright © 2000 by Free Software Foundation
Copyright (c) 2000 Free Software Foundation
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

Table of Contents
1. GNUe Module Proposal	000
1.1. Introduction	000
1.1.1. What is this document intended for?	000
1.1.2. General Structure of GNUe Modules	000
1.2. Table Design	000
1.2.1. Naming Conventions	000
1.2.2. Package Names	000
1.2.3. Data Modeling Rules	000
1.2.4. Data Types	000
1.2.5. Storing Redundant Data	000
1.3. Form Design	000
1.4. Report Design	000
2. GNUe Business Objects	000
2.1. Introduction	000
2.1.1. Business Objects	000
2.1.2. Naming Conventions	000
2.1.3. Coding Conventions	000
2.2. GNUe Class Files	000
2.2.1. MODULES and CLASSES	000
2.2.2. EXTEND	000
2.2.3. Fields	000
2.2.4. TYPE (Complex Fields)	000
2.2.5. TYPE (Typedef) (NOT IMPLEMENTED YET)	000
2.2.6. Comments	000
2.2.7. Include	000
2.2.8. ORDER BY	000
2.2.9. LOOKUP	000
2.2.10. REFERENCE	000
2.2.11. LIST	000
2.2.12. METHOD	000
2.2.13. Inheritance	000
I. Appendixes	000
A. GNU General Public License	000
B. GNU Free Documentation License	000

List of Tables
1-1. Module Structure	000

Chapter 1. GNUe Module Proposal
1.1. Introduction
 
1.1.1. What is this document intended for?
This document shows some of the ideas I would suggest for Gnu Enterprise and I would like to have them discussed. 
I plan to take other concepts discussed in the mailing list (and widely accepted) into this document, so that maybe this document will somewhen be merged together with others (e.g. An Introduction for Developers from James S. Thompson) and become the Gnu Enterprise Module Writer's Guide. 
Comments about what should be changed in this document (and what is even missing) are very appreciated, because every comment possibly reflects on future versions of this document and therefore will make the final document better. 
1.1.2. General Structure of GNUe Modules
Generally speaking, all GNUe Modules share the following structure: (note that this drawing shows the parts a GNUe Module consists of, not the way how these parts interact with each other) 
+--------------------+-----------+
!                    !           !
!    Components      !           !
!                    !           !
+--------------------+  Reports  !
!                    !           !
!  Business Objects  !           !
!                    !           !
+--------------------+-----------+
!                                !
!        Table Definitions       !
!                                !
+--------------------------------+
  
Table 1-1. Module Structure
 Table Definitions 	In GNUe, Data is held mainly in a RDBMS. Each module that will bring new persistent data into the system will probably add some table definitions by defining new tables and/or adding columns to existing tables. Of course it is possible to have modules not expanding table definitions, although that would be rather unlikely. 	
 Business Objects 	Most modules will add business objects; this is the part where the business logic lies. Business objects do not necessarily represent (or encapsulate) underlying data structures; there could also be business objects only providing some functionality in between other objects, e.g. generating purchase orders out of analyzing current stock and past sales figures (correct me: or would that be an application?). 	
 Components 	Components can provide an interface between the business objects and the user or even other processes and programs. Also Forms and other necessary items are considered components. A module can be one giant component or several components. (This really needs to be better explained. :)) (Derek: I agree :) - Reinhard) 	
 Reports 	Generating reports from the underlying data is done using GNUe Reports. First versions of GNUe Reports will probably take their data directly out of the database. However, there are plans to make GNUe Reports communicate with the business objects / GEDI instead of directly with the database. 	

1.2. Table Design
In GNUe, all the installed modules will store their data in one database. The following conventions should be considered when table definitions are designed. 
You should note that most of the GNUe design will be accomplished by the design of business objects. This section really refers to GEAS and how GEAS handles the back end databases. For designing business objects see the next chapter.
1.2.1. Naming Conventions
Every GNUe module can add new tables as well as add new columns to existing tables. So it has to be made sure that not two modules use the same name for two different tables, and that not two modules use the same column name in a table for two different purposes. 
Another purpose for naming conventions is to make it easy for users to recognize intuitively the meaning of the different columns and tables. 
I would suggest the following naming conventions for tables that are newly created by the module: 
•	Every table name consists of a module-name, an underline symbol, and a meaningful class name. The module-name is the same for all new tables a module defines. 
•	The module-name should be 3 characters or longer, where big and widely-used modules should have shorter names and small and seldom used modules can have longer names. 
To ensure uniqueness of module prefixes, they should be coordinated by some central authority at least for standard and extended modules. 
•	Modules that belong together somehow should show their relationship by using prefixes with the first some letters being the same. 
•	The meaningful name should conventionally be singular rather than plural. 
The naming conventions for columns would be: 
•	Columns of a table belonging to the module should have a simple column name. The module-prefix need not be used for such columns. 
•	Columns a module adds to a table belonging to another module must be prefixed by the module-prefix. This is the same prefix that is used for table names. 
•	Column names should be understandable (consider the rules for naming variables in the Gnu Coding Standards). Columns of different tables with the same meaning should have the same name. 
The following examples should make things clearer: 
One of the base modules could be a customer management module, used in the G/L as well as for sales order processing or for CRM. This module would probably choose cus as it's module-prefix. 
So, according to the above conventions, the customer table would be named cus_customer, and the name of the customer would be cus_customer.name. 
Another widely used module would be the sales order processing module, maybe choosing the prefix sop. The sales order table would be named sop_order and could be easily distinguished from the purchase order tables pop_order of the purchase order processing module pop. The terms of payment for this order would be saved in a column named sop_order.payment. 
If the designer of the sales order processing module would choose to extend the customer table to store the default terms of payment for a given customer, the resulting column would be named cus_customer.sop_payment. Thus, this column can be easily identified as being a ``cuckoo's egg''. 
Another module, the famous local car dealer's ``favorite car module'' would not add any table at all, but only extend the cus_customer table by the column cus_customer.favcar_favorite. 
1.2.2. Package Names
Eventually packages will be used to select parts of GNUe for distribution and use. Currently packages names are only used in the cvs heirachy to group modules. 
It should also be noted that the base level of granularity for the GNUe system is modules. Any module can be installed individually. 
The following package names should be used: 
•	 supply_chain - Supply chain, distribution, purchasing, inventory. 
•	 base - Common to all modules. 
•	 sales - Traditional sales and order entry. 
•	 e_comm - Electronic commerce, EDI, and web sales. 
•	 crm - Customer relations management. 
•	 mfg - Manufacturing. 
•	 fin - Finance and accounting. (recent change) 
•	 hr - Human Relations. 
•	 prj - Project Management. 
•	 budget - Budget Management. 
•	 r_d - Research and Development. 
•	 facilities - Facilities Management. 
•	 eng - Engineering 
1.2.3. Data Modeling Rules
Understanding the data model is a very basic thing for understanding a module. In order to make the data model more understandable for others, some general guidelines should be agreed upon and followed. 
(Remark: I know that none of the following topics is new or revolutionary, but that rather all of them have somehow been implemented yet. The point would be that we would use these structure consistently.) 
I would divide the tables of a data model into the following classes: 
1.2.3.1. Base Tables
These tables are typically common or used with many modules. The base tables are created from base business objects which are currently found in the base package in cvs. 
Examples include: 
•	item - only the base item fields, as the modules may also have a sales_item and a stock_item. 
•	units of measure 
•	currency 
•	people 
•	locations 
•	etc 
These tables contain rather static information. No usual transaction should result in any change in such a table.
Most of the information stored in these tables is entered directly by the user.
These tables are typically introduced by some modules and occasionally extended by some columns in other modules. In some cases the business objects are not tables at all, but are used as generic definitions that are included in other business objects. See Chapter 2 inheritance and EXTEND keywords. 
1.2.3.2. Auxiliary Tables
 Auxiliary tables are those tables giving meaning to codes, which can range from just expanding a shortcut into some longer text to providing information about how to process transactions depending on the code. 
 Some examples: 
•	expanding territory codes to their full, human-understandable meaning, e.g. E12a to Northern Europe. 
•	expanding a warehouse code into the full address of the warehouse. 
•	providing taxation information per item tax code. 
Auxiliary tables are probably the most static tables of the whole system. They are maintained only by the user. No change in a table of this type may be done auto magically by the system.
Some proprietary systems use a single table for all code-to-meaning-expansions, providing a column in this table telling what type of code is expanded. We don't do this in GNUe, because it may come that for some code we will need additional columns. Very many tables have started as code/meaning-tables and have grown. Instead, GNUe uses a separate table for each type of code.
Something very related to auxiliary tables are matrix tables. They store static, user-provided information depending on two or more codes and/or base table ID's.
Examples for matrix tables are
•	accounting information per item accounting code and customer accounting code 
•	special prices per item and customer 
•	discount per customer and item discount code @end itemize 
1.2.3.3. Document Tables
These tables store the business documents. There is typically some master/detail-relationship in these tables; sometimes a rather complex one. 
Some modules include more than one document type (each of them consisting of several tables).
Examples include:
•	GNUe Inventory would provide some document for shifting goods from one storeroom to another and for changing stock without using sales/purchase order processing. 
•	GNUe Sales would possibly follow the line: offer -> sales order -> bill of material -> invoice 
Document tables are filled by the user through the corresponding business object.
Some documents result in a transaction (e.g. a bill of material does, an offer does not). These transaction should take place as soon as the document is entered or generated, even if it is not printed out immediately. The record of the generated transaction log entry should be addressable out of the document table, so that the transaction log entry can be deleted when the document is reversed. Transaction logs are discussed in Transaction Log Tables. 
1.2.3.4. Batch Tables
Batch tables should be a convenient way for other modules and/or external systems and/or the user to feed a GNUe module with data.
Batch tables are flat tables without master/detail relationships. There are document batch tables and transaction batch tables.
Document batch tables can be used to easily generate documents without dealing with the complex table structure of the document.
Transaction batch tables are the only way to generate transactions without going the direct way through the business object.
Examples include:
•	sales order batch table, from which sales orders can be generated 
•	G/L batch table, which could be a way for the user to enter data into the G/L module without having booked it immediately. Data would of course be checked while entered. 
 Every batch table has an assigned business object which is able to process a given batch number. For supporting external systems, batch processing should be doable even from command line.
Batch tables typically consist of few columns that must be filled in and more columns that may be filled in, but can also be left empty, so that the system will take standard values.
Using batch tables is an additional possibility to feed data into GNUe modules, complementing the business objects. However, batch tables have some advantages:
•	Document batch tables make it easily possible to feed a number of items to be processed and let the business object decide which items can be combined into one document. 
•	Batch tables can be persistent. Processing of batch tables can be delayed by the user, e.g. to 
•	print the batch and let the boss sign it before it is processed 
•	wait until the batch is big enough to be worth while being processed 
•	save time during the day and process it in the night. 
•	Batch tables can even be used by systems that don't speak CORBA. 
•	You can transfer data in batch tables from one GNUe installation to another without having problems with data integrity. 
By convention, batch table names end in _batch. 
1.2.3.5. Transaction Log Tables
These tables store all information on all the transactions concerning a certain base table. Every base table has a transaction log table assigned.
Transaction log tables are flat (have no master/detail-relationship).
Examples include:
•	stock log stores all transactions where any item's stock has changed 
•	customer log stores all bills, credits and payments 
•	account log of course stores all transactions on a given account 
Records of such a table are neither created nor modified manually by a user, but maintained automatically by the corresponding business objects; mostly generated out of batch tables or document tables.
Transaction log tables usually have many secondary keys as they serve as the base for many reports.
Transaction log tables are by convention named after the corresponding base table suffixed by ``_log''. 
1.2.3.6. Balance Tables
These tables contain information about balances regarding certain dates.
A master/detail-relationship in the base table can be reflected in a master/detail-relationship in the corresponding balance table.
Examples:
•	item balance stores actual stock, reserved stock and available stock for every item per end of each month 
•	stock balance stores the same per storeroom 
•	customer balance stores what the customer owes per end of each month 
•	account balance simply stores the balance of each account per end of each month 
These tables contain 100% redundant information and are never changed by the user. These tables are updated by the system every time a entry in the transaction log table is created, modified or deleted.
The only reason to have these tables is for performance reasons.
For each balance table, the period of creating balances should be configurable by the user.
If GNUe has no bugs, the figures in the balance table must at every moment be identical to the sum of all entries of the transaction log before the given point in time. Due to this, there will be business objects for every balance table that
•	check whether the sums are still correct and 
•	correct the balances according to the transaction log or maybe even 
•	generate an entry in the transaction log to make it fit the balance. 
By convention, balance tables are named like the corresponding base tables and suffixed by _bal. 
1.2.4. Data Types
Using the same data types for the same purpose consistently makes it easy for the modules to communicate with each other, and for the maintainers to learn into another module.
Use of the following data types would be recommended: 
1.2.4.1. Primary Keys
Primary Keys of a table should never be user-visible and may not have any other meaning than to provide a unique identification of a specific row.
All tables will have a user-visible, meaningful key, which may consist of one or more columns, and which will not be the primary key.
Batch tables, as they may be filled by the user or by external systems, should provide the possibility to choose between filling in the primary key or the user-visible key.
All other tables must reference the primary key to make all user-visible data changeable.
For the generation of primary keys, we will not use auto increment features of the database, as different database back ends implement that very differently or maybe even not at all. We will rather use 64-bit-integer values for primary keys and have seed tables, where the last used value per table is stored. There are very strong plans about implementing this in GEDI and have the business layer see ``virtual auto increment fields'', so a module writer doesn't have to know about this at all. (I wonder, why I write this here, anyway). 
1.2.4.2. Money
Money is now defined as a base object in the currency module. It is defined as a 64 bit integer with an implied decimal point. So if the integer value was = 1234567 and the implied decimal point was 3, the actual amount of money representated will be 1234.567. Also a currency must be defined for all money objects. In a single currency system the default currency should make this transparent to the casual user. 
1.2.4.3. Quantity
Quantity is now defined as a base object in the unit module. Like currency, a quantity is defined with a 64 bit integer, an implied decimal point and a unit of measure. If the unit of measure is "each" then "each" must be defined in the unit object of the unit module. 
1.2.4.4. Codes
Codes (that means the user-visible key to auxiliary tables) will be char<8> consistently, which will enable the user to make the codes meaningful and easy to remember. 
1.2.5. Storing Redundant Data
Redundant data is stored in the database if and only if performance can be won, >i.e. if a large (in most cases undetermined) count of database rows would have to be processed to come to the result.
Sums and balances are a typical case of redundant data which is stored in the database, e.g. grand total value of an invoice, or all balance tables.
Redundant data which can easily be calculated out of a known low number of database rows (in most cases one, or one result row of some joined tables) will not be stored in the database but will be provided by the middle tier business objects. Typical examples include total of an invoice item (which calculates from quantity x price - discount), or stock available when we have stock total and stock reserved.
For every redundant data stored in the database, the corresponding business object must have a method to check whether the redundant data is consistent and to adjust inconsistent data if desired. 
1.3. Form Design
This section will be added later. Feel free to send proposals. 
1.4. Report Design
This section will be added later. Feel free to send proposals. 

Chapter 2. GNUe Business Objects 
2.1. Introduction
 This chapter is $Id: main.rtf,v 1.1 2003/01/05 00:00:26 psu_gnue Exp $. 
 Quick links to the various sections. 
                   Business Objects
                        Coding Conventions
                        Comments
                        EXTEND
                        Fields
                        Include
                        LINK CONTENT ENDTERM 'ORDERBY.TITLE' MISSING
                        Inheritance
                        LIST
                        LOOKUP
                        METHOD
                        MODULES and CLASSES
                        Naming Conventions
                        REFERENCE
                        TYPE (Complex Fields)
                        TYPE (Typedef) (NOT IMPLEMENTED YET)
        
2.1.1. Business Objects
 Comments about what should be changed in this document (and what is even missing) are very appreciated, because every comment possibly reflects on future versions of this document and therefore will make the final document better. Please direct your comments to Neil Tiffin (neilt@gnue.org). 
This chapter was originally written by Neil Tiffin (neilt@gnue.org) and comes from documents and code originally written by Andrew Murie (andrewm@gnue.org) and coding standard from Reinhard Müller(reinhard@gnue.org). Some examples contributed by Stanley A. Klein. 
 GNUe business objects are defined in GNUe Class Files (GCD). These files have the extension ".gcd". This chapter discusses the format of GCD files. Business objects are processed by the GEAS server. If you are using GNUe Forms in 2-tier mode then things work a little differently. 
 This document contains only definitions that are implemented in geas now or noted specifically as not implemented. Names in CAPITALS are literal words for the purpose of this document. More technical information may be present in the geas document directory in cvs. 
2.1.2. Naming Conventions
 All names must start with an alpha character and contain only characters, numbers, and the "_" character. Names may not contain two "_" characters together (e.g "__") and may not end with the "_" character. 
 The GCD syntax does not care about upper or lower case so all names should be written in lower case. 
 Words in names should be separated by a single "_" character. 
2.1.3. Coding Conventions
	1.	 All words, reserved words (class, module...) as well as identifiers (person, given_names...) are written all in lowercase, because lowercase is easier to write.  
	2.	 Class definitions start at column 1, and the "{" is on its own line. This will probably enable some emacs magic (we would have to adapt the c-mode a little bit for ignoring the "module"-line). Would need an emacs expert for that.  
	3.	 The first line of all files is blank. This is required because docbook may not start a new line when including the file in the documentation.  
	4.	 Lines are wrapped at 72 characters. Docbook will automatically wrap the lines and it does not look right.  
	5.	 Use 2 character indenting, as this is GNU standard.  
	6.	 The "*" is after the whitespace, just like normal c coding style.  
	7.	 Beginning of all identifiers are in line for each class ("person" and "*type" start at the same column).  
	8.	 Don't duplicate the module name in a class. That means that we don't use class names like "person_type" in a module "person", but we user rather "type". Module "person", class "person" and field "person" is ok.  
	9.	 Don't duplicate the class name in a field. Don't use "type_code" as a fieldname in a class "type", but we use just "code". Module "person", class "person" and field "person" is ok.  
	10.	 Every file should have a second line that contains the filename and a short (one-line) explanation what this module is for. The filename should utilize the cvs keyword substitution string. For example: "# $RCSfile: main.rtf,v $ - then the one line description of the file."  
	11.	 Every type, class and extend definition should be preceded by a one-line comment that tells what this type/class is for. I am a fan of having such comments surrounded by lines.  
	12.	 Module names and class names are always singular. It is hell to remember whether the class is called "phones_numbers", "phone_numbers", "phones_number" or "phone_number".  
	13.	 Field names are always singular, except list references are always plural.  
	14.	 Similar fields in different classes should have the same field name. If names are like employee::surname, customer::last_name, and supplier::lastname, this will drive every consultant crazy :)  
	15.	 Types should be generic types (type code_t = char<8>;) rather than specific types (type person_code_type).  
 An example:

module person
{

  # -------------------------------------------
  # common definitions for persons
  # -------------------------------------------
  type person
  {
    char surname<35>;
    char given_names<35>;
  };
  
  # -------------------------------------------
  # types of persons
  # -------------------------------------------
  class type
  {
    char code<8>;
    char description<35>;
  };
  
  # -------------------------------------------
  # employees
  # -------------------------------------------
  class employee
  {
    person::person *person;
    person::type   *type;
  };

}; # end of module

2.2. GNUe Class Files
2.2.1. MODULES and CLASSES
 A business object is defined using classes. Each class belongs to a module. If "MODULE module_name" is not specified then the class belongs to the "global" module. (e.g classes outside of a formal MODULE specification are assumed to be in the "MODULE global".) The basic format for this definition is: 

  MODULE module_name
  {
    CLASS class_name
    {
      # class body goes here.
    };
  };

Where:
    module_name - the name of the module (or name space).
    class_name - the name of the class (or business object).

 To reference a class in a different module or from a different class in the same module you must use the fully qualified name syntax: 

    module_name::class_name

 In each class GEAS automatically includes a unique 128 bit object identifier called objectid, which is stored as a char<32>. So in the previous example, the first field is module_name::class_name.objectid.
2.2.2. EXTEND
A class may be extended by using the EXTEND keyword. EXTEND allows a module to add to the definition of an existing class. The syntax is exactly like a class definition:
    EXTEND fully_qualified_class_name
    {

    };
For example an existing class item might be defined in the base module as:

    MODULE base
    {
      CLASS item
      {
        char   description<35>;
      };
    };

And in the supply chain module we might want to add stock information ot it. So we would define:

  EXTEND base::item
  {
    int   quantity_on_hand;
  };
    
Note that the extend defintion exists outside of any module definition even if it is defined inside a module definition. This produces the same results as if it had been originally defined as:

    MODULE base
    {
      CLASS item {
        char   description<35>;
        int   quantity_on_hand;
      };
    };

This should not be confused with inheritance which produces two tables when processed by geas.
2.2.3. Fields
 Within a class fields and methods may be defined. A field is defined with the following format: 

Syntax:
    type  field_name<size> = default_value NOT NULL;

Where:
•	 field_name - is the field name. 
•	 type - is one of INT, INT16, INT32, INT64, TEXT, FLOAT, DATE, TIME, DATETIME or CHAR. 
•	 size - is the length for TEXT and CHAR fields. 
•	 default_value - is a value assigned with a new object is created. This is optional. If no default_value then dont include the equal sign. 
•	 NOT NULL - specifies that the field can not be written if the value is null. (not implemented yet) 
Example:

    MODULE example
    {
      CLASS first
      {
        CHAR    street1<25>;
        CHAR    street2<25>;
        CHAR    city<15>;
        CHAR    county<15>;
        CHAR    state_code<8>;
        CHAR    country_code<8>;
        CHAR    postal_code<10>;
        TEXT    my_notes;
        FLOAT   latitude;
        FLOAT   longitude;
        INT     some_int32_number;
        INT16   some_small_number;
        INT32   same_as_int;
        INT64   some_large_number;
        BOOLEAN a_boolean;
        BOOL    another_boolean;
        DATE    today;
        TIME    now;
      };
    };

 Note: TEXT and CHAR fields should not be confused with SQL field types. They are GEAS field types and are mapped to the best type depending on the back end database. (For PostgreSQL they are both VARCHAR).
 Note: Field names may not start with "sys_". These field names are reserved for use by GEAS. For example, GEAS will automatically insert the fields sys_id, sys_cre_user, sys_cre_time, sys_mod_user, and sys_mod_time for object uuid, user name that created object, date/time object created, user name that last modified object, and date/time object last modified respectively.
 TEXT - fields do not have a size attribute. They take up the amount of space actually required. That may be 1000 in one record and 100 in the next record for the same field. TEXT fields can not be searched. 
 CHAR - fields have a maximum size attribute and default to a length of 1 if not specified. Any trailing space (ASCII 32) characters are removed. 
 INT - Integer number currently implemented in 32 bits. 
 INT16 - Integer number currently implemented in 16 bits. 
 INT32 - Integer number currently implemented in 32 bits. 
 INT64 - Integer number currently implemented in 64 bits. 
 DATE - Date formatted for the underlying SQL database.
 TIME - Time formatted for the underlying SQL database.
 BOOL - Boolean 1 or 0. Implemented as SQL boolean value in PostGreSQL and char<1> is MySQL.
 BOOLEAN - Alias for BOOL.
 DATETIME- Is formatted for both date and time as provided for in the SQL database.
2.2.4. TYPE (Complex Fields)
 The TYPE syntax allows the creation of complex types. Complex types can be used in CLASS definitions as shorthand. The syntax essentially the same as CLASS and is:

Syntax:

    TYPE type_name
    {

    };

Example:

    TYPE money
    {
        int  amount;
        char currency<3>;
    };

This allows the following to work:

    CLASS item
    {
        money   cost;
        char    desc<25>;
    };

 This creates the fields item::cost.amount and item::cost.currency. And is roughly the same as doing:

    CLASS item
    {
      int     cost_amount;
      char    cost_currency<25>;
      char    desc<25>;
    };

2.2.5. TYPE (Typedef) (NOT IMPLEMENTED YET)
 The TYPE syntax also allows the specification of general types. The syntax is:

Syntax:
    TYPE new_type = base_type<size>;  (NOT IMPLEMENTED YET)

Where:
    new_type - is the name of the new type.
    
    base_type - is a previously existing type.
    
    size - is the size of the type if necessary.
    
Example:

    TYPE product_code = char<25>;

 This defines a new type called product_code that can be used in class definitions. 

    MODULE inventory
    {
      TYPE product_code = char<25>;
      TYPE product_class = char<8>;
    
      CLASS product
      {
        inventory::product_code  product_id;
        inventory::product_class class;
        char                     description<100>;
      };
    
      CLASS product_classification
      {
        inventory::product_class class;
        char                     description<20>;
      };
    };

 In this example product.class is defined as a char<8> and product.product_id is defined as a char<15>;
 As you can see using TYPE you only have to define the size of a field once and dont have to worry about a mistake in another definition causing a related field to be a different size. 
 To reference types from another module use the fully qualified name. For example:
    inventory::product_code
2.2.6. Comments
 Comments start with the "#" character and continue to the end of the line. 
 For example:
    char   phone_code<4>;    # for validating phone country code
2.2.7. Include
 The include statement is used to reference classes defined outside of the current file. The include path is relative to the current file. If the file has already been included the scanner will not include it a second time.
For example:
    include "../../../base/location/classes/address.gcd"
You may not have more than one file with the same name. Paths do not make files unique to GEAS. Therefore you may not have the following:
    include "../../../base/location/classes/address.gcd"
    include "../../../supply-chain/vendor/classes/address.gcd"
 The second file will never ever get processed.
2.2.8. ORDER BY
Classes can have an 'order by' section, that causes all queries to be sorted on a given field. (er, should have been multiple fields - call that a TODO)
 Syntax: 
   ORDER BY  [DESC];

 Examples: 
class hello
{
    int32 field;
    ORDER BY field;
};

class there
{
    int32 field;
    ORDER BY field DESC;
};

(with the query API - ie, the classes defined in query.idl - the 'DESC' option reverses the sort order.) 
2.2.9. LOOKUP
Use of LOOKUP, REFERENCE, and LIST: We are not really happy with the LOOKUP, REFERENCE and LIST keywords. They make it possible to link tables together with a field that is not the primary key, even with a field that is not guaranteed to have an unique value.
What we would rather like it if geas made it possible to define any field of an object explicitely as the primary key of the table, and that all references would use _that_ field for the foreign key. Only if no field was explicitely defined as primary key, geas would create the implicite objectid. But that's way ahead.
Meanwhile we expect that the usage of the LOOKUP, REFERENCE and LIST syntax will be depreciated.
Apart from that, we will in most cases use the objectid as the primary key; we have discussed that in detail some time ago and widely agreed on not having user-visible primary keys.
 The lookup type is used to lookup a field from another class. A LOOKUP can be defined where a field is defined in the class definition.
Syntax:

    LOOKUP new_fld_name : src_class(src_fld).src_data = comp_field;

Where:
    new_fld_name - is the new field name for reference in the class. It
         does not result in a table column in the database.
    
    src_class - is the name of the source class used to find the lookup
         data.  If this class is in a different module then is requires
         a fully qualified name.
    
    src_data - is the data that is copied into the new_fld_name.
    
    comp_field - is the field from the current class that is matched.
    
Therefore:
       if src_class.src_fld equal comp_field then
           src_class.src_data is copied into new_fld_name
2.2.10. REFERENCE
Use of LOOKUP, REFERENCE, and LIST: We are not really happy with the LOOKUP, REFERENCE and LIST keywords. They make it possible to link tables together with a field that is not the primary key, even with a field that is not guaranteed to have an unique value.
What we would rather like it if geas made it possible to define any field of an object explicitely as the primary key of the table, and that all references would use _that_ field for the foreign key. Only if no field was explicitely defined as primary key, geas would create the implicite objectid. But that's way ahead.
Meanwhile we expect that the usage of the LOOKUP, REFERENCE and LIST syntax will be depreciated.
Apart from that, we will in most cases use the objectid as the primary key; we have discussed that in detail some time ago and widely agreed on not having user-visible primary keys.
 The explicit reference type is used to get a complete instance of a class object. A REFERENCE can be defined where a field is in the class definition. Its syntax is nearly the same as LOOKUP.
    REFERENCE new_fld_name : src_class(src_field) = comp_field;

 Where:

    new_fld_name - is the new field name for reference in the class. It
         does not result in a table column in the database.
    
    src_class - is the fully qualified name of the source class used to 
         find the lookup data.
         
    src_field - is the field in the src_class used for comparison.
    
    comp_field - is the field from the current class that is matched.

 Therefore:
 The new_fld_name is a reference to an object instance where src_fld and comp_field match.
 In the following example, order2 represents an explicit REFERENCE and order1 represents an implicit REFERENCE. Each field references the specific instance of the order:master object from the order::detail object. In the case of the implicit REFERENCE (order1) the reference is make by using the objectid of order::master. In the case of the explicit REFERENCE (order2) the field order_number is used to relate the objects. 
MODULE order
{
  class master
  {
    int     order_number;
    char    stuff<20>;
    int     more_stuff;
    char    the_last_stuff<20>; 
  };

class detail
  {
    int       order_number;
    REFERENCE        order2 : order::master(order_number) = this.order_number;
    order::master [] order1;
    int       detail_stuff;
    char      last_detail_stuff;
  };
};

 REFERENCE is used to implement many to one relationships. A short hand way to create a REFERENCE is to use the following syntax:

    src_module::src_class *new_fld_name;
    
This is a shortcut for:

    REFERENCE new_fld_name : src_module::src_class(id) = other_new_fld_name;
    
Where id and other_new_fld_name are fields that are used and maintained automatically by geas.
 To make this work in theory, you're supposed to programmatically use container.setReference(fieldname,object) and container.getReference(fieldname) from the client code and let GEAS handle the reference automatically.
2.2.11. LIST
Use of LOOKUP, REFERENCE, and LIST: We are not really happy with the LOOKUP, REFERENCE and LIST keywords. They make it possible to link tables together with a field that is not the primary key, even with a field that is not guaranteed to have an unique value.
What we would rather like it if geas made it possible to define any field of an object explicitely as the primary key of the table, and that all references would use _that_ field for the foreign key. Only if no field was explicitely defined as primary key, geas would create the implicite objectid. But that's way ahead.
Meanwhile we expect that the usage of the LOOKUP, REFERENCE and LIST syntax will be depreciated.
Apart from that, we will in most cases use the objectid as the primary key; we have discussed that in detail some time ago and widely agreed on not having user-visible primary keys.
 The LIST type is used to get multiple instances of a class object. A LIST can be defined where a field is defined in the class definition. Its syntax is nearly the same as LOOKUP.

    LIST new_fld_name : src_class(src_field) = comp_field;

Where:
    new_fld_name - is the new field name for reference in the class. It
         does not result in a table column in the database.
    
    src_class - is the name of the source class used to find the lookup
         data.  If this class is in a different module then is requires
         a fully qualified name.
    
    src_field - is the field in the src_class used for comparison.

    comp_field - is the field from the current class that is matched.

Therefore:
    The new_fld_name is a reference to an object instance where src_fld and
    comp_field match.

 List is typically used to create one to many relationships (master-detail). Many to many relationships require an intermediate class. A short hand way to create a LIST is to use the following syntax:
        
    src_class [] new_fld_name;

This is a shortcut for:

    LIST new_fld_name : src_module::src_class(id) = other_new_fld_name;
    
Where id and other_new_fld_name are fields that are used and maintained automatically by geas.
 To make this work in theory, you're supposed to programmatically use container.setReference(fieldname,object) and container.getReference(fieldname) from the client code and let GEAS handle the reference automatically.
 In the following example, detail1 represents an explicit LIST and detail2 represents an implicit LIST. Each field references the specific instances of the order:detail objects from the order::master object. In the case of the implicit LIST reference (detail2) the reference is make by using the objectid's of order::detail. In the case of the explicit LIST reference (detail1) the field order_number is used to relate the objects. 
MODULE order
{
  class master
  {
    int               order_number;
    LIST              detail1 : order::detail(order_number) = this.order_number;
    order::detail  [] detail2;
  }; 

class detail
  {
    int       order_number;
    int       detail_stuff;
    char      last_detail_stuff;
  };
};

2.2.12. METHOD
 Methods allow a call to C or Python code. A method can be defined where a field is defined in the class definition. Its syntax is:

    return_type method_name(arg_type arg_name);
    
 Where:

    return_type - the type (CHAR, INT, FLOAT) of the returned value, 
        if any.  The only type currently working is CHAR.
    method_name - the method name.
    arg_type - the type of the argument.  See caveat below.
    arg_name - the argument name.
    
 Caveat - the only type passed to C or Python is string type. So your method code will have to do conversions as necessary. 
Example: 

    class test
    {
      char callme( int a , int b );
    };

 Python Example

    import string

    def test_callme(obj,a,b,server):
        print "callme called"
        print "this.name = " + obj.getField("name")
        return obj.getField("name")

 C Example:

    #include <glib.h>
    #include <gmodule.h>
    #include <stdio.h>
    #include "../../../src/geas.h"
    #include "../../../src/exceptions.h"

    G_MODULE_EXPORT char *
    test_callme( GEAS_DataObject obj , GEAS_Arguments *args ,
                 GEAS_Connection server , CORBA_Environment *ev )
    {
       /* concatenate arguments using g_strdup_printf */
       CORBA_char *retval;
       char *tmp = g_strdup_printf( "%s:%s" , args->_buffer[0] , args->_buffer[1] );

       retval = CORBA_string_dup( tmp ); // must use CORBA_string_dup for return vlaues
       g_free( tmp ); 

       return( retval );
    }

2.2.13. Inheritance
 Classes can inherit from parent classes. The syntax is:

    CLASS class_name : parent1_class, parent2_class
    {

    };

CLASS example:

    CLASS item
    {
      char  desc<25>;
    };
    
    CLASS stock_item
    {
      int quantity_on_hand;
    };
    
    CLASS sales_item : item, stock_item
    {
      float  price;
    };

 TYPE example

    TYPE item
    {
      char  desc<25>;
    };
    
    TYPE stock_item
    {
      int quantity_on_hand;
    };
    
    TYPE sales_item : item, stock_item
    {
      float  price;
    };

 Where:
    item - is a parent of sales_item.
    
    stock_item - is a parent of sales_item.
 Inheritance works for both CLASS or TYPE, but you can not mix them.
 The field sales_item.desc is the description inherited from class item and sales_item.quantity_on_hand is inherited from class stock_item. Of course you can still refer directly to the parent class as item.desc or stock_item.quantity_on_hand.
 If a field name is used more than once in parent and child classes then geas will die a slow and terrible death. (Hopefully this will be fixed soon.)

I. Appendixes

Appendix A. GNU General Public License 
                    GNU GENERAL PUBLIC LICENSE
                       Version 2, June 1991

 Copyright (C) 1989, 1991 Free Software Foundation, Inc.
                       59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

                            Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

  When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it
in new free programs; and that you know you can do these things.

  To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

  For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

  We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

  Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

  Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

  The precise terms and conditions for copying, distribution and
modification follow.

                    GNU GENERAL PUBLIC LICENSE
   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  0. This License applies to any program or other work which contains
a notice placed by the copyright holder saying it may be distributed
under the terms of this General Public License.  The "Program", below,
refers to any such program or work, and a "work based on the Program"
means either the Program or any derivative work under copyright law:
that is to say, a work containing the Program or a portion of it,
either verbatim or with modifications and/or translated into another
language.  (Hereinafter, translation is included without limitation in
the term "modification".)  Each licensee is addressed as "you".

Activities other than copying, distribution and modification are not
covered by this License; they are outside its scope.  The act of
running the Program is not restricted, and the output from the Program
is covered only if its contents constitute a work based on the
Program (independent of having been made by running the Program).
Whether that is true depends on what the Program does.

  1. You may copy and distribute verbatim copies of the Program's
source code as you receive it, in any medium, provided that you
conspicuously and appropriately publish on each copy an appropriate
copyright notice and disclaimer of warranty; keep intact all the
notices that refer to this License and to the absence of any warranty;
and give any other recipients of the Program a copy of this License
along with the Program.

You may charge a fee for the physical act of transferring a copy, and
you may at your option offer warranty protection in exchange for a fee.

  2. You may modify your copy or copies of the Program or any portion
of it, thus forming a work based on the Program, and copy and
distribute such modifications or work under the terms of Section 1
above, provided that you also meet all of these conditions:

    a) You must cause the modified files to carry prominent notices
    stating that you changed the files and the date of any change.

    b) You must cause any work that you distribute or publish, that in
    whole or in part contains or is derived from the Program or any
    part thereof, to be licensed as a whole at no charge to all third
    parties under the terms of this License.

    c) If the modified program normally reads commands interactively
    when run, you must cause it, when started running for such
    interactive use in the most ordinary way, to print or display an
    announcement including an appropriate copyright notice and a
    notice that there is no warranty (or else, saying that you provide
    a warranty) and that users may redistribute the program under
    these conditions, and telling the user how to view a copy of this
    License.  (Exception: if the Program itself is interactive but
    does not normally print such an announcement, your work based on
    the Program is not required to print an announcement.)

These requirements apply to the modified work as a whole.  If
identifiable sections of that work are not derived from the Program,
and can be reasonably considered independent and separate works in
themselves, then this License, and its terms, do not apply to those
sections when you distribute them as separate works.  But when you
distribute the same sections as part of a whole which is a work based
on the Program, the distribution of the whole must be on the terms of
this License, whose permissions for other licensees extend to the
entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest
your rights to work written entirely by you; rather, the intent is to
exercise the right to control the distribution of derivative or
collective works based on the Program.

In addition, mere aggregation of another work not based on the Program
with the Program (or with a work based on the Program) on a volume of
a storage or distribution medium does not bring the other work under
the scope of this License.

  3. You may copy and distribute the Program (or a work based on it,
under Section 2) in object code or executable form under the terms of
Sections 1 and 2 above provided that you also do one of the following:

    a) Accompany it with the complete corresponding machine-readable
    source code, which must be distributed under the terms of Sections
    1 and 2 above on a medium customarily used for software interchange; or,

    b) Accompany it with a written offer, valid for at least three
    years, to give any third party, for a charge no more than your
    cost of physically performing source distribution, a complete
    machine-readable copy of the corresponding source code, to be
    distributed under the terms of Sections 1 and 2 above on a medium
    customarily used for software interchange; or,

    c) Accompany it with the information you received as to the offer
    to distribute corresponding source code.  (This alternative is
    allowed only for noncommercial distribution and only if you
    received the program in object code or executable form with such
    an offer, in accord with Subsection b above.)

The source code for a work means the preferred form of the work for
making modifications to it.  For an executable work, complete source
code means all the source code for all modules it contains, plus any
associated interface definition files, plus the scripts used to
control compilation and installation of the executable.  However, as a
special exception, the source code distributed need not include
anything that is normally distributed (in either source or binary
form) with the major components (compiler, kernel, and so on) of the
operating system on which the executable runs, unless that component
itself accompanies the executable.

If distribution of executable or object code is made by offering
access to copy from a designated place, then offering equivalent
access to copy the source code from the same place counts as
distribution of the source code, even though third parties are not
compelled to copy the source along with the object code.

  4. You may not copy, modify, sublicense, or distribute the Program
except as expressly provided under this License.  Any attempt
otherwise to copy, modify, sublicense or distribute the Program is
void, and will automatically terminate your rights under this License.
However, parties who have received copies, or rights, from you under
this License will not have their licenses terminated so long as such
parties remain in full compliance.

  5. You are not required to accept this License, since you have not
signed it.  However, nothing else grants you permission to modify or
distribute the Program or its derivative works.  These actions are
prohibited by law if you do not accept this License.  Therefore, by
modifying or distributing the Program (or any work based on the
Program), you indicate your acceptance of this License to do so, and
all its terms and conditions for copying, distributing or modifying
the Program or works based on it.

  6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the
original licensor to copy, distribute or modify the Program subject to
these terms and conditions.  You may not impose any further
restrictions on the recipients' exercise of the rights granted herein.
You are not responsible for enforcing compliance by third parties to
this License.

  7. If, as a consequence of a court judgment or allegation of patent
infringement or for any other reason (not limited to patent issues),
conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License.  If you cannot
distribute so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you
may not distribute the Program at all.  For example, if a patent
license would not permit royalty-free redistribution of the Program by
all those who receive copies directly or indirectly through you, then
the only way you could satisfy both it and this License would be to
refrain entirely from distribution of the Program.

If any portion of this section is held invalid or unenforceable under
any particular circumstance, the balance of the section is intended to
apply and the section as a whole is intended to apply in other
circumstances.

It is not the purpose of this section to induce you to infringe any
patents or other property right claims or to contest validity of any
such claims; this section has the sole purpose of protecting the
integrity of the free software distribution system, which is
implemented by public license practices.  Many people have made
generous contributions to the wide range of software distributed
through that system in reliance on consistent application of that
system; it is up to the author/donor to decide if he or she is willing
to distribute software through any other system and a licensee cannot
impose that choice.

This section is intended to make thoroughly clear what is believed to
be a consequence of the rest of this License.

  8. If the distribution and/or use of the Program is restricted in
certain countries either by patents or by copyrighted interfaces, the
original copyright holder who places the Program under this License
may add an explicit geographical distribution limitation excluding
those countries, so that distribution is permitted only in or among
countries not thus excluded.  In such case, this License incorporates
the limitation as if written in the body of this License.

  9. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.

Each version is given a distinguishing version number.  If the Program
specifies a version number of this License which applies to it and "any
later version", you have the option of following the terms and conditions
either of that version or of any later version published by the Free
Software Foundation.  If the Program does not specify a version number of
this License, you may choose any version ever published by the Free Software
Foundation.

  10. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission.  For software which is copyrighted by the Free
Software Foundation, write to the Free Software Foundation; we sometimes
make exceptions for this.  Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.

                            NO WARRANTY

  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.

  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.

                     END OF TERMS AND CONDITIONS

            How to Apply These Terms to Your New Programs

  If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

  To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

    -one line to give the program's name and a brief idea of what it does.-
    Copyright (C) 19yy  -name of author-

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:

    Gnomovision version 69, Copyright (C) 19yy name of author
    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
    This is free software, and you are welcome to redistribute it
    under certain conditions; type `show c' for details.

The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License.  Of course, the commands you use may
be called something other than `show w' and `show c'; they could even be
mouse-clicks or menu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary.  Here is a sample; alter the names:

  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
  `Gnomovision' (which makes passes at compilers) written by James Hacker.

  -signature of Ty Coon-, 1 April 1989
  Ty Coon, President of Vice

This General Public License does not permit incorporating your program into
proprietary programs.  If your program is a subroutine library, you may
consider it more useful to permit linking proprietary applications with the
library.  If this is what you want to do, use the GNU Library General
Public License instead of this License.

Appendix B. GNU Free Documentation License 
               GNU Free Documentation License
                   Version 1.1, March 2000

 Copyright (C) 2000  Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 Everyone is permitted to copy and distribute verbatim copies
 of this license document, but changing it is not allowed.

0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other
written document "free" in the sense of freedom: to assure everyone
the effective freedom to copy and redistribute it, with or without
modifying it, either commercially or noncommercially.  Secondarily,
this License preserves for the author and publisher a way to get
credit for their work, while not being considered responsible for
modifications made by others.

This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense.  It
complements the GNU General Public License, which is a copyleft
license designed for free software.

We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does.  But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book.  We recommend this License
principally for works whose purpose is instruction or reference.

1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be distributed
under the terms of this License.  The "Document", below, refers to any
such manual or work.  Any member of the public is a licensee, and is
addressed as "you".

A "Modified Version" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject.  (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.)  The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.

The "Invariant Sections" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License.

The "Cover Texts" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License.

A "Transparent" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, whose contents can be viewed and edited directly and
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters.  A copy made in an otherwise Transparent file
format whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent.  A copy that is
not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML designed for human modification.  Opaque formats include
PostScript, PDF, proprietary formats that can be read and edited only
by proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML produced by some word processors for output
purposes only.

The "Title Page" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page.  For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.

2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License.  You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute.  However, you may accept
compensation in exchange for copies.  If you distribute a large enough
number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and
you may publicly display copies.

3. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100,
and the Document's license notice requires Cover Texts, you must enclose
the copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover.  Both covers must also clearly and legibly identify
you as the publisher of these copies.  The front cover must present
the full title with all words of the title equally prominent and
visible.  You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.

If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a publicly-accessible computer-network location containing a complete
Transparent copy of the Document, free of added material, which the
general network-using public has access to download anonymously at no
charge using public-standard network protocols.  If you use the latter
option, you must take reasonably prudent steps, when you begin
distribution of Opaque copies in quantity, to ensure that this
Transparent copy will remain thus accessible at the stated location
until at least one year after the last time you distribute an Opaque
copy (directly or through your agents or retailers) of that edition to
the public.

It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.

4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it.  In addition, you must do these things in the Modified Version:

A. Use in the Title Page (and on the covers, if any) a title distinct
   from that of the Document, and from those of previous versions
   (which should, if there were any, be listed in the History section
   of the Document).  You may use the same title as a previous version
   if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
   responsible for authorship of the modifications in the Modified
   Version, together with at least five of the principal authors of the
   Document (all of its principal authors, if it has less than five).
C. State on the Title page the name of the publisher of the
   Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
   adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
   giving the public permission to use the Modified Version under the
   terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
   and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section entitled "History", and its title, and add to
   it an item stating at least the title, year, new authors, and
   publisher of the Modified Version as given on the Title Page.  If
   there is no section entitled "History" in the Document, create one
   stating the title, year, authors, and publisher of the Document as
   given on its Title Page, then add an item describing the Modified
   Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
   public access to a Transparent copy of the Document, and likewise
   the network locations given in the Document for previous versions
   it was based on.  These may be placed in the "History" section.
   You may omit a network location for a work that was published at
   least four years before the Document itself, or if the original
   publisher of the version it refers to gives permission.
K. In any section entitled "Acknowledgements" or "Dedications",
   preserve the section's title, and preserve in the section all the
   substance and tone of each of the contributor acknowledgements
   and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
   unaltered in their text and in their titles.  Section numbers
   or the equivalent are not considered part of the section titles.
M. Delete any section entitled "Endorsements".  Such a section
   may not be included in the Modified Version.
N. Do not retitle any existing section as "Endorsements"
   or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant.  To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.

You may add a section entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.

You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version.  Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity.  If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.

5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice.

The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy.  If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled "History"
in the various original documents, forming one section entitled
"History"; likewise combine any sections entitled "Acknowledgements",
and any sections entitled "Dedications".  You must delete all sections
entitled "Endorsements."

6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.

7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, does not as a whole count as a Modified Version
of the Document, provided no compilation copyright is claimed for the
compilation.  Such a compilation is called an "aggregate", and this
License does not apply to the other self-contained works thus compiled
with the Document, on account of their being thus compiled, if they
are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one quarter
of the entire aggregate, the Document's Cover Texts may be placed on
covers that surround only the Document within the aggregate.
Otherwise they must appear on covers around the whole aggregate.

8. TRANSLATION

Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections.  You may include a
translation of this License provided that you also include the
original English version of this License.  In case of a disagreement
between the translation and the original English version of this
License, the original English version will prevail.

9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License.  Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License.  However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.

10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time.  Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http:///www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation.  If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:

      Copyright (c)  YEAR  YOUR NAME.
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with the Invariant Sections being LIST THEIR TITLES, with the
      Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
      A copy of the license is included in the section entitled "GNU
      Free Documentation License".

If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no
Front-Cover Texts, write "no Front-Cover Texts" instead of
"Front-Cover Texts being LIST"; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.