convert index.html to README.rst

This is a bit more discoverable, and easier to read for humans.

5 files changed, 152 insertions, 191 deletions

diff --git a/CMakeLists.txt b/CMakeLists.txt
index 198befb6..2c58ab46 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -7,7 +7,7 @@ if(NOT ENABLE_CMAKE)
 	message(FATAL_ERROR
 	        "The cmake build system has been deprecated in favour of "
 	        "meson, and will be removed eventually. For instructions on "
-	        "how to use meson, see index.html.\n"
+	        "how to use meson, see README.rst.\n"
 	        "If you still want to use the autotools build, then add "
 	        "-DENABLE_CMAKE=ON to the cmake command line.")
 endif()
@@ -165,7 +165,7 @@ endif (BUILD_SHARED_LIBS AND NOT DEFINED LIBDIR)
 add_subdirectory (src)
 
 
-install (FILES index.html DESTINATION doc)
+install (FILES README.rst DESTINATION doc)
 
 set (CPACK_PACKAGE_NAME "mesa-demos")
 set (CPACK_PACKAGE_VERSION_MAJOR "8")
diff --git a/Makefile.am b/Makefile.am
index 1669f12c..8a166a01 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -30,6 +30,6 @@ AM_DISTCHECK_CONFIGURE_FLAGS = --enable-autotools
 SUBDIRS = src
 
 EXTRA_DIST = \
-	index.html \
+	README.rst \
 	meson_options.txt \
 	meson.build
