From 619fb4f7b2289bbf2bda9156d866b89451cac70e Mon Sep 17 00:00:00 2001
From: Andres Freund <andres@anarazel.de>
Date: Wed, 8 Nov 2023 15:03:00 -0800
Subject: [PATCH v2 6/7] meson: Add 'help' target, build docs from a common
 source file

Author:
Reviewed-by:
Discussion: https://postgr.es/m/
Backpatch:
---
 meson.build                            |   7 +
 doc/src/sgml/Makefile                  |   3 +
 doc/src/sgml/filelist.sgml             |   1 +
 doc/src/sgml/generate-meson-targets.pl |  63 +++++++
 doc/src/sgml/installation.sgml         | 231 +------------------------
 doc/src/sgml/meson-targets.txt         |  38 ++++
 doc/src/sgml/meson.build               |   9 +
 7 files changed, 122 insertions(+), 230 deletions(-)
 create mode 100644 doc/src/sgml/generate-meson-targets.pl
 create mode 100644 doc/src/sgml/meson-targets.txt

diff --git a/meson.build b/meson.build
index 5b03e90c3db..0f086757e17 100644
--- a/meson.build
+++ b/meson.build
@@ -3330,6 +3330,13 @@ alias_target('testprep', testprep_targets)
 alias_target('world', all_built, docs)
 alias_target('install-world', install_quiet, installdocs)
 
