[patch+doc] New gdbinit.5 man page

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

Hi Eli,

the primary goal is to add a new infrastructure so that man pages can be
generated from gdb.texinfo, like src/binutils/doc/ does.

Later I would like to convert current nroff src/gdb/gdb.1 also into
gdb.texinfo and also convert pending gdb_gcore.pod patch that way:
	[patch] gdb_gcore man/help/install [+doc] #2
	http://sourceware.org/ml/gdb-patches/2011-12/msg00157.html
	Message-ID: <20111206002555.GA12329@host2.jankratochvil.net>

It adds gdbinit.5 as a proof of concept as I had to write it anyway now.
I did not want to duplicate much the gdb.info content so this man page is
mostly just about references into the info document.

I have not developed any of the Makefile rules myself, it is just a port
+ simplification of the scripts and texinfo usage from src/binutils/doc/ .
Particularly the parts of Makefile.in generated from Makefile.am .


Thanks,
Jan


gdb/doc/
2013-02-11  Jan Kratochvil  <jan.kratochvil@redhat.com>

	New gdbinit.5 man page.
	* Makefile.in (mandir, man5dir, SYSTEM_GDBINIT, MANCONF, TEXI2POD)
	(POD2MAN5, MAN5S, MANS, man, install-man, install-man5, uninstall-man)
	(uninstall-man5): New.
	(STAGESTUFF): Add *.5.
	(GDBvn.texi): Add SYSTEM_GDBINIT.
	(gdbinit.5): New.
	(mostlyclean): Add $(MANS).
	* gdb.texinfo (@include gdb-cfg.texi): Wrap it by @c man begin INCLUDE.
	(@copying): Wrap it by @c man begin COPYRIGHT.
	(Top): Add Man Pages.
	(Man Pages, gdbinit man): New.

diff --git a/gdb/doc/Makefile.in b/gdb/doc/Makefile.in
index 7da67c6..ce3fa27 100644
--- a/gdb/doc/Makefile.in
+++ b/gdb/doc/Makefile.in
@@ -26,6 +26,8 @@ datarootdir = @datarootdir@
 docdir = @docdir@
 pdfdir = @pdfdir@
 htmldir = @htmldir@
+mandir = @mandir@
+man5dir = $(mandir)/man5
 
 SHELL = @SHELL@
 
@@ -35,6 +37,8 @@ INSTALL = @INSTALL@
 INSTALL_PROGRAM = @INSTALL_PROGRAM@
 INSTALL_DATA = @INSTALL_DATA@
 
+SYSTEM_GDBINIT = @SYSTEM_GDBINIT@
+
 mkinstalldirs = $(SHELL) $(srcdir)/../../mkinstalldirs
 
 # main GDB source directory
@@ -160,6 +164,21 @@ ANNOTATE_DOC_FILES = \
 	$(ANNOTATE_DOC_SOURCE_INCLUDES) \
 	$(ANNOTATE_DOC_BUILD_INCLUDES)
 
+# Options to extract the man page from gdb.texinfo
+MANCONF = -Dman
+
+TEXI2POD = perl $(srcdir)/../../etc/texi2pod.pl \
+		$(MAKEINFOFLAGS) $(MAKEINFO_EXTRA_FLAGS)
+
+POD2MAN5 = pod2man --center="GNU Development Tools" \
+		   --release="gdb-$(VERSION)" --section=5
+
+# List of man pages generated from gdb.texi
+MAN5S = \
+	gdbinit.5
+
+MANS = $(MAN5S)
+
 #### Host, target, and site specific Makefile fragments come in here.
 ###
 
@@ -170,6 +189,7 @@ 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)
+man: $(MANS)
 all-doc: info dvi ps # pdf
 diststuff: info
 	rm -f gdb-cfg.texi GDBvn.texi
@@ -242,7 +262,30 @@ install-pdf: $(PDFFILES)
 	  $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(pdfdir)/$$f"; \
 	done
 
-STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf
+install-man: install-man5
+
+install-man5: $(MAN5S)
+	test -z "$(man5dir)" || $(mkinstalldirs) "$(DESTDIR)$(man5dir)"
+	@list='$(MANS)'; for p in $$list; do \
+	  if test -f "$$p"; then d=; else d="$(srcdir)/"; fi; \
+	  f=`echo $$p | sed -e 's|^.*/||'`; \
+	  echo " $(INSTALL_DATA) '$$d$$p' '$(DESTDIR)$(man5dir)/$$f'"; \
+	  $(INSTALL_DATA) "$$d$$p" "$(DESTDIR)$(man5dir)/$$f"; \
+	done
+
+uninstall-man: uninstall-man5
+
+uninstall-man5:
+	@test -n "$(man5dir)" || exit 0; \
+	files=`{ l2='$(MANS)'; for i in $$l2; do echo "$$i"; done | \
+	  sed -n '/\.5[a-z]*$$/p'; \
+	} | sed -e 's,.*/,,;h;s,.*\.,,;s,^[^5][0-9a-z]*$$,5,;x' \
+	      -e 's,\.[0-9a-z]*$$,,;$(transform);G;s,\n,.,'`; \
+	test -z "$$files" || { \
+	  echo " ( cd '$(DESTDIR)$(man5dir)' && rm -f" $$files ")"; \
+	  cd "$(DESTDIR)$(man5dir)" && rm -f $$files; }
+
+STAGESTUFF = *.info* gdb-all.texi GDBvn.texi *.ps *.dvi *.pdf *.5
 
 # Copy the object files from a particular stage into a subdirectory.
 stage1: force
