gprofng: PR29521 [docs] man pages are not in the release tarball

gprofng/ChangeLog
2023-01-20  Vladimir Mezentsev  <vladimir.mezentsev@oracle.com>

	PR gprofng/29521
	* configure.ac: Check if $MAKEINFO and $HELP2MAN are missing.
	* Makefile.am: Build doc if $MAKEINFO exists.
	* doc/gprofng.texi: Update documentation for gprofng.
	* doc/Makefile.am: Build gprofng.1.
	* src/Makefile.am: Move the build of gprofng.1 to doc/Makefile.am.
	* configure: Rebuild.
	* Makefile.in: Rebuild.
	* doc/Makefile.in: Rebuild.
	* src/Makefile.in: Rebuild.

3 files changed, 272 insertions, 14 deletions

diff --git a/gprofng/doc/Makefile.am b/gprofng/doc/Makefile.am
index 760c34f..8be0e92 100644
--- a/gprofng/doc/Makefile.am
+++ b/gprofng/doc/Makefile.am
@@ -19,9 +19,31 @@
 
 AUTOMAKE_OPTIONS = info-in-builddir foreign no-texinfo.tex
 
+# Options to extract the man page
+MANCONF = -Dman
+
+TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl $(AM_MAKEINFOFLAGS)
+POD2MAN = pod2man --center="User Commands" \
+	--release="binutils-$(VERSION)" --section=1
+
 info_TEXINFOS       = gprofng.texi
 gprofng_TEXINFOS    = fdl.texi
 TEXINFO_TEX         = .
 MAKEINFOHTML        = $(MAKEINFO) --html --no-split
 
-MAINTAINERCLEANFILES = gprofng.info
+man_MANS = gprofng.1
+
+# Build the man page from the texinfo file
+# The sed command removes the no-adjust Nroff command so that
+# the man output looks standard.
+gprofng.1: $(srcdir)/gprofng.texi
+	$(AM_V_GEN)touch $@
+	$(AM_V_at)-$(TEXI2POD) $(MANCONF) < $(srcdir)/gprofng.texi > gprofng.pod
+	$(AM_V_at)-($(POD2MAN) gprofng.pod | \
+	  sed -e '/^.if n .na/d' > $@.tmp && \
+	  mv -f $@.tmp $@) || (rm -f $@.tmp && exit 1)
+	$(AM_V_at)rm -f gprofng.pod
+
+MAINTAINERCLEANFILES = gprofng.info $(man_MANS)
+
+info: $(man_MANS)
diff --git a/gprofng/doc/Makefile.in b/gprofng/doc/Makefile.in
index a450183..3cd2068 100644
--- a/gprofng/doc/Makefile.in
+++ b/gprofng/doc/Makefile.in
@@ -182,7 +182,7 @@ am__can_run_installinfo = \
     n|no|NO) false;; \
     *) (install-info --version) >/dev/null 2>&1;; \
   esac
