ChangeLog

2007-02-20  Matthias Klose  <doko@ubuntu.com>

        * doc/Makefile.am: Add rules to build and install man pages
        from texinfo docs.
        * doc/hacking.texinfo doc/tools.texinfo, doc/vmintegration.texinfo:
        Rename, prefix files with "cp-".
        * doc/cp-tools.texinfo: Add markup for man page generation,
        add documentation for command line options for gjar, gjavah,
        gnative2ascii, gorbd, grmid, grmiregistry, gserialver, gtnameserv.
        doc/texi2pod.pl: New, taken from the GCC sources.

ChangeLog.gcj

2007-02-20  Matthias Klose  <doko@ubuntu.com>

        * Merge doc update from classpath HEAD.
        * doc/texi2pod.pl: Not imported.
        * doc/Makefile.am: Use GCC's texi2pod.pl
        * doc/Makefile.in: Regenerate.



git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@122170 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 0 insertions, 1733 deletions

diff --git a/libjava/classpath/doc/hacking.texinfo b/libjava/classpath/doc/hacking.texinfo
deleted file mode 100644
index efb7aa903c0..00000000000
--- a/libjava/classpath/doc/hacking.texinfo
+++ /dev/null
@@ -1,1733 +0,0 @@
-\input texinfo @c -*-texinfo-*-
-
-@c %**start of header
-@setfilename hacking.info
-@settitle GNU Classpath Hacker's Guide
-@c %**end of header
-
-@setchapternewpage off
-
-@ifinfo
-This file contains important information you will need to know if you
-are going to hack on the GNU Classpath project code.
-
-Copyright (C) 1998,1999,2000,2001,2002,2003,2004, 2005 Free Software Foundation, Inc.
-
-@ifnotplaintext
-@dircategory GNU Libraries
-@direntry
-* Classpath Hacking: (hacking).   GNU Classpath Hacker's Guide
-@end direntry
-@end ifnotplaintext
-@end ifinfo
-
-@titlepage
-@title GNU Classpath Hacker's Guide
-@author Aaron M. Renn
-@author Paul N. Fisher
-@author John Keiser
-@author C. Brian Jones
-@author Mark J. Wielaard
-
-@page
-@vskip 0pt plus 1filll
-Copyright @copyright{} 1998,1999,2000,2001,2002,2003,2004 Free Software Foundation, Inc.
-@sp 2
-Permission is granted to make and distribute verbatim copies of
-this document provided the copyright notice and this permission notice
-are preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-document under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that this permission notice may be stated in a translation
-approved by the Free Software Foundation.
-
-@end titlepage
-
-@ifinfo
-@node Top, Introduction, (dir), (dir)
-@top GNU Classpath Hacker's Guide
-
-This document contains important information you'll want to know if
-you want to hack on GNU Classpath, Essential Libraries for Java, to
-help create free core class libraries for use with virtual machines
-and compilers for the java programming language.
-@end ifinfo
-
-@menu
-* Introduction::                An introduction to the GNU Classpath project
-* Requirements::                Very important rules that must be followed
-* Volunteering::                So you want to help out
-* Project Goals::               Goals of the GNU Classpath project
-* Needed Tools and Libraries::  A list of programs and libraries you will need
-* Programming Standards::       Standards to use when writing code
-* Hacking Code::                Working on code, Working with others
-* Programming Goals::           What to consider when writing code
-* API Compatibility::           How to handle serialization and deprecated methods
-* Specification Sources::       Where to find class library specs
-* Naming Conventions::          How files and directories are named
-* Character Conversions::       Working on Character conversions
-* Localization::                How to handle localization/internationalization
-
-@detailmenu
- --- The Detailed Node Listing ---
-
-Programming Standards
-
-* Source Code Style Guide::     
-
-Working on the code, Working with others
-
-* Branches::                    
-* Writing ChangeLogs::          
-
-Working with branches
-
-* Writing ChangeLogs::          
-
-Programming Goals
-
-* Portability::                 Writing Portable Software                
-* Utility Classes::             Reusing Software
-* Robustness::                  Writing Robust Software               
-* Java Efficiency::             Writing Efficient Java            
-* Native Efficiency::           Writing Efficient JNI          
-* Security::                    Writing Secure Software
-
-API Compatibility
-
-* Serialization::               Serialization
-* Deprecated Methods::          Deprecated methods
-
-Localization
-
-* String Collation::            Sorting strings in different locales
-* Break Iteration::             Breaking up text into words, sentences, and lines
-* Date Formatting and Parsing::  Locale specific date handling
-* Decimal/Currency Formatting and Parsing::  Local specific number handling
-
-@end detailmenu
-@end menu
-
-@node Introduction, Requirements, Top, Top
-@comment node-name, next, previous, up
-@chapter Introduction
-
-The GNU Classpath Project is a dedicated to providing a 100% free,
-clean room implementation of the standard core class libraries for
-compilers and runtime environments for the java programming language.
-It offers free software developers an alternative core library
-implementation upon which larger java-like programming environments
-can be build.  The GNU Classpath Project was started in the Spring of
-1998 as an official Free Software Foundation project.  Most of the
-volunteers working on GNU Classpath do so in their spare time, but a
-couple of projects based on GNU Classpath have paid programmers to
-improve the core libraries.  We appreciate everyone's efforts in the
-past to improve and help the project and look forward to future
-contributions by old and new members alike.
-
-@node Requirements, Volunteering, Introduction, Top
-@comment node-name, next, previous, up
-@chapter Requirements
-
-Although GNU Classpath is following an open development model where input
-from developers is welcome, there are certain base requirements that
-need to be met by anyone who wants to contribute code to this project.
-They are mostly dictated by legal requirements and are not arbitrary
-restrictions chosen by the GNU Classpath team.
-
-You will need to adhere to the following things if you want to donate
-code to the GNU Classpath project:
-
-@itemize @bullet
-@item
-@strong{Never under any circumstances refer to proprietary code while
-working on GNU Classpath.}  It is best if you have never looked at
-alternative proprietary core library code at all.  To reduce
-temptation, it would be best if you deleted the @file{src.zip} file
-from your proprietary JDK distribution (note that recent versions of
-GNU Classpath and the compilers and environments build on it are
-mature enough to not need any proprietary implementation at all when
-working on GNU Classpath, except in exceptional cases where you need
-to test compatibility issues pointed out by users).  If you have
-signed Sun's non-disclosure statement, then you unfortunately cannot
-work on Classpath code at all.  If you have any reason to believe that
-your code might be ``tainted'', please say something on the mailing
-list before writing anything.  If it turns out that your code was not
-developed in a clean room environment, we could be very embarrassed
-someday in court.  Please don't let that happen.
-
-@item
-@strong{Never decompile proprietary class library implementations.}  While
-the wording of the license in Sun's Java 2 releases has changed, it is
-not acceptable, under any circumstances, for a person working on
-GNU Classpath to decompile Sun's class libraries.  Allowing the use of
-decompilation in the GNU Classpath project would open up a giant can of
-legal worms, which we wish to avoid.
-
-@item
-Classpath is licensed under the terms of the
-@uref{http://www.fsf.org/copyleft/gpl.html,GNU General Public
-License}, with a special exception included to allow linking with
-non-GPL licensed works as long as no other license would restrict such
-linking.  To preserve freedom for all users and to maintain uniform
-licensing of Classpath, we will not accept code into the main
-distribution that is not licensed under these terms.  The exact
-wording of the license of the current version of GNU Classpath can be
-found online from the
-@uref{http://www.gnu.org/software/classpath/license.html, GNU
-Classpath license page} and is of course distributed with current
-snapshot release from @uref{ftp://ftp.gnu.org/gnu/classpath/} or by
-obtaining a copy of the current CVS tree.
-
-@item
-GNU Classpath is GNU software and this project is being officially sponsored
-by the @uref{http://www.fsf.org/,Free Software Foundation}.  Because of
-this, the FSF will hold copyright to all code developed as part of
-GNU Classpath.  This will allow them to pursue copyright violators in court,
-something an individual developer may neither have the time nor
-resources to do.  Everyone contributing code to GNU Classpath will need to
-sign a copyright assignment statement.  Additionally, if you are
-employed as a programmer, your employer may need to sign a copyright
-waiver disclaiming all interest in the software.  This may sound harsh,
-but unfortunately, it is the only way to ensure that the code you write
-is legally yours to distribute.
-@end itemize
-
-@node Volunteering, Project Goals, Requirements, Top
-@comment node-name, next, previous, up
-@chapter Volunteering to Help
-
-The GNU Classpath project needs volunteers to help us out.  People are
-needed to write unimplemented core packages, to test GNU Classpath on
-free software programs written in the java programming language, to
-test it on various platforms, and to port it to platforms that are
-currently unsupported.
-
-While pretty much all contributions are welcome (but see 
-@pxref{Requirements}) it is always preferable that volunteers do the
-whole job when volunteering for a task.  So when you volunteer to write
-a Java package, please be willing to do the following:
-
-@itemize @bullet
-@item
-Implement a complete drop-in replacement for the particular package.
-That means implementing any ``internal'' classes.  For example, in the
-java.net package, there are non-public classes for implementing sockets.
-Without those classes, the public socket interface is useless.  But do
-not feel obligated to completely implement all of the functionality at
-once.  For example, in the java.net package, there are different types
-of protocol handlers for different types of URL's.  Not all of these
-need to be written at once.
-
-@item
-Please write complete and thorough API documentation comments for
-every public and protected method and variable.  These should be
-superior to Sun's and cover everything about the item being
-documented.
-
-@item
-Please write a regression test package that can be used to run tests
-of your package's functionality.  GNU Classpath uses the
-@uref{http://sources.redhat.com/mauve/,Mauve project} for testing the
-functionality of the core class libraries.  The Classpath Project is
-fast approaching the point in time where all modifications to the
-source code repository will require appropriate test cases in Mauve to
-ensure correctness and prevent regressions.  
-@end itemize
-
-Writing good documentation, tests and fixing bugs should be every
-developer's top priority in order to reach the elusive release of
-version 1.0.
-
-@node Project Goals, Needed Tools and Libraries, Volunteering, Top
-@comment node-name, next, previous, up
-@chapter Project Goals
-
-The goal of the Classpath project is to produce a
-@uref{http://www.fsf.org/philosophy/free-sw.html,free} implementation of
-the standard class library for Java.  However, there are other more
-specific goals as to which platforms should be supported.
-
-Classpath is targeted to support the following operating systems:
-
-@enumerate
-@item
-Free operating systems.  This includes GNU/Linux, GNU/Hurd, and the free
-BSDs.
-
-@item
-Other Unix-like operating systems.
-
-@item
-Platforms which currently have no Java support at all.
-
-@item 
-Other platforms such as MS-Windows.
-@end enumerate
-
-While free operating systems are the top priority, the other priorities
-can shift depending on whether or not there is a volunteer to port
-Classpath to those platforms and to test releases.
-
-Eventually we hope the Classpath will support all JVM's that provide
-JNI or CNI support.  However, the top priority is free JVM's.  A small
-list of Compiler/VM environments that are currently actively
-incorporating GNU Classpath is below.  A more complete overview of
-projects based on GNU classpath can be found online at
-@uref{http://www.gnu.org/software/classpath/stories.html,the GNU
-Classpath stories page}.
-
-@enumerate
-@item
-@uref{http://gcc.gnu.org/java/,GCJ}
-@item 
-@uref{http://jamvm.sourceforge.net/,jamvm}
-@item 
-@uref{http://kissme.sourceforge.net/,Kissme}
-@item
-@uref{http://www.ibm.com/developerworks/oss/jikesrvm/,Jikes RVM}
-@item
-@uref{http://www.sablevm.org/,SableVM}
-@item
-@uref{http://www.kaffe.org/,Kaffe}
-@end enumerate
-
-As with OS platform support, this priority list could change if a
-volunteer comes forward to port, maintain, and test releases for a
-particular JVM.  Since gcj is part of the GNU Compiler Collective it
-is one of the most important targets.  But since it doesn't currently
-work out of the box with GNU Classpath it is currently not the easiest
-target.  When hacking on GNU Classpath the easiest is to use
-compilers and runtime environments that that work out of the box with
-it, such as the jikes compiler and the runtime environments jamvm and
-kissme.  But you can also work directly with targets like gcj and
-kaffe that have their own copy of GNU Classpath currently.  In that
-case changes have to be merged back into GNU Classpath proper though,
-which is sometimes more work.  SableVM is starting to migrate from an
-integrated GNU Classpath version to being usable with GNU Classpath
-out of the box.
-
-
-The initial target version for Classpath is the 1.1 spec.  Higher
-versions can be implemented (and have been implemented, including lots
-of 1.4 functionality) if desired, but please do not create classes
-that depend on features in those packages unless GNU Classpath already
-contains those features.  GNU Classpath has been free of any
-proprietary dependencies for a long time now and we like to keep it
-that way.  But finishing, polishing up, documenting, testing and
-debugging current functionality is of higher priority then adding new
-functionality.
-
-@node Needed Tools and Libraries, Programming Standards, Project Goals, Top
-@comment node-name, next, previous, up
-@chapter Needed Tools and Libraries
-
-If you want to hack on Classpath, you should at least download and
-install the following tools.  And try to familiarize yourself with
-them.  Although in most cases having these tools installed will be all
-you really need to know about them.  Also note that when working on
-(snapshot) releases only GCC 3.3+ (plus a free VM from the list above
-and the libraries listed below) is needed.  The other tools are only
-needed when working directly on the CVS version.
-
-@itemize @bullet
-@item
-GCC 3.3+
-@item
-CVS 1.11+
-@item
-automake 1.7+
-@item
-autoconf 2.59+
-@item
-libtool 1.4.2+
-@item
-GNU m4 1.4
-@item
-texinfo 4.2+
-@end itemize
-
-All of these tools are available from
-@uref{ftp://gnudist.gnu.org/pub/gnu/,gnudist.gnu.org} via anonymous
-ftp, except CVS which is available from
-@uref{http://www.cvshome.org/,www.cvshome.org}.  They are fully
-documented with texinfo manuals.  Texinfo can be browsed with the
-Emacs editor, or with the text editor of your choice, or transformed
-into nicely printable Postscript.
-
-Here is a brief description of the purpose of those tools.
-
-@table @b
-
-@item GCC
-The GNU Compiler Collection. This contains a C compiler (gcc) for
-compiling the native C code and a compiler for the java programming
-language (gcj).  You will need at least gcj version 3.3 or higher.  If
-that version is not available for your platform you can try the
-@uref{http://www.jikes.org/, jikes compiler}.  We try to keep all code
-compilable with both gcj and jikes at all times.
-
-@item CVS  
-A version control system that maintains a centralized Internet
-repository of all code in the Classpath system.
-
-@item automake  
-This tool automatically creates Makefile.in files from Makefile.am
-files.  The Makefile.in is turned into a Makefile by autoconf.  Why
-use this?  Because it automatically generates every makefile target
-you would ever want (clean, install, dist, etc) in full compliance
-with the GNU coding standards.  It also simplifies Makefile creation
-in a number of ways that cannot be described here.  Read the docs for
-more info.
-
-@item autoconf  
-Automatically configures a package for the platform on which it is
-being built and generates the Makefile for that platform.
-
-@item libtool  
-Handles all of the zillions of hairy platform specific options needed
-to build shared libraries.
-
-@item m4
-The free GNU replacement for the standard Unix macro processor.
-Proprietary m4 programs are broken and so GNU m4 is required for
-autoconf to work though knowing a lot about GNU m4 is not required to
-work with autoconf.
-
-@item perl
-Larry Wall's scripting language.  It is used internally by automake.
-
-@item texinfo
-Manuals and documentation (like this guide) are written in texinfo.
-Texinfo is the official documentation format of the GNU project.
-Texinfo uses a single source file to produce output in a number of formats,
-both online and printed (dvi, info, html, xml, etc.). This means that
-instead of writing different documents for online information and another
-for a printed manual, you need write only one document. And when the work
-is revised, you need revise only that one document.
-
-@end table
-
-
-For compiling the native AWT libraries you need to have the following
-libraries installed:
-
-@table @b
-@item GTK+ 2.2.x
-@uref{http://www.gtk.org/,GTK+} is a multi-platform toolkit for
-creating graphical user interfaces.  It is used as the basis of the
-GNU desktop project GNOME.
-
-@item gdk-pixbuf
-@uref{http://www.gnome.org/start/,gdk-pixbuf} is a GNOME library for
-representing images.
-@end table
-
-
-GNU Classpath comes with a couple of libraries included in the source
-that are not part of GNU Classpath proper, but that have been included
-to provide certain needed functionality.  All these external libraries
-should be clearly marked as such.  In general we try to use as much as
-possible the clean upstream versions of these sources.  That way
-merging in new versions will be easiest.  You should always try to get
-bug fixes to these files accepted upstream first.  Currently we
-include the following 'external' libraries.  Most of these sources are
-included in the @file{external} directory.  That directory also
-contains a @file{README} file explaining how to import newer versions.
-
-@table @b
-
-@item GNU jaxp
-Can be found in @file{external/jaxp}.  Provides javax.xml, org.w3c and
-org.xml packages.  Upstream is
-@uref{http://www.gnu.org/software/classpathx/,GNU ClasspathX}.
-
-@item fdlibm
-Can be found in @file{native/fdlibm}.  Provides native implementations
-of some of the Float and Double operations.  Upstream is
-@uref{http://gcc.gnu.org/java/,libgcj}, they sync again with the
-'real' upstream @uref{http://www.netlib.org/fdlibm/readme}.  See also
-java.lang.StrictMath.
-
-@end table
-
-
-@node Programming Standards, Hacking Code, Needed Tools and Libraries, Top
-@comment node-name, next, previous, up
-@chapter Programming Standards
-
-For C source code, follow the
-@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}.
-The standards also specify various things like the install directory
-structure.  These should be followed if possible.
-
-For Java source code, please follow the
-@uref{http://www.gnu.org/prep/standards/,GNU Coding
-Standards}, as much as possible.  There are a number of exceptions to
-the GNU Coding Standards that we make for GNU Classpath as documented
-in this guide.  We will hopefully be providing developers with a code
-formatting tool that closely matches those rules soon.
-
-For API documentation comments, please follow
-@uref{http://java.sun.com/products/jdk/javadoc/writingdoccomments.html,How
-to Write Doc Comments for Javadoc}.  We would like to have a set of
-guidelines more tailored to GNU Classpath as part of this document.
-
-@menu
-* Source Code Style Guide::     
-@end menu
-
-@node Source Code Style Guide,  , Programming Standards, Programming Standards
-@comment node-name, next, previous, up
-@section Java source coding style
-
-Here is a list of some specific rules used when hacking on GNU
-Classpath java source code. We try to follow the standard
-@uref{http://www.gnu.org/prep/standards/,GNU Coding Standards}
-for that. There are lots of tools that can automatically generate it
-(although most tools assume C source, not java source code) and it
-seems as good a standard as any. There are a couple of exceptions and
-specific rules when hacking on GNU Classpath java source code however.
-The following lists how code is formatted (and some other code
-conventions):
-
-
-@itemize @bullet
-
-@item
-Java source files in GNU Classpath are encoded using UTF-8.  However,
-ordinarily it is considered best practice to use the ASCII subset of
-UTF-8 and write non-ASCII characters using \u escapes.
-
-@item
-If possible, generate specific imports (expand) over java.io.* type
-imports. Order by gnu, java, javax, org. There must be one blank line
-between each group. The imports themselves are ordered alphabetically by
-package name. Classes and interfaces occur before sub-packages. The
-classes/interfaces are then also sorted alphabetical. Note that uppercase
-characters occur before lowercase characters.
-
-@example
-import gnu.java.awt.EmbeddedWindow;
-
-import java.io.IOException;
-import java.io.InputStream;
-
-import javax.swing.JFrame;
-@end example
-
-@item
-Blank line after package statement, last import statement, classes,
-interfaces, methods.
-
-@item
-Opening/closing brace for class and method is at the same level of
-indent as the declaration.  All other braces are indented and content
-between braces indented again.
-
-@item
-Since method definitions don't start in column zero anyway (since they
-are always inside a class definition), the rational for easy grepping
-for ``^method_def'' is mostly gone already. Since it is customary for
-almost everybody who writes java source code to put modifiers, return
-value and method name on the same line, we do too.
-
-@c fixme Another rational for always indenting the method definition is that itmakes it a bit easier to distinguish methods in inner and anonymousclasses from code in their enclosing context. NEED EXAMPLE.
-
-@item
-Implements and extends on separate lines, throws too.  Indent extends,
-implements, throws.  Apply deep indentation for method arguments.
-
-@c fixme Needs example.
-
-@item
-Don't add a space between a method or constructor call/definition and
-the open-bracket. This is because often the return value is an object on
-which you want to apply another method or from which you want to access
-a field.
-        
-Don't write:
-
-@example
-  getToolkit ().createWindow (this);
-@end example
-
-But write:
-@example
-  getToolkit().createWindow(this);
-@end example
-
-@item
-The GNU Coding Standard it gives examples for almost every construct
-(if, switch, do, while, etc.).  One missing is the try-catch construct
-which should be formatted as:
-
-@example
-  try
-    @{
-      //
-    @}
-  catch (...)
-    @{
-      //
-    @}
-@end example
-
-@item
-Wrap lines at 80 characters after assignments and before operators.
-Wrap always before extends, implements, throws, and labels.
-
-@item
-Don't put multiple class definitions in the same file, except for
-inner classes. File names (plus .java) and class names should be the
-same.
-
-@item
-Don't catch a @code{NullPointerException} as an alternative to simply
-checking for @code{null}.  It is clearer and usually more efficient
-to simply write an explicit check.
-
-For instance, don't write:
-
-@example
-try
-  @{
-    return foo.doit();
-  @}
-catch (NullPointerException _)
-  @{
-    return 7;
-  @}
-@end example
-
-If your intent above is to check whether @samp{foo} is @code{null},
-instead write:
-
-@example
-if (foo == null)
-  return 7;
-else
-  return foo.doit();
-@end example
-
-@item
-Don't use redundant modifiers or other redundant constructs.  Here is
-some sample code that shows various redundant items in comments:
-
-@example
-/*import java.lang.Integer;*/
-/*abstract*/ interface I @{
-   /*public abstract*/ void m();
-   /*public static final*/ int i = 1;
-   /*public static*/ class Inner @{@}
-@}
-final class C /*extends Object*/ @{
-   /*final*/ void m() @{@}
-@}
-@end example
-
-Note that Jikes will generate warnings for redundant modifiers if you
-use @code{+Predundant-modifiers} on the command line.
-
-@item
-Modifiers should be listed in the standard order recommended by the
-JLS.  Jikes will warn for this when given @code{+Pmodifier-order}.
-
-@item
-Because the output of different compilers differs, we have
-standardized on explicitly specifying @code{serialVersionUID} in
-@code{Serializable} classes in Classpath.  This field should be
-declared as @code{private static final}.  Note that a class may be
-@code{Serializable} without being explicitly marked as such, due to
-inheritance.  For instance, all subclasses of @code{Throwable} need to
-have @code{serialVersionUID} declared.
-@c fixme index
-@c fixme link to the discussion
-
-@item
-Don't declare unchecked exceptions in the @code{throws} clause of a
-method.  However, if throwing an unchecked exception is part of the
-method's API, you should mention it in the Javadoc.  There is one
-important exception to this rule, which is that a stub method should
-be marked as throwing @code{gnu.classpath.NotImplementedException}.
-This will let our API comparison tools note that the method is not
-fully implemented.
-
-@item
-When overriding @code{Object.equals}, remember that @code{instanceof}
-filters out @code{null}, so an explicit check is not needed.
-
-@item
-When catching an exception and rethrowing a new exception you should
-``chain'' the Throwables.  Don't just add the String representation of
-the caught exception.
-
-@example
-  try
-    @{
-      // Some code that can throw
-    @}
-  catch (IOException ioe)
-    @{
-      throw (SQLException) new SQLException("Database corrupt").setCause(ioe);
-    @}
-@end example
-
-@item
-Avoid the use of reserved words for identifiers.  This is obvious with those
-such as @code{if} and @code{while} which have always been part of the Java
-programming language, but you should be careful about accidentally using
-words which have been added in later versions.  Notable examples are
-@code{assert} (added in 1.4) and @code{enum} (added in 1.5).  Jikes will warn
-of the use of the word @code{enum}, but, as it doesn't yet support the 1.5
-version of the language, it will still allow this usage through.  A
-compiler which supports 1.5 (e.g. the Eclipse compiler, ecj) will simply
-fail to compile the offending source code.
-
-@c fixme Describe Anonymous classes (example).
-@c fixme Descibe Naming conventions when different from GNU Coding Standards.
-@c fixme Describee API doc javadoc tags used.
-
-@end itemize
-
-Some things are the same as in the normal GNU Coding Standards:
-
-@itemize @bullet
-
-@item
-Unnecessary braces can be removed, one line after an if, for, while as
-examples.
-
-@item
-Space around operators (assignment, logical, relational, bitwise,
-mathematical, shift).
-
-@item
-Blank line before single-line comments, multi-line comments, javadoc
-comments.
-
-@item
-If more than 2 blank lines, trim to 2.
-
-@item
-Don't keep commented out code.  Just remove it or add a real comment
-describing what it used to do and why it is changed to the current
-implementation.
-@end itemize
-
-
-@node Hacking Code, Programming Goals, Programming Standards, Top
-@comment node-name, next, previous, up
-@chapter Working on the code, Working with others
-
-There are a lot of people helping out with GNU Classpath.  Here are a
-couple of practical guidelines to make working together on the code
-smoother.
-
-The main thing is to always discuss what you are up to on the
-mailinglist.  Making sure that everybody knows who is working on what
-is the most important thing to make sure we cooperate most
-effectively.
-
-We maintain a
-@uref{http://www.gnu.org/software/classpath/tasks.html,Task List}
-which contains items that you might want to work on.
-
-Before starting to work on something please make sure you read this
-complete guide.  And discuss it on list to make sure your work does
-not duplicate or interferes with work someone else is already doing.
-Always make sure that you submit things that are your own work.  And
-that you have paperwork on file (as stated in the requirements
-section) with the FSF authorizing the use of your additions.
-
-Technically the GNU Classpath project is hosted on
-@uref{http://savannah.gnu.org/,Savannah} a central point for
-development, distribution and maintenance of GNU Software.  Here you
-will find the
-@uref{https://savannah.gnu.org/projects/classpath/,project page}, bug
-reports, pending patches, links to mailing lists, news items and CVS.
-
-You can find instructions on getting a CVS checkout for classpath at
-@uref{https://savannah.gnu.org/cvs/?group=classpath}.
-
-You don't have to get CVS commit write access to contribute, but it is
-sometimes more convenient to be able to add your changes directly to
-the project CVS. Please contact the GNU Classpath savannah admins to
-arrange CVS access if you would like to have it.
-
-Make sure to be subscribed to the commit-classpath mailinglist while
-you are actively hacking on Classpath.  You have to send patches (cvs
-diff -uN) to this list before committing.
-
-We really want to have a pretty open check-in policy.  But this means
-that you should be extra careful if you check something in.  If at all
-in doubt or if you think that something might need extra explaining
-since it is not completely obvious please make a little announcement
-about the change on the mailinglist.  And if you do commit something
-without discussing it first and another GNU Classpath hackers asks for
-extra explanation or suggests to revert a certain commit then please
-reply to the request by explaining why something should be so or if
-you agree to revert it.  (Just reverting immediately is OK without
-discussion, but then please don't mix it with other changes and please
-say so on list.)
-
-Patches that are already approved for libgcj or also OK for Classpath.
-(But you still have to send a patch/diff to the list.)  All other
-patches require you to think whether or not they are really OK and
-non-controversial, or if you would like some feedback first on them
-before committing.  We might get real commit rules in the future, for
-now use your own judgment, but be a bit conservative.
-
-Always contact the GNU Classpath maintainer before adding anything
-non-trivial that you didn't write yourself and that does not come from
-libgcj or from another known GNU Classpath or libgcj hacker.  If you
-have been assigned to commit changes on behalf of another project or
-a company always make sure they come from people who have signed the
-papers for the FSF and/or fall under the arrangement your company made
-with the FSF for contributions.  Mention in the ChangeLog who actually
-wrote the patch.
-
-Commits for completely unrelated changes they should be committed
-separately (especially when doing a formatting change and a logical
-change, do them in two separate commits). But do try to do a commit of
-as much things/files that are done at the same time which can
-logically be seen as part of the same change/cleanup etc.
-
-When the change fixes an important bug or adds nice new functionality
-please write a short entry for inclusion in the @file{NEWS} file.  If it
-changes the VM interface you must mention that in both the @file{NEWS} file
-and the VM Integration Guide.
-
-All the ``rules'' are really meant to make sure that GNU Classpath
-will be maintainable in the long run and to give all the projects that
-are now using GNU Classpath an accurate view of the changes we make to
-the code and to see what changed when.  If you think the requirements
-are ``unworkable'' please try it first for a couple of weeks.  If you
-still feel the same after having some more experience with the project
-please feel free to bring up suggestions for improvements on the list.
-But don't just ignore the rules!  Other hackers depend on them being
-followed to be the most productive they can be (given the above
-constraints).
-
-@menu
-* Branches::                    
-* Writing ChangeLogs::          
-@end menu
-
-@node Branches, Writing ChangeLogs, Hacking Code, Hacking Code
-@comment node-name, next, previous, up
-@section Working with branches
-
-Sometimes it is necessary to create branch of the source for doing new
-work that is disruptive to the other hackers, or that needs new
-language or libraries not yet (easily) available.
-
-After discussing the need for a branch on the main mailinglist with
-the other hackers explaining the need of a branch and suggestion of
-the particular branch rules (what will be done on the branch, who will
-work on it, will there be different commit guidelines then for the
-mainline trunk and when is the branch estimated to be finished and
-merged back into the trunk) every GNU Classpath hacker with commit
-access should feel free to create a branch. There are however a couple
-of rules that every branch should follow:
-
-@itemize @bullet
-
-@item All branches ought to be documented in the developer wiki at
-@uref{http://developer.classpath.org/mediation/ClasspathBranches}, so
-we can know which are live, who owns them, and when they die.
-
-@item Some rules can be changed on a branch.  In particular the branch
-maintainer can change the review requirements, and the requirement of
-keeping things building, testing, etc, can also be lifted.  (These
-should be documented along with the branch name and owner if they
-differ from the trunk.)
-
-@item Requirements for patch email to classpath-patches and for paperwork
-@strong{cannot} be lifted. See @ref{Requirements}.
-
-@item A branch should not be seen as ``private'' or
-``may be completely broken''. It should be as much as possible
-something that you work on with a team (and if there is no team - yet
-- then there is nothing as bad as having a completely broken build to
-get others to help out). There can of course be occasional breakage, but
-it should be planned and explained. And you can certainly have a rule
-like ``please ask me before committing to this branch''.
-
-@item Merges from the trunk to a branch are at the discretion of the
-branch maintainer.
-
-@item A merge from a branch to the trunk is treated like any other patch.
-In particular, it has to go through review, it must satisfy all the
-trunk requirements (build, regression test, documentation).
-
-@item There may be additional timing requirements on merging a branch to
-the trunk depending on the release schedule, etc.  For instance we may
-not want to do a branch merge just before a release.
-
-@end itemize
-
-If any of these rules are unclear please discuss on the list first.
-
-@menu
-* Writing ChangeLogs::          
-@end menu
-
-@node Writing ChangeLogs,  , Branches, Hacking Code
-@comment node-name, next, previous, up
-@section Documenting what changed when with ChangeLog entries
-
-To keep track of who did what when we keep an explicit ChangeLog entry
-together with the code.  This mirrors the CVS commit messages and in
-general the ChangeLog entry is the same as the CVS commit message.
-This provides an easy way for people getting a (snapshot) release or
-without access to the CVS server to see what happened when.  We do not
-generate the ChangeLog file automatically from the CVS server since
-that is not reliable.
-
-A good ChangeLog entry guideline can be found in the Guile Manual at
-@uref{http://www.gnu.org/software/guile/changelogs/guile-changelogs_3.html}.
-
-Here are some example to explain what should or shouldn't be in a
-ChangeLog entry (and the corresponding commit message):
-
-@itemize @bullet
-
-@item
-The first line of a ChangeLog entry should be:
-
-@example
-[date] <two spaces> [full name] <two spaces> [email-contact]
-@end example
-
-The second line should be blank. All other lines should be indented
-with one tab.
-
-@item
-Just state what was changed.  Why something is done as it is done in
-the current code should be either stated in the code itself or be
-added to one of the documentation files (like this Hacking Guide).
-
-So don't write:
-
-@example
-        * java/awt/font/OpenType.java: Remove 'public static final'
-        from OpenType tags, reverting the change of 2003-08-11.  See
-        Classpath discussion list of 2003-08-11.
-@end example
-
-Just state:
-
-@example
-        * java/awt/font/OpenType.java: Remove 'public static final' from
-        all member fields.
-@end example
-
-In this case the reason for the change was added to this guide.
-
-@item
-Just as with the normal code style guide, don't make lines longer then
-80 characters.
-
-@item
-Just as with comments in the code. The ChangeLog entry should be a
-full sentence, starting with a captital and ending with a period.
-
-@item
-Be precise in what changed, not the effect of the change (which should
-be clear from the code/patch).  So don't write:
-
-@example
- * java/io/ObjectOutputStream.java : Allow putFields be called more 
- than once.
-@end example
-
-But explain what changed and in which methods it was changed:
-
-@example
- * java/io/ObjectOutputStream.java (putFields): Don't call
- markFieldsWritten(). Only create new PutField when
- currentPutField is null.
- (writeFields): Call markFieldsWritten().
-@end example
-
-@end itemize
-
-The above are all just guidelines.  We all appreciate the fact that writing
-ChangeLog entries, using a coding style that is not ``your own'' and the
-CVS, patch and diff tools do take some time to getting used to.  So don't
-feel like you have to do it perfect right away or that contributions
-aren't welcome if they aren't ``perfect''.  We all learn by doing and
-interacting with each other.
-
-
-@node Programming Goals, API Compatibility, Hacking Code, Top
-@comment node-name, next, previous, up
-@chapter Programming Goals
-
-When you write code for Classpath, write with three things in mind, and
-in the following order: portability, robustness, and efficiency.
-
-If efficiency breaks portability or robustness, then don't do it the
-efficient way.  If robustness breaks portability, then bye-bye robust
-code.  Of course, as a programmer you would probably like to find sneaky
-ways to get around the issue so that your code can be all three ... the
-following chapters will give some hints on how to do this.
-
-@menu
-* Portability::                 Writing Portable Software                
-* Utility Classes::             Reusing Software
-* Robustness::                  Writing Robust Software               
-* Java Efficiency::             Writing Efficient Java            
-* Native Efficiency::           Writing Efficient JNI          
-* Security::                    Writing Secure Software
-@end menu
-
-@node Portability, Utility Classes, Programming Goals, Programming Goals
-@comment node-name, next, previous, up
-@section Portability
-
-The portability goal for Classpath is the following:
-
-@enumerate
-@item
-native functions for each platform that work across all VMs on that
-platform
-@item
-a single classfile set that work across all VMs on all platforms that
-support the native functions.
-@end enumerate
-
-For almost all of Classpath, this is a very feasible goal, using a
-combination of JNI and native interfaces.  This is what you should shoot
-for.  For those few places that require knowledge of the Virtual Machine
-beyond that provided by the Java standards, the VM Interface was designed.
-Read the Virtual Machine Integration Guide for more information.
-
-Right now the only supported platform is Linux.  This will change as that
-version stabilizes and we begin the effort to port to many other
-platforms.  Jikes RVM runs Classpath on AIX, and generally the Jikes
-RVM team fixes Classpath to work on that platform. 
-
-@node Utility Classes, Robustness, Portability, Programming Goals
-@comment  node-name,  next,  previous,  up
-@section Utility Classes
-
-At the moment, we are not very good at reuse of the JNI code.  There
-have been some attempts, called @dfn{libclasspath}, to
-create generally useful utility classes.  The utility classes are in
-the directory @file{native/jni/classpath} and they are mostly declared
-in @file{native/jni/classpath/jcl.h}.  These utility classes are
-currently only discussed in @ref{Robustness} and in @ref{Native
-Efficiency}.
-
-There are more utility classes available that could be factored out if
-a volunteer wants something nice to hack on.  The error reporting and
-exception throwing functions and macros in
-@file{native/jni/gtk-peer/gthread-jni.c} might be good
-candidates for reuse.  There are also some generally useful utility
-functions in @file{gnu_java_awt_peer_gtk_GtkMainThread.c} that could
-be split out and put into libclasspath.
-
-@node Robustness, Java Efficiency, Utility Classes, Programming Goals
-@comment node-name, next, previous, up
-@section Robustness
-
-Native code is very easy to make non-robust.  (That's one reason Java is
-so much better!)  Here are a few hints to make your native code more
-robust.
-
-Always check return values for standard functions.  It's sometimes easy
-to forget to check that malloc() return for an error.  Don't make that
-mistake.  (In fact, use JCL_malloc() in the jcl library instead--it will
-check the return value and throw an exception if necessary.)
-
-Always check the return values of JNI functions, or call
-@code{ExceptionOccurred} to check whether an error occurred.  You must
-do this after @emph{every} JNI call.  JNI does not work well when an
-exception has been raised, and can have unpredictable behavior.
-
-Throw exceptions using @code{JCL_ThrowException}.  This guarantees that if
-something is seriously wrong, the exception text will at least get out
-somewhere (even if it is stderr).
-
-Check for null values of @code{jclass}es before you send them to JNI functions.
-JNI does not behave nicely when you pass a null class to it: it
-terminates Java with a "JNI Panic."
-
-In general, try to use functions in @file{native/jni/classpath/jcl.h}.  They
-check exceptions and return values and throw appropriate exceptions.
-
-@node Java Efficiency, Native Efficiency, Robustness, Programming Goals
-@comment node-name, next, previous, up
-@section Java Efficiency
-
-For methods which explicitly throw a @code{NullPointerException} when an
-argument is passed which is null, per a Sun specification, do not write
-code like:
-
-@example
-int 
-strlen (String foo) throws NullPointerException
-@{
-  if (foo == null)
-    throw new NullPointerException ("foo is null");
-  return foo.length ();
-@}
-@end example
-
-Instead, the code should be written as:
-
-@example
-int
-strlen (String foo) throws NullPointerException
-@{
-  return foo.length ();
-@}
-@end example
-
-Explicitly comparing foo to null is unnecessary, as the virtual machine
-will throw a NullPointerException when length() is invoked.  Classpath
-is designed to be as fast as possible -- every optimization, no matter
-how small, is important.
-
-@node Native Efficiency, Security, Java Efficiency, Programming Goals
-@comment node-name, next, previous, up
-@section Native Efficiency
-
-You might think that using native methods all over the place would give
-our implementation of Java speed, speed, blinding speed.  You'd be
-thinking wrong.  Would you believe me if I told you that an empty
-@emph{interpreted} Java method is typically about three and a half times
-@emph{faster} than the equivalent native method?
-
-Bottom line: JNI is overhead incarnate.  In Sun's implementation, even
-the JNI functions you use once you get into Java are slow.
-
-A final problem is efficiency of native code when it comes to things
-like method calls, fields, finding classes, etc.  Generally you should
-cache things like that in static C variables if you're going to use them
-over and over again.  GetMethodID(), GetFieldID(), and FindClass() are
-@emph{slow}.  Classpath provides utility libraries for caching methodIDs
-and fieldIDs in @file{native/jni/classpath/jnilink.h}.  Other native data can
-be cached between method calls using functions found in
-@file{native/jni/classpath/native_state.h}.
-
-Here are a few tips on writing native code efficiently:
-
-Make as few native method calls as possible.  Note that this is not the
-same thing as doing less in native method calls; it just means that, if
-given the choice between calling two native methods and writing a single
-native method that does the job of both, it will usually be better to
-write the single native method.  You can even call the other two native
-methods directly from your native code and not incur the overhead of a
-method call from Java to C.
-
-Cache @code{jmethodID}s and @code{jfieldID}s wherever you can.  String
-lookups are 
-expensive.  The best way to do this is to use the 
-@file{native/jni/classpath/jnilink.h}
-library.  It will ensure that @code{jmethodID}s are always valid, even if the
-class is unloaded at some point.  In 1.1, jnilink simply caches a
-@code{NewGlobalRef()} to the method's underlying class; however, when 1.2 comes
-along, it will use a weak reference to allow the class to be unloaded
-and then re-resolve the @code{jmethodID} the next time it is used.
-
-Cache classes that you need to access often.  jnilink will help with
-this as well.  The issue here is the same as the methodID and fieldID
-issue--how to make certain the class reference remains valid.
-
-If you need to associate native C data with your class, use Paul
-Fisher's native_state library (NSA).  It will allow you to get and set
-state fairly efficiently.  Japhar now supports this library, making
-native state get and set calls as fast as accessing a C variable
-directly.
-
-If you are using native libraries defined outside of Classpath, then
-these should be wrapped by a Classpath function instead and defined
-within a library of their own.  This makes porting Classpath's native
-libraries to new platforms easier in the long run.  It would be nice
-to be able to use Mozilla's NSPR or Apache's APR, as these libraries
-are already ported to numerous systems and provide all the necessary
-system functions as well.
-
-@node Security,  , Native Efficiency, Programming Goals
-@comment  node-name,  next,  previous,  up
-@section Security
-
-Security is such a huge topic it probably deserves its own chapter.
-Most of the current code needs to be audited for security to ensure
-all of the proper security checks are in place within the Java
-platform, but also to verify that native code is reasonably secure and
-avoids common pitfalls, buffer overflows, etc.  A good source for
-information on secure programming is the excellent HOWTO by David
-Wheeler,
-@uref{http://www.dwheeler.com/secure-programs/Secure-Programs-HOWTO/index.html,Secure
-Programming for Linux and Unix HOWTO}.
-
-@node API Compatibility, Specification Sources, Programming Goals, Top
-@comment  node-name,  next,  previous,  up
-@chapter API Compatibility
-
-@menu
-* Serialization::               Serialization
-* Deprecated Methods::          Deprecated methods
-@end menu
-
-@node Serialization, Deprecated Methods, API Compatibility, API Compatibility
-@comment  node-name,  next,  previous,  up
-@section Serialization
-
-Sun has produced documentation concerning much of the information
-needed to make Classpath serializable compatible with Sun
-implementations.  Part of doing this is to make sure that every class
-that is Serializable actually defines a field named serialVersionUID
-with a value that matches the output of serialver on Sun's
-implementation.  The reason for doing this is below.
-
-If a class has a field (of any accessibility) named serialVersionUID
-of type long, that is what serialver uses. Otherwise it computes a
-value using some sort of hash function on the names of all method
-signatures in the .class file.  The fact that different compilers
-create different synthetic method signatures, such as access$0() if an
-inner class needs access to a private member of an enclosing class,
-make it impossible for two distinct compilers to reliably generate the
-same serial #, because their .class files differ. However, once you
-have a .class file, its serial # is unique, and the computation will
-give the same result no matter what platform you execute on.
-
-Serialization compatibility can be tested using tools provided with
-@uref{http://www.kaffe.org/~stuart/japi/,Japitools}.  These
-tools can test binary serialization compatibility and also provide
-information about unknown serialized formats by writing these in XML
-instead.  Japitools is also the primary means of checking API
-compatibility for GNU Classpath with Sun's Java Platform.
-
-@node Deprecated Methods,  , Serialization, API Compatibility
-@comment  node-name,  next,  previous,  up
-@section Deprecated Methods
-
-Sun has a practice of creating ``alias'' methods, where a public or
-protected method is deprecated in favor of a new one that has the same
-function but a different name.  Sun's reasons for doing this vary; as
-an example, the original name may contain a spelling error or it may
-not follow Java naming conventions.
-
-Unfortunately, this practice complicates class library code that calls
-these aliased methods.  Library code must still call the deprecated
-method so that old client code that overrides it continues to work.
-But library code must also call the new version, because new code is
-expected to override the new method.
-
-The correct way to handle this (and the way Sun does it) may seem
-counterintuitive because it means that new code is less efficient than
-old code: the new method must call the deprecated method, and throughout
-the library code calls to the old method must be replaced with calls to
-the new one.
-
-Take the example of a newly-written container laying out a component and
-wanting to know its preferred size.  The Component class has a
-deprecated preferredSize method and a new method, getPreferredSize. 
-Assume that the container is laying out an old component that overrides
-preferredSize and a new component that overrides getPreferredSize.  If
-the container calls getPreferredSize and the default implementation of
-getPreferredSize calls preferredSize, then the old component will have
-its preferredSize method called and new code will have its
-getPreferredSize method called.
-
-Even using this calling scheme, an old component may still be laid out
-improperly if it implements a method, getPreferredSize, that has the
-same signature as the new Component.getPreferredSize.  But that is a
-general problem -- adding new public or protected methods to a
-widely-used class that calls those methods internally is risky, because
-existing client code may have already declared methods with the same
-signature.
-
-The solution may still seem counterintuitive -- why not have the
-deprecated method call the new method, then have the library always call
-the old method?  One problem with that, using the preferred size example
-again, is that new containers, which will use the non-deprecated
-getPreferredSize, will not get the preferred size of old components.
-
-@node Specification Sources, Naming Conventions, API Compatibility, Top
-@comment node-name, next, previous, up
-@chapter Specification Sources
-
-There are a number of specification sources to use when working on
-Classpath.  In general, the only place you'll find your classes
-specified is in the JavaDoc documentation or possibly in the
-corresponding white paper.  In the case of java.lang, java.io and
-java.util, you should look at the Java Language Specification.
-
-Here, however, is a list of specs, in order of canonicality:
-
-@enumerate
-@item
-@uref{http://java.sun.com/docs/books/jls/clarify.html,Clarifications and Amendments to the JLS - 1.1}
-@item
-@uref{http://java.sun.com/docs/books/jls/html/1.1Update.html,JLS Updates
-- 1.1}
-@item
-@uref{http://java.sun.com/docs/books/jls/html/index.html,The 1.0 JLS}
-@item
-@uref{http://java.sun.com/docs/books/vmspec/index.html,JVM spec - 1.1}
-@item
-@uref{http://java.sun.com/products/jdk/1.1/docs/guide/jni/spec/jniTOC.doc.html,JNI spec - 1.1}
-@item
-@uref{http://java.sun.com/products/jdk/1.1/docs/api/packages.html,Sun's javadoc - 1.1}
-(since Sun's is the reference implementation, the javadoc is
-documentation for the Java platform itself.)
-@item
-@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jvmdi/jvmdi.html,JVMDI spec - 1.2},
-@uref{http://java.sun.com/products/jdk/1.2/docs/guide/jni/jni-12.html,JNI spec - 1.2}
-(sometimes gives clues about unspecified things in 1.1; if
-it was not specified accurately in 1.1, then use the spec
-for 1.2; also, we are using JVMDI in this project.)
-@item
-@uref{http://java.sun.com/products/jdk/1.2/docs/api/frame.html,Sun's javadoc - 1.2}
-(sometimes gives clues about unspecified things in 1.1; if
-it was not specified accurately in 1.1, then use the spec
-for 1.2)
-@item
-@uref{http://developer.java.sun.com/developer/bugParade/index.html,The
-Bug Parade}: I have obtained a ton of useful information about how
-things do work and how they *should* work from the Bug Parade just by
-searching for related bugs.  The submitters are very careful about their
-use of the spec.  And if something is unspecified, usually you can find
-a request for specification or a response indicating how Sun thinks it
-should be specified here.
-@end enumerate
-
-You'll notice that in this document, white papers and specification
-papers are more canonical than the JavaDoc documentation.  This is true
-in general.
-
-
-@node Naming Conventions, Character Conversions, Specification Sources, Top
-@comment node-name, next, previous, up
-@chapter Directory and File Naming Conventions
-
-The Classpath directory structure is laid out in the following manner:
-
-@example
-classpath
- |
- |---->java
- |       |
- |       |-->awt
- |       |-->io
- |       |-->lang
- |       |-->util
- |       |     |
- |       |     |--->zip
- |       |     |--->jar
- |       |-->net
- |       |-->etc
- |
- |---->gnu
- |       |
- |       |-->java
- |             |
- |             |-->awt
- |             |-->lang
- |             |-->util
- |             |     |
- |             |     |-->zip
- |             |-->etc
- |
- |---->native
-         |
-         |-->jni
-         |    |-->classpath
-         |    |-->gtk-peer
-         |    |-->java-io
-         |    |-->java-lang
-         |    |-->java-net
-         |    |-->java-util
-         |    |-->etc
-         |-->cni
-  
-@end example
-
-Here is a brief description of the toplevel directories and their contents.
-
-@table @b
-
-@item java
-Contains the source code to the Java packages that make up the core
-class library.  Because this is the public interface to Java, it is
-important that the public classes, interfaces, methods, and variables
-are exactly the same as specified in Sun's documentation.  The directory
-structure is laid out just like the java package names.  For example,
-the class java.util.zip would be in the directory java-util.
-
-@item gnu/java
-Internal classes (roughly analogous to Sun's sun.* classes) should go
-under the @file{gnu/java} directory.  Classes related to a particular public
-Java package should go in a directory named like that package.  For
-example, classes related to java.util.zip should go under a directory
-@file{gnu/java/util/zip}.  Sub-packages under the main package name are
-allowed.  For classes spanning multiple public Java packages, pick an
-appropriate name and see what everybody else thinks.
-
-@item native
-This directory holds native code needed by the public Java packages.
-Each package has its own subdirectory, which is the ``flattened'' name
-of the package.  For example, native method implementations for
-java.util.zip should go in @file{native/classpath/java-util}.  Classpath
-actually includes an all Java version of the zip classes, so no native
-code is required.
-
-@end table
-
-Each person working on a package get's his or her own ``directory
-space'' underneath each of the toplevel directories.  In addition to the
-general guidelines above, the following standards should be followed:
-
-@itemize @bullet
-
-@item
-Classes that need to load native code should load a library with the
-same name as the flattened package name, with all hyphens removed.  For
-example, the native library name specified in LoadLibrary for
-java-util would be ``javautil''.
-
-@item
-Each package has its own shared library for native code (if any).
-
-@item
-The main native method implementation for a given method in class should
-go in a file with the same name as the class with a ``.c'' extension.
-For example, the JNI implementation of the native methods in
-java.net.InetAddress would go in @file{native/jni/java-net/InetAddress.c}.
-``Internal'' native functions called from the main native method can
-reside in files of any name.
-@end itemize
-
-@node Character Conversions, Localization, Naming Conventions, Top
-@comment node-name, next, previous, up
-@chapter Character Conversions
-
-Java uses the Unicode character encoding system internally.  This is a
-sixteen bit (two byte) collection of characters encompassing most of the
-world's written languages.  However, Java programs must often deal with
-outside interfaces that are byte (eight bit) oriented.  For example, a
-Unix file, a stream of data from a network socket, etc.  Beginning with
-Java 1.1, the @code{Reader} and @code{Writer} classes provide functionality
-for dealing with character oriented streams.  The classes 
-@code{InputStreamReader} and @code{OutputStreamWriter} bridge the gap
-between byte streams and character streams by converting bytes to 
-Unicode characters and vice versa.
-
-In Classpath, @code{InputStreamReader} and @code{OutputStreamWriter}
-rely on an internal class called @code{gnu.java.io.EncodingManager} to load
-translaters that perform the actual conversion.  There are two types of
-converters, encoders and decoders.  Encoders are subclasses of
-@code{gnu.java.io.encoder.Encoder}.  This type of converter takes a Java
-(Unicode) character stream or buffer and converts it to bytes using
-a specified encoding scheme.  Decoders are a subclass of 
-@code{gnu.java.io.decoder.Decoder}.  This type of converter takes a 
-byte stream or buffer and converts it to Unicode characters.  The
-@code{Encoder} and @code{Decoder} classes are subclasses of
-@code{Writer} and @code{Reader} respectively, and so can be used in
-contexts that require character streams, but the Classpath implementation
-currently does not make use of them in this fashion.
-
-The @code{EncodingManager} class searches for requested encoders and
-decoders by name.  Since encoders and decoders are separate in Classpath,
-it is possible to have a decoder without an encoder for a particular 
-encoding scheme, or vice versa.  @code{EncodingManager} searches the
-package path specified by the @code{file.encoding.pkg} property.  The
-name of the encoder or decoder is appended to the search path to
-produce the required class name.  Note that @code{EncodingManager} knows
-about the default system encoding scheme, which it retrieves from the
-system property @code{file.encoding}, and it will return the proper
-translator for the default encoding if no scheme is specified.  Also, the 
-Classpath standard translator library, which is the @code{gnu.java.io} package, 
-is automatically appended to the end of the path.
-
-For efficiency, @code{EncodingManager} maintains a cache of translators
-that it has loaded.  This eliminates the need to search for a commonly
-used translator each time it is requested.
-
-Finally, @code{EncodingManager} supports aliasing of encoding scheme names.
-For example, the ISO Latin-1 encoding scheme can be referred to as
-''8859_1'' or ''ISO-8859-1''.  @code{EncodingManager} searches for 
-aliases by looking for the existence of a system property called
-@code{gnu.java.io.encoding_scheme_alias.<encoding name>}.  If such a
-property exists.  The value of that property is assumed to be the
-canonical name of the encoding scheme, and a translator with that name is 
-looked up instead of one with the original name.
-
-Here is an example of how @code{EncodingManager} works.  A class requests
-a decoder for the ''UTF-8'' encoding scheme by calling
-@code{EncodingManager.getDecoder("UTF-8")}.  First, an alias is searched
-for by looking for the system property 
-@code{gnu.java.io.encoding_scheme_alias.UTF-8}.  In our example, this
-property exists and has the value ''UTF8''.  That is the actual
-decoder that will be searched for.  Next, @code{EncodingManager} looks
-in its cache for this translator.  Assuming it does not find it, it
-searches the translator path, which is this example consists only of
-the default @code{gnu.java.io}.  The ''decoder'' package name is 
-appended since we are looking for a decoder.  (''encoder'' would be 
-used if we were looking for an encoder).  Then name name of the translator
-is appended.  So @code{EncodingManager} attempts to load a translator
-class called @code{gnu.java.io.decoder.UTF8}.  If that class is found,
-an instance of it is returned.  If it is not found, a
-@code{UnsupportedEncodingException}.
-
-To write a new translator, it is only necessary to subclass 
-@code{Encoder} and/or @code{Decoder}.  Only a handful of abstract
-methods need to be implemented.  In general, no methods need to be
-overridden.  The needed methods calculate the number of bytes/chars
-that the translation will generate, convert buffers to/from bytes,
-and read/write a requested number of characters to/from a stream.
-
-Many common encoding schemes use only eight bits to encode characters.
-Writing a translator for these encodings is very easy.  There are 
-abstract translator classes @code{gnu.java.io.decode.DecoderEightBitLookup}
-and @code{gnu.java.io.encode.EncoderEightBitLookup}.  These classes
-implement all of the necessary methods.  All that is necessary to
-create a lookup table array that maps bytes to Unicode characters and
-set the class variable @code{lookup_table} equal to it in a static
-initializer.  Also, a single constructor that takes an appropriate
-stream as an argument must be supplied.  These translators are
-exceptionally easy to create and there are several of them supplied
-in the Classpath distribution.
-
-Writing multi-byte or variable-byte encodings is more difficult, but
-often not especially challenging.  The Classpath distribution ships with
-translators for the UTF8 encoding scheme which uses from one to three
-bytes to encode Unicode characters.  This can serve as an example of
-how to write such a translator.
-
-Many more translators are needed.  All major character encodings should
-eventually be supported.
-
-@node Localization,  , Character Conversions, Top
-@comment node-name, next, previous, up
-@chapter Localization
-
-There are many parts of the Java standard runtime library that must
-be customized to the particular locale the program is being run in.
-These include the parsing and display of dates, times, and numbers;
-sorting words alphabetically; breaking sentences into words, etc.
-In general, Classpath uses general classes for performing these tasks,
-and customizes their behavior with configuration data specific to a
-given locale.
-
-@menu
-* String Collation::            Sorting strings in different locales
-* Break Iteration::             Breaking up text into words, sentences, and lines
-* Date Formatting and Parsing::  Locale specific date handling
-* Decimal/Currency Formatting and Parsing::  Local specific number handling
-@end menu
-
-In Classpath, all locale specific data is stored in a 
-@code{ListResourceBundle} class in the package @code{gnu/java/locale}.
-The basename of the bundle is @code{LocaleInformation}.  See the
-documentation for the @code{java.util.ResourceBundle} class for details
-on how the specific locale classes should be named.
-
-@code{ListResourceBundle}'s are used instead of 
-@code{PropertyResourceBundle}'s because data more complex than simple
-strings need to be provided to configure certain Classpath components.
-Because @code{ListResourceBundle} allows an arbitrary Java object to
-be associated with a given configuration option, it provides the
-needed flexibility to accomodate Classpath's needs.
-
-Each Java library component that can be localized requires that certain
-configuration options be specified in the resource bundle for it.  It is
-important that each and every option be supplied for a specific 
-component or a critical runtime error will most likely result.
-
-As a standard, each option should be assigned a name that is a string.
-If the value is stored in a class or instance variable, then the option
-should name should have the name name as the variable.  Also, the value
-associated with each option should be a Java object with the same name
-as the option name (unless a simple scalar value is used).  Here is an
-example:
-
-A class loads a value for the @code{format_string} variable from the
-resource bundle in the specified locale.  Here is the code in the
-library class:
-
-@example
-  ListResourceBundle lrb = 
-    ListResourceBundle.getBundle ("gnu/java/locale/LocaleInformation", locale);
-  String format_string = lrb.getString ("format_string");
-@end example
-
-In the actual resource bundle class, here is how the configuration option
-gets defined:
-
-@example
-/**
-  * This is the format string used for displaying values
-  */
-private static final String format_string = "%s %d %i";
-
-private static final Object[][] contents =
-@{
-  @{ "format_string", format_string @}
-@};
-@end example
-
-Note that each variable should be @code{private}, @code{final}, and
-@code{static}.  Each variable should also have a description of what it
-does as a documentation comment.  The @code{getContents()} method returns
-the @code{contents} array.
-
-There are many functional areas of the standard class library that are
-configured using this mechanism.  A given locale does not need to support
-each functional area.  But if a functional area is supported, then all
-of the specified entries for that area must be supplied.  In order to
-determine which functional areas are supported, there is a special key
-that is queried by the affected class or classes.  If this key exists, 
-and has a value that is a @code{Boolean} object wrappering the
-@code{true} value, then full support is assumed.  Otherwise it is
-assumed that no support exists for this functional area.  Every class
-using resources for configuration must use this scheme and define a special
-scheme that indicates the functional area is supported.  Simply checking
-for the resource bundle's existence is not sufficient to ensure that a
-given functional area is supported.
-
-The following sections define the functional areas that use resources
-for locale specific configuration in GNU Classpath.  Please refer to the 
-documentation for the classes mentioned for details on how these values 
-are used.  You may also wish to look at the source file for 
-@file{gnu/java/locale/LocaleInformation_en} as an example.
-
-@node String Collation, Break Iteration, Localization, Localization
-@comment node-name, next, previous, up
-@section String Collation
-
-Collation involves the sorting of strings.  The Java class library provides
-a public class called @code{java.text.RuleBasedCollator} that performs
-sorting based on a set of sorting rules.
-
-@itemize @bullet
-@item RuleBasedCollator - A @code{Boolean} wrappering @code{true} to indicate
-that this functional area is supported.
-@item collation_rules - The rules the specify how string collation is to
-be performed.
-@end itemize
-
-Note that some languages might be too complex for @code{RuleBasedCollator}
-to handle.  In this case an entirely new class might need to be written in
-lieu of defining this rule string.
-
-@node Break Iteration, Date Formatting and Parsing, String Collation, Localization
-@comment node-name, next, previous, up
-@section Break Iteration
-
-The class @code{java.text.BreakIterator} breaks text into words, sentences,
-and lines.  It is configured with the following resource bundle entries:
-
-@itemize @bullet
-@item BreakIterator - A @code{Boolean} wrappering @code{true} to indicate
-that this functional area is supported.
-@item word_breaks - A @code{String} array of word break character sequences.
-@item sentence_breaks - A @code{String} array of sentence break character
-sequences.
-@item line_breaks - A @code{String} array of line break character sequences.
-@end itemize
-
-@node Date Formatting and Parsing, Decimal/Currency Formatting and Parsing, Break Iteration, Localization
-@comment node-name, next, previous, up
-@section Date Formatting and Parsing
-
-Date formatting and parsing is handled by the 
-@code{java.text.SimpleDateFormat} class in most locales.  This class is
-configured by attaching an instance of the @code{java.text.DateFormatSymbols}
-class.  That class simply reads properties from our locale specific
-resource bundle.  The following items are required (refer to the 
-documentation of the @code{java.text.DateFormatSymbols} class for details
-io what the actual values should be):
-
-@itemize @bullet
-@item DateFormatSymbols - A @code{Boolean} wrappering @code{true} to indicate
-that this functional area is supported.
-@item months - A @code{String} array of month names.
-@item shortMonths - A @code{String} array of abbreviated month names.
-@item weekdays - A @code{String} array of weekday names.
-@item shortWeekdays - A @code{String} array of abbreviated weekday names.
-@item ampms - A @code{String} array containing AM/PM names.
-@item eras - A @code{String} array containing era (ie, BC/AD) names.
-@item zoneStrings - An array of information about valid timezones for this 
-locale.
-@item localPatternChars - A @code{String} defining date/time pattern symbols.
-@item shortDateFormat - The format string for dates used by 
-@code{DateFormat.SHORT}
-@item mediumDateFormat - The format string for dates used by 
-@code{DateFormat.MEDIUM}
-@item longDateFormat - The format string for dates used by 
-@code{DateFormat.LONG}
-@item fullDateFormat - The format string for dates used by 
-@code{DateFormat.FULL}
-@item shortTimeFormat - The format string for times used by 
-@code{DateFormat.SHORT}
-@item mediumTimeFormat - The format string for times used by 
-@code{DateFormat.MEDIUM}
-@item longTimeFormat - The format string for times used by 
-@code{DateFormat.LONG}
-@item fullTimeFormat - The format string for times used by 
-@code{DateFormat.FULL}
-@end itemize
-
-Note that it may not be possible to use this mechanism for all locales.
-In those cases a special purpose class may need to be written to handle 
-date/time processing.
-
-@node Decimal/Currency Formatting and Parsing,  , Date Formatting and Parsing, Localization
-@comment node-name, next, previous, up
-@section Decimal/Currency Formatting and Parsing
-
-@code{NumberFormat} is an abstract class for formatting and parsing numbers.
-The class @code{DecimalFormat} provides a concrete subclass that handles
-this is in a locale independent manner.  As with @code{SimpleDateFormat},
-this class gets information on how to format numbers from a class that
-wrappers a collection of locale specific formatting values.  In this case,
-the class is @code{DecimalFormatSymbols}.  That class reads its default
-values for a locale from the resource bundle.  The required entries are:
-
-@itemize @bullet
-@item DecimalFormatSymbols - A @code{Boolean} wrappering @code{true} to 
-indicate that this functional area is supported.
-@item currencySymbol - The string representing the local currency.
-@item intlCurrencySymbol - The string representing the local currency in an
-international context.
-@item decimalSeparator - The character to use as the decimal point as a
-@code{String}.
-@item digit - The character used to represent digits in a format string,
-as a @code{String}.
-@item exponential - The char used to represent the exponent separator of a 
-number written in scientific notation, as a @code{String}.
-@item groupingSeparator - The character used to separate groups of numbers
-in a large number, such as the ``,'' separator for thousands in the US, as
-a @code{String}.
-@item infinity - The string representing infinity.
-@item NaN - The string representing the Java not a number value.
-@item minusSign - The character representing the negative sign, as a 
-@code{String}.
-@item monetarySeparator - The decimal point used in currency values, as a
-@code{String}.
-@item patternSeparator - The character used to separate positive and 
-negative format patterns, as a @code{String}.
-@item percent - The percent sign, as a @code{String}.
-@item perMill - The per mille sign, as a @code{String}.
-@item zeroDigit - The character representing the digit zero, as a @code{String}.
-@end itemize
-
-Note that several of these values are an individual character.  These should
-be wrappered in a @code{String} at character position 0, not in a
-@code{Character} object.
-
-@bye
-