updates for release

Original commit message from CVS:
updates for release

1 files changed, 91 insertions, 79 deletions

diff --git a/README b/README
index 1bd0d623f..6bdc2cab5 100644
--- a/README
+++ b/README
@@ -1,83 +1,86 @@
 WHAT IT IS
 ----------
-This is gst-plugins, a set of plug-ins for GStreamer.
+This is GStreamer, a framework for streaming media.
+
+This package is in the 0.9.x series.  This means that this is a
+development series leading up to a stable 0.10.x series.
+You have been warned.
+
+OVERVIEW
+--------
+GStreamer is split up over a number of modules, tarballs and packages:
+
+- gstreamer:
+  The core.  It contains the main library and header files, as well as
+  some fundamental elements.  Every GStreamer project needs at least this
+  installed.
+- gst-plugins-base:
+  A base set of plugins.  This set is the set we actively keep synchronized
+  with the core and are also meant to serve as examples on how to write
+  GStreamer elements.  It also contains a number of base classes for writing
+  GStreamer elements.
+
+INSTALLING FROM PACKAGES
+------------------------
+You should always prefer installing from packages first.  GStreamer is
+well-maintained for a number of distributions, including Fedora, Debian,
+Ubuntu, Mandrake, Gentoo, ...
+
+Only in cases where you:
+- want to hack on GStreamer
+- want to verify that a bug has been fixed
+- do not have a sane distribution
+should you choose to build from source tarballs or CVS.
+
+Find more information about the various packages at
+http://gstreamer.freedesktop.org/download/
+
+COMPILING FROM SOURCE TARBALLS
+------------------------------
+- again, make sure that you really need to install from source !
+  If GStreamer is one of your first projects ever that you build from source,
+  consider taking on an easier project.
 
-COMPILING FROM SOURCE
----------------------
-- make sure you compiled and at least did a test-run of GStreamer (core)
 - check output of ./configure --help to see if any options apply to you
-- configure the source tree:
-  - if you installed GStreamer, then do:
-      ./configure
-    If configure complains about missing GStreamer, you should try the 
-    following command:
-    $export PKG_CONFIG_PATH=prefix/lib/pkgconfig
-    where prefix should be replaced by the prefix you used to configure
-    GStreamer. (Be mindful NOT to ADD a trailing / to that option !).
-    After that, rerun ./configure. If this doesn't fix it, you have other
-    issues ;)
-
-  - if you didn't install GStreamer, you can still compile the plug-ins.
-    Add the path to gstreamer-uninstalled.pc (which lives in the gstreamer
-    source tree) to PKG_CONFIG_PATH
-    or run configure --with-pkg-config-path=(path to gstreamer uninstalled)
-  
-  - the output of configure will give you a list of plug-ins with external
-    dependencies (ie, depending on other libs, see below).  By no means
-    should you try to get them all built on your first run.  This is hard
-    enough as it is ;)  Resist the urge to get the most features for now.
-    It doesn't list all of the non-depending plug-ins, which get built
-    regardless (unless you explicitly asked it not to).
-
-- build the tree:
+- run
+  ./configure
   make
