grub-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [PATCH] Improve man page headers


From: Vladimir 'φ-coder/phcoder' Serbinenko
Subject: Re: [PATCH] Improve man page headers
Date: Wed, 09 Jun 2010 21:36:06 +0200
User-agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.1.9) Gecko/20100515 Icedove/3.0.4

On 06/08/2010 07:46 PM, Colin Watson wrote:
> 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.
>
>   
This doesn't seem likely to be a maintenance burden so go ahead.
> 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
>
>   


-- 
Regards
Vladimir 'φ-coder/phcoder' Serbinenko


Attachment: signature.asc
Description: OpenPGP digital signature


reply via email to

[Prev in Thread] Current Thread [Next in Thread]