[patch] gdb_gcore man/help/install [+doc] #2

[Jan Kratochvil <jan dot kratochvil at redhat dot com>]

On Mon, 25 Apr 2011 17:36:03 +0200, Tom Tromey wrote:
> Jan> The ".1.z" rule seems bogus to me, I have found these entries for it:
> 
> Yes, nuke it.

Done.


On Tue, 26 Apr 2011 21:59:44 +0200, Tom Tromey wrote:
> Tom> I wonder if we could use the same texi->man rules that gcc uses.
> 
> I found out today that binutils uses this, too, and that the texi2pod
> code is already in src/etc/.

I have found they generate man page from the main as.texinfo file itself.

gdb_gcore.sh (gcore) shell script has no entry in gdb.texinfo so far.

>From the practical point of view with the goal to generate only the nroff .1
format I think the choice is clear from nroff, pod and texinfo.
The most simple format for maintenance is pod.  Therefore I did not use
texi2pod at all.

Therefore I have written gdb_gcore.pod.  With this checked-in I would like to
convert gdb.1 also to gdb.pod.  There are various outstanding requests to
document this or that in gdb.1 but it is not too feasible IMHO in nroff.

Another approach would be some reorganization of gdb.texinfo to generate also
some huge man page from it but I do not plan to do so myself.

