From 46d51dbdc8b9c93871c34416006cf7f28b987c90 Mon Sep 17 00:00:00 2001
From: Olivier Dion <odion@efficios.com>
Date: Mon, 2 Oct 2023 12:01:29 -0400
Subject: [PATCH] doc/man/Makefile: Mimic mandb(5) path hierarchy
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

The following allows developers to read locally generated man pages by
using the `pre-inst-env' script. For example:

  $ ./pre-inst-env man lttng-add-context

will open the `lttng-add-context.1' man pages in the build directory
under which the `pre-inst-env' was generated.

This is done by:

  1. Simlinking `build/doc/man{1,3,7,8}' to `build/doc/man'

  2. Adding MANPATH to `pre-inst-env'

The symlinking part is a hack to force `man' to use our current doc
layout, doing a less invasive change than would be required otherwise

Change-Id: I2ea1af779f237fe1808a1d44d4f3b1c3a8535e2d
Signed-off-by: Olivier Dion <odion@efficios.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>
---
 doc/man/Makefile.am | 29 ++++++++++++++++++++++++++++-
 pre-inst-env.in     |  4 ++++
 2 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/doc/man/Makefile.am b/doc/man/Makefile.am
index 037d84d9f..8f20ede92 100644
--- a/doc/man/Makefile.am
+++ b/doc/man/Makefile.am
@@ -7,6 +7,9 @@
 # function which adds the source directory prefix and adds a given suffix
 manaddsuffix = $(addsuffix $(1),$(addprefix $(srcdir)/,$(2)))
 
+# Local targets.
+LOCAL =
+
 # List only the names without the .*.txt extension here:
 MAN1_NAMES = \
 	lttng \
@@ -113,7 +116,7 @@ MAN_H_RECIPE = \
 %.8.h: %.8
 	$(MAN_H_RECIPE)
 
-all-local: $(MAN_H)
+LOCAL += $(MAN_H)
 
 CLEANFILES += $(MAN_H)
 endif # EMBED_HELP
@@ -205,6 +208,27 @@ dist_man7_MANS += $(MAN7)
 dist_man8_MANS += $(MAN8)
 endif # MAN_PAGES_OPT
 
+MAN_HIERARCHY = man1 man3 man7 man8
+
+LOCAL += $(MAN_HIERARCHY)
+
+CLEANFILES += $(MAN_HIERARCHY)
+
+# Mimic mandb(8) path hierarchy -- as if installed -- by symlinking
+# sub-directories to the top man directory. This allows developers to read
+# the locally generated man pages. For example `$ ./pre-inst-env man lttng'.
+man1:
+	@ln -s $(abs_builddir) $@
+
+man3:
+	@ln -s $(abs_builddir) $@
+
+man7:
+	@ln -s $(abs_builddir) $@
+
+man8:
+	@ln -s $(abs_builddir) $@
+
 if !MAN_PAGES_OPT
 dist-hook:
 	@echo "Error: Please enable the man pages before creating a distribution tarball."
@@ -215,5 +239,8 @@ endif # !MAN_PAGES_OPT
 EXTRA_DIST = $(MAN_TXT) $(COMMON_TXT) $(XSL_FILE) \
 	$(ASCIIDOC_CONF) $(ASCIIDOC_ATTRS_CONF).in
 
+# Build local targets.
+all-local: $(LOCAL)
+
 # keep generated man pages that can be considered intermediate files
 .PRECIOUS: %.1 %.3 %.7 %.8
diff --git a/pre-inst-env.in b/pre-inst-env.in
index acc6e8a83..1a0641d6a 100644
--- a/pre-inst-env.in
+++ b/pre-inst-env.in
@@ -24,4 +24,8 @@ export LTTNG_SESSIOND_PATH
 PATH="$bin/lttng:$bin/lttng-consumerd:$bin/lttng-crash:$bin/lttng-relayd:$bin/lttng-sessiond:$PATH"
 export PATH
 
+# Use local path to search manual pages.
+MANPATH="$builddir/doc/man"
+export MANPATH
+
 exec "$@"
-- 
2.34.1