From: "Vladimir 'φ-coder/phcoder' Serbinenko" <phcoder@gmail.com>
To: The development of GNU GRUB <grub-devel@gnu.org>
Subject: Re: [PATCH] Improve man page headers
Date: Wed, 09 Jun 2010 21:36:06 +0200 [thread overview]
Message-ID: <4C0FED26.1030906@gmail.com> (raw)
In-Reply-To: <20100608174656.GU21862@riva.ucam.org>
[-- Attachment #1: Type: text/plain, Size: 9248 bytes --]
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 <cjwatson@ubuntu.com>
>
> * 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 #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]
prev parent reply other threads:[~2010-06-09 19:36 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2010-06-08 17:46 [PATCH] Improve man page headers Colin Watson
2010-06-08 17:58 ` Grégoire Sutre
2010-06-08 18:26 ` Colin Watson
2010-06-09 15:14 ` Grégoire Sutre
2010-06-09 20:31 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-11 21:12 ` Colin Watson
2010-06-09 19:34 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-09 20:15 ` Colin Watson
2010-06-09 20:29 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-09 16:02 ` Jordi Mallach
2010-06-09 19:36 ` Vladimir 'φ-coder/phcoder' Serbinenko [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=4C0FED26.1030906@gmail.com \
--to=phcoder@gmail.com \
--cc=grub-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.