gprofng: Update documentation

This patch addresses bugzilla 29521:
Bug 29521 - [docs] man pages are not in the release tarball

The dependence on help2man to create the man pages has been eliminated.
All man pages are now written in Texinfo. Texi2pod and pod2man are used
to generate the man pages from the source.

The user guide has been significantly expanded. It also includes all
the man pages. These are formatted appropriately in the INFO, PDF, and
HTML formats.

The index in the user guide has been enhanced to include an overview
of all options and commands that have been documented so far.

The work on the documentation has not been completed, but this is
a significant step forward.

gprofng/ChangeLog
2023-04-15  Vladimir Mezentsev  <vladimir.mezentsev@oracle.com>

	PR gprofng/29521
	* doc/Makefile.am: Build documentation.
	* doc/gprofng.texi: Update documentation.
	* doc/version.texi: Likewise.
	* src/Makefile.am: Move the man pages generation to doc/Makefile.am.
	* gp-display-html/Makefile.am: Likewise.
	* doc/gp-archive.texi: New file.
	* doc/gp-collect-app.texi: New file.
	* doc/gp-display-html.texi: New file.
	* doc/gp-display-src.texi: New file.
	* doc/gp-display-text.texi: New file.
	* doc/gp-macros.texi: New file.
	* doc/gprofng_ug.texi: New file.
	* doc/Makefile.in: Rebuild.
	* gp-display-html/Makefile.in: Rebuild.
	* src/Makefile.in" Rebuild.

2 files changed, 10 insertions, 160 deletions

diff --git a/gprofng/src/Makefile.am b/gprofng/src/Makefile.am
index ab90bb0..219367f 100644
--- a/gprofng/src/Makefile.am
+++ b/gprofng/src/Makefile.am
@@ -121,7 +121,7 @@ QLParser.tab.cc QLParser.tab.hh: QLParser.yy
 	$(BISON) $^
 
 BUILT_SOURCES = QLParser.tab.hh
-EXTRA_DIST = QLParser.yy $(man_MANS)
+EXTRA_DIST = QLParser.yy
 
 
 lib_LTLIBRARIES = $(LIBGPROFNG)
@@ -157,60 +157,6 @@ gp_display_src_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
 gp_display_text_SOURCES = gp-display-text.cc ipc.cc ipcio.cc
 gp_display_text_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
 
-
-if BUILD_MAN
-
-man_MANS = \
-	gp-archive.1 \
-	gp-collect-app.1 \
-	gp-display-src.1 \
-	gp-display-text.1
-
-MAINTAINERCLEANFILES = $(man_MANS)
-
-# The man pages depend on the version number and on a help2man include file.
-common_mandeps = $(top_srcdir)/../bfd/version.m4
-
-# Use -o so that the `missing' program can infer the output file.
-# Embolden subcommand names in the output, and include a SEE ALSO.
-# Arrange to regenerate the output if we have help2man, but leave the
-# disted output there otherwise.
-# Some extra annoying complexity is in place so that people without
-# help2man dno't accidentally overwrite the manpage.
-
-INFO_PAGE            = "gprofng"
-MANUAL               = "User Commands"
-TEXT_GPROFNG         = "the driver for the gprofng tool suite"
-TEXT_GP_ARCHIVE      = "archive gprofng experiment data"
-TEXT_GP_COLLECT_APP  = "collect performance data for the target application"
-TEXT_GP_DISPLAY_SRC  = "display the source code, optionally interleaved with the disassembly of the target object"
-TEXT_GP_DISPLAY_TEXT = "display the performance data in plain text format"
-
-HELP2MAN_OPT = --libtool --no-info --info-page=$(INFO_PAGE) --manual=$(MANUAL)
-H2M_FILTER = | sed 's/\.TP/\.TP\n.B/' | sed 's/Commands:/\.SH COMMANDS/' \
-  | sed 's/See also:/\.SH SEE ALSO/' | sed 's/Documentation:/.SH DOCUMENTATION/' \
-  | sed 's/Limitations:/.SH LIMITATIONS/'
-
-gp-archive.1: $(srcdir)/gp-archive.cc $(common_mandeps) | ./gp-archive$(EXEEXT)
-	$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
-	  --name=$(TEXT_GP_ARCHIVE) ./gp-archive$(EXEEXT) $(H2M_FILTER) > $@
-
-gp-collect-app.1: $(srcdir)/gp-collect-app.cc $(common_mandeps) | ./gp-collect-app$(EXEEXT)
-	$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
-	  --name=$(TEXT_GP_COLLECT_APP) ./gp-collect-app$(EXEEXT) $(H2M_FILTER) > $@
-
-gp-display-src.1: $(srcdir)/gp-display-src.cc $(srcdir)/Command.cc \
-		$(common_mandeps) | ./gp-display-src$(EXEEXT)
-	$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
-	  --name=$(TEXT_GP_DISPLAY_SRC) ./gp-display-src$(EXEEXT) $(H2M_FILTER) > $@
-
-gp-display-text.1: $(srcdir)/gp-display-text.cc $(srcdir)/Command.cc \
-		$(common_mandeps) | ./gp-display-text$(EXEEXT)
-	$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
-	  --name=$(TEXT_GP_DISPLAY_TEXT) ./gp-display-text$(EXEEXT) $(H2M_FILTER) > $@
-
-endif
-
 # Distribution involves building the binaries to generate the manpage,
 # so ensure that the necessary libraries are built at dist time.
 dist-hook: $(LIBGPROFNG)
