[glom] Documentation: Added libglom main page. Installed _sources for pyglom.

[Murray Cumming <murrayc src gnome org>]

commit 3576e8f3ea50d4553c7cf6c97f9080dcfb2806ec
Author: Murray Cumming <murrayc murrayc com>
Date:   Tue Apr 27 10:06:33 2010 +0200

    Documentation: Added libglom main page. Installed _sources for pyglom.
    
    * docs/pyglom_reference/Makefile.am: Also install html/_sources, used by search.
    * glom/libglom/init.h: Add a doxygen main page.

 ChangeLog                         |   17 ++++++++---
 docs/pyglom_reference/Makefile.am |    2 +
 glom/libglom/init.h               |   53 +++++++++++++++++++++++++++++++++++++
 3 files changed, 67 insertions(+), 5 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 2829b6f..c9a94a2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,9 +1,16 @@
+2010-04-27  Murray Cumming  <murrayc murrayc-desktop>
+
+    Documentation: Added libglom main page. Installed _sources for pyglom.
+
+	* docs/pyglom_reference/Makefile.am: Also install html/_sources, used by search.
+	* glom/libglom/init.h: Add a doxygen main page.
+
 2010-04-26  Murray Cumming  <murrayc murrayc com>
 
 	Fix the build.
 
-	* Makefile_tests.am: test_selfhosting_new_empty: Link to the Glom sources 
-	to fix the unresolved link to Glom::Priv's method. We will use more from 
+	* Makefile_tests.am: test_selfhosting_new_empty: Link to the Glom sources
+	to fix the unresolved link to Glom::Priv's method. We will use more from
 	the rest of Glom here too.
 
 2010-04-26  Daniel Elstner  <danielk openismus com>
@@ -20,9 +27,9 @@
 2010-04-26  Murray Cumming  <murrayc murrayc com>
 
 	Reenable test_load_document.
-	
+
 	* Makefile_tests.am: Reenable test_load_document.cc
-	* tests/test_load_document/test_load_document.cc: Restore (rewrite) this 
+	* tests/test_load_document/test_load_document.cc: Restore (rewrite) this
 	missing file.
 
 2010-04-26  Murray Cumming  <murrayc murrayc com>
@@ -32,7 +39,7 @@
 2010-04-26  Murray Cumming  <murrayc murrayc com>
 
 	Self-Hosting test: Check that cleanup works.
-	
+
 	* Makefile_tests.am:
 	* glom/libglom/connectionpool.[h|cc]:
 	* glom/libglom/connectionpool_backends/backend.[h|cc]:
diff --git a/docs/pyglom_reference/Makefile.am b/docs/pyglom_reference/Makefile.am
index c219d01..57b5ca0 100644
--- a/docs/pyglom_reference/Makefile.am
+++ b/docs/pyglom_reference/Makefile.am
@@ -22,6 +22,7 @@ libdocdir    = $(datarootdir)/doc/$(book_name)
 referencedir = $(libdocdir)/reference
 htmlrefdir   = $(referencedir)/html
 htmlref_staticdir = $(htmlrefdir)/_static
+htmlref_sourcesdir = $(htmlrefdir)/_sources
 
 # Function: $(call vpath_listall,PATTERN ...)
 # Get all filenames which match a PATTERN from the list.  Look for files
@@ -32,6 +33,7 @@ vpath_listall = $(sort $(wildcard $(1)) $(if $(srcdir:.=),$(vpath_srclist)))
 
 dist_htmlref_DATA = $(call vpath_listall,$(addprefix $(html_outdir)/,$(htmlref_patterns)))
 dist_htmlref_static_DATA = $(call vpath_listall,$(addprefix $(html_outdir)/_static/,$(htmlref_patterns)))
+dist_htmlref_sources_DATA = $(call vpath_listall,$(addprefix $(html_outdir)/_sources/,$(htmlref_patterns)))
 
 MAINTAINERCLEANFILES = $(html_outdir)/_sources/* $(html_outdir)/_static/* $(html_outdir)/*
 
diff --git a/glom/libglom/init.h b/glom/libglom/init.h
index 7d33cad..a9de801 100644
--- a/glom/libglom/init.h
+++ b/glom/libglom/init.h
@@ -21,6 +21,59 @@
 #ifndef GLOM_LIBGLOM_INIT_H
 #define GLOM_LIBGLOM_INIT_H
 
+/** @mainpage libglom Reference Manual
+ *
+ * @section description Description
+ *
+ * libglom provides API to access Glom's XML-based Glom::Document structure.
+ * Applications may use it to load a .glom document and then call methods
+ * on the document to discover the connection details and the data structure, including:
+ * - The list of tables
+ * - The list of fields in each table
+ * - The details of each field, such as field type, title, default value, formatting, etc.
+ * - The relationships between tables.
+ * - The layout of fields on list and details views.
+ * - The layout of print layouts.
+ * - The layout of reports.
+ *
+ * libglom also contains utility functions, such as
+ * Glom::Utils::build_sql_select_with_where_clause(), to build the complicated SQL queries
+ * used by Glom to retrieve information from the database.
+ *
+ * See http://git.gnome.org/browse/glom/tree/glom/libglom/example_document_load.cc
+ * for a small working example.
+ *
+ * @section warning Warning
+ *
+ * libglom is not yet API stable, not properly documented, not thoroughly tested,
+ * and not yet really intended for serious use by applications other than
+ * <a href="http://www.glom.org/";>Glom</a> and
+ * <a href="http://gitorious.org/qlom";>Qlom</a>.
+ *
+ * @section basics Basic Usage
+ *
+ * Include the individual libglom headers. For instance:
+ * @code
+ * #include <libglom/document/document.h>
+ * @endcode
+ *
+ * If your source file is @c program.cc, you can compile it with:
+ * @code
+ * g++ program.cc -o program  `pkg-config --cflags --libs glom-1.14`
+ * @endcode
+ *
+ * Alternatively, if using autoconf, use the following in @c configure.ac:
+ * @code
+ * PKG_CHECK_MODULES([DEPS], [glom-1.14])
+ * @endcode
+ * Then use the generated @c DEPS_CFLAGS and @c DEPS_LIBS variables in the
+ * project @c Makefile.am files. For example:
+ * @code
+ * program_CPPFLAGS = $(DEPS_CFLAGS)
+ * program_LDADD = $(DEPS_LIBS)
+ * @endcode
+ */
+
 namespace Glom
 {