Convert README to README.md and OVERVIEW.md

* README -> README.md + OVERVIEW.md
* meson.build: Install README.md and OVERVIEW.md
* Makefile.am: Distribute and install README.md and OVERVIEW.md
* configure.ac: Set `foreign` option to automake.
Without the `foreign` option, old versions of automake require
a README file, which no longer exists. New versions (like 1.16.5)
without the `foreign` option require README or README.md.

5 files changed, 94 insertions, 97 deletions

diff --git a/Makefile.am b/Makefile.am
index c3182b4..03aa1e4 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -77,7 +77,7 @@ noinst_DATA = \
 	doctags/mm-common-libstdc++-uninstalled.pc \
 	util/mm-common-util-uninstalled.pc
 
-dist_doc_DATA = README
+dist_doc_DATA = README.md OVERVIEW.md
 doc_DATA = skeletonmm.tar.gz
 
 skeletonmm_data_files =							\
diff --git a/README b/OVERVIEW.md
index 6b1ce92..6fec949 100644
--- a/README
+++ b/OVERVIEW.md
@@ -1,52 +1,10 @@
-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 gnome.org version
-control repository.  An installation of mm-common is not required for
-building tarball releases, unless configured to use maintainer-mode.
-
-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 it was extracted from.  More information
-is available at <http://gcc.gnu.org/onlinedocs/libstdc++/>.
-
-Autotools or Meson?
-===================
-
-mm-common can be built with Autotools or Meson. Building with Autotools
-may be phased out in the future.
-
-The files that mm-common installs and mm-common-prepare copies to other
-modules are useful in modules that are built with Autotools.
-The files that mm-common installs and mm-common-get copies to other
-modules are useful in modules that are built with Meson.
-
-The files in the skeletonmm directory show the start of a project that will
-use Meson.
-
-Skeleton C++ binding module
-===========================
-
-When creating a new C++ binding module based on mm-common, the easiest way
-to get started is to copy the skeletonmm directory shipped with mm-common.
-It contains the build support files required for a C++ binding module using
-Meson, gmmproc and glibmm.
-
-In order to create a new binding project from the copied skeleton directory,
-any files which have "skeleton" in the filename must be renamed.  References
-to the project name or author in the files need to be substituted with the
-actual name and author of the new binding.
-
-mm-common overview
-==================
+# 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 and Autotools
--------------------------------
+## mm-common-prepare and Autotools
 
 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
@@ -54,7 +12,7 @@ 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=.
@@ -62,24 +20,23 @@ mm-common-prepare.  A typical autogen.sh would look like this:
   mm-common-prepare --copy --force "$srcdir"
   autoreconf --force --install --verbose "$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's 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.
 
-mm-common-get and Meson
------------------------
+## mm-common-get and Meson
 
 The mm-common-get shell script is installed in ${bindir} and must be
 invoked with run_command() early in a meson.build file. The meson.build file
 should contain code similar to
-
+```
   python3 = import('python').find_installation()
   cmd_py = '''
   import os
@@ -106,9 +63,9 @@ should contain code similar to
       check: true,
     )
   endif
+```
 
-Autoconf M4 macros (Autotools)
-------------------------------
+## Autoconf M4 macros (Autotools)
 
 The Autoconf M4 macros are installed into the system-wide macro repository
 in the ${datadir}/aclocal directory.  Since all used M4 macros are copied
@@ -117,22 +74,22 @@ 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_PATH accordingly so that
 aclocal can find the M4 files:
-
+```
   export ACLOCAL_PATH="${mm_common_prefix}/share/aclocal"
-
+```
 This step is not necessary when using jhbuild, as it takes care of setting
 up the environment for using the locally built modules.
 
-macros/mm-common.m4: (generated from macros/mm-common.m4.in)
+- 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:
+- 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
+- macros/mm-doc.m4: \
+  Implements the MM_ARG_ENABLE_DOCUMENTATION() Autoconf macro to initialize
   the documentation support for a C++ binding package.  Among other things,
   it provides the --enable-documentation configure option, and checks for
   the required utilities.
