meson: add docs, docs_pdf options

Detect and report if the tools necessary to build documentation are available
during configure. This is represented as two new options 'docs' and
'docs_pdf', both defaulting to 'auto'.

This should also fix a meson error about the installdocs target, when none of
the doc tools are found.

Reviewed-by: Justin Pryzby <pryzby@telsasoft.com>
Discussion: https://postgr.es/m/20230325201414.sh7c6xlut2fpunnv@awork3.anarazel.de
Discussion: https://postgr.es/m/ZB8331v5IhUA/pNu@telsasoft.com

Author: anarazel

doc/src/sgml/installation.sgml

@@ -2893,6 +2893,39 @@ ninja install
     </variablelist>
    </sect3>
 
+   <sect3 id="meson-options-docs">
+    <title>Documentation</title>
+
+    <para>
+     See <xref linkend="docguide-toolsets"/> for the tools needed for building
+     the documentation.
+    </para>
+
+    <variablelist>
+
+     <varlistentry id="configure-docs-meson">
+      <term><option>-Ddocs={ auto | enabled | disabled }</option></term>
+      <listitem>
+       <para>
+        Enables building the documentation in <acronym>HTML</acronym> and
+        <acronym>man</acronym> format. It defaults to auto.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry id="configure-docs-pdf-meson">
+      <term><option>-Ddocs_pdf={ auto | enabled | disabled }</option></term>
+      <listitem>
+       <para>
+        Enables building the documentation in <acronym>PDF</acronym>
+        format. It defaults to auto.
+       </para>
+      </listitem>
+     </varlistentry>
+
+    </variablelist>
+   </sect3>
+
    <sect3 id="meson-options-misc">
     <title>Miscellaneous</title>
 

doc/src/sgml/meson.build

@@ -5,9 +5,6 @@ installdocs = []
 alldocs = []
 doc_generated = []
 