Tested some basic install/uninstall/install-man/uninstall-man.
The gdb_gcore.1 man page gets installed during default `make install',
together with the other existing man pages like gdb.1.

That rule to call pod2man looks weird, it seems to still workaround pod2man
bugs described in:
	http://sourceware.org/ml/binutils/2001-03/msg00453.html
It also produces empty output if pod2man is missing on the host system.
But the man-page should be pregenerated in .tar.gz (I did not test this part)
so the case of missing pod2man should not be a concern in the current style of
gdb.tar.gz.


Thanks,
Jan


gdb/
2011-12-06  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* Makefile.in (INSTALL_SCRIPT, install-man): New.
	(gdb.z): Remove.
	(install-only): Add gdb_gcore.sh installed as gcore.
	(uninstall): Add gcore.
	* data-directory/Makefile.in (.PHONY): Add install-man.
	(install-man): New.

gdb/doc/
2011-12-06  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* Makefile.in (program_transform_name, mandir, man1dir, POD2MAN)
	(MANFILES, man): New.
	(all-doc): Add man.
	(diststuff): Add man.
	(STAGESTUFF): Add *.1.
	(install-man, install-man1, uninstall-man, uninstall-man1, gdb_gcore.1):
	New.
	(maintainer-clean realclean): Add *.1.
	(install): Add install-man.
	(uninstall): Add uninstall-man.
	* gdb_gcore.pod: New file.
	* gdb_gcore.sh: Support also -h and --help.  Document multiple PIDs.

gdb/gdbserver/
2011-12-06  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* Makefile.in (install-man): New.

gdb/testsuite/
2011-12-06  Jan Kratochvil  <jan.kratochvil@redhat.com>

	* Makefile.in (install-man): New.

--- a/gdb/Makefile.in
+++ b/gdb/Makefile.in
@@ -59,6 +59,7 @@ LN_S = @LN_S@
 INSTALL = @INSTALL@
 INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_DATA = @INSTALL_DATA@
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
 
 DESTDIR =
 
@@ -1006,14 +1007,9 @@ check//%: force
 	    "$$target"; \
 	else true; fi
 
-info install-info clean-info dvi pdf install-pdf html install-html: force
+info install-info clean-info dvi pdf install-pdf html install-html install-man: force
 	@$(MAKE) $(FLAGS_TO_PASS) DO=$@ "DODIRS=$(SUBDIRS)" subdir_do
 
-gdb.z:gdb.1
-	nroff -man $(srcdir)/gdb.1 | col -b > gdb.t
-	pack gdb.t ; rm -f gdb.t
-	mv gdb.t.z gdb.z
-
 # Traditionally "install" depends on "all".  But it may be useful
 # not to; for example, if the user has made some trivial change to a
 # source file and doesn't care about rebuilding or just wants to save the
@@ -1039,6 +1035,16 @@ install-only: $(CONFIG_INSTALL)
 			$(DESTDIR)$(man1dir)/$$transformed_name.1 ; \
 		$(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(includedir)/gdb ; \
 		$(INSTALL_DATA) jit-reader.h $(DESTDIR)$(includedir)/gdb/jit-reader.h
+	transformed_name=`t='$(program_transform_name)'; \
+			  echo gcore | sed -e "$$t"` ; \
+		if test "x$$transformed_name" = x; then \
+		  transformed_name=gcore ; \
+		else \
+		  true ; \
+		fi ; \
+		$(SHELL) $(srcdir)/../mkinstalldirs $(DESTDIR)$(bindir) ; \
+		$(INSTALL_SCRIPT) $(srcdir)/gdb_gcore.sh \
+			$(DESTDIR)$(bindir)/$$transformed_name
 	@$(MAKE) DO=install "DODIRS=$(SUBDIRS)" $(FLAGS_TO_PASS) subdir_do
 .PHONY: install-tui
 install-tui:
@@ -1070,6 +1076,14 @@ uninstall: force $(CONFIG_UNINSTALL)
 		fi ; \
 		rm -f $(DESTDIR)$(bindir)/$$transformed_name$(EXEEXT) \
 		      $(DESTDIR)$(man1dir)/$$transformed_name.1
+	transformed_name=`t='$(program_transform_name)'; \
+			  echo gcore | sed -e $$t` ; \
+		if test "x$$transformed_name" = x; then \
+		  transformed_name=gcore ; \
+		else \
+		  true ; \
+		fi ; \
+		rm -f $(DESTDIR)$(bindir)/$$transformed_name
 	@$(MAKE) DO=uninstall "DODIRS=$(SUBDIRS)" $(FLAGS_TO_PASS) subdir_do
 .PHONY: uninstall-tui
 uninstall-tui:
--- a/gdb/data-directory/Makefile.in
+++ b/gdb/data-directory/Makefile.in
@@ -200,10 +200,10 @@ maintainer-clean realclean distclean: clean
 	rm -f Makefile
 
 .PHONY: check installcheck info dvi pdf html
-.PHONY: install-info install-pdf install-html clean-info
+.PHONY: install-info install-pdf install-html install-man clean-info
 check installcheck:
 info dvi pdf html:
-install-info install-pdf install-html:
+install-info install-pdf install-html install-man:
 clean-info:
 
 # GNU Make has an annoying habit of putting *all* the Makefile variables
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -27,6 +27,8 @@ datarootdir = @datarootdir@
 docdir = @docdir@
 pdfdir = @pdfdir@
 htmldir = @htmldir@
+program_transform_name = @program_transform_name@
+mandir = @mandir@
 
 SHELL = @SHELL@
 
@@ -37,6 +39,7 @@ INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_DATA = @INSTALL_DATA@
 
 mkinstalldirs = $(SHELL) $(srcdir)/../../mkinstalldirs
+man1dir = $(mandir)/man1
 
 # main GDB source directory
 gdbdir = $(srcdir)/..
@@ -59,6 +62,10 @@ TEXI2ROFF=texi2roff
 # where to find texi2dvi, ditto
 TEXI2DVI=texi2dvi
 
+# pod2man is used for man pages formatting.
+POD2MAN = pod2man --center="GNU Development Tools" \
+		  --release="gdb-`sed q $(srcdir)/../version.in`" --section=1
+
 # Package version and bug-reporting URL.
 PKGVERSION = @PKGVERSION@
 BUGURL_TEXI = @REPORT_BUGS_TEXI@
@@ -83,6 +90,9 @@ PDFFILES = gdb.pdf gdbint.pdf stabs.pdf refcard.pdf annotate.pdf
 HTMLFILES =  gdb/index.html gdbint/index.html stabs/index.html annotate/index.html
 HTMLFILES_INSTALL = gdb gdbint stabs annotate
 
+# Files to generate for man pages.
+MANFILES = gdb_gcore.1
+
 # There may be alternate predefined collections of switches to configure
 # the GDB manual.  Normally this is not done in synch with the software
 # config system, since this choice tends to be independent; most people
@@ -171,8 +181,9 @@ dvi: gdb.dvi gdbint.dvi stabs.dvi refcard.dvi annotate.dvi
 ps: gdb.ps gdbint.ps stabs.ps refcard.ps annotate.ps
 html: $(HTMLFILES)
 pdf: $(PDFFILES)
-all-doc: info dvi ps # pdf
-diststuff: info
+man: $(MANFILES)
+all-doc: info dvi ps man # pdf
+diststuff: info man
 	rm -f gdb-cfg.texi GDBvn.texi
 
 install-info: $(INFO_DEPS)
@@ -243,7 +254,35 @@ install-pdf: $(PDFFILES)
 	  $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \
 	done
 
-STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf
+install-man: install-man1
+
+install-man1: $(MANFILES)
+	-transformed_name=`t='$(program_transform_name)'; \
+			  echo gcore | sed -e "$$t"` ; \
+		if test "x$$transformed_name" = x; then \
+		  transformed_name=gcore ; \
+		else \
+		  true ; \
+		fi ; \
+		$(SHELL) $(gdbdir)/../mkinstalldirs \
+			$(DESTDIR)$(man1dir) ; \
+		$(INSTALL_DATA) $(srcdir)/gdb_gcore.1 \
+			$(DESTDIR)$(man1dir)/$$transformed_name.1
+
+uninstall-man: uninstall-man1
+
+uninstall-man1:
+	$(NORMAL_UNINSTALL)
+	transformed_name=`t='$(program_transform_name)'; \
+			  echo gcore | sed -e "$$t"` ; \
+		if test "x$$transformed_name" = x; then \
+		  transformed_name=gcore ; \
+		else \
+		  true ; \
+		fi ; \
+		rm -f $(DESTDIR)$(man1dir)/$$transformed_name.1
+
+STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf *.1
 
 # Copy the object files from a particular stage into a subdirectory.
 stage1: force
@@ -524,6 +563,16 @@ annotate.info: $(ANNOTATE_DOC_FILES)
 annotate/index.html: $(ANNOTATE_DOC_FILES)
 	$(MAKEHTML) $(MAKEHTMLFLAGS) -I $(srcdir) $(srcdir)/annotate.texinfo
 
+# Build the man page from the texinfo file.
+# The sed command removes the no-adjust Nroff command so that
+# the man output looks standard.
+gdb_gcore.1: $(srcdir)/gdb_gcore.pod
+	touch $@
+	-($(POD2MAN) gdb_gcore.pod | \
+		sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || \
+		(rm -f $@.T$$$$ && exit 1)
+
 force:
 
 Makefile: Makefile.in $(host_makefile_frag) ../config.status
@@ -552,8 +601,8 @@ distclean: clean
 # "clean" or "distclean".  Use maintainer-clean to remove them.
 
 maintainer-clean realclean: distclean
-	rm -f GDBvn.texi *.info* *.dvi *.ps *.html *.pdf
+	rm -f GDBvn.texi *.info* *.dvi *.ps *.html *.pdf *.1
 
-install: install-info
+install: install-info install-man
 
-uninstall: uninstall-info
+uninstall: uninstall-info uninstall-man
--- /dev/null
+++ b/gdb/doc/gdb_gcore.pod
@@ -0,0 +1,43 @@
+=head1 NAME
+
+gcore - generate a core file of a running program
+
+=head1 SYNOPSIS
+
+gcore [B<-o> I<filename>] I<PID1> [I<PID2>...]
+
+=head1 DESCRIPTION
+
+B<gcore> starts up B<gdb>, attaches to the given I<PID> and invokes the gcore
+command dumping the cores into files core.I<PID1>, core.I<PID2> etc.
+The programs being dumped remain running unaffected, except for being stopped
+for a short time during the dump.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-o> I<filename>
+
+Alternative core files base name from the default "core".
+
+=back
+
+=head1 SEE ALSO
+
+gdb(1)
+
+=head1 AUTHOR
+
+Jan Kratochvil <jan.kratochvil@redhat.com>
+
+=head1 COPYRIGHT
+
+Copyright (c) 2011 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".
--- a/gdb/gdb_gcore.sh
+++ b/gdb/gdb_gcore.sh
@@ -22,11 +22,16 @@
 # It starts up gdb, attaches to the given PID and invokes the gcore command.
 #
 
-if [ "$#" -eq "0" ]
-then
-    echo "usage:  gcore [-o filename] pid"
-    exit 2
-fi
+case $#$1 in
+  0|1-h|1--help)
+    echo "usage:  gcore [-o filename] pid1 [pid2...]"
+    if [ "$#" -eq "0" ]
+    then
+      exit 2
+    fi
+    exit 0
+    ;;
+esac
 
 # Need to check for -o option, but set default basename to "core".
 name=core
--- a/gdb/gdbserver/Makefile.in
+++ b/gdb/gdbserver/Makefile.in
@@ -227,6 +227,7 @@ install-pdf:
 html:
 install-html:
 clean-info:
+install-man:
 
 gdbserver$(EXEEXT): $(OBS) ${ADD_DEPS} ${CDEPS}
 	rm -f gdbserver$(EXEEXT)
--- a/gdb/testsuite/Makefile.in
+++ b/gdb/testsuite/Makefile.in
@@ -97,6 +97,7 @@ pdf:
 install-pdf:
 html:
 install-html:
+install-man:
 
 install: