- Put stuff in the README. Sri is my bitch.

* README:
- Put stuff in the README.  Sri is my bitch.

1 files changed, 89 insertions, 0 deletions

diff --git a/README b/README
index e69de29..67d3e1f 100644
--- a/README
+++ b/README
@@ -0,0 +1,89 @@
+ABOUT
+=====
+gnome-doc-utils is a collection of documentation utilities for the Gnome
+project.  Notably, it contains utilities for building documentation and
+all auxiliary files in your source tree, and it contains the DocBook
+XSLT stylesheets that were once distributed with Yelp.  Starting with
+Gnome 2.8, Yelp will require gnome-doc-utils for the XSLT.
+
+ORGANIZATION
+============
+test/
+	The test directory contains a number of tests for gnome-doc-utils.
+	Directories of the form testdocn, where n is a positive integer,
+	are skeleton source trees containing documentation, with the same
+	layout that would be used by actual projects.
+
+	The testdocs directory contains the unit tests from docbook-testdocs,
+	developed by Norm and Co. for the pan-galactic DocBook stylesheets.
+	An additional README file is in that directory, giving instructions
+	on extending or changing any of the files in gnome-doc-utils CVS.
+
+doc/
+	The doc directory contains documentation for gnome-doc-utils.  In
+	most cases, gnome-doc-utils is required to build its documentation.
+	Mechanisms are in place for bootstrapping.
+
+xslt/
+	The xslt directory contains all of the XSLT in gnome-doc-utils.
+	Notably, the xslt/docbook directory contains the DocBook XSLT,
+	and xslt/gettext contains the XSLT gettext utility for translating
+	automatic text.
+   
+sandbox/
+	The sandbox directory is not DISTed, so it will only appear if you
+	have a CVS checkout.  It's a playground for new ideas.
+
+xml2po/
+	The xml2po directory contains the xml2po tool developed by Danilo
+	Segan for translation of arbitrary XML formats.  It is used by
+	gnome-doc-utils for DocBook translation.
+
+TESTING
+=======
+Under the test directory are a number of tests for gnome-doc-utils.  To
+test the build system (gnome-doc-utils.m4 and gnome-doc-utils.make), you
+can use any of the testdocn (for n a positive integer) directories.  These
+are set up as skeleton source trees, behaving exactly as a real project
+would.  Also, gnome-doc-utils uses itself to build its own documentation
+(under doc), so gnome-doc-utils itself is a test of the build tools.
+
+To test the DocBook stylesheets, use the test/testdocs directory.  These
+unit tests are from the docbook-testdocs package on docbook.sourceforge.net,
+developed by Norm and Co.  Simply typing make in that directory will build
+each test.  If the name of the test file is foo.001.xml, the output will be
+html/foo.001/foo.001.html.  Each test generally tests a small number of
+related DocBook elements.  Many of the features of DocBook or of the XSLT
+in gnome-doc-utils might not be tested by these.  Additional tests may
+be added; follow the instructions in test/testdocs/README for that.
+
+Also useful for testing the XSLT is to transform some large documents
+using it.  The Gnome User Guide and the Gnumeric Manual both serve as
+excellent test docs.
+
+HACKING
+=======
+Unlike most C programming, working on much of gnome-doc-utils really does
+involve isolated incremental improvements.  There's no way to give a short
+list of broad features in a TODO list.
+
+To work on the build tools (gnome-doc-utils.m4 and gnome-doc-utils.make),
+build the test docs and see what doesn't work.  gnome-doc-utils.make has
+a list of all the high-level targets that should be fully supported.
+
+To work on the DocBook XSLT, find an element that isn't implemented yet and
+implement it.  If you have XML Starlet (xmlstar.sourceforge.net) installed, 
+you can type 'make report.html' in the xslt/docbook/html directory to get
+a nice HTML report on what elements are implemented.  There is also a TODO
+file in this directory with a very succinct list of matches that need to be
+done that can't be caught by report.html.
+
+Note that the XSLT is documented inline with xsldoc, which is itself a part
+of gnome-doc-utils.  Feel free to work on xsldoc as well.  The documentation
+generated by xsldoc is included in the manual under doc/xslt.
+
+When in doubt, talk to Shaun McCance <shaunm@gnome.org>.  Never commit without
+permission, unless Shaun has told you otherwise.  Wash behind your ears.  Don't
+take candy from strangers.  Support independant musicicians.
+
+