Merge branch 'rst-man' into 'master'

Replace DocBook with reStructuredText for man pages

See merge request GNOME/gdk-pixbuf!134

7 files changed, 183 insertions, 284 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index a0932f8c1..5a293ebff 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -10,7 +10,7 @@ variables:
   COMMON_MESON_FLAGS: "-Dwerror=true -Dglib:werror=false"
   LOADERS_FLAGS: "-Dpng=enabled -Djpeg=enabled -Dtiff=enabled"
   MESON_TEST_TIMEOUT_MULTIPLIER: 3
-  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gdk-pixbuf/fedora:v3"
+  FEDORA_IMAGE: "registry.gitlab.gnome.org/gnome/gdk-pixbuf/fedora:v4"
 
 .only-default:
   only:
diff --git a/.gitlab/ci/fedora.Dockerfile b/.gitlab/ci/fedora.Dockerfile
index 6ae97559c..76890fac1 100644
--- a/.gitlab/ci/fedora.Dockerfile
+++ b/.gitlab/ci/fedora.Dockerfile
@@ -1,4 +1,4 @@
-FROM fedora:33
+FROM fedora:36
 
 RUN dnf -y install \
         ccache \
@@ -22,6 +22,7 @@ RUN dnf -y install \
         libX11-devel \
         meson \
         python3 \
+        python3-docutils \
         python3-jinja2 \
         python3-markdown \
         python3-pip \
@@ -34,7 +35,7 @@ RUN dnf -y install \
         which \
  && dnf clean all
 
-RUN pip3 install meson==0.56.0
+RUN pip3 install meson==0.56
 
 ARG HOST_USER_ID=5555
 ENV HOST_USER_ID ${HOST_USER_ID}
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