From bcda6eb0d8d6203d01c6f09c179f4d94bc5ebfd8 Mon Sep 17 00:00:00 2001
From: Georges Basile Stavracas Neto <georges.stavracas@gmail.com>
Date: Wed, 11 Oct 2023 11:42:09 -0300
Subject: [PATCH] docs: Rework portals.conf manpage

Generate a synopsis, and tag it a bit more. Cleanup some attributes
in the manpage file.

Closes: https://github.com/flatpak/xdg-desktop-portal/issues/1096
---
 doc/meson.build                               | 12 ++++++++--
 doc/{portals-conf.rst => portals.conf.rst.in} | 24 ++++++++++++++++---
 2 files changed, 31 insertions(+), 5 deletions(-)
 rename doc/{portals-conf.rst => portals.conf.rst.in} (92%)

diff --git a/doc/meson.build b/doc/meson.build
index 099f537bf..97c5af643 100644
--- a/doc/meson.build
+++ b/doc/meson.build
@@ -39,16 +39,24 @@ if build_docbook
 endif
 
 if rst2man.found()
+  manpage_conf = configuration_data()
+  manpage_conf.set('DATADIR', datadir)
+  manpage_conf.set('SYSCONFDIR', sysconfdir)
+
   rst2man_flags = [
     '--syntax-highlight=none',
   ]
   
   man_pages = [
-    { 'input': 'portals-conf.rst', 'output': 'portals.conf', 'section': '5' },
+    { 'input': 'portals.conf.rst.in', 'output': 'portals.conf', 'section': '5' },
   ]
 
   foreach man_page: man_pages
-    man_input = man_page.get('input')
+    man_input = configure_file(
+      input: man_page.get('input'),
+      output: man_page.get('input').split('.in').get(0),
+      configuration: manpage_conf,
+    )
     man_output = man_page.get('output', man_input)
     man_section = man_page.get('section', '1')
     man_full = '@0@.@1@'.format(man_output, man_section)
diff --git a/doc/portals-conf.rst b/doc/portals.conf.rst.in
similarity index 92%
rename from doc/portals-conf.rst
rename to doc/portals.conf.rst.in
index ddb087554..5b2a04558 100644
--- a/doc/portals-conf.rst
+++ b/doc/portals.conf.rst.in
@@ -1,5 +1,3 @@
-.. _portals.conf(5):
-
 ============
 portals.conf
 ============
@@ -8,8 +6,28 @@ portals.conf
 XDG desktop portal configuration
 --------------------------------
 
+:Manual section: 5
+:Manual group: File Formats Manual
+
+.. _synopsis:
+
+SYNOPSIS
+========
+
+*$XDG_CONFIG_HOME/xdg-desktop-portal/{\*-}portals.conf*
+
+*$XDG_CONFIG_DIRS/xdg-desktop-portal/{\*-}portals.conf*
+
+*@SYSCONFDIR@/xdg-desktop-portal/{\*-}portals.conf*
+
+*$XDG_DATA_HOME/xdg-desktop-portal/{\*-}portals.conf*
+
+*$XDG_DATA_DIRS/xdg-desktop-portal/{\*-}portals.conf*
+
+*@DATADIR@/xdg-desktop-portal/{\*-}portals.conf*
+
 DESCRIPTION
------------
+===========
 
 xdg-desktop-portal uses a configuration file to determine which portal backend
 should be used to provide the implementation for the requested interface.