diff --git a/README.rst b/README.rst
new file mode 100644
index 00000000..a5ea745a
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,148 @@
+Mesa Demos Distribution
+=======================
+
+Introduction
+------------
+
+The Mesa Demos package contains a large number of OpenGL demonstration
+and test programs.
+
+These programs were previously distributed as the MesaDemos-x.y.z.tar.gz
+package released in conjunction with the MesaLib-x.y.z.tar.gz package.
+The demos are separated now since they don't change often and
+aren't tied to a particular version of Mesa.
+
+Note that the Mesa demos should be usable with any OpenGL implementation;
+not just Mesa.
+
+FTP site
+--------
+
+The latest version of the Mesa demos can be found on the `mesa3d.org
+archives <https://archive.mesa3d.org/demos/>`_ site.
+
+Git Repository
+--------------
+
+The Mesa demos git repository can be obtained with:
+
+.. code-block:: sh
+
+  $ git clone https://gitlab.freedesktop.org/mesa/demos.git
+
+
+Building
+--------
+
+The Mesa demos can be built with `Meson <https://mesonbuild.com/>`_.
+
+
+Prerequisites
+^^^^^^^^^^^^^
+
+You'll need glut or `freeglut <http://freeglut.sourceforge.net/>`_
+(runtime libraries and header files).
+
+If you're using an RPM-based Linux distro you can install these items
+with:
+
+.. code-block:: sh
+
+  $ yum install freeglut freeglut-devel
+
+And if you're using a Debian based Linux distro you can install these
+items with:
+
+.. code-block:: sh
+
+  $ apt-get install freeglut3-dev
+
+For `Wayland <https://wayland.freedesktop.org/>`_ support,
+`wayland-protocols <https://gitlab.freedesktop.org/wayland/wayland-protocols>`_
+and
+`wayland-scanner <https://gitlab.freedesktop.org/wayland/wayland>`_
+must be available.  Additionally, to build for Wayland using CMake,
+`Extra CMake Modules <https://invent.kde.org/frameworks/extra-cmake-modules>`_
+must be available.
+
+Meson
+^^^^^
+
+Run **meson configure** to see the options available for building
+the demos.
+
+Otherwise, just run **meson build-dir; meson compile -C build-dir** to
+build the demos.
+
+See the `Meson documentation <https://mesonbuild.com/>`_ for more
+information about Meson.
+
+
+MinGW cross-compilation
+"""""""""""""""""""""""
+
+Create a **cross-file** file containing:
+
+.. code-block:: ini
+
+  [binaries]
+  c = '/usr/bin/x86_64-w64-mingw32-gcc'
+  cpp = '/usr/bin/x86_64-w64-mingw32-g++'
+  ar = '/usr/bin/x86_64-w64-mingw32-ar'
+  strip = '/usr/bin/x86_64-w64-mingw32-strip'
+  pkgconfig = 'x86_64-w64-mingw32-pkg-config'
+  exe_wrapper = 'wine'
+
+  [host_machine]
+  system = 'windows'
+  cpu_family = 'x86_64'
+  cpu = 'i686'
+  endian = 'little'
+
+Then do:
+
+.. code-block:: sh
+
+  $ meson --prefix=/path/to/install --cross-file /path/to/cross-file build-dir
+  $ meson compile -C build-dir
+  $ meson install -C build-dir
+
+The Demos
+---------
+
+Look in the **src/** directory for these sub-directories, among others:
+
+- demos - the original Mesa demos, such as gears, gloss, etc.
+- redbook - the OpenGL Programming Guide demos
+- samples- original SGI OpenGL demos
+- glsl - OpenGL Shading Language demos
+- gs - Geometry shader demos
+- xdemos - GLX-based demos
+- egl - EGL-based demos
+- wgl - WGL-based demos
+- fp - fragment program tests
+- vp - vertex program tests
+- data - data files used by the demos
+- perf - performance tests
+- tests - assorted test programs
+- objviewer - program to view .obj modes with a skybox
+
+
+Getting Help
+------------
+
+If you have trouble building or using the Mesa demos, you can post
+to the `Mesa users <http://lists.freedesktop.org/mailman/listinfo/mesa-users>`_
+mailing list.
+
+If your question is especially technical, you can try the
+to the `Mesa dev <http://lists.freedesktop.org/mailman/listinfo/mesa-dev>`_
+mailing list.
+
+
+Reporting Bugs
+--------------
+
+Bugs in the demos can be reported to the
+`Mesa demos issue tracker <https://gitlab.freedesktop.org/mesa/demos/-/issues>`_.
+
diff --git a/configure.ac b/configure.ac
index 927d2c63..1e3255c6 100644
--- a/configure.ac
+++ b/configure.ac
@@ -48,7 +48,7 @@ AC_ARG_ENABLE(autotools,
 if test "x$enable_autotools" != "xyes" ; then
     AC_MSG_ERROR([the autotools build system has been deprecated in favour
     of meson, and will be removed eventually. For instructions on how to
-    use meson, see index.html.
+    use meson, see README.rst.
 
     If you still want to use the autotools build, then add --enable-autotools
     to the configure command line.])
diff --git a/index.html b/index.html
deleted file mode 100644
index efb93992..00000000
--- a/index.html
+++ /dev/null
@@ -1,187 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<html lang="en">
-<head>
-  <meta http-equiv="content-type" content="text/html; charset=utf-8">
-  <title>Mesa Demos Distribution</title>
-  <style type="text/css">
-    <!--
-    pre { background: #cccccc; }
-	-->
-  </style>
-</head>
-<body>
-
-<h1>Introduction</h1>
-<p>
-The Mesa Demos package contains a large number of OpenGL demonstration
-and test programs.
-</p>
-
-<p>
-These programs were previously distributed as the MesaDemos-x.y.z.tar.gz
-package released in conjunction with the MesaLib-x.y.z.tar.gz package.
-The demos are separated now since they don't change often and
-aren't tied to a particular version of Mesa.
-</p>
-
-<p>
-Note that the Mesa demos should be usable with any OpenGL implementation;
-not just Mesa.
-</p>
-
-
-<h1>FTP site</h1>
-
-<p>
-The latest version of the Mesa demos can be found on the
-<a href="https://archive.mesa3d.org/demos/">mesa3d.org archives</a>
-site.
-</p>
-
-
-
-<h1>Git Repository</h1>
-
-<p>
-The Mesa demos git repository can be obtained with:
-</p>
-<pre>
-git clone https://gitlab.freedesktop.org/mesa/demos.git
-</pre>
-
-
-<h1>Building</h1>
-
-<p>
-The Mesa demos can be built with <a href="https://mesonbuild.com/">Meson</a>.
-</p>
-
-
-<h2>Prerequisites</h2>
-
-<p>
-You'll need glut or <a href="http://freeglut.sourceforge.net/">freeglut</a> (runtime libraries and header files).
-</p>
-
-<p>
-If you're using an RPM-based Linux distro you can install these items with:
-</p>
-<pre>
-yum install freeglut freeglut-devel
-</pre>
-
-<p>
-And if you're using a Debian based Linux distro you can install these items with:
-</p>
-<pre>
-apt-get install freeglut3-dev
-</pre>
-
-<p>
-For <a href="https://wayland.freedesktop.org/">Wayland</a> support,
-<a href="https://gitlab.freedesktop.org/wayland/wayland-protocols">wayland-protocols</a>
-and
-<a href="https://gitlab.freedesktop.org/wayland/wayland">wayland-scanner</a>
-must be available.  Additionally, to build for Wayland using CMake,
-<a href="https://invent.kde.org/frameworks/extra-cmake-modules">Extra CMake
-  Modules</a> must be available.
-</p>
-
-
-<h2>Meson</h2>
-
-<p>
-Run <b>meson configure</b> to see the options available for building
-the demos.
-</p>
-
-<p>
-Otherwise, just run <b>meson build-dir; meson compile -C build-dir</b> to build the demos.
-</p>
-
-<p>
-See the <a href="https://mesonbuild.com/">Meson documentation</a> for more information about Meson.
-</p>
-
-
-<h3>MinGW cross-compilation</h3>
-
-<p>
-Create a <b>cross-file</b> file containing:
-</p>
-<pre>
-[binaries]
-c = '/usr/bin/x86_64-w64-mingw32-gcc'
-cpp = '/usr/bin/x86_64-w64-mingw32-g++'
-ar = '/usr/bin/x86_64-w64-mingw32-ar'
-strip = '/usr/bin/x86_64-w64-mingw32-strip'
-pkgconfig = 'x86_64-w64-mingw32-pkg-config'
-exe_wrapper = 'wine'
-
-[host_machine]
-system = 'windows'
-cpu_family = 'x86_64'
-cpu = 'i686'
-endian = 'little'
-</pre>
-
-<p>
-Then do:
-</p>
-<pre>
-meson --prefix=/path/to/install --cross-file /path/to/cross-file build-dir
-meson compile -C build-dir
-meson install -C build-dir
-</pre>
-
-
-<h1>The Demos</h1>
-
-<p>
-Look in the <b>src/</b> directory for these sub-directories, among others:
-</p>
-<ul>
-  <li>demos - the original Mesa demos, such as gears, gloss, etc.</li>
-  <li>redbook - the OpenGL Programming Guide demos</li>
-  <li>samples- original SGI OpenGL demos</li>
-  <li>glsl - OpenGL Shading Language demos</li>
-  <li>gs - Geometry shader demos</li>
-  <li>xdemos - GLX-based demos</li>
-  <li>egl - EGL-based demos</li>
-  <li>wgl - WGL-based demos</li>
-  <li>fp - fragment program tests</li>
-  <li>vp - vertex program tests</li>
-  <li>data - data files used by the demos</li>
-  <li>perf - performance tests</li>
-  <li>tests - assorted test programs</li>
-  <li>objviewer - program to view .obj modes with a skybox</li>
-</ul>
-
-
-
-<h1>Getting Help</h1>
-
-<p>
-If you have trouble building or using the Mesa demos, you can post
-to the<a href="http://lists.freedesktop.org/mailman/listinfo/mesa-users">
-Mesa users</a> mailing list.
-</p>
-
-<p>
-If your question is especially technical, you can try the
-to the<a href="http://lists.freedesktop.org/mailman/listinfo/mesa-dev">
-Mesa dev</a> mailing list.
-</p>
-
-
-<h1>Reporting Bugs</h1>
-
-<p>
-Bugs in the demos can be reported to the
-<a href="https://gitlab.freedesktop.org/mesa/demos/-/issues">
-Mesa demos issue tracker</a>.
-</p>
-
-
-</body>
-</html>