-am__installdirs = "$(DESTDIR)$(infodir)"
+am__installdirs = "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"
 am__vpath_adj_setup = srcdirstrip=`echo "$(srcdir)" | sed 's|.|.|g'`;
 am__vpath_adj = case $$p in \
     $(srcdir)/*) f=`echo "$$p" | sed "s|^$$srcdirstrip/||"`;; \
@@ -210,6 +210,9 @@ am__uninstall_files_from_dir = { \
     || { echo " ( cd '$$dir' && rm -f" $$files ")"; \
          $(am__cd) "$$dir" && rm -f $$files; }; \
   }
+man1dir = $(mandir)/man1
+NROFF = nroff
+MANS = $(man_MANS)
 am__tagged_files = $(HEADERS) $(SOURCES) $(TAGS_FILES) $(LISP)
 am__DIST_COMMON = $(gprofng_TEXINFOS) $(srcdir)/Makefile.in \
 	$(top_srcdir)/../mkinstalldirs mdate-sh texinfo.tex
@@ -361,11 +364,19 @@ top_srcdir = @top_srcdir@
 zlibdir = @zlibdir@
 zlibinc = @zlibinc@
 AUTOMAKE_OPTIONS = info-in-builddir foreign no-texinfo.tex
+
+# Options to extract the man page
+MANCONF = -Dman
+TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl $(AM_MAKEINFOFLAGS)
+POD2MAN = pod2man --center="User Commands" \
+	--release="binutils-$(VERSION)" --section=1
+
 info_TEXINFOS = gprofng.texi
 gprofng_TEXINFOS = fdl.texi
 TEXINFO_TEX = .
 MAKEINFOHTML = $(MAKEINFO) --html --no-split
-MAINTAINERCLEANFILES = gprofng.info
+man_MANS = gprofng.1
+MAINTAINERCLEANFILES = gprofng.info $(man_MANS)
 all: all-am
 
 .SUFFIXES:
@@ -558,6 +569,49 @@ maintainer-clean-aminfo:
 	  echo " rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]"; \
 	  rm -f $$i $$i-[0-9] $$i-[0-9][0-9] $$i_i[0-9] $$i_i[0-9][0-9]; \
 	done
+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)
 tags TAGS:
 
 ctags CTAGS:
@@ -600,9 +654,9 @@ distdir: $(DISTFILES)
 	  dist-info
 check-am: all-am
 check: check-am
-all-am: Makefile $(INFO_DEPS)
+all-am: Makefile $(INFO_DEPS) $(MANS)
 installdirs:
-	for dir in "$(DESTDIR)$(infodir)"; do \
+	for dir in "$(DESTDIR)$(infodir)" "$(DESTDIR)$(man1dir)"; do \
 	  test -z "$$dir" || $(MKDIR_P) "$$dir"; \
 	done
 install: install-am
@@ -652,11 +706,9 @@ html: html-am
 
 html-am: $(HTMLS)
 
-info: info-am
-
 info-am: $(INFO_DEPS)
 
-install-data-am: install-info-am
+install-data-am: install-info-am install-man
 
 install-dvi: install-dvi-am
 
@@ -739,7 +791,7 @@ install-info-am: $(INFO_DEPS)
 	    install-info --info-dir="$(DESTDIR)$(infodir)" "$(DESTDIR)$(infodir)/$$relfile" || :;\
 	  done; \
 	else : ; fi
-install-man:
+install-man: install-man1
 
 install-pdf: install-pdf-am
 
@@ -794,7 +846,9 @@ ps: ps-am
 ps-am: $(PSS)
 
 uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
-	uninstall-pdf-am uninstall-ps-am
+	uninstall-man uninstall-pdf-am uninstall-ps-am
+
+uninstall-man: uninstall-man1
 
 .MAKE: install-am install-strip
 
@@ -804,19 +858,32 @@ uninstall-am: uninstall-dvi-am uninstall-html-am uninstall-info-am \
 	html-am info info-am install install-am install-data \
 	install-data-am install-dvi install-dvi-am install-exec \
 	install-exec-am install-html install-html-am install-info \
-	install-info-am install-man install-pdf install-pdf-am \
-	install-ps install-ps-am install-strip installcheck \
-	installcheck-am installdirs maintainer-clean \
+	install-info-am install-man install-man1 install-pdf \
+	install-pdf-am install-ps install-ps-am install-strip \
+	installcheck installcheck-am installdirs maintainer-clean \
 	maintainer-clean-aminfo maintainer-clean-generic \
 	maintainer-clean-vti mostlyclean mostlyclean-aminfo \
 	mostlyclean-generic mostlyclean-libtool mostlyclean-vti pdf \
 	pdf-am ps ps-am tags-am uninstall uninstall-am \
 	uninstall-dvi-am uninstall-html-am uninstall-info-am \
-	uninstall-pdf-am uninstall-ps-am
+	uninstall-man uninstall-man1 uninstall-pdf-am uninstall-ps-am
 
 .PRECIOUS: Makefile
 
 
+# Build the man page from the texinfo file
+# The sed command removes the no-adjust Nroff command so that
+# the man output looks standard.
+gprofng.1: $(srcdir)/gprofng.texi
+	$(AM_V_GEN)touch $@
+	$(AM_V_at)-$(TEXI2POD) $(MANCONF) < $(srcdir)/gprofng.texi > gprofng.pod
+	$(AM_V_at)-($(POD2MAN) gprofng.pod | \
+	  sed -e '/^.if n .na/d' > $@.tmp && \
+	  mv -f $@.tmp $@) || (rm -f $@.tmp && exit 1)
+	$(AM_V_at)rm -f gprofng.pod
+
+info: $(man_MANS)
+
 # Tell versions [3.59,3.63) of GNU make to not export all variables.
 # Otherwise a system limit (for SysV at least) may be exceeded.
 .NOEXPORT:
diff --git a/gprofng/doc/gprofng.texi b/gprofng/doc/gprofng.texi
index 8b54878..1a2c84b 100644
--- a/gprofng/doc/gprofng.texi
+++ b/gprofng/doc/gprofng.texi
@@ -1,5 +1,8 @@
 \input texinfo @c -*-texinfo-*-
 
+@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
+@c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
+
 @c ----------------------------------------------------------------------------
 @c This is the Texinfo source file for the GPROFNG manual.
 @c
@@ -59,6 +62,10 @@ gprofng
 @cindex \label\, \string\
 @end macro
 
+@macro gcctabopt{body}
+@code{\body\}
+@end macro
+
 @c -- Get the version information ---------------------------------------------
 @include version.texi
 
@@ -99,6 +106,20 @@ section entitled ``GNU Free Documentation License.''
 @page
 @vskip 0pt plus 1filll
 @insertcopying
+
+@c man begin COPYRIGHT
+
+Copyright @copyright{} 2022-2023 Free Software Foundation, Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with no Invariant Sections, with no Front-Cover Texts, and with no
+Back-Cover Texts.  A copy of the license is included in the
+section entitled ``GNU Free Documentation License''.
+
+@c man end
+
 @end titlepage
 
 @c -- Generate the Table of Contents ------------------------------------------
@@ -163,6 +184,154 @@ Terminology
 @end menu
 @end ifinfo
 
+@ifset man
+
+@c man title gprofng the driver for the gprofng tool suite
+
+@c man begin SYNOPSIS
+gprofng [OPTION(S)] ACTION [@b{QUALIFIER}] [ARGUMENTS] TARGET
+@c man end
+
+@c man begin DESCRIPTION
+This is the driver for the GPROFNG tools suite to gather and analyze performance data.
+
+The driver executes the action specified. An example of an action is @code{collect}
+to collect performance data. Depending on the action, a qualifier may be needed to
+define the command. Several qualifiers support options. The last item on the command
+is the target the command applies to.
+
+For example, to collect performance data for an application called @code{a.out} and
+store the results in experiment directory @code{mydata.er}, the following command may
+be used:
+
+@smallexample
+$ gprofng collect app -o mydata.er a.out
+@end smallexample
+
+In this example, the action is @code{collect}, the qualifier is @code{app}, the single
+argument is @code{-o mydata.er} and the target is @code{a.out}.
+
+If gprofng is executed without any additional option, action, or target, a usage
+overview is printed.
+
+@c man end
+
+@c man begin OPTIONS
+
+@table @gcctabopt
+
+@item @var{--version}
+print the version number and exit.
+
+@item @var{--help}
+print usage information and exit.
+
+@end table
+
+@c man end
+
+@c man begin NOTES
+
+The gprofng driver supports the following commands.
+
+@c The man pages for the commands below can be viewed using the command name with "gprofng" replaced by "gp" and the spaces replaced by a dash ("-"). For example the man page
+@c        name for "gprofng collect app" is "gp-collect-app".
+
+Collect performance data:
+
+@table @code
+
+@item gprofng collect app
+collect application performance data.
+
+@end table
+
+Display the performance results:
+
+@table @code
+
+@item gprofng display text
+display the performance data in ASCII format.
+
+@item gprofng display html
+generate an HTML file from one or more experiments.
+
+@end table
+
+Miscellaneous commands:
+
+@table @code
+
+@item gprofng display src
+display source or disassembly with compiler annotations.
+
+@item gprofng archive
+include binaries and source code in an experiment directory.
+
+@end table
+
+It is also possible to invoke the lower level commands directly, but since
+these are subject to change, in particular the options, we recommend to
+use the driver.
+
+@c man end
+
+@c man begin ENVIRONMENT
+The following environment variables are supported:
+
+@table @code
+
+@item @env{GPROFNG_MAX_CALL_STACK_DEPTH}
+set the depth of the call stack (default is 256).
+
+@item @env{GPROFNG_USE_JAVA_OPTIONS}
+may be set when profiling a C/C++ application that uses dlopen() to execute Java code.
+
+@item @env{GPROFNG_SSH_REMOTE_DISPLAY}
+use this variable to define the ssh command executed by the remote display tool.
+
+@item @env{GPROFNG_SKIP_VALIDATION}
+set this variable to disable checking hardware, system, and Java versions.
+
+@item @env{GPROFNG_ALLOW_CORE_DUMP}
+set this variable to allow a core file to be generated; otherwise an error report is created on /tmp.
+
+@item @env{GPROFNG_ARCHIVE}
+use this variable to define the settings for automatic archiving upon experiment recording completion.
+
+@item @env{GPROFNG_ARCHIVE_COMMON_DIR}
+set this variable to the location of the common archive.
+
+@item @env{GPROFNG_JAVA_MAX_CALL_STACK_DEPTH}
+set the depth of the Java call stack; the default is 256; set to 0 to disable capturing of call stacks.
+
+@item @env{GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH}
+set the depth of the Java native call stack; the default is 256; set to 0 to disable capturing of call stacks (JNI and assembly call stacks are not captured).
+
+@end table
+
+@c man end
+
+@c man begin SEEALSO
+The man pages for the various gprofng commands are not available yet, but
+the @option{--help} option supported on each of the commands lists the options
+and provides more information.
+
+For example this displays the options supported on the @command{gprofng collect app}
+command:
+
+@smallexample
+$ gprofng collect app --help
+@end smallexample
+
+The user guide is available as an Info entry for @file{gprofng}.
+@c man end
+
+@end ifset
+
+@c man begin DESCRIPTION
+@c man end
+
 @c -- A new node --------------------------------------------------------------
 @node    Introduction
 @chapter Introduction