Re: [patch+doc] New gdbinit.5 man page

Jan Kratochvil
2013-02-20T08:44:12Z

On Tue, 19 Feb 2013 19:02:09 +0100, Eli Zaretskii wrote:
> There's a downside as well: you need Perl to be available.

Good catch, binutils.tar distributes the *.1 files, fixed gdb/doc/Makefile.in
to do the same [attached].

> If doing that helps people contribute and keep the man pages up to
> date, let's go for it.

I will therefore add later the other (two) man pages to gdb.texinfo.

Jan

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

New gdbinit.5 man page.
* Makefile.in (mandir, man5dir, SYSTEM_GDBINIT, MANCONF, TEXI2POD)
(POD2MAN5, MAN5S, MANS, man): New.
(diststuff): Add man.
(install-man, install-man5, uninstall-man, uninstall-man5): New.
(STAGESTUFF): Add *.5.
(GDBvn.texi): Add SYSTEM_GDBINIT.
(gdbinit.5): New.
(maintainer-clean realclean): 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..4572041 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,8 +189,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)
+man: $(MANS)
all-doc: info dvi ps # pdf
-diststuff: info
+diststuff: info man
rm -f gdb-cfg.texi GDBvn.texi

install-info: $(INFO_DEPS)
@@ -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
@@ -551,7 +605,7 @@ 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 $(MANS)

install: install-info

diff --git a/gdb/doc/gdb.texinfo b/gdb/doc/gdb.texinfo
index e8ac8c5..82d81b4 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
@@ -41350,6 +41355,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