@@ -145,31 +102,30 @@ macros/mm-doc.m4:
   default base paths for substitution into the configuration Doxyfile.  It
   also generates the command line options for doc-install.pl.
 
-macros/mm-module.m4:
+- 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:
+- macros/mm-pkg.m4: \
   The helper macro MM_PKG_CONFIG_SUBST, which simplifies the retrieval of
   specific configuration values from pkg-config.  Checks for particular
   utility programs are also defined here, such as MM_CHECK_GNU_MAKE and
   MM_CHECK_PERL.
 
-macros/mm-dietlib.m4:
+- 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.
   The MM_PROG_GCC_VISIBILITY macro is defined in this file as well.
 
-macros/mm-ax_cxx_compile_stdcxx.m4:
+- macros/mm-ax_cxx_compile_stdcxx.m4: \
   Implements the MM_AX_CXX_COMPILE_STDCXX() macro to test and set flags
   for C++11/14/17 compatibility of the C++ compiler. This is identical to the
   AX_CXX_COMPILE_STDCXX() macro described at
-  http://www.gnu.org/software/autoconf-archive/ax_cxx_compile_stdcxx.html,
+  <http://www.gnu.org/software/autoconf-archive/ax_cxx_compile_stdcxx.html>,
   except for the MM_ prefix.
 
-Automake include files (Autotools)
-----------------------------------
+## Automake include files (Autotools)
 
 The Automake include files are located in the am_include/ directory.
 The installed mm-common-prepare program copies all of the .am files into
@@ -177,65 +133,64 @@ 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.
 
-am_include/generate-binding.am:
+- am_include/generate-binding.am: \
   Variables and rules for running the gmmproc code generator to produce
   the source code files for a C++ binding module.
 
-am_include/compile-binding.am:
+- am_include/compile-binding.am: \
   Variables and rules for compiling and linking the shared library which
   implements a C++ binding module.
 
-am_include/doc-reference.am:
+- am_include/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.
 
-am_include/dist-changelog.am:
+- am_include/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.
 
-Python build scripts (Meson)
-----------------------------
+## Python build scripts (Meson)
 
 These scripts can be called from meson.build files with run_command(),
 custom_target(), meson.add_postconf_script(), meson.add_install_script()
 and meson.add_dist_script().
 
-util/build_scripts/generate-binding.py:
+- util/build_scripts/generate-binding.py: \
   Commands for running the gmmproc code generator to produce
   the source code files for a C++ binding module.
 
-util/build_scripts/doc-reference.py:
+- util/build_scripts/doc-reference.py: \
   Commands 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.
 
-util/build_scripts/dist-changelog.py:
+- util/build_scripts/dist-changelog.py: \
   A git command to generate a ChangeLog file when making a release,
   intended to be used by modules which use the version control
   log exclusively to document changes.
 
-util/build_scripts/dist-build-scripts.py:
+- util/build_scripts/dist-build-scripts.py: \
   Commands that trim the distribution directory before a tarball is made.
   The scripts copied by mm-common-get are distributed, although they are
   not checked into the git repository. All .gitignore files and an empty build/
   directory are removed
 
-util/build_scripts/check-dllexport-usage.py:
-  Command that checks on the gmmproc version that is to be used or been used
+- util/build_scripts/check-dllexport-usage.py: \
+  Command that checks on the gmmproc version that is to be used or has been used
   to generate the sources, to check whether to use compiler directives to
   export symbols.  Only used for Visual Studio or clang-cl builds.
 
-Documentation utilities (Meson and Autotools)
----------------------------------------------
+## Documentation utilities (Meson and Autotools)
 
-These are two Perl scripts, a style sheet, 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.
+These are two Perl scripts and two equivalent Python scripts, a style sheet,
+and one XSL transformation which assist with the task of generating and installing
+the Doxygen reference documentation.  At least doc-install.pl or doc-install.py
+is also required for tarball builds. Autotools uses the Perl scripts.
+Meson uses the Python scripts.
 
 Autotools: To avoid copying these files into all binding modules, they are
 distributed and installed with the mm-common module.  Those binding modules
