From a11760ef39629fd5f850b9a495e5b155c2cb120d Mon Sep 17 00:00:00 2001
From: Eli Schwartz <eschwartz@gentoo.org>
Date: Sun, 10 Nov 2024 17:59:55 -0500
Subject: [PATCH] build: make manpages a mandatory part of the build by default

Currently, both man pages and gtk-doc HTML documentation are enabled by
the same build option. It is common for users to want to choose whether
to build HTML docs, as not everyone cares about HTML developer docs, but
manpages are intended directly for end-user consumption and should
always be available. At the very least, there should be a separate
option to disable them to avoid accidentally disabling them while trying
to disable HTML developer docs.

Resolves: https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/issues/1653
---
 man/meson.build             | 105 +++++++++++++++++++-----------------
 meson.build                 |  10 +++-
 meson_options.txt           |   1 +
 tools/meson-post-install.sh |   5 +-
 4 files changed, 68 insertions(+), 53 deletions(-)

diff --git a/man/meson.build b/man/meson.build
index 5a8e52042..d3310dc1d 100644
--- a/man/meson.build
+++ b/man/meson.build
@@ -41,54 +41,53 @@ foreach man: mans + introspection_mans
   built_mans += name
 endforeach
 
-if built_mans.length() > 0
-  install_man(built_mans)
-  subdir_done()
+if enable_introspection or enable_docs
+  common_ent_file = configure_file(
+    input: 'common.ent.in',
+    output: '@BASENAME@',
+    configuration: data_conf,
+  )
 endif
 
+if enable_introspection and (enable_man or enable_docs)
+  xsltproc_options = [
+    find_program('xsltproc'),
+    '--output', '@OUTPUT@',
+    '--path', meson.current_build_dir(),
+    '--xinclude',
+    '--nonet',
+    '--stringparam', 'man.output.quietly', '1',
+    '--stringparam', 'funcsynopsis.style', 'ansi',
+    '--stringparam', 'man.th.extra1.suppress', '1',
+    '--stringparam', 'man.authors.section.enabled', '0',
+    '--stringparam', 'man.copyright.section.enabled', '0',
+    '--stringparam', 'man.th.title.max.length', '30',
+  ]
 
-common_ent_file = configure_file(
-  input: 'common.ent.in',
-  output: '@BASENAME@',
-  configuration: data_conf,
-)
+  docbook_xls = 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl'
 
-xsltproc_options = [
-  find_program('xsltproc'),
-  '--output', '@OUTPUT@',
-  '--path', meson.current_build_dir(),
-  '--xinclude',
-  '--nonet',
-  '--stringparam', 'man.output.quietly', '1',
-  '--stringparam', 'funcsynopsis.style', 'ansi',
-  '--stringparam', 'man.th.extra1.suppress', '1',
-  '--stringparam', 'man.authors.section.enabled', '0',
-  '--stringparam', 'man.copyright.section.enabled', '0',
-  '--stringparam', 'man.th.title.max.length', '30',
-]
+  mans_xmls = []
 
-docbook_xls = 'http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl'
+  foreach man: mans
+    input = man[0] + '.xml'
+    content_files += join_paths(meson.current_source_dir(), input)
 
-mans_xmls = []
+    output = '@0@.@1@'.format(man[0], man[1])
 
-foreach man: mans
-  input = man[0] + '.xml'
-  content_files += join_paths(meson.current_source_dir(), input)
+    # not needed if only html requested
+    if enable_man
+      custom_target(
+        output,
+        input: input,
+        output: output,
+        command: xsltproc_options + [docbook_xls, '@INPUT@'],
+        depend_files: common_ent_file,
+        install: true,
+        install_dir: join_paths(nm_mandir, 'man' + man[1]),
+      )
+    endif
+  endforeach
 
-  output = '@0@.@1@'.format(man[0], man[1])
-
-  custom_target(
-    output,
-    input: input,
-    output: output,
-    command: xsltproc_options + [docbook_xls, '@INPUT@'],
-    depend_files: common_ent_file,
-    install: true,
-    install_dir: join_paths(nm_mandir, 'man' + man[1]),
-  )
-endforeach
-
-if enable_introspection
   merge_cmd = files(source_root / 'tools' / 'generate-docs-nm-settings-docs-merge.py')
 
   name = 'dbus'
@@ -151,13 +150,23 @@ if enable_introspection
 
     output = '@0@.@1@'.format(man[0], man[1])
 
