docs: Move compiling documentation to Markdown

Helps: #3037

docs/reference/glib/compiling.md

@@ -0,0 +1,71 @@
+Title: Compiling GLib Applications
+
+# Compiling GLib Applications
+
+To compile a GLib application, you need to tell the compiler where to find
+the GLib header files and libraries. This is done with the
+[`pkg-config`](https://www.freedesktop.org/wiki/Software/pkg-config/)
+utility.
+
+The following interactive shell session demonstrates how pkg-config is used
+(the actual output on your system may be different):
+
+    $ pkg-config --cflags glib-2.0
+    -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
+    $ pkg-config --libs glib-2.0
+    -L/usr/lib -lm -lglib-2.0
+
+See the `pkg-config` website for more information about `pkg-config`.
+
+If your application uses or GObject features, it must be compiled and linked
+with the options returned by the following `pkg-config` invocation:
+
+    $ pkg-config --cflags --libs gobject-2.0
+
+If your application uses modules, it must be compiled and linked with the
+options returned by one of the following pkg-config invocations:
+
+    $ pkg-config --cflags --libs gmodule-no-export-2.0
+    $ pkg-config --cflags --libs gmodule-2.0
+
+The difference between the two is that `gmodule-2.0` adds `--export-dynamic`
+to the linker flags, which is often not needed.
+
+The simplest way to compile a program is to use the "backticks" feature of
+the shell. If you enclose a command in backticks (not single quotes), then
+its output will be substituted into the command line before execution. So to
+compile a GLib Hello, World, you would type the following:
+
+    $ cc `pkg-config --cflags glib-2.0` hello.c -o hello `pkg-config --libs glib-2.0`
+
+Deprecated GLib functions are annotated to make the compiler emit warnings
+when they are used (e.g. with GCC, you need to use the
+`-Wdeprecated-declarations option`). If these warnings are problematic, they
+can be turned off by defining the preprocessor symbol
+`GLIB_DISABLE_DEPRECATION_WARNINGS` by using the commandline option
+`-DGLIB_DISABLE_DEPRECATION_WARNINGS`
+
+GLib deprecation annotations are versioned; by defining the macros
+`GLIB_VERSION_MIN_REQUIRED` and `GLIB_VERSION_MAX_ALLOWED`, you can specify the
+range of GLib versions whose API you want to use. APIs that were deprecated
+before or introduced after this range will trigger compiler warnings.
+
+Since GLib 2.62, the older deprecation mechanism of hiding deprecated
+interfaces entirely from the compiler by using the preprocessor symbol
+`G_DISABLE_DEPRECATED` has been removed. All deprecations are now handled
+using the above mechanism.
+
+The recommended way of using GLib has always been to only include the
+toplevel headers `glib.h`, `glib-object.h`, `gio.h`. Starting with 2.32, GLib
+enforces this by generating an error when individual headers are directly
+included.
+
+Still, there are some exceptions; these headers have to be included
+separately:
+
+- `gmodule.h`
+- `glib-unix.h`
+- `glib/gi18n-lib.h` or `glib/gi18n.h` (see the section on
+  [Internationalization](i18n.html))
+- `glib/gprintf.h` and `glib/gstdio.h` (we don't want to pull in all of
+  stdio)

docs/reference/glib/compiling.xml

@@ -1,125 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
-               "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
-]>
-<refentry id="glib-compiling" revision="17 Jan 2002">
-<refmeta>
-<refentrytitle>Compiling GLib Applications</refentrytitle>
-<manvolnum>3</manvolnum>
-<refmiscinfo>GLib Library</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>Compiling GLib Applications</refname>
-<refpurpose>
-How to compile your GLib application
-</refpurpose>
-</refnamediv>
-
-<refsect1>
-<title>Compiling GLib Applications on UNIX</title>
-
-<para>
-To compile a GLib application, you need to tell the compiler where to
-find the GLib header files and libraries. This is done with the
-<application>pkg-config</application> utility.
-</para>
-<para>
-The following interactive shell session demonstrates how
-<application>pkg-config</application> is used (the actual output on
-your system may be different):
-<programlisting>
-$ pkg-config --cflags glib-2.0
- -I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include
-$ pkg-config --libs glib-2.0
- -L/usr/lib -lm -lglib-2.0
-</programlisting>
-</para>
-<para>
-See the <ulink url="http://www.freedesktop.org/wiki/Software/pkg-config">pkg-config website</ulink>
-for more information about <application>pkg-config</application>.
-</para>
-<para>
-If your application uses or <structname>GObject</structname>
-features, it must be compiled and linked with the options returned
-by the following <application>pkg-config</application> invocation:
-<programlisting>
-$ pkg-config --cflags --libs gobject-2.0
-</programlisting>
-</para>
-<para>
-If your application uses modules, it must be compiled and linked
-with the options returned by one of the following
-<application>pkg-config</application> invocations:
-<programlisting>
-$ pkg-config --cflags --libs gmodule-no-export-2.0
-$ pkg-config --cflags --libs gmodule-2.0
-</programlisting>
-The difference between the two is that gmodule-2.0 adds
-<option>--export-dynamic</option> to the linker flags,
-which is often not needed.
-</para>
-<para>
-The simplest way to compile a program is to use command substitution
-feature of a shell. A command written in the format
-<literal>$(command)</literal> gets substituted into the command line
-before execution. So to compile a GLib Hello, World, you would type
-the following:
-<programlisting>
-$ cc hello.c $(pkg-config --cflags --libs glib-2.0) -o hello
-</programlisting>
-</para>
-<note><para>
-Note that the name of the file must come before the other options
-(such as <emphasis>pkg-config</emphasis>), or else you may get an
-error from the linker.
-</para></note>
-
-<para>
-Deprecated GLib functions are annotated to make the compiler
-emit warnings when they are used (e.g. with gcc, you need to use
-the -Wdeprecated-declarations option). If these warnings are
-problematic, they can be turned off by defining the preprocessor
-symbol %GLIB_DISABLE_DEPRECATION_WARNINGS by using the commandline
-option <literal>-DGLIB_DISABLE_DEPRECATION_WARNINGS</literal>
-</para>
-
-<para>
-GLib deprecation annotations are versioned; by defining the
-macros %GLIB_VERSION_MIN_REQUIRED and %GLIB_VERSION_MAX_ALLOWED,
-you can specify the range of GLib versions whose API you want
-to use. APIs that were deprecated before or introduced after
-this range will trigger compiler warnings.
-</para>
-
-<para>
-Since GLib 2.62, the older deprecation mechanism of hiding deprecated interfaces
-entirely from the compiler by using the preprocessor symbol
-<literal>G_DISABLE_DEPRECATED</literal> has been removed. All deprecations
-are now handled using the above mechanism.
-</para>
-
-<para>
-The recommended way of using GLib has always been to only include the
-toplevel headers <filename>glib.h</filename>,
-<filename>glib-object.h</filename>, <filename>gio.h</filename>.
-Starting with 2.32, GLib enforces this by generating an error
-when individual headers are directly included.
-</para>
-
-<para>
-Still, there are some exceptions; these headers have to be included
-separately:
-<filename>gmodule.h</filename>,
-<filename>glib-unix.h</filename>,
-<filename>glib/gi18n-lib.h</filename> or
-<filename>glib/gi18n.h</filename> (see
-the <link linkend="glib-I18N">Internationalization section</link>),
-<filename>glib/gprintf.h</filename> and
-<filename>glib/gstdio.h</filename>
-(we don't want to pull in all of stdio).
-</para>
-
-</refsect1>
-
-</refentry>

docs/reference/glib/glib-docs.xml

@@ -26,7 +26,6 @@
 
     <xi:include href="building.xml" />
     <xi:include href="programming.xml" />
-    <xi:include href="xml/compiling.xml" />
     <xi:include href="changes.xml" />
     <xi:include href="resources.xml" />
 

docs/reference/glib/glib.toml.in

@@ -40,6 +40,7 @@ show_class_hierarchy = true
 urlmap_file = "urlmap.js"
 # The same order will be used when generating the index
 content_files = [
+  "compiling.md",
   "cross-compiling.md",
   "running.md",
 

docs/reference/glib/meson.build

@@ -73,7 +73,6 @@ if get_option('gtk_doc')
                content_files : [
                  'building.xml',
                  'changes.xml',
-                 'compiling.xml',
                  'programming.xml',
                  'resources.xml',
                  'regex-syntax.xml',
@@ -82,7 +81,6 @@ if get_option('gtk_doc')
                  'gtester-report.xml',
                ],
                expand_content_files : [
-                 'compiling.xml',
                ],
                html_assets : [
                  'file-name-encodings.png',
@@ -149,6 +147,7 @@ endif
 # gi-docgen version
 expand_content_files = [
   'character-set.md',
+  'compiling.md',
   'cross-compiling.md',
   'error-reporting.md',
   'gvariant-format-strings.md',