doc: Convert manpages to rst

This will make it more fun to add details and more manpages.

debian/control

@@ -5,7 +5,6 @@ Maintainer: Guido Günther <agx@sigxcpu.org>
 Build-Depends:
  dbus,
  debhelper-compat (= 12),
- docbook-xsl <!nodoc>,
  dh-sequence-gir,
  gsettings-desktop-schemas <!nocheck>,
  gi-docgen <!nodoc>,
@@ -17,8 +16,8 @@ Build-Depends:
  libjson-glib-dev,
  meson,
  pkg-config,
+ python3-docutils <!nodoc>,
  valac,
- xsltproc <!nodoc>,
 Standards-Version: 4.4.0
 Homepage: https://source.puri.sm/Librem5/feedbackd
 

doc/fbcli.rst

@@ -0,0 +1,49 @@
+.. _fbcli(1):
+
+=====
+fbcli
+=====
+
+------------------------
+Emit events to feedbackd
+------------------------
+
+SYNOPSIS
+--------
+|   **fbcli** [OPTIONS...]
+
+
+DESCRIPTION
+-----------
+
+``fbcli`` can be used to submit events to ``feedbackd`` to trigger
+audio, visual or haptic feedback.
+
+OPTIONS
+=======
+
+``-h``, ``--help``
+   print help and exit
+
+``-E=EVENT``; ``--event=EVENT``
+  Submit the given event to ``feedbackd``. Valid events are listes in
+  the event naming spec at
+  `https://source.puri.sm/Librem5/feedbackd/-/blob/main/Event-naming-spec-0.0.0.md`__
+
+``-t=TIMEOUT``; ``--timeout=TIMEOUT``
+  The timeout in seconds after which feedback for the given event should
+  be stopped.
+
+``-P=PROFILE``; ``--profile=PROFILE``
+  The feedback profile (``full``, ``quiet``, ``silent``)
+  to use for the given event. If no event is specified then the global
+  feedback profile is changed.
+
+``-w=TIMEOUT``; ``--watch=TIMEOUT``
+  Maximum timeout to wait for the feedback for the given event to end and
+  ``fbcli`` to exit.
+
+See also
+========
+
+``feedbackd(8)``

doc/fbcli.xml

@@ -1,100 +0,0 @@
-<refentry id="gtester">
-
-<refentryinfo>
-<title>fbcli</title>
-<productname>feedbackd</productname>
-<authorgroup>
-<author>
-<contrib>Developer</contrib>
-<firstname>Guido</firstname>
-<surname>Günther</surname>
-</author>
-</authorgroup>
-</refentryinfo>
-
-<refmeta>
-<refentrytitle>fbcli</refentrytitle>
-<manvolnum>1</manvolnum>
-<refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>fbcli</refname>
-<refpurpose>Emit events to feedbackd</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<cmdsynopsis>
-<command>fbcli</command>
-<arg choice="opt" rep="repeat">OPTION</arg>
-</cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para><command>fbcli</command> can be used to submit events to <command>feedbackd</command>
-to trigger audio, visual or haptic feedback.
-</para>
-</refsect1>
-
-<refsect1><title>Options</title>
-<variablelist>
-
-<varlistentry>
-<term><option>-h</option>, <option>--help</option></term>
-<listitem><para>
-print help and exit
-</para></listitem>
-</varlistentry>
-
-<varlistentry>
-<term><option>-E=<replaceable>EVENT</replaceable></option></term>
-<term><option>--event=<replaceable>EVENT</replaceable></option></term>
-<para>
-  Submit the given event to <command>feedbackd</command>. Valid events are
-  listes in the event naming spec at
-  <ulink url="https://source.puri.sm/Librem5/feedbackd/-/blob/main/doc/Event-naming-spec-0.0.0.md"/>
-</para>
-</varlistentry>
-
-<varlistentry>
-<term><option>-t=<replaceable>TIMEOUT</replaceable></option></term>
-<term><option>--timeout=<replaceable>TIMEOUT</replaceable></option></term>
-<para>
-  The timeout in seconds after which feedback for the given event should
-  be stopped.
-</para>
-</varlistentry>
-
-<varlistentry>
-<term><option>-P=<replaceable>PROFILE</replaceable></option></term>
-<term><option>--profile=<replaceable>PROFILE</replaceable></option></term>
-<para>
-  The feedback profile (<literal>full</literal>, <literal>quiet</literal>, <literal>silent</literal>)
-  to use for the given event. If no event is specified then the global
-  feedback profile is changed.
-</para>
-</varlistentry>
-
-<varlistentry>
-<term><option>-w=<replaceable>TIMEOUT</replaceable></option></term>
-<term><option>--watch=<replaceable>TIMEOUT</replaceable></option></term>
-<para>
-  Maximum timeout to wait for the feedback for the given event to end and
-  <command>fbcli</command> to exit.
-</para>
-</varlistentry>
-
-</variablelist>
-</refsect1>
-
-
-
-<refsect1><title>See also</title>
-<para>
-<citerefentry>
-<refentrytitle>feedbackd</refentrytitle>
-<manvolnum>1</manvolnum>
-</citerefentry>
-</para>
-</refsect1>
-</refentry>

