docs, tools: generate Mardown versions of the man pages directly…

… 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

@@ -10,7 +10,7 @@ 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',
+gimprc_man = custom_target('gimprc-' + gimp_app_version + '.5',
                            output: 'gimprc-' + gimp_app_version + '.5',
                            depends: [ gimp_exe_depends ],
                            command: [ gimp_exe, '--no-interface',
@@ -21,27 +21,22 @@ custom_target('gimprc-' + gimp_app_version + '.5',
                            install: true,
                            install_dir: get_option('mandir') / 'man5')
 
-man_files = [
-  configure_file(
-    input : 'gimptool.1.in',
+gimptool_man = configure_file(input : 'gimptool.1.in',
                               output: 'gimptool-' + gimp_app_version + '.1',
-    configuration: manconf,
-  )
-]
+                              configuration: manconf)
+man_files = [ gimptool_man ]
 
 if enable_console_bin
-  man_files += configure_file(
-    input : 'gimp.1.in',
+  gimp_console_man = configure_file(input : 'gimp.1.in',
                                     output: 'gimp-console-' + gimp_app_version + '.1',
-    configuration: manconf,
-  )
+                                    configuration: manconf)
+  man_files += [ gimp_console_man ]
 endif
 
-man_files +=  configure_file(
-  input : 'gimp.1.in',
+gimp_man = configure_file(input : 'gimp.1.in',
                           output: 'gimp-' + gimp_app_version + '.1',
-  configuration: manconf,
-)
+                          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)

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)