diff --git a/gprofng/src/Makefile.in b/gprofng/src/Makefile.in
index 605fa4f..b881268 100644
--- a/gprofng/src/Makefile.in
+++ b/gprofng/src/Makefile.in
@@ -156,7 +156,7 @@ am__uninstall_files_from_dir = { \
          $(am__cd) "$$dir" && rm -f $$files; }; \
   }
 am__installdirs = "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" \
-	"$(DESTDIR)$(man1dir)" "$(DESTDIR)$(dbedir)"
+	"$(DESTDIR)$(dbedir)"
 LTLIBRARIES = $(lib_LTLIBRARIES)
 am__DEPENDENCIES_1 =
 libgprofng_la_DEPENDENCIES = $(top_builddir)/../opcodes/libopcodes.la \
@@ -275,9 +275,6 @@ am__can_run_installinfo = \
     n|no|NO) false;; \
     *) (install-info --version) >/dev/null 2>&1;; \
   esac
-man1dir = $(mandir)/man1
-NROFF = nroff
-MANS = $(man_MANS)
 DATA = $(dbe_DATA)
 am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
 # Read a list of newline-separated strings from the standard input,
@@ -547,7 +544,7 @@ AM_CFLAGS = $(GPROFNG_CFLAGS) $(PTHREAD_CFLAGS) \
 
 AM_CXXFLAGS = $(AM_CFLAGS)
 BUILT_SOURCES = QLParser.tab.hh
-EXTRA_DIST = QLParser.yy $(man_MANS)
+EXTRA_DIST = QLParser.yy
 lib_LTLIBRARIES = $(LIBGPROFNG)
 libgprofng_la_SOURCES = $(CCSOURCES) $(CSOURCES)
 libgprofng_la_LDFLAGS = -version-info 0:0:0
@@ -572,35 +569,6 @@ gp_display_src_SOURCES = gp-display-src.cc
 gp_display_src_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
 gp_display_text_SOURCES = gp-display-text.cc ipc.cc ipcio.cc
 gp_display_text_LDADD = $(LIBGPROFNG) $(CLOCK_GETTIME_LINK) $(ZLIB)
-@BUILD_MAN_TRUE@man_MANS = \
-@BUILD_MAN_TRUE@	gp-archive.1 \
-@BUILD_MAN_TRUE@	gp-collect-app.1 \
-@BUILD_MAN_TRUE@	gp-display-src.1 \
-@BUILD_MAN_TRUE@	gp-display-text.1
-
-@BUILD_MAN_TRUE@MAINTAINERCLEANFILES = $(man_MANS)
-
-# The man pages depend on the version number and on a help2man include file.
-@BUILD_MAN_TRUE@common_mandeps = $(top_srcdir)/../bfd/version.m4
-
-# Use -o so that the `missing' program can infer the output file.
-# Embolden subcommand names in the output, and include a SEE ALSO.
-# Arrange to regenerate the output if we have help2man, but leave the
-# disted output there otherwise.
-# Some extra annoying complexity is in place so that people without
-# help2man dno't accidentally overwrite the manpage.
-@BUILD_MAN_TRUE@INFO_PAGE = "gprofng"
-@BUILD_MAN_TRUE@MANUAL = "User Commands"
-@BUILD_MAN_TRUE@TEXT_GPROFNG = "the driver for the gprofng tool suite"
-@BUILD_MAN_TRUE@TEXT_GP_ARCHIVE = "archive gprofng experiment data"
-@BUILD_MAN_TRUE@TEXT_GP_COLLECT_APP = "collect performance data for the target application"
-@BUILD_MAN_TRUE@TEXT_GP_DISPLAY_SRC = "display the source code, optionally interleaved with the disassembly of the target object"
-@BUILD_MAN_TRUE@TEXT_GP_DISPLAY_TEXT = "display the performance data in plain text format"
-@BUILD_MAN_TRUE@HELP2MAN_OPT = --libtool --no-info --info-page=$(INFO_PAGE) --manual=$(MANUAL)
-@BUILD_MAN_TRUE@H2M_FILTER = | sed 's/\.TP/\.TP\n.B/' | sed 's/Commands:/\.SH COMMANDS/' \
-@BUILD_MAN_TRUE@  | sed 's/See also:/\.SH SEE ALSO/' | sed 's/Documentation:/.SH DOCUMENTATION/' \
-@BUILD_MAN_TRUE@  | sed 's/Limitations:/.SH LIMITATIONS/'
-
 all: $(BUILT_SOURCES)
 	$(MAKE) $(AM_MAKEFLAGS) all-am
 
