[PATCH] Improve man page headers

[Colin Watson]

The following patch improves the man pages we generate by giving them
decent NAME sections, which are included in indexes of man pages and so
are worth getting right.  help2man's default is something like
"grub-bin2h \- manual page for grub-bin2h (GRUB) 1.98" which is of
course hopeless in an index.

I know that the GNU Coding Standards do not recommend putting lots of
effort into manual pages, although they don't forbid doing so either -
see http://www.gnu.org/prep/standards/standards.html#Man-Pages.  In this
case, I haven't, and I don't think this is a big maintenance burden,
just a set of tweaks on top of most of the work being done by help2man
in order to make some warnings emitted by Debian's package checker go
away.  That said, I maintain the man-db package and I'm more than happy
to maintain GRUB's manual pages insofar as they need maintaining if
that's a requirement.

2010-06-08  Colin Watson  <address@hidden>

        * Makefile.in (install-local): Include $(srcdir)/docs/man/$$dest.h2m
        when generating manual pages.
        * docs/man/grub-bin2h.h2m: New file.
        * docs/man/grub-editenv.h2m: New file.
        * docs/man/grub-fstest.h2m: New file.
        * docs/man/grub-install.h2m: New file.
        * docs/man/grub-macho2img.h2m: New file.
        * docs/man/grub-mkconfig.h2m: New file.
        * docs/man/grub-mkdevicemap.h2m: New file.
        * docs/man/grub-mkfont.h2m: New file.
        * docs/man/grub-mkimage.h2m: New file.
        * docs/man/grub-mkpasswd-pbkdf2.h2m: New file.
        * docs/man/grub-mkrelpath.h2m: New file.
        * docs/man/grub-mkrescue.h2m: New file.
        * docs/man/grub-ofpathname.h2m: New file.
        * docs/man/grub-pe2elf.h2m: New file.
        * docs/man/grub-probe.h2m: New file.
        * docs/man/grub-reboot.h2m: New file.
        * docs/man/grub-script-check.h2m: New file.
        * docs/man/grub-set-default.h2m: New file.
        * docs/man/grub-setup.h2m: New file.

=== modified file 'Makefile.in'
--- Makefile.in 2010-05-18 11:55:26 +0000
+++ Makefile.in 2010-06-08 17:25:15 +0000
@@ -323,26 +323,26 @@ install-local: all
          if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
          dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
          $(INSTALL_PROGRAM) $$dir$$file $(DESTDIR)$(bindir)/$$dest; \