-  If any plug-in causes a problem at this stage, you should re-configure
-  with --disable-(dependency)
-  and doublecheck if configure reports this plug-in as being disabled.
-  Then re-run make.
-
-- install:
-  - if you installed GStreamer, and want to install the plug-ins as well, run
-      make install
-    and, as root, run
-      gst-register
-  - if you installed GStreamer, but don't want to install the plug-ins, run
-      gst-register --gst-plugin-path=.
-  - if you didn't install GStreamer, then do
-      path/to/gstreamer/tools/gst-register --gst-plugin-path=.
-      (Replace path/to/gstreamer obviously)
-
-- test:
-  - run 
-     gst-launch sinesrc ! fakesink
-   and prefix gst-launch with the path to gstreamer/tools if you didn't install
-   GStreamer.
-   If this doesn't give any errors, you can abort it.  
-
-  - try replacing fakesink with your choice of 
-    osssink/esdsink/artsdsink/alsasink/jacksink (depending on what output
-    method you have available) and see if you hear a C tone.
-
-- After this, you should look into installing an application, like
-  gst-player, gst-editor or monkey-media with rhythmbox.
+
+  to build GStreamer.
+- if you want to install it (not required), run
+  make install
+- You should create a registry for things to work.
+  If you ran make install in the previous step, run
+  gst-register
+  as root.
+
+  If you didn't install, run
+  tools/gst-register
+  as a normal user.
+
+- try out a simple test:
+  gst-launch fakesrc num_buffers=5 ! fakesink
+  (If you didn't install GStreamer, again prefix gst-launch with tools/)
+
+  If it outputs a bunch of messages from fakesrc and fakesink, everything is
+  ok.
+
+- After this, you're ready to install gst-plugins, which will provide the
+  functionality you're probably looking for by now, so go on and read
+  that README.
 
 COMPILING FROM CVS
 ------------------
-When building from CVS sources, you will need to run autogen.sh to generate
+When building from CVS sources, you will need to run autogen.sh to generate 
 the build system files.
 
-GStreamer is cutting-edge stuff.  To be a CVS developer, you need
-what used to be considered cutting-edge tools.
+You will need a set of additional tools typical for building from CVS,
+including:
+- autoconf
+- automake
+- libtool
 
-ATM, most of us have at least these versions :
-
-* autoconf      2.52    (NOT 2.52d)
-* automake      1.5     
-* gettext	0.11.5
-* libtool       1.4     (NOT Gentoo's genetic failure 1.4.2)
-* pkg-config    0.8.0
-
-autogen.sh will check for these versions and complain if you don't have 
+autogen.sh will check for recent enough versions and complain if you don't have
 them.  You can also specify specific versions of automake and autoconf with
 --with-automake and --with-autoconf
 
@@ -87,8 +90,6 @@ autogen.sh can pass on arguments to configure - you just need to separate them
 from autogen.sh with -- between the two.
 prefix has been added to autogen.sh but will be passed on to configure because
 some build scripts like that.
-You will probably have to pass at least --with-pkg-config-path to autogen.sh
-to point to the CVS version of GStreamer.
 
 When you have done this once, you can use autoregen.sh to re-autogen with
 the last passed options as a handy shortcut.  Use it.
@@ -96,14 +97,25 @@ the last passed options as a handy shortcut.  Use it.
 After the autogen.sh stage, you can follow the directions listed in
 "COMPILING FROM SOURCE"
 
+You can also run your whole cvs stack uninstalled.  The script in
+the gstreamer module /docs/faq/gst-uninstalled) is helpful in setting
+up your environment for this.
+
 PLUG-IN DEPENDENCIES AND LICENSES
 ---------------------------------
-GStreamer is developed under the terms of the LGPL (see LICENSE file for 
-details). Some of our plug-ins however rely on libraries which are available 
-under other licenses. This means that if you are using an application which 
-has a non-GPL compatible license (for instance a closed-source application) 
+GStreamer is developed under the terms of the LGPL (see LICENSE file for
+details). Some of our plug-ins however rely on libraries which are available
+under other licenses. This means that if you are using an application which
+has a non-GPL compatible license (for instance a closed-source application)
 with GStreamer, you have to make sure not to use GPL-linked plug-ins.
-When using GPL-linked plug-ins, GStreamer is for all practical reasons 
-under the GPL itself. 
-
-There is a LICESENSE_readme file containing licensing information on the plugins
+When using GPL-linked plug-ins, GStreamer is for all practical reasons
+under the GPL itself.
+
+HISTORY
+-------
+The fundamental design comes from the video pipeline at Oregon Graduate
+Institute, as well as some ideas from DirectMedia.  It's based on plug-ins that
+will provide the various codec and other functionality.  The interface
+hopefully is generic enough for various companies (ahem, Apple) to release
+binary codecs for Linux, until such time as they get a clue and release the
+source.