[mm-common] Put overview documentation into README file

[Daniel Elstner <daniel src gnome org>]

commit 34347ab40e488902cda0365edfb4d0d384bf643d
Author: Daniel Elstner <danielk openismus com>
Date:   Mon Aug 17 19:13:23 2009 +0200

    Put overview documentation into README file
    
    * README: Compile the overview sent to the gtkmm mailing list into
    a proper document.  Make the text slightly more formal and provide
    explanations for some things not covered in the original mail.
    Mention that the shipped libstdc++.tag file was not created by us.

 README |  179 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 176 insertions(+), 3 deletions(-)
---
diff --git a/README b/README
index ac5c8dd..436202e 100644
--- a/README
+++ b/README
@@ -1,6 +1,179 @@
+This module is part of the GNOME C++ bindings effort <http://www.gtkmm.org/>.
+
 The mm-common module provides the build infrastructure and utilities
 shared among the GNOME C++ binding libraries.  It is only a required
-dependency for building the C++ bindings from the version control
-repository.  It is not required for building tarball releases.
+dependency for building the C++ bindings from the gnome.org version
+control repository.  An installation of mm-common is not required for
+building tarball releases, unless configured to use maintainer-mode.
 
-This module is part of the GNOME C++ bindings effort <http://www.gtkmm.org/>.
+Release archives of mm-common include the Doxygen tag file for the
+GNU C++ Library reference documentation.  It is covered by the same
+licence as the source code is was extracted from.  More information
+is available at <http://gcc.gnu.org/onlinedocs/libstdc++/>.
+
+mm-common overview
+==================
+
+The following sections provide an overview of the various files shipped
+with mm-common, and briefly explain their purpose.  Detailed documentation
+and usage instructions can be found in the files themselves.
+
+mm-common-prepare
+-----------------
+
+The mm-common-prepare shell script is installed in ${bindir} and must be
+invoked from the bootstrap script of a binding module in order to set up
+necessary support files in the project's source tree.  It should be run
+before any of Autotools own setup utilities.  The classic command line
+options such as --copy and --force can be used to adjust the behavior of
+mm-common-prepare.  A typical autogen.sh would look like this:
+
+  #! /bin/sh -e
+  test -n "$srcdir" || srcdir=`dirname "$0"`
+  test -n "$srcdir" || srcdir=.
+
+  mm-common-prepare --force --copy "$srcdir"
+  autoreconf --force --install "$srcdir"
+  test -n "$NOCONFIGURE" || "$srcdir/configure" --enable-maintainer-mode "$@"
+
+Do not forget to set:
+
+  ACLOCAL_AMFLAGS = -I build ${ACLOCAL_FLAGS}
+
+in your project's top-level Makefile.am.  "build" should be changed to the
+name of the Autoconf M4 macro subdirectory of your project source tree.
+Also note that mm-common-prepare inspects the project's configure.ac file
+for the AC_CONFIG_AUX_DIR([...]) argument.  This is explained in further
+detail below in the section on Automake include files.
+
+Autoconf M4 macros
+------------------
+
+The Autoconf M4 macros are installed into the system-wide macro repository
+in the ${datadir}/aclocal directory.  Since all used M4 macros are copied
+into aclocal.m4, these macro files are required only in maintainer-mode.
+For this reason, they are not copied into the source tree of a project by
+mm-common-prepare.  If mm-common is installed to a different prefix than
+Automake, it may be necessary to adjust ACLOCAL_FLAGS accordingly so that
+aclocal can find the M4 files.
+
+macros/mm-common.m4: (generated from macros/mm-common.m4.in)
+  Provides MM_PREREQ() for requiring a minimum version of mm-common, and
+  an internal initialization macro shared by the other mm-common macros.
+
+macros/mm-warnings.m4:
+  Implements the MM_ARG_ENABLE_WARNINGS() Autoconf macro for easy setup
+  of compiler diagnostics through the --enable-warnings configure option.
+
+macros/mm-doc.m4:
+  Implements the MM_ARG_ENABLE_DOCUMENTATION() Autoconf macro to intialize
+  the documentation support for a C++ binding package.  Among other things,
+  it provides the --enable-documentation configure option, and checks for
+  the required utilities.
+  The other Autoconf macro defined here is MM_ARG_WITH_TAGFILE_DOC(), which
+  ties all the ends together in order to make cross-referencing to external
+  documentation work.  This macro should be called once for each external
+  Doxygen tag file a binding package depends on.  It implements a configure
+  option to override tag file locations, attempts automatic configuration
+  if possible, and takes care of building the list of tag files and their
+  default base paths for substitution into the configuration Doxyfile.  It
+  also generates the command line options for doc-install.pl.
+
+macros/mm-module.m4:
+  The magic MM_INIT_MODULE() macro takes care of defining the various
+  substitution variables and preprocessor macros to identify the name,
+  version and API version of a C++ binding module.
+
+macros/mm-pkg.m4:
+  The helper macro MM_PKG_CONFIG_SUBST, which simplifies the retrieval of
+  specific configuration values from pkg-config.
+
+macros/mm-dietlib.m4:
+  Implements Autoconf macros which provide options intended to reduce the
+  binary size of the generated binding library, typically for embedded use.
+
+Automake include files
+----------------------
+
+The Automake include files are located in the build/ directory.  The
+installed mm-common-prepare program copies all of the .am files into
+a project's source tree.  If AC_CONFIG_AUX_DIR([...]) is specified in
+the configure.ac file, the .am files will be placed in the indicated
+subdirectory.
+
+build/generate-binding.am:
+  Variables and rules for running the gmmproc code generate to produce
+  the source code files for a C++ binding module.
+
+build/compile-binding.am:
+  Variables and rules for compiling and linking the shared library which
+  implements a C++ binding module.
+
+build/doc-reference.am:
+  Variables and rules for building the API reference documentation using
+  Doxygen, and to create a Devhelp book for the library.  The installation
+  rules also take care of translating references to external documentation
+  in the generated hypertext documents.
+
+build/dist-changelog.am:
+  A dist-hook rule to automatically generate a ChangeLog file when making
+  a release, intended to be used by modules which use the version control
+  log exclusively to document changes.
+
+Documentation utilities
+-----------------------
+
+These are two Perl scripts and one XSL transformation which assist with
+the task of generating and installing the Doxygen reference documentation.
+At least doc-install.pl is also required for tarball builds.  To avoid
+copying these files into all binding modules, they are also distributed
+and installed by the glibmm module.  Those binding modules which cannot
+depend on glibmm must call MM_CONFIG_DOCTOOL_DIR([...]) in configure.ac
+to indicate to mm-common-prepare that it should copy the documentation
+utilities into the project's source tree.  Otherwise the files installed
+with glibmm will be used automatically.
+
+util/doc-postprocess.pl:
+  A simple script to post-process the HTML files generated by Doxygen.
+  It replaces various code constructs that do not match the coding style
+  used throughout the C++ bindings.  For instance, it rewrites function
+  prototypes in order to place the reference symbol (&) next to the type
+  instead of the name of the argument.
+
+util/doc-install.pl:
+  A replacement for the installdox script generated by Doxygen.  Its
+  purpose is to translate references to external documentation at the
+  time the documentation is installed.  This step is necessary because
+  the documentation is included in the tarballs, and the location of
+  external documentation on the installation system is not known at the
+  time the documentation is generated.
+  Apart from replacing the functionality of installdox, doc-install.pl
+  also acts as a drop-in replacement for the classic BSD install command
+  for easy integration with Automake.  It also translates Devhelp books
+  as well, and will happily pass through unrecognized files without any
+  alterations.
+
+util/tagfile-to-devhelp2.xsl:
+  An XSLT script to generate a Devhelp2 book for the Doxygen reference
+  documentation.  The generated Doxygen tag file serves as the input of
+  the translation.
+
+GNU C++ Library tag file
+------------------------
+
+All modules in the GNOME C++ bindings set make use of the C++ standard
+library in the API.  As the GNU C++ Library shipped with GCC also uses
+Doxygen for its reference documentation, its tag file is made available
+by mm-common at a shared location for use by all C++ binding modules.
+
+doctags/libstdc++.tag:
+  The Doxygen tag file for the GNU libstdc++ reference documentation
+  hosted at <http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/>.
+  This file is distributed with release archives of mm-common, but not
+  checked into version control on gnome.org.  If mm-common is built in
+  maintainer-mode, the file will be downloaded automatically from the
+  gcc.gnu.org web server.
+  The file libstdc++.tag is installed into the package data directory
+  of mm-common.  The mm-common-libstdc++ pkg-config module defines the
+  variables ${doxytagfile} and ${htmlrefpub}, which can be queried for
+  the location of the tag file and the URL of the online documentation.