svn commit: r896598 - /incubator/kato/branches/M1-incubating/org.apache.kato/kato.distro/src/main/readme/README

[mo...@apache.org]

Author: monteith
Date: Wed Jan  6 18:26:05 2010
New Revision: 896598

URL: http://svn.apache.org/viewvc?rev=896598&view=rev
Log:
Review, fixup readme

Modified:
    incubator/kato/branches/M1-incubating/org.apache.kato/kato.distro/src/main/readme/README

Modified: incubator/kato/branches/M1-incubating/org.apache.kato/kato.distro/src/main/readme/README
URL: http://svn.apache.org/viewvc/incubator/kato/branches/M1-incubating/org.apache.kato/kato.distro/src/main/readme/README?rev=896598&r1=896597&r2=896598&view=diff
==============================================================================
--- incubator/kato/branches/M1-incubating/org.apache.kato/kato.distro/src/main/readme/README (original)
+++ incubator/kato/branches/M1-incubating/org.apache.kato/kato.distro/src/main/readme/README Wed Jan  6 18:26:05 2010
@@ -1,12 +1,37 @@
 Apache Kato ${project.version}
 ==============================
 
-This file explains how to use the various subprojects that constitute
-Apache Kato.
-
 Overview
 ========
 
+This project aims to provide the specification of JSR-326 (a Java Specfication
+Request), a technology compliance kit (a test framework) and implementations of
+the standard, including the reference implementation.
+
+The project's goal is to enable Java virtual machines to generate files containing the
+state of the virtual machine and for those files to be read in a consistent manner
+using a standardised API. The generated files could be core files, hprof files or
+a file generated by a JVMTI agent attached to the Java virtual machine. 
+
+Benefits
+========
+
+Apache Kato enables use-cases that had previously been unavailable, non-portable
+or had other restrictions. For example:
+
+o Program state can be examined without halting, instead a file can be generated
+  and examined later.
+
+o Instead of requiring patches to be applied with improved first-failure data 
+  capture code, analysis tools can be updated independently.
+
+o Tooling can be written to target the API and not just the output of a specific
+  vendor's Java virtual machine.
+
+
+Contents
+========
+
 Apache Kato supplies the following:
 
     . A JVMTI agent for enabling Java Virtual Machines to produce rich
@@ -36,14 +61,15 @@
 (CJVMTI) that generates a dump of the JVM state and a JNI library that provides
 a method of initiating a dump (hprof or JVMTI) without user intervention.
 
-The libraries are package separately in the following packages:
+The libraries are packaged separately in the following packages:
 
     apache-kato-${project.version}-native-bin-linux-i386.tar.gz
     apache-kato-${project.version}-native-bin-windows-x86.zip
 
 They can be unpackaged on top of this package. The libraries appear under 
 the lib directory.
-Please see their in README-native.txt .
+Additional instructions on how to install and use the libraries are included in
+the file called README-native.txt.
 
 Dump API
 ========
@@ -118,9 +144,9 @@
 
 Where "katoview" is suffixed with .sh or .cmd.
 
-The script should be passed a dump file after the -dump parameter.
+The script should be passed a dump's filename after the -dump parameter.
 KatoView will use any JSR-326 compliant implementation, but currently
-only hprof files and cdmp (CJVMTI agent dumps) will read.
+only hprof files and cdmp (CJVMTI agent dumps) are supported.
 
 KatoView supports a large number of different commands. Use the help
 command for a list of commands. Further help can be brought up using
@@ -193,4 +219,5 @@
 
     jdb -attach localhost:8732
 
-
+The JDI server is best used with the cdmp format. Only that dump format provides
+local variable information.