Convert the man pages to MarkDown format

We've got a new contributor that wants to make the man pages actually helpful
and interesting. Rather than making them use troff, just convert the document
from a more modern format using pandoc.

Use a meson feature to auto-disable the manpages if pandoc is not available.

.markdownlint.json

@@ -1,6 +1,7 @@
 {
   "default": true,
   "MD033": false,
+  "MD041": false,
   "MD013": {
     "tables": false,
     "line_length": 1000

contrib/ci/dependencies.xml

@@ -1078,6 +1078,24 @@
       <package variant="x86_64" />
     </distro>
   </dependency>
+  <!-- not including void as we need to test it not existing -->
+  <dependency id="pandoc">
+    <distro id="debian">
+      <control />
+      <package variant="x86_64" />
+      <package variant="i386" />
+    </distro>
+    <distro id="ubuntu">
+      <control />
+      <package variant="x86_64" />
+    </distro>
+    <distro id="fedora">
+      <package variant="x86_64" />
+    </distro>
+    <distro id="arch">
+      <package variant="x86_64">pandoc-cli</package>
+    </distro>
+  </dependency>
   <dependency id="pkg-config">
     <distro id="debian">
       <control />

contrib/fwupd.spec.in

@@ -77,6 +77,7 @@ BuildRequires: libarchive-devel
 BuildRequires: libcbor-devel
 BuildRequires: gobject-introspection-devel
 BuildRequires: gcab
+BuildRequires: pandoc
 %ifarch %{valgrind_arches}
 BuildRequires: valgrind
 BuildRequires: valgrind-devel

meson.build

@@ -273,6 +273,9 @@ if libgcab.type_name() == 'pkgconfig'
   endif
 endif
 
+# manpages
+pandoc = find_program('pandoc', required: get_option('man'))
+
 bashcomp = dependency('bash-completion', required: false)
 python3 = import('python').find_installation('python3')
 

meson_options.txt

@@ -5,7 +5,7 @@ option('firmware-packager', type : 'boolean', value : true, description : 'enabl
 option('docs', type : 'feature', description : 'Build developer documentation', deprecated: {'docgen': 'enabled', 'none': 'disabled'})
 option('introspection', type : 'feature', description : 'generate GObject Introspection data', deprecated: {'true': 'enabled', 'false': 'disabled'})
 option('lvfs', type : 'combo', choices : ['true', 'false', 'disabled'], value : 'true', description : 'install LVFS remotes')
-option('man', type : 'boolean', value : true, description : 'enable man pages')
+option('man', type : 'feature', deprecated: {'true': 'enabled', 'false': 'disabled'}, description : 'man pages')
 option('libarchive', type : 'feature', description : 'libarchive support', deprecated: {'true': 'enabled', 'false': 'disabled'})
 option('gudev', type : 'feature', description : 'GUdev support', deprecated: {'true': 'enabled', 'false': 'disabled'})
 option('gusb', type : 'feature', description : 'GUsb support', deprecated: {'true': 'enabled', 'false': 'disabled'})

plugins/dfu/dfu-tool.1

@@ -1,31 +0,0 @@
-.\" Report problems in https://github.com/fwupd/fwupd
-.TH man 1 "11 April 2021" @PACKAGE_VERSION@ "dfu-tool man page"
-.SH NAME
-dfu-tool \- write firmware to DFU devices
-.SH SYNOPSIS
-dfu-tool [CMD]
-.SH DESCRIPTION
-.PP
-This manual page documents briefly the \fBdfu-tool\fR command.
-.PP
-\fBdfu-tool\fR allows a user to write various kinds of
-firmware onto devices supporting the USB Device Firmware Upgrade protocol.
-This tool can be used to switch the device from the normal runtime mode
-to `DFU mode' which allows the user to read and write firmware.
-Either the whole device can be written in one operation, or individual
-`targets' can be specified with the alternative name or number.
-.PP
-All synchronous actions can be safely cancelled and on failure will return
-errors with both a type and a full textual description.
-libdfu supports DFU 1.0, DFU 1.1 and the ST DfuSe vendor extension, and
-handles many device `quirks' necessary for the real-world implementations
-of DFU\&.
-.SH OPTIONS
-The dfu-tool command takes various options depending on the action.
-Run \fBdfu-tool --help\fR for the full list.
-.SH SEE ALSO
-fwupdtool(1), fwupdmgr(1)
-.SH BUGS
-No known bugs.
-.SH AUTHOR
-Richard Hughes (richard@hughsie.com)

plugins/dfu/dfu-tool.md

@@ -0,0 +1,45 @@
+% dfu-tool(1) @PACKAGE_VERSION@ | dfu-tool man page
+
+NAME
+====
+
+**dfu-tool** — write firmware to DFU devices
+
+SYNOPSIS
+========
+
+| **dfu-tool** [CMD]
+
+DESCRIPTION
+===========
+
+This manual page documents briefly the **dfu-tool** command.
+
+**dfu-tool** allows a user to write various kinds of
+firmware onto devices supporting the USB Device Firmware Upgrade protocol.
+This tool can be used to switch the device from the normal runtime mode
+to DFU mode which allows the user to read and write firmware.
+Either the whole device can be written in one operation, or individual
+targets can be specified with the alternative name or number.
+
+All synchronous actions can be safely cancelled and on failure will return
+errors with both a type and a full textual description.
+libdfu supports DFU 1.0, DFU 1.1 and the ST DfuSe vendor extension, and
+handles many device quirks necessary for the real-world implementations
+of DFU.
+
+OPTIONS
+=======
+
+The dfu-tool command takes various options depending on the action.
+Run **dfu-tool --help** for the full list.
+
+BUGS
+====
+
+See GitHub Issues: <https://github.com/fwupd/fwupd/issues>
+
+SEE ALSO
+========
+
+fwupdtool(1), fwupdmgr(1)

plugins/dfu/meson.build

@@ -42,11 +42,20 @@ fu_dfu_tool = executable(
 )
 endif
 
-if get_option('compat_cli') and get_option('man')
+if get_option('compat_cli') and pandoc.found()
-  configure_file(
+  conf_man = configuration_data()
-    input: 'dfu-tool.1',
+  conf_man.set('PACKAGE_VERSION', fwupd_version)
+  dfu_tool_md = configure_file(
+    input: 'dfu-tool.md',
+    output: 'dfu-tool.md',
+    configuration: conf_man,
+  )
+  custom_target('dfu-tool.1',
+    input: dfu_tool_md,
     output: 'dfu-tool.1',
-    configuration: conf,
+    command: [
+      pandoc, '--standalone', '--to', 'man', '@INPUT@', '-o', '@OUTPUT@',
+    ],
     install: true,
     install_dir: join_paths(mandir, 'man1'),
   )

plugins/uefi-capsule/fwupdate.1

@@ -1,17 +0,0 @@
-.\" Report problems in https://github.com/fwupd/fwupd
-.TH man 1 "27 May 2022" @PACKAGE_VERSION@ "fwupdate man page"
-.SH NAME
-fwupdate \-debugging utility for UEFI firmware updates
-.SH SYNOPSIS
-fwupdate [CMD]
-.SH DESCRIPTION
-fwupdate is a deprecated tool that allows deploying capsule updates.
-.SH OPTIONS
-The fwupdate command takes various options depending on the action.
-Run \fBfwupdate --help\fR for the full list.
-.SH SEE ALSO
-fwupdtool(1), fwupdmgr(1)
-.SH BUGS
-No known bugs.
-.SH AUTHOR
-Richard Hughes (richard@hughsie.com)

plugins/uefi-capsule/fwupdate.md

@@ -0,0 +1,32 @@
+% fwupdate(1) @PACKAGE_VERSION@ | fwupdate man page
+
+NAME
+====
+
+**fwupdate** — debugging utility for UEFI firmware updates
+
+SYNOPSIS
+========
+
+| **fwupdate** \[CMD]
+
+DESCRIPTION
+===========
+
+**fwupdate** is a deprecated tool that allows deploying capsule updates.
+
+OPTIONS
+=======
+
+The fwupdate command takes various options depending on the action.
+Run **fwupdate --help** for the full list.
+
+BUGS
+====
+
+See GitHub Issues: <https://github.com/fwupd/fwupd/issues>
+
+SEE ALSO
+========
+
+**fwupdmr(1)**, **fwupdtool(1)**

plugins/uefi-capsule/meson.build

@@ -77,11 +77,20 @@ fwupdate = executable(
 )
 endif
 
-if get_option('compat_cli') and get_option('man')
+if get_option('compat_cli') and pandoc.found()
-  configure_file(
+  conf_man = configuration_data()
-    input: 'fwupdate.1',
+  conf_man.set('PACKAGE_VERSION', fwupd_version)
+  fwupdate_md = configure_file(
+    input: 'fwupdate.md',
+    output: 'fwupdate.md',
+    configuration: conf_man,
+  )
+  custom_target('fwupdate.1',
+    input: fwupdate_md,
     output: 'fwupdate.1',
-    configuration: conf,
+    command: [
+      pandoc, '--standalone', '--to', 'man', '@INPUT@', '-o', '@OUTPUT@',
+    ],
     install: true,
     install_dir: join_paths(mandir, 'man1'),
   )

plugins/uefi-dbx/dbxtool.1

@@ -1,22 +0,0 @@
-.\" Report problems in https://github.com/fwupd/fwupd
-.TH man 1 "11 April 2021" @PACKAGE_VERSION@ "dbxtool man page"
-.SH NAME
-dbxtool \- modify the dbx revocation list
-.SH SYNOPSIS
-dbxtool [CMD]
-.SH DESCRIPTION
-.PP
-This manual page documents briefly the \fBdbxtool\fR command.
-.PP
-\fBdbxtool\fR allows a user to operate on the UEFI dbx revocation list.
-This tool can be used to list the current dbx contents or update it to a newer
-version.
-.SH OPTIONS
-The dbxtool command takes various options depending on the action.
-Run \fBdbxtool --help\fR for the full list.
-.SH SEE ALSO
-fwupdmgr(1)
-.SH BUGS
-No known bugs.
-.SH AUTHOR
-Richard Hughes (richard@hughsie.com)

plugins/uefi-dbx/dbxtool.md

@@ -0,0 +1,35 @@
+% dbxtool(1) @PACKAGE_VERSION@ | dbxtool man page
+
+NAME
+====
+
+**dbxtool** — modify the dbx revocation list
+
+SYNOPSIS
+========
+
+| **dbxtool** [CMD]
+
+DESCRIPTION
+===========
+
+This manual page documents briefly the **dbxtool** command.
+
+**dbxtool** allows a user to operate on the UEFI dbx revocation list.
+This tool can be used to list the current dbx contents or update it to a newer version.
+
+OPTIONS
+=======
+
+The dbxtool command takes various options depending on the action.
+Run **dbxtool --help** for the full list.
+
+BUGS
+====
+
+See GitHub Issues: <https://github.com/fwupd/fwupd/issues>
+
+SEE ALSO
+========
+
+fwupdtool(1), fwupdmgr(1)

plugins/uefi-dbx/meson.build

@@ -56,11 +56,20 @@ dbxtool = executable(
   c_args: cargs,
 )
 
-if get_option('man')
+if pandoc.found()
-  configure_file(
+  conf_man = configuration_data()
-    input: 'dbxtool.1',
+  conf_man.set('PACKAGE_VERSION', fwupd_version)
+  dbxtool_md = configure_file(
+    input: 'dbxtool.md',
+    output: 'dbxtool.md',
+    configuration: conf_man,
+  )
+  custom_target('dbxtool.1',
+    input: dbxtool_md,
     output: 'dbxtool.1',
-    configuration: conf,
+    command: [
+      pandoc, '--standalone', '--to', 'man', '@INPUT@', '-o', '@OUTPUT@',
+    ],
     install: true,
     install_dir: join_paths(mandir, 'man1'),
   )

src/fwupdagent.1

@@ -1,18 +0,0 @@
-.\" Report problems in https://github.com/fwupd/fwupd
-.TH man 1 "11 April 2021" @PACKAGE_VERSION@ "fwupdagent man page"
-.SH NAME
-fwupdagent \- firmware updating agent
-.SH SYNOPSIS
-fwupdagent [CMD]
-.SH DESCRIPTION
-fwupdagent used to be a command line fwupd client intended to be used by scripts.
-You should now use the 100% compatible \fBfwupdmgr --json\fR command instead.
-The output is JSON and guaranteed to be stable.
-.SH EXIT STATUS
-Commands that successfully execute will return "0".
-.SH SEE ALSO
-fwupdmgr(1), fwupdtool(1)
-.SH BUGS
-No known bugs.
-.SH AUTHOR
-Richard Hughes (richard@hughsie.com)

src/fwupdagent.md

@@ -0,0 +1,33 @@
+% fwupdagent(1) @PACKAGE_VERSION@ | fwupdagent man page
+
+NAME
+====
+
+**fwupdagent** — firmware updating agent
+
+SYNOPSIS
+========
+
+| **fwupdagent** [CMD]
+
+DESCRIPTION
+===========
+
+fwupdagent used to be a command line fwupd client intended to be used by scripts.
+You should now use the 100% compatible **fwupdmgr \-\-json** command instead.
+The output is JSON and guaranteed to be stable.
+
+EXIT STATUS
+===========
+
+Commands that successfully execute will return "0".
+
+BUGS
+====
+
+See GitHub Issues: <https://github.com/fwupd/fwupd/issues>
+
+SEE ALSO
+========
+
+fwupdmgr(1), fwupdtool(1)

src/fwupdmgr.1

@@ -1,21 +0,0 @@
-.\" Report problems in https://github.com/fwupd/fwupd
-.TH man 1 "11 April 2021" @PACKAGE_VERSION@ "fwupdmgr man page"
-.SH NAME
-fwupdmgr \- firmware update manager client utility
-.SH SYNOPSIS
-fwupdmgr [CMD]
-.SH DESCRIPTION
-fwupdmgr is a command line fwupd client intended to be used interactively.
-The output between versions of fwupd is not guaranteed to be stable.
-.SH OPTIONS
-The fwupdmgr command takes various options depending on the action.
-Run \fBfwupdmgr --help\fR for the full list.
-.SH EXIT STATUS
-Commands that successfully execute will return "0", but commands that have no
-actions but successfully execute will return "2".
-.SH SEE ALSO
-fwupdagent(1), fwupdtool(1)
-.SH BUGS
-No known bugs.
-.SH AUTHOR
-Richard Hughes (richard@hughsie.com)

src/fwupdmgr.md

@@ -0,0 +1,40 @@
+% fwupdmgr(1) @PACKAGE_VERSION@ | fwupdmgr man page
+
+NAME
+====
+
+**fwupdmgr** — firmware update manager client utility
+
+SYNOPSIS
+========
+
+| **fwupdmgr** [CMD]
+
+DESCRIPTION
+===========
+
+fwupdmgr is a command line fwupd client intended to be used interactively.
+The terminal output between versions of fwupd is not guaranteed to be stable, but if you plan on
+parsing the results then adding **\-\-json** might be just what you need.
+
+OPTIONS
+=======
+
+The fwupdmgr command takes various options depending on the action.
+Run **fwupdmgr \-\-help** for the full list.
+
+EXIT STATUS
+===========
+
+Commands that successfully execute will return "0", but commands that have no
+actions but successfully execute will return "2".
+
+BUGS
+====
+
+See GitHub Issues: <https://github.com/fwupd/fwupd/issues>
+
+SEE ALSO
+========
+
+fwupdtool(1)

src/fwupdtool.1

@@ -1,25 +0,0 @@
-.\" Report problems in https://github.com/fwupd/fwupd
-.TH man 1 "11 April 2021" @PACKAGE_VERSION@ "fwupdtool man page"
-.SH NAME
-fwupdtool \- standalone firmware update utility
-.SH SYNOPSIS
-fwupdtool [CMD]
-.SH DESCRIPTION
-This tool allows an administrator to use fwupd plugins directly without using the daemon process.
-.PP
-Additionally \fBfwupdtool\fR can be used to convert firmware from various different formats,
-or to modify the images contained inside the container firmware file.
-For example, you can convert DFU or Intel HEX firmware into the vendor-specific format.
-.SH OPTIONS
-The fwupdtool command takes various options depending on the action.
-Run \fBfwupdtool --help\fR for the full list.
-Note that some runtimes failures can be ignored using \fB--force\fR.
-.SH EXIT STATUS
-Commands that successfully execute will return "0", but commands that have no
-actions but successfully execute will return "2".
-.SH SEE ALSO
-fwupdagent(1), fwupdmgr(1)
-.SH BUGS
-No known bugs.
-.SH AUTHOR
-Richard Hughes (richard@hughsie.com)

src/fwupdtool.md

@@ -0,0 +1,45 @@
+% fwupdtool(1) @PACKAGE_VERSION@ | standalone firmware update utility man page
+
+NAME
+====
+
+**fwupdtool** — standalone firmware update utility
+
+SYNOPSIS
+========
+
+| **fwupdtool** [CMD]
+
+DESCRIPTION
+===========
+
+This tool allows an administrator to use fwupd plugins directly without using the daemon process,
+which may be faster or easier to use when creating or debugging specific plugins.
+For most end-users, **fwupdmgr** is a more suitable program to use in almost all cases.
+
+Additionally **fwupdtool** can be used to convert firmware from various different formats,
+or to modify the images contained inside the container firmware file.
+For example, you can convert DFU or Intel HEX firmware into the vendor-specific format.
+
+OPTIONS
+=======
+
+The fwupdtool command takes various options depending on the action.
+Run **fwupdtool \-\-help** for the full list.
+Note that some runtimes failures can be ignored using **\-\-force**.
+
+EXIT STATUS
+===========
+
+Commands that successfully execute will return "0", but commands that have no
+actions but successfully execute will return "2".
+
+BUGS
+====
+
+See GitHub Issues: <https://github.com/fwupd/fwupd/issues>
+
+SEE ALSO
+========
+
+fwupdmgr(1)

src/meson.build

@@ -245,30 +245,53 @@ fwupdtool = executable(
   install_dir: bindir
 )
 
-if get_option('man')
+if pandoc.found()
+  conf_man = configuration_data()
+  conf_man.set('PACKAGE_VERSION', fwupd_version)
   if build_daemon
-    configure_file(
+    fwupdmgr_md = configure_file(
-      input: 'fwupdmgr.1',
+      input: 'fwupdmgr.md',
+      output: 'fwupdmgr.md',
+      configuration: conf_man,
+    )
+    custom_target('fwupdmgr.1',
+      input: fwupdmgr_md,
       output: 'fwupdmgr.1',
-      configuration: conf,
+      command: [
+        pandoc, '--standalone', '--to', 'man', '@INPUT@', '-o', '@OUTPUT@',
+      ],
+      install: true,
+      install_dir: join_paths(mandir, 'man1'),
+    )
+  endif
+  if build_daemon and get_option('compat_cli')
+    fwupdagent_md = configure_file(
+      input: 'fwupdagent.md',
+      output: 'fwupdagent.md',
+      configuration: conf_man,
+    )
+    custom_target('fwupdagent.1',
+      input: fwupdagent_md,
+      output: 'fwupdagent.1',
+      command: [
+        pandoc, '--standalone', '--to', 'man', '@INPUT@', '-o', '@OUTPUT@',
+      ],
       install: true,
       install_dir: join_paths(mandir, 'man1'),
     )
-    if get_option('compat_cli')
-      configure_file(
-        input: 'fwupdagent.1',
-        output: 'fwupdagent.1',
-        configuration: conf,
-        install: true,
-        install_dir: join_paths(mandir, 'man1'),
-      )
-    endif
   endif
   if build_standalone
-    configure_file(
+    fwupdtool_md = configure_file(
-      input: 'fwupdtool.1',
+      input: 'fwupdtool.md',
+      output: 'fwupdtool.md',
+      configuration: conf_man,
+    )
+    custom_target('fwupdtool.1',
+      input: fwupdtool_md,
       output: 'fwupdtool.1',
-      configuration: conf,
+      command: [
+        pandoc, '--standalone', '--to', 'man', '@INPUT@', '-o', '@OUTPUT@',
+      ],
       install: true,
       install_dir: join_paths(mandir, 'man1'),
     )