[Top][All Lists]
[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
signature.asc
Description: OpenPGP digital signature
Re: [PATCH] Improve man page headers, Jordi Mallach, 2010/06/09
Re: [PATCH] Improve man page headers,
Vladimir 'φ-coder/phcoder' Serbinenko <=