Replace DocBook with reStructuredText for man pages

The dependency on xsltproc and the DocBook style sheets is vaguely
annoying, and there are better tools these days that do not require
writing XML.

5 files changed, 179 insertions, 281 deletions

diff --git a/docs/gdk-pixbuf-csource.rst b/docs/gdk-pixbuf-csource.rst
new file mode 100644
index 000000000..43854bccd
--- /dev/null
+++ b/docs/gdk-pixbuf-csource.rst
@@ -0,0 +1,101 @@
+.. _gdk-pixbuf-csource(1):
+
+==================
+gdk-pixbuf-csource
+==================
+
+----------------------------------------------
+C code generation utility for GdkPixbuf images
+----------------------------------------------
+
+SYNOPSIS
+--------
+|   **gdk-pixbuf-csource** [OPTIONS...] <IMAGE>
+
+DESCRIPTION
+-----------
+
+``gdk-pixbuf-csource`` is a small utility that generates C code containing
+images, useful for compiling images directly into programs.
+
+``gdk-pixbuf-csource`` either takes as input one image file name to generate
+code for, or, using the ``--build-list`` option, a list of (``name``, ``image``)
+pairs to generate code for a list of images into named variables.
+
+This tool is mostly meant to be used for backward compatibility. Newly written
+applications and libraries should use GResource to embed image assets in their
+binary.
+
+OPTIONS
+-------
+
+``--stream``
+
+  Generate pixbuf data stream: a single string containing a serialized
+  ``GdkPixdata`` structure in network byte order.
+
+``--struct``
+
+  Generate ``GdkPixdata`` structure; your code needs the ``GdkPixdata``
+  structure definition from ``gdk-pixdata.h``.
+
+``--macros``
+
+  Generate ``*_ROWSTRIDE``, ``*_WIDTH``, ``*_HEIGHT``, ``*_BYTES_PER_PIXEL``
+  and ``*_RLE_PIXEL_DATA`` or ``*_PIXEL_DATA`` macro definitions for the
+  image.
+
+``--rle``
+
+  Enables run-length encoding for the generated pixel data (default).
+
+``--raw``
+
+  Disables run-length encoding for the generated pixel data.
+
+``--extern``
+
+  Generate extern symbols.
+
+``--static``
+
+  Generate static symbols (default).
+
+``--decoder``
+
+  Provide a ``*_RUN_LENGTH_DECODE(image_buf, rle_data, size, bpp)`` macro
+  definition to decode run-length encoded image data.
+
+``--name=identifier``
+
+  Specifies the identifier name (prefix) for the generated variables or
+  macros (useful only if ``--build-list`` was not specified).
+
+``--build-list``
+
+  Enables (``name``, ``image``) pair parsing mode.
+
+``-h, --help``
+
+  Prints a brief help and exit.
+
+``-v, --version``
+
+  Prints the tool version and exit.
+
+``--g-fatal-warnings``
+
+  Makes warnings fatal, and causes the program to abort.
+
+SEE ALSO
+--------
+
+The ``GdkPixbuf`` documentation, shipped by gdk-pixbuf, and also
+available online on `docs.gtk.org <https://docs.gtk.org/gdk-pixbuf/>`__.
+
+BUGS
+----
+
+The runlength encoder gets out of sync with the pixel boundaries, since
+it includes the rowstride padding in the encoded stream. Furthermore, it
+generates pixbufs with suboptimal rowstride in some cases.
diff --git a/docs/gdk-pixbuf-csource.xml b/docs/gdk-pixbuf-csource.xml
deleted file mode 100644
index d9d848705..000000000
--- a/docs/gdk-pixbuf-csource.xml
+++ /dev/null
@@ -1,177 +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="gdk-pixbuf-csource">
-
-<refentryinfo>
-<title>gdk-pixbuf-csource</title>
-<productname>gdk-pixbuf</productname>
-<authorgroup>
-<author>
-<contrib>Developer</contrib>
-<firstname>Tim</firstname>
-<surname>Janik</surname>
-</author>
-</authorgroup>
-</refentryinfo>
-
-<refmeta>
-<refentrytitle>gdk-pixbuf-csource</refentrytitle>
-<manvolnum>1</manvolnum>
-<refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>gdk-pixbuf-csource</refname>
-<refpurpose>C code generation utility for GdkPixbuf images</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<cmdsynopsis>
-<command>gdk-pixbuf-csource</command>
-<arg choice="opt" rep="repeat">OPTION</arg>
-<arg choice="opt">IMAGE</arg>
-</cmdsynopsis>
-<cmdsynopsis>
-<command>gdk-pixbuf-csource</command>
-<arg choice="opt" rep="repeat">OPTION</arg>
-<arg choice="plain">--build-list</arg>
-<arg rep="repeat">
-  <arg>NAME</arg>
-  <arg>IMAGE</arg>
-</arg>
-</cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para>
-<command>gdk-pixbuf-csource</command> is a small utility that generates
-C code containing images, useful for compiling images directly into programs.
-</para>
-<para>
-<command>gdk-pixbuf-csource</command> either takes as input one image file
-name to generate code for, or, using the <option>--build-list</option> option,
-a list of (<replaceable>name</replaceable>, <replaceable>image</replaceable>)
-pairs to generate code for a list of images into named variables.
-</para>
-</refsect1>
-
-<refsect1><title>Options</title>
-<variablelist>
-
-<varlistentry>
-<term><option>--stream</option></term>
-<listitem><para>
-Generate pixbuf data stream (a single string containing a serialized
-<structname>GdkPixdata</structname> structure in network byte order).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--struct</option></term>
-<listitem><para>
-Generate GdkPixdata structure (needs the <structname>GdkPixdata</structname>
-structure definition from <filename>gdk-pixdata.h</filename>).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--macros</option></term>
-<listitem><para>
-Generate *_ROWSTRIDE, *_WIDTH, *_HEIGHT, *_BYTES_PER_PIXEL and
-*_RLE_PIXEL_DATA or *_PIXEL_DATA macro definitions for the image.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--rle</option></term>
-<listitem><para>
-Enables run-length encoding for the generated pixel data (default).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--raw</option></term>
-<listitem><para>
-Disables run-length encoding for the generated pixel data.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--extern</option></term>
-<listitem><para>
-Generate extern symbols.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--static</option></term>
-<listitem><para>
-Generate static symbols (default).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--decoder</option></term>
-<listitem><para>
-Provide a *_RUN_LENGTH_DECODE(image_buf, rle_data, size, bpp) macro definition
-to decode run-length encoded image data.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--name=identifier</option></term>
-<listitem><para>
-Specifies the identifier name (prefix) for the generated variables or
-macros (useful only if <option>--build-list</option> was not specified).
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--build-list</option></term>
-<listitem><para>
-Enables (<replaceable>name</replaceable>, <replaceable>image</replaceable>)
-pair parsing mode.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-h</option>, <option>--help</option></term>
-<listitem><para>
-Print brief help and exit.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-v</option>, <option>--version</option></term>
-<listitem><para>
-Print version and exit.
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>--g-fatal-warnings</option></term>
-<listitem><para>
-Make warnings fatal (causes the program to abort).
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</refsect1>
-
-<refsect1><title>See also</title>
-<para>
-The <structname>GdkPixbuf</structname> documentation, shipped with the
-Gtk+ distribution, available from <ulink url="http://www.gtk.org">www.gtk.org</ulink>.
-</para>
-</refsect1>
-
-<refsect1><title>Bugs</title>
-<para>
-The runlength encoder gets out of sync with the pixel boundaries, since
-it includes the rowstride padding in the encoded stream. Furthermore, it
-generates pixbufs with suboptimal rowstride in some cases.
-</para>
-</refsect1>
-</refentry>
diff --git a/docs/gdk-pixbuf-query-loaders.rst b/docs/gdk-pixbuf-query-loaders.rst
new file mode 100644
index 000000000..8fc9e7eba
--- /dev/null
+++ b/docs/gdk-pixbuf-query-loaders.rst
@@ -0,0 +1,51 @@
+.. _gdk-pixbuf-query-loaders(1):
+
+========================
+gdk-pixbuf-query-loaders
+========================
+
+-------------------------------------
+GdkPixbuf loader registration utility
+-------------------------------------
+
+SYNOPSIS
+--------
+|   **gdk-pixbuf-query-loaders** [OPTIONS...] [MODULES..]
+
+DESCRIPTION
+-----------
+
+``gdk-pixbuf-query-loaders`` collects information about loadable modules for
+``gdk-pixbuf`` and writes it to the default cache file location, or to
+``stdout``.
+
+If called without arguments, it looks for modules in the ``gdk-pixbuf`` loader
+directory.
+
+If called with arguments, it looks for the specified modules. The arguments may
+be absolute or relative paths.
+
+Normally, the output of ``gdk-pixbuf-query-loaders`` is written to
+``$libdir/gdk-pixbuf-2.0/2.10.0/loaders.cache``, where ``gdk-pixbuf`` looks for
+it by default. If it is written to some other location, the environment variable
+``GDK_PIXBUF_MODULE_FILE`` can be set to point ``gdk-pixbuf`` at the file.
+
+OPTIONS
+-------
+
+``--update-cache``
+
+  Writes the output to the default cache location instead of the standard
+  output.
+
+ENVIRONMENT
+-----------
+
+The environment variable ``GDK_PIXBUF_MODULEDIR`` can be used to specify a
+different loader directory.
+
+The default ``gdk-pixbuf`` loader directory is
+``LIBDIR/gdk-pixbuf-2.0/VERSION/loaders``, where:
+
+- ``LIBDIR`` is the libdir used when building ``gdk-pixbuf``
+- ``VERSION`` is the ABI version for ``gdk-pixbuf`` loaders
diff --git a/docs/gdk-pixbuf-query-loaders.xml b/docs/gdk-pixbuf-query-loaders.xml
deleted file mode 100644
index 9aecd9613..000000000
--- a/docs/gdk-pixbuf-query-loaders.xml
+++ /dev/null
@@ -1,79 +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="gdk-pixbuf-query-loaders">
-
-<refentryinfo>
-<title>gdk-pixbuf-query-loaders</title>
-<productname>gdk-pixbuf</productname>
-<authorgroup>
-<author>
-<contrib>Developer</contrib>
-<firstname>Owen</firstname>
-<surname>Taylor</surname>
-</author>
-</authorgroup>
-</refentryinfo>
-
-<refmeta>
-<refentrytitle>gdk-pixbuf-query-loaders</refentrytitle>
-<manvolnum>1</manvolnum>
-<refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>gdk-pixbuf-query-loaders</refname>
-<refpurpose>GdkPixbuf loader registration utility</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<cmdsynopsis>
-<command>gdk-pixbuf-query-loaders</command>
-<arg choice="opt">--update-cache</arg>
-<arg choice="opt" rep="repeat">MODULE</arg>
-</cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para>
-<command>gdk-pixbuf-query-loaders</command> collects information about
-loadable modules for <application>gdk-pixbuf</application> and writes it to
-the default cache file location, or to <filename>stdout</filename>.
-</para>
-<para>
-If called without arguments, it looks for modules in the
-<application>gdk-pixbuf</application> loader directory.
-</para>
-<para>
-If called with arguments, it looks for the specified modules. The arguments
-may be absolute or relative paths.
-</para>
-<para>
-Normally, the output of <command>gdk-pixbuf-queryloaders</command> is written
-to <filename><replaceable>libdir</replaceable>/gdk-pixbuf-2.0/2.10.0/loaders.cache</filename>, where <application>gdk-pixbuf</application> looks for it by default. If it is written to some other
-location, the environment variable <envar>GDK_PIXBUF_MODULE_FILE</envar>
-can be set to point <application>gdk-pixbuf</application> at the file.
-</para>
-</refsect1>
-
-<refsect1><title>Options</title>
-<variablelist>
-  <varlistentry>
-    <term>--update-cache</term>
-    <listitem><para>Write the output to the default cache location instead of
-                    <filename>stdout</filename></para></listitem>
-  </varlistentry>
-</variablelist>
-</refsect1>
-
-<refsect1><title>Environment</title>
-<para>
-The environment variable <envar>GDK_PIXBUF_MODULEDIR</envar> can be used
-to specify a different loader directory. The default
-<application>gdk-pixbuf</application> loader
-directory is <filename><replaceable>libdir</replaceable>/gdk-pixbuf-2.0/<replaceable>version</replaceable>/loaders</filename>.
-</para>
-</refsect1>
-
-</refentry>
diff --git a/docs/meson.build b/docs/meson.build
index 9c065f7c4..c4ba5e400 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -65,34 +65,36 @@ if build_docs
   )
 endif
 
