Grub Development Archive on lore.kernel.org
 help / color / mirror / Atom feed
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 --]

      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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox