From 0148fcbac16e22a6906be3a545f273b9336d65a2 Mon Sep 17 00:00:00 2001
From: Jehan <jehan@girinstud.io>
Date: Mon, 30 Mar 2026 11:31:44 +0200
Subject: [PATCH] =?UTF-8?q?docs,=20tools:=20generate=20Mardown=20versions?=
 =?UTF-8?q?=20of=20the=20man=20pages=20directly=E2=80=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

… from the main repository.

The new script is basically a copy of tools/man_to_md.py from the
gimp-web repository, with a few improvements.

This is meant to improve our release procedure, with much more
automatization and less manual steps.
---
 docs/meson.build | 67 +++++++++++++++++++++++++++++-------------------
 tools/man2md.py  | 49 +++++++++++++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 27 deletions(-)
 create mode 100755 tools/man2md.py

diff --git a/docs/meson.build b/docs/meson.build
index 454c2a9d75..70b57b52ef 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -10,38 +10,33 @@ manconf.set('manpage_gimpdir', '$XDG_CONFIG_HOME/' + gimpdir / gimp_app_version)
 manconf.set('gimpsysconfdir', prefix / gimpsysconfdir)
 manconf.set('mypaint_brushes_dir', mypaint_brushes_dir)
 
-custom_target('gimprc-' + gimp_app_version + '.5',
-              output: 'gimprc-' + gimp_app_version + '.5',
-              depends: [ gimp_exe_depends ],
-              command: [ gimp_exe, '--no-interface',
-                         '--dump-gimprc-manpage' ],
-              capture: true,
-              build_by_default: true,
-              env: gimp_run_env,
-              install: true,
-              install_dir: get_option('mandir') / 'man5')
+gimprc_man = custom_target('gimprc-' + gimp_app_version + '.5',
+                           output: 'gimprc-' + gimp_app_version + '.5',
+                           depends: [ gimp_exe_depends ],
+                           command: [ gimp_exe, '--no-interface',
+                                      '--dump-gimprc-manpage' ],
+                           capture: true,
+                           build_by_default: true,
+                           env: gimp_run_env,
+                           install: true,
+                           install_dir: get_option('mandir') / 'man5')
 
-man_files = [
-  configure_file(
-    input : 'gimptool.1.in',
-    output: 'gimptool-' + gimp_app_version + '.1',
-    configuration: manconf,
-  )
-]
+gimptool_man = configure_file(input : 'gimptool.1.in',
+                              output: 'gimptool-' + gimp_app_version + '.1',
+                              configuration: manconf)
+man_files = [ gimptool_man ]
 
 if enable_console_bin
-  man_files += configure_file(
-    input : 'gimp.1.in',
-    output: 'gimp-console-' + gimp_app_version + '.1',
-    configuration: manconf,
-  )
+  gimp_console_man = configure_file(input : 'gimp.1.in',
+                                    output: 'gimp-console-' + gimp_app_version + '.1',
+                                    configuration: manconf)
+  man_files += [ gimp_console_man ]
 endif
 
-man_files +=  configure_file(
-  input : 'gimp.1.in',
-  output: 'gimp-' + gimp_app_version + '.1',
-  configuration: manconf,
-)
+gimp_man = configure_file(input : 'gimp.1.in',
+                          output: 'gimp-' + gimp_app_version + '.1',
+                          configuration: manconf)
+man_files += [ gimp_man ]
 
 install_man(man_files)
 
@@ -76,3 +71,21 @@ if enable_default_bin and not platform_windows
                   pointing_to: 'gimp-' + gimp_app_version + '.1',
                   install_dir: get_option('mandir') + '/man1')
 endif
+
+# Optional Markdown versions for the website.
+pandoc = find_program('pandoc', required: false)
+custom_target('Markdown GIMP man page',
+              input: [ gimp_man ],
+              output: 'gimp.md',
+              command: [ '../tools/man2md.py', '@INPUT@', '@OUTPUT@', prefix ],
+              build_by_default: false)
+custom_target('Markdown gimprc man page',
+              input: [ gimprc_man ],
+              output: 'gimprc.md',
+              command: [ '../tools/man2md.py', '@INPUT@', '@OUTPUT@', prefix ],
+              build_by_default: false)
+custom_target('Markdown gimptool man page',
+              input: [ gimptool_man ],
+              output: 'gimptool.md',
+              command: [ '../tools/man2md.py', '@INPUT@', '@OUTPUT@', prefix ],
+              build_by_default: false)
diff --git a/tools/man2md.py b/tools/man2md.py
new file mode 100755
index 0000000000..96c26cb0be
--- /dev/null
+++ b/tools/man2md.py
@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+
+import os
+import re
+import subprocess
+import sys
+import datetime
+
+man_file = sys.argv[1]
+md_file  = sys.argv[2]
+prefix   = sys.argv[3]
+
+if not man_file.endswith(('.1', '.5')):
+  sys.stderr.write(f'File "{man_file}" does not end in .1 or .5.\n')
+  sys.exit(1)
+
+# Convert from troff to Markdown
+try:
+  subprocess.run(['pandoc','-f', 'man','-t', 'markdown','--shift-heading-level-by=1',
+                 man_file,'-o', md_file], check=True)
+except subprocess.CalledProcessError as e:
+  sys.stderr.write(f"(ERROR): {man_file} conversion failed: {e}")
+  sys.exit(1)
+
+try:
+  with open(md_file, 'r', encoding='utf-8') as f:
+    content = f.read()
+
+  # Generate pelican metadata block
+  metadata = (f"Title: {os.path.splitext(os.path.basename(md_file))[0]} Man Page\n"
+               "Date: 2015-08-17T11:31:37-05:00\n"
+              f"Modified: {datetime.datetime.now().isoformat()}\n"
+              "Authors: GIMP Team\n"
+              "Status: hidden\n")
+  content = f"{metadata}\n\n" + content
+
+  # Remove build-time prefix
+  new_prefix = "/usr"
+  if prefix not in content:
+    raise ValueError(f"Prefix '{prefix}' not found in {md_file}")
+  content = content.replace(prefix, new_prefix)
+
+  with open(md_file, 'w', encoding='utf-8') as f:
+    f.write(content)
+
+  sys.stderr.write(f"(INFO): generated: {md_file}")
+except Exception as e:
+  sys.stderr.write(f"(ERROR): {md_file} processing failed: {e}")
+  sys.exit(1)