-xsltproc = find_program('xsltproc', required: false)
-if get_option('man') and xsltproc.found()
-  xlstproc_flags = [
-    '--nonet',
-    '--stringparam', 'man.output.quietly', '1',
-    '--stringparam', 'funcsynopsis.style', 'ansi',
-    '--stringparam', 'man.th.extra1.suppress', '1',
-    '--stringparam', 'man.authors.section.enabled', '0',
-    '--stringparam', 'man.copyright.section.enabled', '0',
+rst2man = find_program('rst2man', required: false)
+if get_option('man') and not rst2man.found()
+  error('No rst2man found, but man pages were explicitly enabled')
+endif
+
+if get_option('man') and rst2man.found()
+  rst_files = [
+    [ 'gdk-pixbuf-csource', ],
+    [ 'gdk-pixbuf-query-loaders', ],
   ]
 
-  man_files = [
-    'gdk-pixbuf-csource',
-    'gdk-pixbuf-query-loaders',
+  rst2man_flags = [
+    '--syntax-highlight=none',
   ]
 
-  foreach m: man_files
-    custom_target(m + '-man',
-                  input: '@0@.xml'.format(m),
-                  output: '@0@.1'.format(m),
-                  command: [
-                    xsltproc,
-                    xlstproc_flags,
-                    '-o', '@OUTPUT@',
-                    'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
-                    '@INPUT@',
-                  ],
-                  install: true,
-                  install_dir: join_paths(gdk_pixbuf_mandir, 'man1'))
+  foreach rst: rst_files
+    man_name = rst[0]
+    man_section = rst.get(1, '1')
+
+    custom_target('man-@0@'.format(man_name),
+      input: '@0@.rst'.format(man_name),
+      output: '@0@.@1@'.format(man_name, man_section),
+      command: [
+        rst2man,
+        rst2man_flags,
+        '@INPUT@',
+      ],
+      capture: true,
+      install: true,
+      install_dir: get_option('mandir') / 'man@0@'.format(man_section),
+    )
   endforeach
 endif