docs: Rename SGML files

We've been using XML for ages.

1 files changed, 0 insertions, 522 deletions

diff --git a/docs/reference/gtk/building.sgml b/docs/reference/gtk/building.sgml
deleted file mode 100644
index fb762cb1e4..0000000000
--- a/docs/reference/gtk/building.sgml
+++ /dev/null
@@ -1,522 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-]>
-<refentry id="gtk-building">
-<refmeta>
-<refentrytitle>Compiling the GTK libraries</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GTK Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Compiling the GTK Libraries</refname>
-<refpurpose>
-How to compile GTK itself
-</refpurpose>
-</refnamediv>
-  <refsect1 id="overview">
-    <title>Building GTK</title>
-    <para>
-      Before we get into the details of how to compile GTK, we should
-      mention that in many cases, binary packages of GTK prebuilt for
-      your operating system will be available, either from your
-      operating system vendor or from independent sources. If such a
-      set of packages is available, installing it will get you
-      programming with GTK much faster than building it yourself. In
-      fact, you may well already have GTK installed on your system
-      already.
-    </para>
-    <para>
-      In order to build GTK, you will need <application>meson</application>
-      installed on your system. On Linux, and other UNIX-like operating
-      systems, you will also need <application>ninja</application>. This
-      guide does not cover how to install these two requirements, but you
-      can refer to the <ulink url="http://mesonbuild.com">Meson website</ulink>
-      for more information. The <ulink url="https://ninja-build.org">Ninja</ulink>
-      build tool is also usable on various operating systems, so we will
-      refer to it in the examples.
-    </para>
-    <para>
-      If you are building GTK from a source distribution or from a Git
-      clone, you will need to use <application>meson</application> to
-      configure the project. The most commonly useful argument is the
-      <systemitem>--prefix</systemitem> one, which determines where the
-      files will go once installed. To install GTK under a prefix
-      like <filename>/opt/gtk</filename> you would run Meson as:
-    </para>
-    <informalexample>
-      <programlisting>
-        meson --prefix /opt/gtk builddir
-      </programlisting>
-    </informalexample>
-    <para>
-      Meson will create the <filename>builddir</filename> directory and
-      place all the build artefacts there.
-    </para>
-    <para>
-      You can get a list of all available options for the build by
-      running <application>meson configure</application>.
-    </para>
-    <para>
-      After Meson successfully configured the build directory, you then
-      can run the build, using Ninja:
-    </para>
-    <informalexample>
-      <programlisting>
-        cd builddir
-        ninja
-        ninja install
-      </programlisting>
-    </informalexample>
-    <para>
-      If you don't have permission to write to the directory you are
-      installing in, you may have to change to root temporarily before
-      running <literal>ninja install</literal>.
-    </para>
-    <para>
-      Several environment variables are useful to pass to set before
-      running <application>meson</application>. <envar>CPPFLAGS</envar>
-      contains options to pass to the C compiler, and is used to tell
-      the compiler where to look for include files. The <envar>LDFLAGS</envar>
-      variable is used in a similar fashion for the linker. Finally the
-      <envar>PKG_CONFIG_PATH</envar> environment variable contains
-      a search path that <command>pkg-config</command> (see below)
-      uses when looking for files describing how to compile
-      programs using different libraries. If you were installing GTK
-      and it's dependencies into <filename>/opt/gtk</filename>, you
-      might want to set these variables as:
-    </para>
-    <programlisting>
-      CPPFLAGS="-I/opt/gtk/include"
-      LDFLAGS="-L/opt/gtk/lib"
-      PKG_CONFIG_PATH="/opt/gtk/lib/pkgconfig"
-      export CPPFLAGS LDFLAGS PKG_CONFIG_PATH
-    </programlisting>
-    <para>
-      You may also need to set the <envar>LD_LIBRARY_PATH</envar>
-      environment variable so the systems dynamic linker can find
-      the newly installed libraries, and the <envar>PATH</envar>
-      environment program so that utility binaries installed by
-      the various libraries will be found.
-    </para>
-    <programlisting>
-      LD_LIBRARY_PATH="/opt/gtk/lib"
-      PATH="/opt/gtk/bin:$PATH"
-      export LD_LIBRARY_PATH PATH
-    </programlisting>
-  </refsect1>
-
-  <refsect1 id="build-types">
-    <title>Build types</title>
-
-    <para>Meson has different build types, exposed by the <literal>buildtype</literal>
-    configuration option. GTK enables and disables functionality depending on
-    the build type used when calling <application>meson</application> to
-    configure the build.</para>
-
-    <formalpara>
-      <title><systemitem>debug</systemitem> and <systemitem>debugoptimized</systemitem></title>
-
-      <para>
-        GTK will enable debugging code paths in both the
-        <literal>debug</literal> and <literal>debugoptimized</literal>
-        build types. Builds with <literal>buildtype</literal> set
-        to <literal>debug</literal> will additionally enable
-        consistency checks on the internal state of the toolkit.
-      </para>
-
-      <para>
-        It is recommended to use the <literal>debug</literal> or
-        <literal>debugoptimized</literal> build types when developing
-        GTK itself. Additionally, <literal>debug</literal> builds of
-        GTK are recommended for profiling and debugging GTK applications,
-        as they include additional validation of the internal state.
-      </para>
-
-      <para>
-        The <literal>debugoptimized</literal> build type is the
-        default for GTK if no build type is specified when calling
-        <application>meson</application>
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><systemitem>release</systemitem></title>
-
-      <para>
-        The <literal>release</literal> build type will disable
-        debugging code paths and additional run time safeties, like
-        checked casts for object instances.
-      </para>
-    </formalpara>
-
-    <para>
-      The <literal>plain</literal> build type provided by Meson
-      should only be used when packaging GTK, and it's expected
-      that packagers will provide their own compiler flags when
-      building GTK. See the previous section for the list of
-      environment variables to be used to define compiler and
-      linker flags.
-    </para>
-  </refsect1>
-
-  <refsect1 id="dependencies">
-    <title>Dependencies</title>
-    <para>
-      Before you can compile the GTK widget toolkit, you need to have
-      various other tools and libraries installed on your
-      system. Dependencies of GTK have their own build systems, so
-      you will need to refer to their own installation instructions.
-    </para>
-    <para>
-      A particular important tool used by GTK to find its dependencies
-      is <application>pkg-config</application>.
-    </para>
-    <para>
-      <ulink url="https://www.freedesktop.org/wiki/Software/pkg-config/">pkg-config</ulink>
-      is a tool for tracking the compilation flags needed for
-      libraries that are used by the GTK libraries. (For each
-      library, a small <literal>.pc</literal> text file is installed
-      in a standard location that contains the compilation flags
-      needed for that library along with version number information.)
-    </para>
-    <para>
-      Some of the libraries that GTK depends on are maintained by
-      by the GTK team: GLib, GdkPixbuf, Pango, ATK and GObject Introspection.
-      Other libraries are maintained separately.
-    </para>
-    <itemizedlist>
-      <listitem>
-        <para>
-          The GLib library provides core non-graphical functionality
-          such as high level data types, Unicode manipulation, and
-          an object and type system to C programs. It is available
-          from  <ulink url="https://download.gnome.org/sources/glib/">here</ulink>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The <ulink url="https://git.gnome.org/browse/gdk-pixbuf/">GdkPixbuf library</ulink>
-          provides facilities for loading images in a variety of file formats.
-          It is available <ulink url="https://download.gnome.org/sources/gdk-pixbuf/">here</ulink>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <ulink url="http://www.pango.org">Pango</ulink> is a library
-          for internationalized text handling. It is available
-          <ulink url="https://download.gnome.org/sources/pango/">here</ulink>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          ATK is the Accessibility Toolkit. It provides a set of generic
-          interfaces allowing accessibility technologies such as
-          screen readers to interact with a graphical user interface.
-          It is available
-          <ulink url="https://download.gnome.org/sources/atk/">here</ulink>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <ulink url="https://wiki.gnome.org/Projects/GObjectIntrospection">Gobject Introspection</ulink>
-          is a framework for making introspection data available to
-          language bindings. It is available
-          <ulink url="https://download.gnome.org/sources/gobject-introspection/">here</ulink>.
-        </para>
-      </listitem>
-    </itemizedlist>
-    <itemizedlist>
-      <title>External dependencies</title>
-      <listitem>
-        <para>
-          The <ulink url="https://www.gnu.org/software/libiconv/">GNU
-          libiconv library</ulink> is needed to build GLib if your
-          system doesn't have the <function>iconv()</function>
-          function for doing conversion between character
-          encodings. Most modern systems should have
-          <function>iconv()</function>.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The libintl library from the <ulink
-          url="https://www.gnu.org/software/gettext/">GNU gettext
-          package</ulink> is needed if your system doesn't have the
-          <function>gettext()</function> functionality for handling
-          message translation databases.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The libraries from the X window system are needed to build
-          Pango and GTK. You should already have these installed on
-          your system, but it's possible that you'll need to install
-          the development environment for these libraries that your
-          operating system vendor provides.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The <ulink url="https://www.freedesktop.org/wiki/Software/fontconfig/">fontconfig</ulink>
-          library provides Pango with a standard way of locating
-          fonts and matching them against font names.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <ulink url="https://www.cairographics.org">Cairo</ulink>
-          is a graphics library that supports vector graphics and image
-          compositing. Both Pango and GTK use Cairo for drawing.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <ulink url="https://github.com/anholt/libepoxy">libepoxy</ulink>
-          is a library that abstracts the differences between different
-          OpenGL libraries. GTK uses it for cross-platform GL support
-          and for its own drawing.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          <ulink url="https://github.com/anholt/libepoxy">Graphene</ulink>
-          is a library that provides vector and matrix types for 2D and
-          3D transformations. GTK uses it internally for drawing.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The <ulink url="https://wayland.freedesktop.org">Wayland</ulink> libraries
-          are needed to build GTK with the Wayland backend.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          The <ulink url="https://www.freedesktop.org/wiki/Software/shared-mime-info">shared-mime-info</ulink>
-          package is not a hard dependency of GTK, but it contains definitions
-          for mime types that are used by GIO and, indirectly, by GTK.
-          gdk-pixbuf will use GIO for mime type detection if possible. For this
-          to work, shared-mime-info needs to be installed and
-          <envar>XDG_DATA_DIRS</envar> set accordingly at configure time.
-          Otherwise, gdk-pixbuf falls back to its built-in mime type detection.
-        </para>
-      </listitem>
-    </itemizedlist>
-  </refsect1>
-  <refsect1 id="building">
-    <title>Building and testing GTK</title>
-    <para>
-      First make sure that you have the necessary external
-      dependencies installed: <command>pkg-config</command>, Meson, Ninja,
-      the JPEG, PNG, and TIFF libraries, FreeType, and, if necessary,
-      libiconv and libintl. To get detailed information about building
-      these packages, see the documentation provided with the
-      individual packages. On any average Linux system, it's quite likely
-      you'll have all of these installed already, or they will be easily
-      accessible through your operating system package repositories.
-    </para>
-    <para>
-      Then build and install the GTK libraries in the order:
-      GLib, Cairo, Pango, ATK, then GTK. For each library, follow the
-      instructions they provide, and make sure to share common settings
-      between them and the GTK build; if you are using a separate prefix
-      for GTK, for instance, you will need to use the same prefix for all
-      its dependencies you build. If you're lucky, this will all go smoothly,
-      and you'll be ready to <link linkend="gtk-compiling">start compiling
-      your own GTK applications</link>. You can test your GTK installation
-      by running the <command>gtk4-demo</command> program that
-      GTK installs.
-    </para>
-    <para>
-      If one of the projects you're configuring or building fails, look
-      closely at the error messages printed; these will often provide useful
-      information as to what went wrong. Every build system has its own
-      log that can help you understand the issue you're encountering. If all
-      else fails, you can ask for help on the gtk-list mailing list.
-      See <xref linkend="gtk-resources"/> for more information.
-    </para>
-  </refsect1>
-
-  <refsect1 id="extra-configuration-options">
-    <title>Extra Configuration Options</title>
-
-    <para>
-      In addition to the normal options provided by Meson, GTK defines
-      various arguments that modify what should be built.
-
-      <cmdsynopsis>
-        <command>meson</command>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dx11-backend=true</arg>
-          <arg choice="plain">-Dx11-backend=false</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dwayland-backend=true</arg>
-          <arg choice="plain">-Dwayland-backend=false</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dbroadway-backend=true</arg>
-          <arg choice="plain">-Dbroadway-backend=false</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dwin32-backend=true</arg>
-          <arg choice="plain">-Dwin32-backend=false</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dquartz-backend=true</arg>
-          <arg choice="plain">-Dquartz-backend=false</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dmedia=gstreamer</arg>
-          <arg choice="plain">-Dmedia=ffmpeg</arg>
-          <arg choice="plain">-Dmedia=all</arg>
-          <arg choice="plain">-Dmedia=none</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dvulkan=yes</arg>
-          <arg choice="plain">-Dvulkan=no</arg>
-          <arg choice="plain">-Dvulkan=auto</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dxinerama=yes</arg>
-          <arg choice="plain">-Dxinerama=no</arg>
-          <arg choice="plain">-Dxinerama=auto</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dcloudproviders=true</arg>
-          <arg choice="plain">-Dcloudproviders=false</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dprint-backends=all</arg>
-          <arg choice="plain">-Dprint-backends=none</arg>
-          <arg choice="plain">-Dprint-backends=cups,lpr,...</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dcolord=yes</arg>
-          <arg choice="plain">-Dcolord=no</arg>
-          <arg choice="plain">-Dcolord=auto</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dgtk_doc=true</arg>
-          <arg choice="plain">-Dgtk_doc=false</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dman-pages=true</arg>
-          <arg choice="plain">-Dman-pages=false</arg>
-        </group>
-        <sbr/>
-        <group>
-          <arg choice="plain">-Dintrospection=true</arg>
-          <arg choice="plain">-Dintrospection=false</arg>
-        </group>
-      </cmdsynopsis>
-    </para>
-
-    <formalpara>
-      <title><systemitem>xinerama</systemitem></title>
-
-      <para>
-        By default GTK will try to link against the Xinerama libraries
-        if they are found. This options can be used to explicitly control
-        whether Xinerama should be used.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><systemitem>gtk_doc</systemitem> and
-        <systemitem>man-pages</systemitem></title>
-
-      <para>
-        The <application>gtk-doc</application> package is
-        used to generate the reference documentation included
-        with GTK. By default support for <application>gtk-doc</application>
-        is disabled because it requires various extra dependencies
-        to be installed. If you have
-        <application>gtk-doc</application> installed and
-        are modifying GTK, you may want to enable
-        <application>gtk-doc</application> support by passing
-        in <systemitem>gtk_doc</systemitem>.
-      </para>
-      <para>
-        Additionally, some tools provided by GTK have their own
-        manual pages generated using a similar set of dependencies;
-        if you have <application>xsltproc</application> then you
-        can generate manual pages by passing <systemitem>man-pages</systemitem>
-        when configuring the build.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><systemitem>print-backends</systemitem></title>
-
-      <para>
-        By default, GTK will try to build various print backends if
-        their dependencies are found. This option can be used to
-        explicitly control which print backends should be built.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><systemitem>x11-backend</systemitem>,
-        <systemitem>win32-backend</systemitem>,
-        <systemitem>quartz-backend</systemitem>,
-        <systemitem>broadway-backend</systemitem> and
-        <systemitem>wayland-backend</systemitem></title>
-
-      <para>
-        Enable specific backends for GDK.  If none of these options
-        are given, the Wayland backend will be enabled by default,
-        if the platform is Linux; the X11 backend will also be enabled
-        by default, unless the platform is Windows, in which case the
-        default is win32, or the platform is macOS, in which case the
-        default is quartz. If any backend is explicitly enabled or disabled,
-        no other platform will be enabled automatically.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><systemitem>introspection</systemitem></title>
-
-      <para>
-        Allows to disable building introspection support. This is option
-        is mainly useful for shortening turnaround times on developer
-        systems. Installed builds of GTK should always have introspection
-        support.
-      </para>
-    </formalpara>
-
-    <formalpara>
-      <title><systemitem>build-tests</systemitem>,
-             <systemitem>install-tests</systemitem>,
-             <systemitem>demos</systemitem></title>
-
-      <para>
-        By default, GTK will build quite a few tests and demos.
-        While these are useful on a developer system, they are not
-        needed when GTK is built e.g. for a flatpak runtime. These
-        options allow to disable building tests and demos.
-      </para>
-    </formalpara>
-
-  </refsect1>
-
-</refentry>
-
-<!-- Local Variables: -->
-<!-- sgml-parent-document: ("gtk-docs.sgml" "chapter" "refentry")  -->
-<!-- End: -->