-xmllint_bin = find_program(get_option('XMLLINT'), native: true, required: false)
-
-
 version_sgml = configure_file(
   input: 'version.sgml.in',
   output: 'version.sgml',
@@ -68,8 +65,6 @@ if not xmllint_bin.found()
 endif
 
 pandoc = find_program('pandoc', native: true, required: false)
-xsltproc_bin = find_program(get_option('XSLTPROC'), native: true, required: false)
-fop = find_program('fop', native: true, required: false)
 
 xmltools_wrapper = [
   python, files('xmltools_dep_wrapper'),
@@ -117,7 +112,7 @@ endif
 #
 # Full documentation as html, text
 #
-if xsltproc_bin.found()
+if docs_dep.found()
   html = custom_target('html',
     input: ['stylesheet.xsl', postgres_full_xml],
     output: 'html',
@@ -167,7 +162,7 @@ endif
 #
 # INSTALL in html, text
 #
-if xsltproc_bin.found()
+if docs_dep.found()
   # Depend on postgres_full_xml, so validity errors are raised in one place,
   # and so dependencies don't need to be re-specified.
   install_xml = custom_target('INSTALL.xml',
@@ -204,7 +199,7 @@ endif
 #
 # Man pages
 #
-if xsltproc_bin.found()
+if docs_dep.found()
   # FIXME: implement / consider sqlmansectnum logic
   man = custom_target('man',
     input: ['stylesheet-man.xsl', postgres_full_xml],
@@ -233,7 +228,7 @@ endif
 #
 # Full documentation as PDF
 #
-if fop.found() and xsltproc_bin.found()
+if docs_pdf_dep.found()
   xsltproc_fo_flags = xsltproc_flags + [
     '--stringparam', 'img.src.path', meson.current_source_dir() + '/'
   ]
@@ -291,7 +286,7 @@ db2x_xsltproc = find_program('db2x_xsltproc', native: true, required: false)
 db2x_texixml = find_program('db2x_texixml', native: true, required: false)
 makeinfo = find_program('makeinfo', native: true, required: false)
 
-if db2x_texixml.found() and db2x_xsltproc.found() and makeinfo.found()
+if xsltproc_bin.found() and db2x_texixml.found() and db2x_xsltproc.found() and makeinfo.found()
   postgres_texixml = custom_target('postgres.texixml',
     output: 'postgres.texixml',
     command: [db2x_xsltproc, '-s', 'texi',
@@ -315,15 +310,11 @@ if db2x_texixml.found() and db2x_xsltproc.found() and makeinfo.found()
 endif
 
 
-if docs.length() == 0
-  run_target('docs', command: [missing, 'xsltproc'])
-else
+if docs_dep.found()
   alias_target('docs', docs)
   alias_target('install-docs', installdocs)
 endif
 
-if alldocs.length() == 0
-  run_target('alldocs', command: [missing, 'xsltproc'])
-else
+if alldocs.length() != 0
   alias_target('alldocs', alldocs)
 endif

meson.build

@@ -341,6 +341,8 @@ program_zstd = find_program(get_option('ZSTD'), native: true, required: false)
 dtrace = find_program(get_option('DTRACE'), native: true, required: get_option('dtrace'))
 missing = find_program('config/missing', native: true)
 cp = find_program('cp', required: false, native: true)
+xmllint_bin = find_program(get_option('XMLLINT'), native: true, required: false)
+xsltproc_bin = find_program(get_option('XSLTPROC'), native: true, required: false)
 
 bison_flags = []
 if bison.found()
@@ -567,6 +569,39 @@ endif
 
 
 
+###############################################################
+# Option: docs in HTML and man page format
+###############################################################
+
+docs_opt = get_option('docs')
+docs_dep = not_found_dep
+if not docs_opt.disabled()
+  if xmllint_bin.found() and xsltproc_bin.found()
+    docs_dep = declare_dependency()
+  elif docs_opt.enabled()
+    error('missing required tools for docs in HTML / man page format')
+  endif
+endif
+
+
+
+###############################################################
+# Option: docs in PDF format
+###############################################################
+
+docs_pdf_opt = get_option('docs_pdf')
+docs_pdf_dep = not_found_dep
+if not docs_pdf_opt.disabled()
+  fop = find_program(get_option('FOP'), native: true, required: docs_pdf_opt)
+  if xmllint_bin.found() and xsltproc_bin.found() and fop.found()
+    docs_pdf_dep = declare_dependency()
+  elif docs_pdf_opt.enabled()
+    error('missing required tools for docs in PDF format')
+  endif
+endif
+
+
+
 ###############################################################
 # Library: GSSAPI
 ###############################################################
@@ -3323,6 +3358,8 @@ if meson.version().version_compare('>=0.57')
     {
       'bonjour': bonjour,
       'bsd_auth': bsd_auth,
+      'docs': docs_dep,
+      'docs_pdf': docs_pdf_dep,
       'gss': gssapi,
       'icu': icu,
       'ldap': ldap,

meson_options.txt

@@ -79,6 +79,12 @@ option('bonjour', type : 'feature', value: 'auto',
 option('bsd_auth', type : 'feature', value: 'auto',
   description: 'build with BSD Authentication support')
 
+option('docs', type : 'feature', value: 'auto',
+  description: 'documentation in HTML and man page format')
+
+option('docs_pdf', type : 'feature', value: 'auto',
+  description: 'documentation in PDF format')
+
 option('dtrace', type : 'feature', value: 'disabled',
   description: 'DTrace support')
 
@@ -159,6 +165,9 @@ option('DTRACE', type : 'string', value: 'dtrace',
 option('FLEX', type : 'array', value: ['flex', 'win_flex'],
   description: 'path to flex binary')
 
+option('FOP', type : 'string', value: 'fop',
+  description: 'path to fop binary')
+
 option('GZIP', type : 'string', value: 'gzip',
   description: 'path to gzip binary')