@@ -313,6 +356,9 @@ GDBvn.texi : ${gdbdir}/version.in
 	if test -z "$(READLINE_TEXI_INCFLAG)"; then \
 	  echo "@set SYSTEM_READLINE" >> ./GDBvn.new; \
 	fi
+	if [ -n "$(SYSTEM_GDBINIT)" ]; then \
+	  echo "@set SYSTEM_GDBINIT $(SYSTEM_GDBINIT)" >> ./GDBvn.new; \
+	fi
 	mv GDBvn.new GDBvn.texi
 
 # Updated atomically
@@ -523,6 +569,14 @@ annotate.info: $(ANNOTATE_DOC_FILES)
 annotate/index.html: $(ANNOTATE_DOC_FILES)
 	$(MAKEHTML) $(MAKEHTMLFLAGS) -I $(srcdir) $(srcdir)/annotate.texinfo
 
+# Man pages
+gdbinit.5: $(GDB_DOC_FILES)
+	touch $@
+	-$(TEXI2POD) $(MANCONF) -Dgdbinit < gdb.texinfo > gdbinit.pod
+	-($(POD2MAN5) gdbinit.pod | sed -e '/^.if n .na/d' > $@.T$$$$ && \
+		mv -f $@.T$$$$ $@) || (rm -f $@.T$$$$ && exit 1)
+	rm -f gdbinit.pod
+
 force:
 
 Makefile: Makefile.in $(host_makefile_frag) ../config.status
@@ -533,7 +587,7 @@ Makefile: Makefile.in $(host_makefile_frag) ../config.status
 # automatically generated files that are just intermediate files,
 
 mostlyclean:
-	rm -f gdb.mm gdb.ms gdb.me links2roff
+	rm -f gdb.mm gdb.ms gdb.me links2roff $(MANS)
 	rm -f $(GDB_TEX_TMPS)
 	rm -f $(GDBINT_TEX_TMPS)
 	rm -f $(STABS_TEX_TMPS)
diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index e3f336e..d789f98 100644
--- a/gdb/doc/gdb.texinfo
+++ b/gdb/doc/gdb.texinfo
@@ -6,7 +6,9 @@
 @c of @set vars.  However, you can override filename with makeinfo -o.
 @setfilename gdb.info
 @c
+@c man begin INCLUDE
 @include gdb-cfg.texi
+@c man end
 @c
 @settitle Debugging with @value{GDBN}
 @setchapternewpage odd
@@ -47,6 +49,7 @@
 @end direntry
 
 @copying
+@c man begin COPYRIGHT
 Copyright @copyright{} 1988-2013 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document
@@ -59,6 +62,7 @@ and with the Back-Cover Texts as in (a) below.
 (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
 this GNU Manual.  Buying copies from GNU Press supports the FSF in
 developing GNU and promoting software freedom.''
+@c man end
 @end copying
 
 @ifnottex
@@ -180,6 +184,7 @@ software in general.  We will miss him.
                                  the operating system
 * Trace File Format::		GDB trace file format
 * Index Section Format::        .gdb_index section format
+* Man Pages::			Manual pages
 * Copying::			GNU General Public License says
                                 how you can copy and share GDB
 * GNU Free Documentation License::  The license for this documentation
@@ -41346,6 +41351,69 @@ switch (die->tag)
 
 @include gpl.texi
 
+@node Man Pages
+@appendix Manual pages
+@cindex Man pages
+
+@menu
+* gdbinit man::                 gdbinit scripts
+@end menu
+
+@node gdbinit man,,,Man Pages
+@heading gdbinit
+
+@c man title gdbinit GDB initialization scripts
+
+@c man begin SYNOPSIS gdbinit
+@table @env
+@ifset SYSTEM_GDBINIT
+@itemx @value{SYSTEM_GDBINIT}
+@end ifset
+@itemx ~/.gdbinit
+@itemx ./.gdbinit
+@end table
+@c man end
+
+@c man begin DESCRIPTION gdbinit
+These files contain @value{GDBN} commands to automatically execute during
+@value{GDBN} startup.  The lines of contents are canned sequences of commands,
+described in the @value{GDBN} manual in node @code{Sequences}, accessible by
+shell command @code{info -f gdb -n Sequences}.
+
+Please read more in the @value{GDBN} manual in node @code{Startup},
+accessible by shell command @code{info -f gdb -n Startup}.
+
+@table @env
+@ifset SYSTEM_GDBINIT
+@item @value{SYSTEM_GDBINIT}
+@end ifset
+@ifclear SYSTEM_GDBINIT
+@item (not enabled during @value{GDBN} compilation with @code{--with-system-gdbinit})
+@end ifclear
+System-wide initialization file.  It is executed unless user specified
+@value{GDBN} option @code{-nx} or @code{-n}.
+See more in the @value{GDBN} manual in node @code{System-wide configuration},
+accessible by shell command @code{info -f gdb -n 'System-wide configuration'}.
+
+@item ~/.gdbinit
+User initialization file.  It is executed unless user specified
+@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}.
+
+@item ./.gdbinit
+Initialization file for current directory.  It may need to be enabled with
+@value{GDBN} security command @code{set auto-load local-gdbinit}.
+See more in the @value{GDBN} manual in node @code{Init File in the Current
+Directory} - shell command
+@code{info -f gdb -n 'Init File in the Current Directory'}.
+@end table
+@c man end
+
+@ignore
+@c man begin SEEALSO gdbinit
+gdb(1), @code{info -f gdb -n Startup}
+@c man end
+@end ignore
+
 @node GNU Free Documentation License
 @appendix GNU Free Documentation License
 @include fdl.texi