-         $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1 
$(builddir)/$$file; \
+         $(HELP2MAN) --section=1 -i $(srcdir)/docs/man/$$dest.h2m -o 
$(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
        done
        $(SHELL) $(mkinstalldirs) $(DESTDIR)$(sbindir) $(DESTDIR)$(mandir)/man8
        @list='$(sbin_UTILITIES)'; for file in $$list; do \
          if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
          dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
          $(INSTALL_PROGRAM) $$dir$$file $(DESTDIR)$(sbindir)/$$dest; \
-         $(HELP2MAN) --section=8 -o $(DESTDIR)$(mandir)/man8/$$dest.8 
$(builddir)/$$file; \
+         $(HELP2MAN) --section=8 -i $(srcdir)/docs/man/$$dest.h2m -o 
$(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
        done
        @list='$(bin_SCRIPTS)'; for file in $$list; do \
          if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
          dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
          $(INSTALL_SCRIPT) $$dir$$file $(DESTDIR)$(bindir)/$$dest; \
-         $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1 
$(builddir)/$$file; \
+         $(HELP2MAN) --section=1 -i $(srcdir)/docs/man/$$dest.h2m -o 
$(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
        done
        @list='$(sbin_SCRIPTS)'; for file in $$list; do \
          if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
          dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
          $(INSTALL_SCRIPT) $$dir$$file $(DESTDIR)$(sbindir)/$$dest; \
-         $(HELP2MAN) --section=8 -o $(DESTDIR)$(mandir)/man8/$$dest.8 
$(builddir)/$$file; \
+         $(HELP2MAN) --section=8 -i $(srcdir)/docs/man/$$dest.h2m -o 
$(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
        done
        $(SHELL) $(mkinstalldirs) $(DESTDIR)$(sysconfdir)/grub.d
        @list='$(grub-mkconfig_SCRIPTS)'; for file in $$list; do \

=== added directory 'docs/man'
=== added file 'docs/man/grub-bin2h.h2m'
--- docs/man/grub-bin2h.h2m     1970-01-01 00:00:00 +0000
+++ docs/man/grub-bin2h.h2m     2010-06-08 17:29:40 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-bin2h \- convert a binary file to a C header

=== added file 'docs/man/grub-editenv.h2m'
--- docs/man/grub-editenv.h2m   1970-01-01 00:00:00 +0000
+++ docs/man/grub-editenv.h2m   2010-06-08 17:30:31 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-editenv \- edit GRUB environment block

=== added file 'docs/man/grub-fstest.h2m'
--- docs/man/grub-fstest.h2m    1970-01-01 00:00:00 +0000
+++ docs/man/grub-fstest.h2m    2010-06-08 17:28:12 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-fstest \- debug tool for GRUB filesystem drivers

=== added file 'docs/man/grub-install.h2m'
--- docs/man/grub-install.h2m   1970-01-01 00:00:00 +0000
+++ docs/man/grub-install.h2m   2010-06-08 17:34:51 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-install \- install GRUB to a device

=== added file 'docs/man/grub-macho2img.h2m'
--- docs/man/grub-macho2img.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-macho2img.h2m 2010-06-08 17:31:07 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-macho2img \- convert Mach-O to raw image

=== added file 'docs/man/grub-mkconfig.h2m'
--- docs/man/grub-mkconfig.h2m  1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkconfig.h2m  2010-06-08 17:33:21 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkconfig \- generate a GRUB configuration file

=== added file 'docs/man/grub-mkdevicemap.h2m'
--- docs/man/grub-mkdevicemap.h2m       1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkdevicemap.h2m       2010-06-08 17:27:47 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkdevicemap \- generate a GRUB device map file automatically

=== added file 'docs/man/grub-mkfont.h2m'
--- docs/man/grub-mkfont.h2m    1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkfont.h2m    2010-06-08 17:28:47 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkfont \- make GRUB font files

=== added file 'docs/man/grub-mkimage.h2m'
--- docs/man/grub-mkimage.h2m   1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkimage.h2m   2010-06-08 17:26:37 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkimage \- make a bootable image of GRUB

=== added file 'docs/man/grub-mkpasswd-pbkdf2.h2m'
--- docs/man/grub-mkpasswd-pbkdf2.h2m   1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkpasswd-pbkdf2.h2m   2010-06-08 17:32:13 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkpasswd-pbkdf2 \- generate hashed password for GRUB

=== added file 'docs/man/grub-mkrelpath.h2m'
--- docs/man/grub-mkrelpath.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkrelpath.h2m 2010-06-08 17:29:13 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkrelpath \- make a system path relative to its root

=== added file 'docs/man/grub-mkrescue.h2m'
--- docs/man/grub-mkrescue.h2m  1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkrescue.h2m  2010-06-08 17:35:04 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkrescue \- make a GRUB rescue image

=== added file 'docs/man/grub-ofpathname.h2m'
--- docs/man/grub-ofpathname.h2m        1970-01-01 00:00:00 +0000
+++ docs/man/grub-ofpathname.h2m        2010-06-08 17:35:57 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-ofpathname \- find OpenBOOT path for a device

=== added file 'docs/man/grub-pe2elf.h2m'
--- docs/man/grub-pe2elf.h2m    1970-01-01 00:00:00 +0000
+++ docs/man/grub-pe2elf.h2m    2010-06-08 17:31:28 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-pe2elf \- convert PE image to ELF

=== added file 'docs/man/grub-probe.h2m'
--- docs/man/grub-probe.h2m     1970-01-01 00:00:00 +0000
+++ docs/man/grub-probe.h2m     2010-06-08 17:27:13 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-probe \- probe device information for GRUB

=== added file 'docs/man/grub-reboot.h2m'
--- docs/man/grub-reboot.h2m    1970-01-01 00:00:00 +0000
+++ docs/man/grub-reboot.h2m    2010-06-08 17:34:12 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-reboot \- set the default boot entry for GRUB, for the next boot only

=== added file 'docs/man/grub-script-check.h2m'
--- docs/man/grub-script-check.h2m      1970-01-01 00:00:00 +0000
+++ docs/man/grub-script-check.h2m      2010-06-08 17:30:11 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-script-check \- check grub.cfg for syntax errors

=== added file 'docs/man/grub-set-default.h2m'
--- docs/man/grub-set-default.h2m       1970-01-01 00:00:00 +0000
+++ docs/man/grub-set-default.h2m       2010-06-08 17:33:50 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-set-default \- set the default boot entry for GRUB

=== added file 'docs/man/grub-setup.h2m'
--- docs/man/grub-setup.h2m     1970-01-01 00:00:00 +0000
+++ docs/man/grub-setup.h2m     2010-06-08 17:32:59 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-setup \- set up a device to boot using GRUB

-- 
Colin Watson                                       address@hidden