[gimp-web-devel/pat/bootstrap] content: improve Windows build instructions.

[Jehan <jehanp src gnome org>]

commit c46f1d9ce6a788ab0431edcdecbd4a10b9ee5421
Author: Jehan <jehan girinstud io>
Date:   Tue Sep 13 11:21:11 2022 +0200

    content: improve Windows build instructions.
    
    - Remove duplicated "Troubleshooting" sections (discovered thanks to the
      new ToC!).
    - Some rewording, reformating and fixes here and there…

 content/core/setup/build/Windows.md | 115 ++++++++++--------------------------
 1 file changed, 31 insertions(+), 84 deletions(-)
---
diff --git a/content/core/setup/build/Windows.md b/content/core/setup/build/Windows.md
index ccc922b..a9dff85 100644
--- a/content/core/setup/build/Windows.md
+++ b/content/core/setup/build/Windows.md
@@ -17,10 +17,13 @@ The supported versions of Windows are noted in the
 * [OS support for GIMP 2.99 (development
   branch)](https://gitlab.gnome.org/GNOME/gimp/-/blob/master/devel-docs/os-support.txt)
 
-Note that the GIMP project is really favoring backward compatibility as
-a general rule and we really don't like deprecating hardware when it is
-just a few years old. Nevertheless we may have to bump our Windows
-requirement when it becomes too hard to maintain.
+Note that GIMP project is really favoring backward compatibility as a
+general rule and we really don't like deprecating hardware
+(unfortunately often associated to OS version, sometimes for no good
+reasons, sometimes on purpose by vendors) when it is just a few years
+old. Nevertheless we may have to bump our Windows requirement when it
+becomes too hard to maintain old and new <abbr title="Application
+Programming Interface">API</abbr>s.
 
 ## Copying our Continuous Integration scripts
 
@@ -31,7 +34,7 @@ a good practice could be to look at
 [.gitlab-ci.yml](https://gitlab.gnome.org/GNOME/gimp/-/blob/master/.gitlab-ci.yml)
 file in our repository.
 
-In particular, we have 2 pipelines for Windows:
+We have 2 pipelines for Windows:
 
 * For cross-compilation on Debian Testing for Windows, you should look
   at the `build-image-w64` job for dependencies to install on Debian
@@ -53,7 +56,7 @@ tools to build Windows software.
 
 ### Setting up the environment
 
-1. First, follow the installation instructionsfor msys2 available at 
[msys2.github.io](https://msys2.github.io/).
+1. First, follow the installation instructions for msys2 available at 
[msys2.github.io](https://msys2.github.io/).
 2. To open a terminal, you need to execute `msys2.exe` or `mingw64.exe`.
 3. Update the system :
 
@@ -266,12 +269,12 @@ originally started to crossbuild GIMP specifically).
 
 Note that GObject-Introspection build (unstable branch only) is very
 hard when cross-compiling so it is usually disabled as an exception when
-a cross-compilation is detected. It is the only missing feature (binding
-such as Python, Lua, Vala…) for a cross-compiled GIMP.
-Yet some people manage to build the GObject-Introspection files, e.g.
-using `yocto`, which is why the `meson` configuration flag
-`-Dcan-crosscompile-gir=true` allows you to force GObject-Introspection
-build.
+a cross-compilation is detected. It is the only missing feature
+(GObject-Introspection is what allows bindings for plug-ins, such as
+Python, Lua, Vala…) for a cross-compiled GIMP. Yet some people manage to
+build the GObject-Introspection files, e.g.  using `yocto`, which is why
+the `meson` configuration flag `-Dcan-crosscompile-gir=true` allows you
+to force GObject-Introspection build.
 
 See the [tutorial explaining how to build GIMP with
 it](http://girinstud.io/news/2016/05/crossroad-0-6-released-cross-building-gimp-as-an-example/).
@@ -505,95 +508,38 @@ instance what you find under `$HOME/w64/share/gimp/2.0/`. Maybe other
 things. But this will have to be tested if needed.
 
 ### Troubleshooting
-
-#### Running gimp-2.x.exe on Windows fails. Error messages about a missing entry point in libglib-2.0-0.dll 
or a missing bzip2.dll are shown.
-
-'''Cause:'''
-
-The missing dll files are in the MinGW binary folder, which is separate from the GIMP folders.
-
-'''Solution:'''
-
-To export the GIMP build to Windows properly, use the following steps:
-
-1. On Windows create a folder for the GIMP build, like GIMP-Master.
-
-2. Copy all files from $HOME/w64/$HOST/sys-root/mingw to the newly created folder.
-
-3. Copy all files from your $PREFIX folder to the newly created folder. There are duplicate subfolders, for 
instance bin, share etc., in both directories. If your filemanager asks you to overwrite them, then confirm.
-
-It's important to keep this order to ensure you overwrite older BABL and GEGL from the grab-stuff.sh script 
by the newer ones from your build.
-
-At the end you have merged your MinGW installation and the GIMP build to a running GIMP on Windows build.
-(It also contains the unnecessary MinGW binaries, which are not needed anymore to run GIMP. But for testing 
purposes you have a running GIMP installation.)
-
-
-#### Some fonts, like Sans, are shown improperly
-
-See also [https://bugzilla.gnome.org/show_bug.cgi?id=688593 the Bugzilla report].
-
-'''Cause:'''
-
-The fontconfig package installation writes absolute paths of the building system to fonts.conf and 
conf.d/*.conf. When GIMP is installed on the Windows target system, these absolute paths become invalid.
-
-'''Solution:'''
-
-The bug should be reported to the Fontconfig developers. Meanwhile do on the Windows target system:
-
-1. Close GIMP.
-
-2. Edit the file ''<gimp folder="" installation="">\etc\fonts\fonts.conf</gimp>'':
-
-Replace the line <code><include ignore_missing="yes">$a_directory/conf.d</include></code> by <code><include 
ignore_missing="yes">..\..\share\fontconfig\conf.avail</include></code>
-
-3. Restart GIMP.
-
-
-## Troubleshooting
-
 #### Running gimp-2.x.exe on Windows fails. Error messages about a missing entry point in libglib-2.0-0.dll 
or a missing bzip2.dll are shown.
 
-'''Cause:'''
+Cause
+: The missing dll files are in the MinGW binary folder, which is separate from the GIMP folders.
 
-The missing dll files are in the MinGW binary folder, which is separate from the GIMP folders.
-
-'''Solution:'''
-
-To export the GIMP build to Windows properly, use the following steps:
+Solution
+: To export the GIMP build to Windows properly, use the following steps:
 
 1. On Windows create a folder for the GIMP build, like GIMP-Master.
-
-2. Copy all files from $HOME/w64/$HOST/sys-root/mingw to the newly created folder.
-
-3. Copy all files from your $PREFIX folder to the newly created folder. There are duplicate subfolders, for 
instance bin, share etc., in both directories. If your filemanager asks you to overwrite them, then confirm.
+2. Copy all files from `$HOME/w64/$HOST/sys-root/mingw` to the newly created folder.
+3. Copy all files from your `$GIMP_PREFIX` folder to the newly created folder. There are duplicate 
subfolders, for instance `bin/`, `share/` etc., in both directories. If your filemanager asks you to 
overwrite them, then confirm.
 
 It's important to keep this order to ensure you overwrite older BABL and GEGL from the grab-stuff.sh script 
by the newer ones from your build.
 
 At the end you have merged your MinGW installation and the GIMP build to a running GIMP on Windows build.
 (It also contains the unnecessary MinGW binaries, which are not needed anymore to run GIMP. But for testing 
purposes you have a running GIMP installation.)
 
-
 #### Some fonts, like Sans, are shown improperly
 
-See also [https://bugzilla.gnome.org/show_bug.cgi?id=688593 the Bugzilla report].
+See also [the Bugzilla report](https://bugzilla.gnome.org/show_bug.cgi?id=688593).
 
-'''Cause:'''
+Cause
+: The fontconfig package installation writes absolute paths of the building system to fonts.conf and 
conf.d/*.conf. When GIMP is installed on the Windows target system, these absolute paths become invalid.
 
-The fontconfig package installation writes absolute paths of the building system to fonts.conf and 
conf.d/*.conf. When GIMP is installed on the Windows target system, these absolute paths become invalid.
-
-'''Solution:'''
-
-The bug should be reported to the Fontconfig developers. Meanwhile do on the Windows target system:
+Solution
+: The bug should be reported to the Fontconfig developers. Meanwhile do on the Windows target system:
 
 1. Close GIMP.
-
-2. Edit the file ''<gimp folder="" installation="">\etc\fonts\fonts.conf</gimp>'':
-
-Replace the line <code><include ignore_missing="yes">$a_directory/conf.d</include></code> by <code><include 
ignore_missing="yes">..\..\share\fontconfig\conf.avail</include></code>
+2. Edit the file `$GIMP_PREFIX\etc\fonts\fonts.conf`: replace the line `<include 
ignore_missing="yes">$a_directory/conf.d</include>` by `<include 
ignore_missing="yes">..\..\share\fontconfig\conf.avail</include>`
 
 3. Restart GIMP.
 
-
 ## Building GIMP using Microsoft tools
 
 Microsoft Visual Studio comes with its own C compiler.
@@ -605,9 +551,10 @@ Visual Studio build chain has its flaws, even while it might work in some points
 
 Because of this you are currently recommended to use MinGW for building
 GIMP on Windows. Eventually we are for more genericity and are therefore
-not against a build working on more compilers. If you wish to contribute
-fixes to make GIMP build with Microsoft Visual Studio, then maintain the
-build, you are welcome to contribute.
+not against a build working on more compilers or tools. If you wish to
+contribute fixes to make GIMP build with Microsoft Visual Studio, then
+maintain the build so that it continues working, you are welcome to
+contribute.
 
 ## Building GIMP plug-ins using Microsoft tools