Convert README files to reST

Rename the msvc readme file because otherwise gitlab picks it up as the default
one for some reason.

4 files changed, 96 insertions, 96 deletions

diff --git a/MSVC.README.rst b/MSVC.README.rst
new file mode 100644
index 00000000..82000773
--- /dev/null
+++ b/MSVC.README.rst
@@ -0,0 +1,82 @@
+Building GObject-Introspection (G-I) on Windows using Visual Studio
+===================================================================
+
+Building G-I on Windows with Visual Studio is now supported via the use
+of the Meson build system, the Visual Studio 2008~2017 projects have been
+dropped from the distribution.  This README.msvc file will outline the
+steps of performing such a build on Visual Studio 2008~2017.
+
+You will need the following, in addition to your Visual Studio installation:
+
+- A Python installation that matches the build configuration that you are
+  planning to build.  That is, you need the 32-bit Python installation for
+  building 32-bit builds of G-I and the 64-bit (amd64) Python installation
+  for building x64/x86_64/amd64 builds of G-I.  You need at least the version
+  that is required for Meson, which is 3.4.x at the time of writing.  You will
+  then need to install Meson using the pip tool.
+
+- The Ninja build tool, which is optional on Visual Studio 2010, 2015 and 2017
+  builds (if one chooses to generate Visual Studio projects with Meson), but is
+  required for 2008, 2012 and 2013 builds.
+
+- GIT for Windows is recommended, as Meson will download using GIT the sources
+  of libraries that it depends on, if they cannot be found (such as GLib, please
+  see below)
+
+- A recent enough version of GLib, preferably built with the same compiler that
+  is now being used to build G-I.  If none is found, the Meson build will fetch
+  GLib from GIT master and build it first before continuing to build G-I.  Note
+  that it will require a libintl implementation (must be installed beforehand, the
+  headers and lib and DLL must be found in the paths specified by %INCLUDE, %LIB%
+  and %PATH% respectively), along with ZLib and libffi (GLib's own Meson build will
+  build  them if they are not found).  If a pre-existing copy of GLib is available,
+  be sure to set PKG_CONFIG_PATH to where its .pc files can be found, and ensure
+  that its DLLs/ executables can be first found in the paths specified in %PATH%.
+  Note that libffi is needed both by GLib and G-I.
+
+- A DLL build of Cairo with Cairo-GObject built, also preferably with the same
+  compiler that is now used to build G-I.
+
+- A recent version of winflex/flex and Bison. They can be obtained via MSYS/MSYS64
+  or Cygwin installations.  Either the 32-bit or 64-bit version will work, as long
+  as they run on your system.
+
+Set PATH to contain your Python-3.4.x+ interpreter, Ninja build tool (if needed) and
+winflex/flex and Bison executables towards its end.
+
+Note that if you plan to use g-ir-scanner for other packages built using Meson, you
+need to use the same Python release series (3.4, 3.5...) for running Meson there as
+well.
+
+Open a Visual Studio command prompt and create an empty build directory (which needs
+to be on the same drive as the G-I sources).  In that directory, run the following::
+
+  python $(PythonInstallationPath)\scripts\meson.py $(G-I_srcdir) --buildtype=<build_configuration> --prefix=$(PREFIX) -Dcairo-libname=<DLL filename of cairo-gobject>
+
+When Meson completes configuring and generating the build files, proceed building
+using Ninja or the generated Visual Studio projects.
+
+Additional notes for building with Visual Studio 2008 only
+----------------------------------------------------------
+Due to its use of security manifests, after Meson completes configuring and
+generating the build files, first build the giscanner\_giscanner.pyd target
+using 'ninja giscanner\_giscanner.pyd'.  After doing so, embed the manifest
+using the following command::
+
+  mt /manifest giscanner\_giscanner.pyd.manifest /outputresource:giscanner\_giscanner.pyd;2
+
+The .gir files cannot be successfully generated without this step.
+
+On x64 builds, building girepository\girepository-1.0-1.dll may hang during compilation.
+If this happens, terminate all 'cl.exe' processes, which will terminate the build process.
+Open build.ninja and change the compiler flags by changing /O2 to /O1 for all the sources
+that hang during compilation.  At this time of writing, girepository\girwriter.c,
+girepository\girparser.c and girepository\girnode.c are affected--this is due to an issue
+in Visual Studio 2008's x64 compiler in regards to optimization.  Re-attempt the build, and
+the build should complete normally.  This does not affect Win32/x86 builds.
+
+On all Visual Studio 2008 builds, after successfully completing/installing the build, run
+the following so that we ensure the manifests are embedded to the built DLLs and EXEs::
+
+  for /r %f in (*.dll.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f /outputresource:$(PREFIX)\bin\%~nf;2
+  for /r %f in (*.exe.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f /outputresource:$(PREFIX)\bin\%~nf;1
diff --git a/Makefile.am b/Makefile.am
index d941a3a9..e071ec25 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -58,7 +58,8 @@ EXTRA_DIST += 			\
 	misc/update-glib-annotations.py	\
 	misc/update-gtkdoc-tests.py	\
 	misc/verbump.py		\
-	README.msvc \
+	README.rst \
+	MSVC.README.rst \
 	meson.build \
 	meson_options.txt
 
diff --git a/README.msvc b/README.msvc
deleted file mode 100644
index a72fe1dc..00000000
--- a/README.msvc
+++ /dev/null
@@ -1,80 +0,0 @@
-Building GObject-Introspection (G-I) on Windows using Visual Studio

-===================================================================

-Building G-I on Windows with Visual Studio is now supported via the use

-of the Meson build system, the Visual Studio 2008~2017 projects have been

-dropped from the distribution.  This README.msvc file will outline the

-steps of performing such a build on Visual Studio 2008~2017.

-

-You will need the following, in addition to your Visual Studio installation:

--A Python installation that matches the build configuration that you are

- planning to build.  That is, you need the 32-bit Python installation for

- building 32-bit builds of G-I and the 64-bit (amd64) Python installation

- for building x64/x86_64/amd64 builds of G-I.  You need at least the version

- that is required for Meson, which is 3.4.x at the time of writing.  You will

- then need to install Meson using the pip tool.

-

--The Ninja build tool, which is optional on Visual Studio 2010, 2015 and 2017

- builds (if one chooses to generate Visual Studio projects with Meson), but is

- required for 2008, 2012 and 2013 builds.

-

--GIT for Windows is recommended, as Meson will download using GIT the sources

- of libraries that it depends on, if they cannot be found (such as GLib, please

- see below)

-

--A recent enough version of GLib, preferably built with the same compiler that

- is now being used to build G-I.  If none is found, the Meson build will fetch

- GLib from GIT master and build it first before continuing to build G-I.  Note

- that it will require a libintl implementation (must be installed beforehand, the

- headers and lib and DLL must be found in the paths specified by %INCLUDE, %LIB%

- and %PATH% respectively), along with ZLib and libffi (GLib's own Meson build will

- build  them if they are not found).  If a pre-existing copy of GLib is available,

- be sure to set PKG_CONFIG_PATH to where its .pc files can be found, and ensure

- that its DLLs/ executables can be first found in the paths specified in %PATH%.

- Note that libffi is needed both by GLib and G-I.

-

--A DLL build of Cairo with Cairo-GObject built, also preferably with the same

- compiler that is now used to build G-I.

-

--A recent version of winflex/flex and Bison.  They can be obtained via MSYS/MSYS64

- or Cygwin installations.  Either the 32-bit or 64-bit version will work, as long

- as they run on your system.

-

-Set PATH to contain your Python-3.4.x+ interpreter, Ninja build tool (if needed) and

-winflex/flex and Bison executables towards its end.

-

-Note that if you plan to use g-ir-scanner for other packages built using Meson, you

-need to use the same Python release series (3.4, 3.5...) for running Meson there as

-well.

-

-Open a Visual Studio command prompt and create an empty build directory (which needs

-to be on the same drive as the G-I sources).  In that directory, run the following:

-

-python $(PythonInstallationPath)\scripts\meson.py $(G-I_srcdir) --buildtype=<build_configuration> --prefix=$(PREFIX) -Dcairo-libname=<DLL filename of cairo-gobject>

-

-When Meson completes configuring and generating the build files, proceed building

-using Ninja or the generated Visual Studio projects.

-

-Additional notes for building with Visual Studio 2008 only

-==========================================================

-Due to its use of security manifests, after Meson completes configuring and

-generating the build files, first build the giscanner\_giscanner.pyd target

-using 'ninja giscanner\_giscanner.pyd'.  After doing so, embed the manifest

-using the following command:

-

-mt /manifest giscanner\_giscanner.pyd.manifest /outputresource:giscanner\_giscanner.pyd;2

-

-The .gir files cannot be successfully generated without this step.

-

-On x64 builds, building girepository\girepository-1.0-1.dll may hang during compilation.

-If this happens, terminate all 'cl.exe' processes, which will terminate the build process.

-Open build.ninja and change the compiler flags by changing /O2 to /O1 for all the sources

-that hang during compilation.  At this time of writing, girepository\girwriter.c,

-girepository\girparser.c and girepository\girnode.c are affected--this is due to an issue

-in Visual Studio 2008's x64 compiler in regards to optimization.  Re-attempt the build, and

-the build should complete normally.  This does not affect Win32/x86 builds.

-

-On all Visual Studio 2008 builds, after successfully completing/installing the build, run

-the following so that we ensure the manifests are embedded to the built DLLs and EXEs:

-

-for /r %f in (*.dll.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f /outputresource:$(PREFIX)\bin\%~nf;2

-for /r %f in (*.exe.manifest) do if exist $(PREFIX)\bin\%~nf mt /manifest %f /outputresource:$(PREFIX)\bin\%~nf;1

diff --git a/README b/README.rst
index 4a57dc08..b8e82a9b 100644
--- a/README
+++ b/README.rst
@@ -4,8 +4,7 @@ The goal of the project is to describe the APIs and collect them in
 a uniform, machine readable format.
 
 GIR XML format
-==============
-
+--------------
 There's an XML format called GIR used by GObjectIntrospection.
 The purpose of it is to provide a common structure to access the complete
 available API that a library or other unit of code exports.
@@ -16,8 +15,7 @@ meant to be usable to use in other situations, for instance to/from another
 set of languages.
 
 Typelib
-=======
-
+-------
 The typelib is an on-disk version of the GIR designed to be fast, memory
 efficient and complete enough so that language bindings can be written
 on top of it without other sources of information.
@@ -26,9 +24,9 @@ accessed from the language binding or another application who wishes to
 use the information.
 
 Tools
-=====
-
+-----
 The following tools are shipped with GObject Introspection:
+
 - g-ir-scanner, a tool which generates GIR XML files by parsing headers,
   GTK-Doc comment blocks including annotations and introspecting GObject
   based libraries.
@@ -41,8 +39,7 @@ The following tools are shipped with GObject Introspection:
 - g-ir-doc-tool, generates API reference documentation from a GIR XML file.
 
 API library
-===========
-
+-----------
 There's also a C based library called libgirepository which provides
 an API to access to the typelib metadata. It also contains an API to
 invoke functions, given the function info object. The implementation is
@@ -53,18 +50,18 @@ There are a number of GIR test files in tests/, and a script to do
 roundtrip tests (GIR -> typelib -> GIR).
 
 Helping out
-===========
+-----------
 The introspection framework needs a lot more work, see TODO.
 
 Homepage
-========
-http://live.gnome.org/GObjectIntrospection
+--------
+https://gi.readthedocs.io/
 
 Reporting bugs
-==============
+--------------
 Bugs should be reported in https://gitlab.gnome.org/GNOME/gobject-introspection/issues.
 
 Contact
-=======
-Mail: gtk-devel-list@gnome.org
-IRC: #introspection@irc.gnome.org
+-------
+:Mail: gtk-devel-list@gnome.org
+:IRC: #introspection@irc.gnome.org
\ No newline at end of file