-    custom_target(
-      output,
-      input: input,
-      output: output,
-      command: xsltproc_options + [docbook_xls, '@INPUT@'],
-      install: true,
-      install_dir: join_paths(nm_mandir, 'man' + man[1]),
-    )
+    # not needed if only html requested
+    if enable_man
+      custom_target(
+        output,
+        input: input,
+        output: output,
+        command: xsltproc_options + [docbook_xls, '@INPUT@'],
+        install: true,
+        install_dir: join_paths(nm_mandir, 'man' + man[1]),
+      )
+    endif
   endforeach
+# not needed if only html requested
+elif enable_man
+  if built_mans.length() > 0
+    install_man(built_mans)
+  else
+    error('Building manpages requires xsltproc and -Dintrospection=true, and no prebuilt manpages were found. Try building from a release tarball or using -Dman=false.')
+  endif
 endif
diff --git a/meson.build b/meson.build
index c03d98c15..1e28a7265 100644
--- a/meson.build
+++ b/meson.build
@@ -816,6 +816,7 @@ if enable_nm_cloud_setup
   assert(jansson_dep.found(), 'nm-cloud-setup requires jansson library. Use -Dnm_cloud_setup=false to disable it')
 endif
 
+enable_man = get_option('man')
 enable_docs = get_option('docs')
 
 more_asserts = get_option('more_asserts')
@@ -1001,9 +1002,14 @@ if enable_qt != 'false'
   endif
 endif
 
+# The man/ directory builds a couple targets needed by the docs build too.
+# If we build with docs but no man, then enter the subdir and only build
+# some targets.
+if enable_docs or enable_man
+  subdir('man')
+endif
 if enable_docs
   assert(enable_introspection, '-Ddocs=true requires -Dintrospection=true')
-  subdir('man')
   subdir('docs')
   meson.add_dist_script(
     'tools/meson-dist-data.sh',
@@ -1054,7 +1060,7 @@ meson.add_install_script(
   nm_pkgstatedir,
   nm_mandir,
   nm_sysconfdir,
-  enable_docs ? '1' : '0',
+  enable_man ? '1' : '0',
   enable_ifcfg_rh ? '1' : '0',
   enable_nm_cloud_setup ? '1' : '0',
   install_systemdunitdir ? '1' : '0',
diff --git a/meson_options.txt b/meson_options.txt
index 18d8bfc44..55762f65d 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -67,6 +67,7 @@ option('config_dhcp_default', type: 'combo', choices: ['dhclient', 'dhcpcd', 'in
 option('introspection', type: 'boolean', value: true, description: 'Enable introspection for this build')
 option('vapi', type : 'combo', choices : ['auto', 'true', 'false'], description: 'build Vala bindings')
 option('docs', type: 'boolean', value: false, description: 'use to build documentation')
+option('man', type: 'boolean', value: true, description: 'Install manpages')
 option('tests', type: 'combo', choices: ['yes', 'no', 'root'], value: 'yes', description: 'Build NetworkManager tests')
 option('firewalld_zone', type: 'boolean', value: true, description: 'Install and use firewalld zone for shared mode')
 option('more_asserts', type: 'string', value: 'auto', description: 'Enable more assertions for debugging (0 = no, 100 = all, default: auto)')
diff --git a/tools/meson-post-install.sh b/tools/meson-post-install.sh
index fe85d417a..2560e3d16 100755
--- a/tools/meson-post-install.sh
+++ b/tools/meson-post-install.sh
@@ -7,7 +7,7 @@ nm_pkglibdir="$4"
 nm_pkgstatedir="$5"
 nm_mandir="$6"
 nm_sysconfdir="$7"
-enable_docs="$8"
+enable_man="$8"
 enable_ifcfg_rh="$9"
 enable_nm_cloud_setup="${10}"
 install_systemdunitdir="${11}"
@@ -40,7 +40,7 @@ done
 mkdir -p "${DESTDIR}${nm_pkgstatedir}"
 chmod 0700 "${DESTDIR}${nm_pkgstatedir}"
 
-if [ "$enable_docs" = 1 ]; then
+if [ "$enable_man" = 1 ]; then
 
     for alias in nmtui-connect nmtui-edit nmtui-hostname; do
         ln -fn "${DESTDIR}${nm_mandir}/man1/nmtui.1" "${DESTDIR}${nm_mandir}/man1/${alias}.1"
@@ -58,4 +58,3 @@ if [ "$enable_nm_cloud_setup" = 1 -a "$install_systemdunitdir" = 1 ]; then
     ln -sfn '../pre-up.d/90-nm-cloud-setup.sh' "${DESTDIR}${nm_pkglibdir}/dispatcher.d/no-wait.d/90-nm-cloud-setup.sh"
     ln -sfn 'no-wait.d/90-nm-cloud-setup.sh' "${DESTDIR}${nm_pkglibdir}/dispatcher.d/90-nm-cloud-setup.sh"
 fi
-