doc/feedbackd.rst

@@ -0,0 +1,42 @@
+.. _feedbackd(8):
+
+=========
+feedbackd
+=========
+
+--------------------------------------
+A daemon to provide feedback on events
+--------------------------------------
+
+SYNOPSIS
+--------
+|   **feedbackd** [OPTIONS...]
+
+
+DESCRIPTION
+===========
+
+``Feedbackd`` is a daemon that runs in the users session to trigger
+event feedback such as playing a sound, trigger a haptic motor or blink
+a LED.
+
+The feedback triggered by a given event is determined by the feedback theme in
+use. Events are submitted via a DBus API.
+
+Any feedback triggered by a client via an event will be stopped latest when the
+client disconnects from DBus. This makes sure all feedbacks get canceled if the
+app that triggered it crashes.
+
+For details refer to the event and feedback theme specs at
+`<https://source.puri.sm/Librem5/feedbackd/>`__
+
+Options
+=======
+
+``-h``, ``--help``
+   print help and exit
+
+See also
+========
+
+``fbcli(1)``

doc/feedbackd.xml

@@ -1,76 +0,0 @@
-<refentry id="gtester">
-
-<refentryinfo>
-<title>feedbackd</title>
-<productname>feedbackd</productname>
-<authorgroup>
-<author>
-<contrib>Developer</contrib>
-<firstname>Guido</firstname>
-<surname>Günther</surname>
-</author>
-</authorgroup>
-</refentryinfo>
-
-<refmeta>
-<refentrytitle>feedbackd</refentrytitle>
-<manvolnum>1</manvolnum>
-<refmiscinfo class="manual">User Commands</refmiscinfo>
-</refmeta>
-
-<refnamediv>
-<refname>feedbackd</refname>
-<refpurpose>A daemon to provide feedback on events</refpurpose>
-</refnamediv>
-
-<refsynopsisdiv>
-<cmdsynopsis>
-<command>feedbackd</command>
-<arg choice="opt" rep="repeat">OPTION</arg>
-</cmdsynopsis>
-</refsynopsisdiv>
-
-<refsect1><title>Description</title>
-<para>
-  <command>feedbackd</command> is a daemon that runs in the users
-  session to trigger event feedback such as playing a sound, trigger
-  a haptic motor or blink a LED.
-</para>
-<para>
-  The feedback triggered by a given event is determined by the feedback
-  theme in use. Events are submitted via a DBus API. 
-</para>
-<para>
-  Any feedback triggered by a client via an event will be stopped latest 
-  when the client disconnects from DBus. This makes sure all feedbacks 
-  get canceled if the app that triggered it crashes.
-</para>
-<para>
-  For details
-  refer to the event and feedback theme specs at
-  <ulink url="https://source.puri.sm/Librem5/feedbackd/"/>
-</para>
-</refsect1>
-
-<refsect1><title>Options</title>
-<variablelist>
-
-<varlistentry>
-<term><option>-h</option>, <option>--help</option></term>
-<listitem><para>
-print help and exit
-</para></listitem>
-</varlistentry>
-
-</variablelist>
-</refsect1>
-
-<refsect1><title>See also</title>
-<para>
-<citerefentry>
-<refentrytitle>fbcli</refentrytitle>
-<manvolnum>1</manvolnum>
-</citerefentry>
-</para>
-</refsect1>
-</refentry>

doc/meson.build

@@ -50,31 +50,30 @@ endif
 
 if get_option('man')
   manpages = [
-    'fbcli',
+    ['fbcli', 1],
-    'feedbackd',
+    ['feedbackd', 8],
   ]
 
-  xsltproc = find_program('xsltproc', required : true)
+  rst2man = find_program('rst2man', 'rst2man.py', required: false)
-  xsltproc_command = [
+  rst2man_flags = [
-    xsltproc,
+    '--syntax-highlight=none',
-    '--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',
-    '-o', '@OUTPUT@',
-    'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl',
-    '@INPUT@',
   ]
-  man1_dir = get_option('mandir') + '/man1'
 
-  foreach page : manpages
+  foreach manpage: manpages
-    custom_target(page + '-man',
+    man_name = manpage[0]
-      input  : page + '.xml',
+    man_section = manpage[1]
-      output : page + '.1',
+
-      command: xsltproc_command,
+    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: man1_dir)
+      install_dir: get_option('mandir') / 'man@0@'.format(man_section),
+    )
   endforeach
 endif

meson_options.txt

@@ -9,7 +9,7 @@ option('gtk_doc',
        description: 'Whether to generate the API reference for Libfeedback')
 option('man',
        type: 'boolean', value : false,
-       description : 'generate man pages (requires xsltproc)')
+       description : 'generate man pages (requires rst2man)')
 option('tests',
        type: 'boolean', value: true,
        description: 'Whether to compile unit tests')