@@ -885,49 +853,6 @@ mostlyclean-libtool:
 
 clean-libtool:
 	-rm -rf .libs _libs
-install-man1: $(man_MANS)
-	@$(NORMAL_INSTALL)
-	@list1=''; \
-	list2='$(man_MANS)'; \
-	test -n "$(man1dir)" \
-	  && test -n "`echo $$list1$$list2`" \
-	  || exit 0; \
-	echo " $(MKDIR_P) '$(DESTDIR)$(man1dir)'"; \
-	$(MKDIR_P) "$(DESTDIR)$(man1dir)" || exit 1; \
-	{ for i in $$list1; do echo "$$i"; done;  \
-	if test -n "$$list2"; then \
-	  for i in $$list2; do echo "$$i"; done \
-	    | sed -n '/\.1[a-z]*$$/p'; \
-	fi; \
-	} | while read p; do \
-	  if test -f $$p; then d=; else d="$(srcdir)/"; fi; \
-	  echo "$$d$$p"; echo "$$p"; \
-	done | \
-	sed -e 'n;s,.*/,,;p;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,' | \
-	sed 'N;N;s,\n, ,g' | { \
-	list=; while read file base inst; do \
-	  if test "$$base" = "$$inst"; then list="$$list $$file"; else \
-	    echo " $(INSTALL_DATA) '$$file' '$(DESTDIR)$(man1dir)/$$inst'"; \
-	    $(INSTALL_DATA) "$$file" "$(DESTDIR)$(man1dir)/$$inst" || exit $$?; \
-	  fi; \
-	done; \
-	for i in $$list; do echo "$$i"; done | $(am__base_list) | \
-	while read files; do \
-	  test -z "$$files" || { \
-	    echo " $(INSTALL_DATA) $$files '$(DESTDIR)$(man1dir)'"; \
-	    $(INSTALL_DATA) $$files "$(DESTDIR)$(man1dir)" || exit $$?; }; \
-	done; }
-
-uninstall-man1:
-	@$(NORMAL_UNINSTALL)
-	@list=''; test -n "$(man1dir)" || exit 0; \
-	files=`{ for i in $$list; do echo "$$i"; done; \
-	l2='$(man_MANS)'; for i in $$l2; do echo "$$i"; done | \
-	  sed -n '/\.1[a-z]*$$/p'; \
-	} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^1][0-9a-z]*$$,1,;x' \
-	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
-	dir='$(DESTDIR)$(man1dir)'; $(am__uninstall_files_from_dir)
 install-dbeDATA: $(dbe_DATA)
 	@$(NORMAL_INSTALL)
 	@list='$(dbe_DATA)'; test -n "$(dbedir)" || list=; \
@@ -1038,11 +963,11 @@ distdir: $(DISTFILES)
 check-am: all-am
 check: $(BUILT_SOURCES)
 	$(MAKE) $(AM_MAKEFLAGS) check-am
-all-am: Makefile $(LTLIBRARIES) $(PROGRAMS) $(MANS) $(DATA)
+all-am: Makefile $(LTLIBRARIES) $(PROGRAMS) $(DATA)
 install-binPROGRAMS: install-libLTLIBRARIES
 
 installdirs:
-	for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(man1dir)" "$(DESTDIR)$(dbedir)"; do \
+	for dir in "$(DESTDIR)$(libdir)" "$(DESTDIR)$(bindir)" "$(DESTDIR)$(dbedir)"; do \
 	  test -z "$$dir" || $(MKDIR_P) "$$dir"; \
 	done
 install: $(BUILT_SOURCES)
@@ -1077,7 +1002,6 @@ maintainer-clean-generic:
 	@echo "This command is intended for maintainers to use"
 	@echo "it deletes files that may require special tools to rebuild."
 	-test -z "$(BUILT_SOURCES)" || rm -f $(BUILT_SOURCES)
-	-test -z "$(MAINTAINERCLEANFILES)" || rm -f $(MAINTAINERCLEANFILES)
 clean: clean-am
 
 clean-am: clean-binPROGRAMS clean-generic clean-libLTLIBRARIES \
@@ -1101,7 +1025,7 @@ info: info-am
 
 info-am:
 
-install-data-am: install-dbeDATA install-man
+install-data-am: install-dbeDATA
 
 install-dvi: install-dvi-am
 
@@ -1117,7 +1041,7 @@ install-info: install-info-am
 
 install-info-am:
 
-install-man: install-man1
+install-man:
 
 install-pdf: install-pdf-am
 
@@ -1148,9 +1072,7 @@ ps: ps-am
 ps-am:
 
 uninstall-am: uninstall-binPROGRAMS uninstall-dbeDATA \
-	uninstall-libLTLIBRARIES uninstall-man
-
-uninstall-man: uninstall-man1
+	uninstall-libLTLIBRARIES
 
 .MAKE: all check install install-am install-strip
 
@@ -1163,13 +1085,13 @@ uninstall-man: uninstall-man1
 	install-data-am install-dbeDATA install-dvi install-dvi-am \
 	install-exec install-exec-am install-html install-html-am \
 	install-info install-info-am install-libLTLIBRARIES \
-	install-man install-man1 install-pdf install-pdf-am install-ps \
+	install-man install-pdf install-pdf-am install-ps \
 	install-ps-am install-strip installcheck installcheck-am \
 	installdirs maintainer-clean maintainer-clean-generic \
 	mostlyclean mostlyclean-compile mostlyclean-generic \
 	mostlyclean-libtool pdf pdf-am ps ps-am tags tags-am uninstall \
 	uninstall-am uninstall-binPROGRAMS uninstall-dbeDATA \
-	uninstall-libLTLIBRARIES uninstall-man uninstall-man1
+	uninstall-libLTLIBRARIES
 
 .PRECIOUS: Makefile
 
@@ -1177,24 +1099,6 @@ uninstall-man: uninstall-man1
 QLParser.tab.cc QLParser.tab.hh: QLParser.yy
 	$(BISON) $^
 
-@BUILD_MAN_TRUE@gp-archive.1: $(srcdir)/gp-archive.cc $(common_mandeps) | ./gp-archive$(EXEEXT)
-@BUILD_MAN_TRUE@	$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
-@BUILD_MAN_TRUE@	  --name=$(TEXT_GP_ARCHIVE) ./gp-archive$(EXEEXT) $(H2M_FILTER) > $@
-
-@BUILD_MAN_TRUE@gp-collect-app.1: $(srcdir)/gp-collect-app.cc $(common_mandeps) | ./gp-collect-app$(EXEEXT)
-@BUILD_MAN_TRUE@	$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
-@BUILD_MAN_TRUE@	  --name=$(TEXT_GP_COLLECT_APP) ./gp-collect-app$(EXEEXT) $(H2M_FILTER) > $@
-
-@BUILD_MAN_TRUE@gp-display-src.1: $(srcdir)/gp-display-src.cc $(srcdir)/Command.cc \
-@BUILD_MAN_TRUE@		$(common_mandeps) | ./gp-display-src$(EXEEXT)
-@BUILD_MAN_TRUE@	$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
-@BUILD_MAN_TRUE@	  --name=$(TEXT_GP_DISPLAY_SRC) ./gp-display-src$(EXEEXT) $(H2M_FILTER) > $@
-
-@BUILD_MAN_TRUE@gp-display-text.1: $(srcdir)/gp-display-text.cc $(srcdir)/Command.cc \
-@BUILD_MAN_TRUE@		$(common_mandeps) | ./gp-display-text$(EXEEXT)
-@BUILD_MAN_TRUE@	$(AM_V_GEN)_BUILDING_MANPAGE=1 $(HELP2MAN) $(HELP2MAN_OPT) \
-@BUILD_MAN_TRUE@	  --name=$(TEXT_GP_DISPLAY_TEXT) ./gp-display-text$(EXEEXT) $(H2M_FILTER) > $@
-
 # Distribution involves building the binaries to generate the manpage,
 # so ensure that the necessary libraries are built at dist time.
 dist-hook: $(LIBGPROFNG)