-This is a very first prototype of an introspection framework for GObject.
-
-The metadata format is described in metadata-format.txt, the XML IDL format
-follows the DTD in gidl.dtd. Look at the files in tests/ for testcases,
-and at examples/ for bigger examples.
-
-The code in src/ currently produces four things:
-- g-idl-compile, a metadata compiler. It converts one or more IDL files
- into one or more metadata blobs. It can either emit the raw metadata
- blob (--raw) or C code (--code).
-- libirepository, the repository API.
-- g-idl-generate, an IDL generator, using the repository API. It generates
- IDL files from binary metadata which can be in a shared object, or a raw
- metadata blob (--raw).
-- a function to invoke functions, given the function info object. The
- implementation is based on libffi (a recent snapshot of libffi can
- be found at http://spindazzle.org/libffi-green.tar.gz).
-
-There are a number of IDL test files in test/, and a script to do
-roundtrip tests (IDL -> binary -> IDL).
-
-The introspection framework needs a lot more work, see TODO.
+GObject Introspection
+=====================
+The goal of the project is to describe the APIs and collect them in
+a uniform, machine readable format.
+
+GIR XML format
+==============
+
+There's an XML format called GIR used by GObjectIntrospection.
+The purpose of it is to provide a common structure to access the complete
+available API that a library or other unit of code exports.
+It is meant to be language agnostic using namespaces to separate
+core, language or library specific functionality.
+There are currently only C based tools that work on the format, but it's
+meant to be usable to use in other situations, for instance to/from another
+set of languages.
+
+Typelib
+=======
+
+The typelib is a to disk version of the GIR designed to be fast, memory
+efficient and complete enough so that language bindings can be written
+on top of it without other sources of information.
+It is normally compiled from a GIR when a library/program is installed and
+accessed from the language binding or another application who wishes to
+use the information.
+
+Tools
+=====
+
+Three tools are shipped with GObject Introspection:
+- g-ir-compile, a typelib compiler. It converts one or more GIR files
+ into one or more typelib blobs. It can either emit the raw typelib
+ blob or C code (--code).
+- g-ir-generate, an GIR generator, using the repository API. It generates
+ GIR files from binary typelib which can be in a shared object, or a raw
+ typelib blob.
+- g-ir-scanner, a tool which generates GIR XML files by parsing headers
+ and introspecting GObject based libraries.
+
+API library
+===========
+
+There's also a C based library called libgirepository which provides
+an API to access to the typelib metadata. It also contains an API to
+invoke functions, given the function info object. The implementation is
+based on libffi (3.0 or higher of libffi required, can be found at
+http://sourceware.org/libffi).
+
+There are a number of GIR test files in tests/, and a script to do
+roundtrip tests (GIR -> typelib -> GIR).
+
+Helping out
+===========
+The introspection framework needs a lot more work, see TODO.
+
+Homepage
+========
+http://live.gnome.org/GObjectIntrospection
+
+Reporting bugs
+==============
+Bugs should be reported in http://bugzilla.gnome.org/, the glib product and
+the introspection component.
+
+Contact
+=======
+Mail: gtk-devel-list@gnome.org
+IRC: #introspection@irc.gnome.org