[gtk/doc-chapters-markdown] docs: Convert platform sections to markdown

[Matthias Clasen <matthiasc src gnome org>]

commit 7f306c664121251b811e43998b2e6bffdf22ea31
Author: Matthias Clasen <mclasen redhat com>
Date:   Sun May 24 10:55:02 2020 -0400

    docs: Convert platform sections to markdown

 docs/reference/gtk/broadway.md  |  36 +++++++++++
 docs/reference/gtk/broadway.xml |  71 ---------------------
 docs/reference/gtk/meson.build  |  10 +--
 docs/reference/gtk/osx.md       |  10 +++
 docs/reference/gtk/osx.xml      |  39 ------------
 docs/reference/gtk/wayland.md   |  10 +++
 docs/reference/gtk/wayland.xml  |  39 ------------
 docs/reference/gtk/windows.md   |  46 ++++++++++++++
 docs/reference/gtk/windows.xml  |  93 ----------------------------
 docs/reference/gtk/x11.md       |  66 ++++++++++++++++++++
 docs/reference/gtk/x11.xml      | 132 ----------------------------------------
 11 files changed, 173 insertions(+), 379 deletions(-)
---
diff --git a/docs/reference/gtk/broadway.md b/docs/reference/gtk/broadway.md
new file mode 100644
index 0000000000..53d6d3d334
--- /dev/null
+++ b/docs/reference/gtk/broadway.md
@@ -0,0 +1,36 @@
+# Using GTK with Broadway {#gtk-broadway}
+
+The GDK Broadway backend provides support for displaying GTK
+applications in a web browser, using HTML5 and web sockets. To run
+your application in this way, select the Broadway backend by setting
+`GDK_BACKEND=broadway`. Then you can make your application appear in
+a web browser by pointing it at `http://127.0.0.1:8080`. Note that
+you need to enable web sockets in your web browser.
+
+You can choose a different port from the default 8080 by setting
+the `BROADWAY_DISPLAY` environment variable to the port that you
+want to use.
+
+It is also possible to use multiple GTK applications in the same
+web browser window, by using the Broadway server, `broadwayd`, that
+ships with GTK. To use broadwayd, start it like this:
+
+```
+broadwayd :5
+```
+
+Then point your web browser at `http://127.0.0.1:8085`.
+Start your applications like this:
+
+```
+GDK_BACKEND=broadway BROADWAY_DISPLAY=:5 gtk4-demo
+```
+
+## Broadway-specific environment variables {#broadway-envar}
+
+### BROADWAY_DISPLAY
+
+Specifies the Broadway display number. The default display is 0.
+The display number determines the port to use when connecting
+to a Broadway application via the following formula:
+`port = 8080 + display`
diff --git a/docs/reference/gtk/meson.build b/docs/reference/gtk/meson.build
index c3535b1e21..536d5a90f6 100644
--- a/docs/reference/gtk/meson.build
+++ b/docs/reference/gtk/meson.build
@@ -340,7 +340,6 @@ images = [
 ]
 
 content_files = [
-  'broadway.xml',
   'glossary.xml',
   'gtk4-broadwayd.xml',
   'gtk4-builder-tool.xml',
@@ -352,7 +351,6 @@ content_files = [
   'gtk4-query-settings.xml',
   'gtk4-update-icon-cache.xml',
   'gtk4-widget-factory.xml',
-  'osx.xml',
   'other_software.xml',
   'overview.xml',
   'question_index.xml',
@@ -360,9 +358,6 @@ content_files = [
   'text_widget.xml',
   'tree_widget.xml',
   'visual_index.xml',
-  'wayland.xml',
-  'windows.xml',
-  'x11.xml',
 ]
 
 expand_content_files = [
@@ -373,6 +368,11 @@ expand_content_files = [
 ]
 
 expand_content_md_files = [
+  'broadway.md',
+  'osx.md',
+  'wayland.md',
+  'windows.md',
+  'x11.md',
   'getting_started.md',
   'building.md',
   'compiling.md',
diff --git a/docs/reference/gtk/osx.md b/docs/reference/gtk/osx.md
new file mode 100644
index 0000000000..2ee5c02bb1
--- /dev/null
+++ b/docs/reference/gtk/osx.md
@@ -0,0 +1,10 @@
+# Using GTK on Apple macOS {#gtk-osx}
+
+The Apple macOS port of GTK is an implementation of GDK (and therefore GTK)
+on top of the Quartz API.
+
+Currently, the macOS port does not use any additional commandline options
+or environment variables.
+
+For up-to-date information about the current status of this port, see the
+[project page](https://wiki.gnome.org/Projects/GTK/OSX).
diff --git a/docs/reference/gtk/wayland.md b/docs/reference/gtk/wayland.md
new file mode 100644
index 0000000000..7c3f708cfe
--- /dev/null
+++ b/docs/reference/gtk/wayland.md
@@ -0,0 +1,10 @@
+# Using GTK with Wayland {#gtk-wayland}
+
+The GDK Wayland backend provides support for running GTK applications
+under a Wayland compositor. To run your application in this way, select
+the Wayland backend by setting `GDK_BACKEND=wayland`.
+
+On UNIX, the Wayland backend is enabled by default, so you don't need to
+do anything special when compiling it, and everything should "just work."
+
+Currently, the Wayland backend does not use any additional environment variables.
diff --git a/docs/reference/gtk/windows.md b/docs/reference/gtk/windows.md
new file mode 100644
index 0000000000..b432175094
--- /dev/null
+++ b/docs/reference/gtk/windows.md
@@ -0,0 +1,46 @@
+# Using GTK on Windows {#gtk-windows}
+
+The Windows port of GTK is an implementation of GDK (and therefore GTK)
+on top of the Win32 API. When compiling GTK on Windows, this backend is
+the default.
+
+More information about GTK on Windows, including detailed build
+instructions, binary downloads, etc, can be found
+[online](https://wiki.gnome.org/Projects/GTK/Win32).
+
+## Windows-specific environment variables {#win32-envar}
+
+The Win32 GDK backend can be influenced with some additional environment
+variables.
+
+### GDK_IGNORE_WINTAB
+
+If this variable is set, GTK doesn't use the Wintab API for tablet support.
+</para>
+
+### GDK_USE_WINTAB
+
+If this variable is set, GTK uses the Wintab API for tablet support.
+This is the default.
+
+## Windows-specific handling of cursors {#win32-cursors}
+
+By default the "system" cursor theme is used. This makes GTK prefer cursors
+that Windows currently uses, falling back to Adwaita cursors and (as the last
+resort) built-in X cursors.
+
+When any other cursor theme is used, GTK will prefer cursors from that theme,
+falling back to Windows cursors and built-in X cursors.
+
+Theme can be changed by setting `gtk-cursor-theme-name` GTK setting. Users
+can override GTK settings in the `settings.ini` file or at runtime in the
+GTK Inspector.
+
+Themes are loaded from normal Windows variants of the XDG locations:
+`%HOME%/icons/THEME/cursors`, 
+`%APPDATA%/icons/THEME/cursors`, 
+`RUNTIME_PREFIX/share/icons/THEME/cursors`
+
+The `gtk-cursor-theme-size`> setting is ignored, GTK will use
+the cursor size that Windows tells it to use.
+
diff --git a/docs/reference/gtk/x11.md b/docs/reference/gtk/x11.md
new file mode 100644
index 0000000000..be2b74dc8e
--- /dev/null
+++ b/docs/reference/gtk/x11.md
@@ -0,0 +1,66 @@
+# GTK for the X Window System {#gtk-x11}
+
+On UNIX, the X backend is enabled by default, so you don't need to do anything
+special when compiling it, and everything should "just work."
+
+To mix low-level Xlib routines into a GTK program, see
+[GDK X Window System interaction](#gdk-X-Window-System-Interaction)
+in the GDK manual.
+
+## X11-specific environment variables {#x11-envar}
+:
+The X11 GDK backend can be influenced with some additional environment variables.
+
+### GDK_SYNCHRONIZE
+
+If set, GDK makes all X requests synchronously. This is a useful
+option for debugging, but it will slow down the performance considerably.
+
+### GDK_SCALE
+
+Must be set to an integer, typically 2. If set, GDK will scale all
+windows by the specified factor. Scaled output is meant to be used on
+high-dpi displays. Normally, GDK will pick up a suitable scale factor
+for each monitor from the display system. This environment variable
+allows to override that.
+
+## Understanding the X11 architecture {#gtk-X11-arch}
+
+People coming from a Windows or MacOS background often find certain
+aspects of the X Window System surprising. This section introduces
+some basic X concepts at a high level. For more details, the book most
+people use is called the "Xlib Programming Manual" by Adrian Nye; this
+book is volume one in the O'Reilly X Window System series.
+
+Standards are another important resource if you're poking in low-level
+X11 details, in particular the ICCCM and the Extended Window Manager
+Hints specifications. [freedesktop.org](http://www.freedesktop.org/standards/)
+has links to many relevant specifications.
+
+The GDK manual covers [using Xlib in a GTK program](#gdk-X-Window-System-Interaction).
+
+### Server, client, window manager
+
+Other window systems typically put all their functionality in the
+application itself. With X, each application involves three different
+programs: the _X server_, the application (called a _client_ because
+it's a client of the X server), and a special client called the
+_window manager_.
+
+The X server is in charge of managing resources, processing drawing
+requests, and dispatching events such as keyboard and mouse events to
+interested applications. So client applications can ask the X server
+to create a window, draw a circle, or move windows around.
+
+The window manager is in charge of rendering the frame or borders
+around windows; it also has final say on the size of each window,
+and window states such as minimized, maximized, and so forth.
+On Windows and MacOS the application handles most of this.
+On X11, if you wish to modify the window's state, or change its frame,
+you must ask the window manager to do so on your behalf, using an
+established  [convention](http://www.freedesktop.org/standards/).
+
+GTK has functions for asking the window manager to do various things;
+see for example gtk_window_minimize() or gtk_window_maximize().
+Keep in mind that most window managers *will* ignore certain requests
+from time to time, in the interests of good user interface.