+run_target('help',
+  command: [
+    perl, '-ne', 'next if /^#/; print',
+    files('doc/src/sgml/meson-targets.txt'),
+  ]
+)
+
 
 
 ###############################################################
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 49d35dd0d6e..28858f42228 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -110,6 +110,9 @@ keywords-table.sgml: $(top_srcdir)/src/include/parser/kwlist.h $(wildcard $(srcd
 wait_event_types.sgml: $(top_srcdir)/src/backend/utils/activity/wait_event_names.txt $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl
 	$(PERL) $(top_srcdir)/src/backend/utils/activity/generate-wait_event_types.pl --docs $<
 
+meson-targets.sgml: meson-targets.txt $(srcdir)/generate-meson-targets.pl
+	$(PERL) $(srcdir)/generate-meson-targets.pl $^ > $@
+
 ##
 ## Generation of some text files.
 ##
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 4c63a7e7689..ed89e75b614 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -38,6 +38,7 @@
 <!ENTITY high-availability      SYSTEM "high-availability.sgml">
 <!ENTITY installbin    SYSTEM "install-binaries.sgml">
 <!ENTITY installation  SYSTEM "installation.sgml">
+<!ENTITY meson-targets  SYSTEM "meson-targets.sgml">
 <!ENTITY installw      SYSTEM "install-windows.sgml">
 <!ENTITY maintenance   SYSTEM "maintenance.sgml">
 <!ENTITY manage-ag     SYSTEM "manage-ag.sgml">
diff --git a/doc/src/sgml/generate-meson-targets.pl b/doc/src/sgml/generate-meson-targets.pl
new file mode 100644
index 00000000000..65314aee282
--- /dev/null
+++ b/doc/src/sgml/generate-meson-targets.pl
@@ -0,0 +1,63 @@
+#!/usr/bin/perl
+#
+# Generate the meson-targets.sgml file from meson-targets.txt
+# Copyright (c) 2000-2023, PostgreSQL Global Development Group
+
+use strict;
+use warnings;
+
+my $meson_targets_file = $ARGV[0];
+open my $meson_targets, '<', $meson_targets_file or die;
+
+print
+  "<!-- autogenerated from doc/src/sgml/meson-targets.txt, do not edit -->\n";
+
+# Find the start of each group of targets
+while (<$meson_targets>)
+{
+	next if /^#/;
+
+	if (/^(.*) Targets:$/)
+	{
+		my $targets = $1;
+		my $targets_id = lc $targets;
+
+		print qq(
+<sect3 id="meson-targets-$targets_id">
+ <title>$targets Targets</title>
+
+ <variablelist>
+);
+
+		# Each target in the group
+		while (<$meson_targets>)
+		{
+			next if /^#/;
+			last if !/^\s+([^ ]+)\s+(.+)/;
+
+			my $target = $1;
+			my $desc = $2;
+			my $target_id = $1;
+
+			$target_id =~ s/\//-/g;
+
+			print qq(
+  <varlistentry id="meson-target-${target_id}">
+    <term><option>${target}</option></term>
+    <listitem>
+     <para>
+      ${desc}
+     </para>
+    </listitem>
+  </varlistentry>
+);
+		}
+
+		print qq(
+ </variablelist>
+</sect3>
+);
+	}
+}
+
+close $meson_targets;
diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml
index 9dde19224a7..d7fefa0918c 100644
--- a/doc/src/sgml/installation.sgml
+++ b/doc/src/sgml/installation.sgml
@@ -3212,236 +3212,7 @@ ninja install
     <replaceable>target</replaceable>.
    </para>
 
-   <sect3 id="meson-targets-code">
-    <title>Code Targets</title>
-
-    <variablelist>
-
-     <varlistentry id="meson-target-all">
-       <term><option>all</option></term>
-       <listitem>
-        <para>
-         Build everything other than documentation
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-backend">
-       <term><option>backend</option></term>
-       <listitem>
-        <para>
-         Build backend and related modules.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-bin">
-       <term><option>bin</option></term>
-       <listitem>
-        <para>
-         Build frontend binaries.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-contrib">
-       <term><option>contrib</option></term>
-       <listitem>
-        <para>
-         Build contrib modules.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-pl">
-       <term><option>pl</option></term>
-       <listitem>
-        <para>
-         Build procedual languages.
-        </para>
-       </listitem>
-     </varlistentry>
-
-    </variablelist>
-
-   </sect3>
-
-   <sect3 id="meson-targets-install">
-    <title>Install Targets</title>
-
-    <variablelist>
-
-     <varlistentry id="meson-target-install">
-       <term><option>install</option></term>
-       <listitem>
-        <para>
-         Install postgres, excluding documentation.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-install-quiet">
-       <term><option>install-quiet</option></term>
-       <listitem>
-        <para>
-         Like <xref linkend="meson-target-install"/>, but installed
-         files are not displayed.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-install-world">
-       <term><option>install-world</option></term>
-       <listitem>
-        <para>
-         Install postgres, including multi-page HTML and man page
-         documentation.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-install-docs">
-       <term><option>install-docs</option></term>
-       <listitem>
-        <para>
-         Install documentation in multi-page HTML and man page formats. See
-         also <xref linkend="meson-target-install-doc-html"/>, <xref
-         linkend="meson-target-install-doc-man"/>.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-install-doc-html">
-       <term><option>install-doc-html</option></term>
-       <listitem>
-        <para>
-         Install documentation in multi-page HTML format.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-install-doc-man">
-       <term><option>install-doc-man</option></term>
-       <listitem>
-        <para>
-         Install documentation in man page format.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-uninstall">
-       <term><option>uninstall</option></term>
-       <listitem>
-        <para>
-         Remove installed files.
-        </para>
-       </listitem>
-     </varlistentry>
-
-    </variablelist>
-   </sect3>
-
-   <sect3 id="meson-targets-docs">
-    <title>Documentation Targets</title>
-
-    <variablelist>
-
-     <varlistentry id="meson-target-docs">
-       <term><option>docs</option></term>
-       <term><option>doc-html</option></term>
-       <listitem>
-        <para>
-         Build documentation in multi-page HTML format.  Note that
-         <option>docs</option> does <emphasis>not</emphasis> include building
-         man page documentation, as man page generation seldom fails when
-         building HTML documentation succeeds.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-doc-man">
-       <term><option>doc-man</option></term>
-       <listitem>
-        <para>
-         Build documentation in man page format.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-html-single-page">
-      <term><option>doc/src/sgml/postgres.html</option></term>
-       <listitem>
-        <para>
-         Build documentation in single-page HTML format.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-pdf">
-      <term><option>doc/src/sgml/postgres-A4.pdf</option></term>
-      <term><option>doc/src/sgml/postgres-US.pdf</option></term>
-       <listitem>
-        <para>
-         Build documentation in PDF format, using A4 and U.S. letter format
-         respectively.
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-alldocs">
-       <term><option>alldocs</option></term>
-       <listitem>
-        <para>
-         Build documentation in all supported formats. Primarily useful when
-         testing larger documentation changes.
-        </para>
-       </listitem>
-     </varlistentry>
-
-    </variablelist>
-
-   </sect3>
-
-   <sect3 id="meson-targets-other">
-    <title>Other Targets</title>
-
-    <variablelist>
-
-     <varlistentry id="meson-target-clean">
-       <term><option>clean</option></term>
-       <listitem>
-        <para>
-         Remove all build products
-        </para>
-       </listitem>
-     </varlistentry>
-
-     <varlistentry id="meson-target-test">
-       <term><option>test</option></term>
-       <listitem>
-        <para>
-         Run all enabled tests (including contrib). Support for some classes
-         of tests can be enabled / disabled with <xref
-         linkend="configure-tap-tests-meson"/> and <xref
-         linkend="configure-pg-test-extra-meson"/>.
-        </para>
-       </listitem>
-     </varlistentry>
-
-
-     <varlistentry id="meson-target-world">
-       <term><option>world</option></term>
-       <listitem>
-        <para>
-         Build everything, including documentation.
-        </para>
-       </listitem>
-     </varlistentry>
-
-    </variablelist>
-
-   </sect3>
-
+   &meson-targets;
   </sect2>
 
  </sect1>
diff --git a/doc/src/sgml/meson-targets.txt b/doc/src/sgml/meson-targets.txt
new file mode 100644
index 00000000000..690e4ebc814
--- /dev/null
+++ b/doc/src/sgml/meson-targets.txt
@@ -0,0 +1,38 @@
+# Copyright (c) 2023, PostgreSQL Global Development Group
+#
+# Description of important meson targets, used for the 'help' target and
+# installation.sgml (via generate-meson-targets.pl). Right now the parsers are
+# extremely simple. Both parsers ignore comments. The help target prints
+# everything else. For xml everything without a leading newline is a group,
+# remaining lines are target separated by whitespace from their description
+#
+Code Targets:
+  all                          Build everything other than documentation
+  backend                      Build backend and related modules
+  bin                          Build frontend binaries
+  contrib                      Build contrib modules
+  pl                           Build procedual languages
+
+Documentation Targets:
+  docs                         Build documentation in multi-page HTML format
+  doc-html                     Build documentation in multi-page HTML format
+  doc-man                      Build documentation in man page format
+  doc/src/sgml/postgres-A4.pdf Build documentation in PDF format, with A4 pages
+  doc/src/sgml/postgres-US.pdf Build documentation in PDF format, with US letter pages
+  doc/src/sgml/postgres.html   Build documentation in single-page HTML format
+  alldocs                      Build documentation in all supported formats
+
+Installation Targets:
+  install                      Install postgres, excluding documentation
+  install-doc-html             Install documentation in multi-page HTML format
+  install-doc-man              Install documentation in man page format
+  install-docs                 Install documentation in multi-page HTML and man page formats
+  install-quiet                Like "install", but installed files are not displayed
+  install-world                Install postgres, including multi-page HTML and man page documentation
+  uninstall                    Remove installed files
+
+Other Targets:
+  clean                        Remove all build products
+  test                         Run all enabled tests (including contrib)
+  world                        Build everything, including documentation
+  help                         List important targets
diff --git a/doc/src/sgml/meson.build b/doc/src/sgml/meson.build
index fac7e701610..2dca38ccf7b 100644
--- a/doc/src/sgml/meson.build
+++ b/doc/src/sgml/meson.build
@@ -71,6 +71,15 @@ doc_generated += custom_target('keywords-table.sgml',
   capture: true,
 )
 
+doc_generated += custom_target('meson-targets.sgml',
+  input: files('meson-targets.txt'),
+  output: 'meson-targets.sgml',
+  command: [perl, files('generate-meson-targets.pl'), '@INPUT@'],
+  build_by_default: false,
+  install: false,
+  capture: true,
+)
+
 # For everything else we need at least xmllint
 if not xmllint_bin.found()
   subdir_done()
-- 
2.38.0

