[gtkmm-documentation] Meson build: Drop dependence on Perl

[Kjell Ahlstedt <kjellahl src gnome org>]

commit 0723134708a4cae59f54ecad2d2e313140750dfe
Author: Kjell Ahlstedt <kjellahlstedt gmail com>
Date:   Fri Sep 18 16:36:21 2020 +0200

    Meson build: Drop dependence on Perl
    
    * tools/tutorial/insert_example_code.py: New Python file, equivalent to
    the insert_example_code.pl Perl file.
    
    The Perl file is still used when building with Autotools.

 .gitignore                             |  3 +-
 docs/tutorial/insert_example_code.py   | 79 ++++++++++++++++++++++++++++++++++
 docs/tutorial/meson.build              |  4 +-
 tools/meson_aux/tutorial-custom-cmd.py | 30 ++++++-------
 4 files changed, 94 insertions(+), 22 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index 3441c70..d886561 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,6 @@
 Makefile
 Makefile.in
 stamp-h?
-*~
 
 /INSTALL
 /aclocal.m4
@@ -11,8 +10,8 @@ stamp-h?
 /config.status.lineno
 /configure
 /configure.lineno
-/docs/FAQ/html/
 /docs/tutorial/html/
+/docs/tutorial/__pycache__/
 /docs/tutorial/*/index.docbook
 /docs/tutorial/*/*.mo
 /docs/tutorial/*/*.stamp
diff --git a/docs/tutorial/insert_example_code.py b/docs/tutorial/insert_example_code.py
new file mode 100755
index 0000000..12350d8
--- /dev/null
+++ b/docs/tutorial/insert_example_code.py
@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+
+#                             argv[1]            argv[2:-1]           argv[-1]
+# insert_example_code.py <examples_base_dir> <input_xml_files>... <output_xml_file>
+
+import os
+import sys
+import re
+import glob
+import shutil
+
+# Where to insert example code.
+source_include_pattern = re.compile(
+  r'\s*<para><ulink url="&url_examples_base;([/\w]+)">Source 
Code</ulink></para>\s*(?:<!--\s*Insert\s+(.*?)-->)?')
+
+# First line not part of leading comment in a source code file.
+# The comment typically consists of copyright and license text.
+start_of_source_pattern = re.compile(r'[#\w]')
+
+def process_source_file(source_directory, source_basename, outfile, skip_leading_comments):
+  found_start = not skip_leading_comments
+  source_filename = os.path.join(source_directory, source_basename)
+  with open(source_filename, mode='r') as srcfile:
+    outfile.write('<para>File: <filename>' + source_basename + '</filename> (For use with gtkmm 4)</para>\n')
+    outfile.write('<programlisting>\n<![CDATA[')
+
+    for line in srcfile:
+      if not found_start:
+        # Skip leading comment.
+        if not start_of_source_pattern.match(line):
+          continue
+        found_start = True
+      outfile.write(line)
+
+    outfile.write(']]></programlisting>\n')
+
+def insert_example_code(examples_base_dir, input_xml_files, output_xml_file):
+  if not isinstance(input_xml_files, list):
+    input_xml_files = [input_xml_files]
+
+  with open(output_xml_file, mode='w') as outfile:
+    for input_xml_file in input_xml_files:
+      with open(input_xml_file, mode='r') as infile:
+        for line in infile:
+          # Look for
+          # <para><ulink url="&url_examples_base;helloworld">Source Code</ulink></para> [<!-- Insert 
filenames... -->]
+          source_include_match = source_include_pattern.match(line)
+          if not source_include_match:
+            # Print the line without changes.
+            outfile.write(line)
+          else:
+            # Modify the line to remove the trailing comment, if any.
+            # url_examples_base is assumed to be a GitLab URL. The git branch is then
+            # included in url_examples_base. No need to add it here.
+            outfile.write(source_include_match.expand(
+              '<para><ulink url="&url_examples_base;\\1">Source Code</ulink></para>\n'))
+            outfile.write('<!-- start inserted example code -->\n')
+
+            # List all the source files in the examples directory.
+            source_directory = os.path.join(examples_base_dir, source_include_match.group(1))
+            for source_filename in glob.glob(os.path.join(source_directory, '*.h')) + \
+                                   glob.glob(os.path.join(source_directory, '*.cc')):
+              source_basename = os.path.basename(source_filename)
+              process_source_file(source_directory, source_basename, outfile, True)
+
+            # And possibly other files in the examples directory.
+            if source_include_match.group(2):
+              for source_basename in source_include_match.group(2).split():
+                process_source_file(source_directory, source_basename, outfile, False)
+            outfile.write('<!-- end inserted example code -->\n')
+  return 0
+
+# ----- Main -----
+if __name__ == '__main__':
+  if len(sys.argv) < 4:
+    print('Usage: ' + sys.argv[0] + ' <examples_base_dir> <input_xml_files>... <output_xml_file>')
+    sys.exit(1)
+
+  sys.exit(insert_example_code(sys.argv[1], sys.argv[2:-1], sys.argv[-1]))
diff --git a/docs/tutorial/meson.build b/docs/tutorial/meson.build
index 2565f1a..13a08b9 100644
--- a/docs/tutorial/meson.build
+++ b/docs/tutorial/meson.build
@@ -7,8 +7,6 @@
 
 # xsltproc is required by tutorial_custom_cmd html.
 xsltproc = find_program('xsltproc', required: true)
-# perl is required by tutorial_custom_cmd insert_example_code.
-perl = find_program('perl', required: true)
 xmllint = find_program('xmllint', required: false)
 
 can_parse_and_validate = xmllint.found()
@@ -142,7 +140,7 @@ index_docbook = custom_target('index.docbook',
   output: 'index.docbook',
   command: [
     python3, tutorial_custom_cmd, 'insert_example_code',
-    meson.current_source_dir() / 'insert_example_code.pl',
+    meson.current_source_dir(),
     project_source_root / 'examples' / 'book',
     '@INPUT@',
     '@OUTPUT@',
diff --git a/tools/meson_aux/tutorial-custom-cmd.py b/tools/meson_aux/tutorial-custom-cmd.py
index f618e07..c23ef91 100755
--- a/tools/meson_aux/tutorial-custom-cmd.py
+++ b/tools/meson_aux/tutorial-custom-cmd.py
@@ -8,31 +8,25 @@
 import os
 import sys
 import subprocess
-from pathlib import Path
 import shutil
 
 subcommand = sys.argv[1]
 
-def insert_example_code():
-  #      argv[2]            argv[3]             argv[4]         argv[5]
-  # <perl_script_file> <examples_book_dir> <input_xml_file> <output_xml_file>
+def insert_ex_code():
+  #     argv[2]          argv[3]            argv[4]          argv[5]
+  # <py_script_dir> <examples_book_dir> <input_xml_file> <output_xml_file>
+
+  # Search for insert_example_code.py first in <py_script_dir>.
+  sys.path.insert(0, sys.argv[2])
+  from insert_example_code import insert_example_code
 
-  perl_script_file = sys.argv[2]
   examples_book_dir = sys.argv[3]
   input_xml_file = sys.argv[4]
   output_xml_file = sys.argv[5]
 
-  cmd = [
-    'perl',
-    '--',
-    perl_script_file,
-    examples_book_dir,
-    input_xml_file,
-  ]
-  with open(output_xml_file, mode='w') as xml_file:
-    result = subprocess.run(cmd, stdout=xml_file)
-    if result.returncode:
-      return result.returncode
+  returncode = insert_example_code(examples_book_dir, input_xml_file, output_xml_file)
+  if returncode:
+    return returncode
 
   # Copy output_xml_file to the source directory.
   shutil.copy(output_xml_file, os.path.dirname(input_xml_file))
@@ -87,6 +81,8 @@ def html():
   return result.returncode
 
 def xmllint():
+  from pathlib import Path
+
   #  argv[2]       argv[3]          argv[4]
   # <validate> <input_xml_file> <stamp_file_path>
 
@@ -182,7 +178,7 @@ def docbook2pdf():
 
 # ----- Main -----
 if subcommand == 'insert_example_code':
-  sys.exit(insert_example_code())
+  sys.exit(insert_ex_code())
 if subcommand == 'html':
   sys.exit(html())
 if subcommand == 'xmllint':