@@ -244,16 +199,16 @@ 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 mm-common will be used automatically.
 
-util/doc-postprocess.pl:
-util/doc_postprocess.py:
+- util/doc-postprocess.pl: \
+  util/doc_postprocess.py: \
   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:
-util/doc_install.py:
+- util/doc-install.pl: \
+  util/doc_install.py: \
   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
@@ -266,29 +221,28 @@ util/doc_install.py:
   as well, and will happily pass through unrecognized files without any
   alterations.
 
-util/doxygen.css:
+- util/doxygen.css: \
   A Cascading Style Sheet to unify the appearance of the HTML reference
   documentation generated by Doxygen for each C++ binding module.
   This file is deprecated. Use util/doxygen-extra.css instead.
 
-util/doxygen-extra.css:
+- util/doxygen-extra.css: \
   A Cascading Style Sheet to unify the appearance of the HTML reference
   documentation generated by Doxygen for each C++ binding module.
 
-util/tagfile-to-devhelp2.xsl:
+- 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
-------------------------
+## 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:
+- 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
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..995fa91
--- /dev/null
+++ b/README.md
@@ -0,0 +1,43 @@
+# mm-common
+
+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 gnome.org version
+control repository.  An installation of mm-common is not required for
+building tarball releases, unless configured to use maintainer-mode.
+
+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 it was extracted from.  More information
+is available at <http://gcc.gnu.org/onlinedocs/libstdc++/>.
+
+# Autotools or Meson?
+
+mm-common can be built with Autotools or Meson. Autotools support may be
+dropped in the future.
+
+The files that mm-common installs and mm-common-prepare copies to other
+modules are useful in modules that are built with Autotools.
+The files that mm-common installs and mm-common-get copies to other
+modules are useful in modules that are built with Meson.
+
+The files in the skeletonmm directory show the start of a project that will
+use Meson.
+
+# Skeleton C++ binding module
+
+When creating a new C++ binding module based on mm-common, the easiest way
+to get started is to copy the `skeletonmm` directory shipped with mm-common.
+It contains the build support files required for a C++ binding module using
+Meson, gmmproc and glibmm.
+
+In order to create a new binding project from the copied skeleton directory,
+any files which have `skeleton` in the filename must be renamed.  References
+to the project name or author in the files need to be substituted with the
+actual name and author of the new binding.
+
+# mm-common overview
+
+See [OVERVIEW.md](OVERVIEW.md) for an overview of the files shipped with mm-common.
diff --git a/configure.ac b/configure.ac
index eed33d7..06b0012 100644
--- a/configure.ac
+++ b/configure.ac
@@ -20,7 +20,7 @@ AC_INIT([mm-common], [1.0.4], [https://gitlab.gnome.org/GNOME/mm-common/issues/]
 AC_PREREQ([2.59])
 AC_CONFIG_SRCDIR([util/mm-common-prepare.in])
 
-AM_INIT_AUTOMAKE([1.9 -Wno-portability check-news no-dist-gzip dist-xz no-define std-options])
+AM_INIT_AUTOMAKE([1.9 -Wno-portability check-news no-dist-gzip dist-xz no-define std-options foreign])
 # Support silent build rules.
 # Disable by either passing --disable-silent-rules to configure or passing V=1 to make.
 m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])])
diff --git a/meson.build b/meson.build
index 8a18c36..821f5c6 100644
--- a/meson.build
+++ b/meson.build
@@ -272,7 +272,7 @@ custom_target(tarball_filename,
   install_dir: install_docdir,
   install: true
 )
-install_data('README', install_dir: install_docdir)
+install_data('OVERVIEW.md', 'README.md', install_dir: install_docdir)
 
 # Either curl or wget is required for downloading libstdc++.tag,
 # used by Doxygen.