[PATCH] manpages for everything

[PATCH] manpages for everything

[Robert Millan]

[-- Attachment #1: Type: text/plain, Size: 451 bytes --]


Hey, I just wrote manpages for everything!

Well, actually I wrote this patch that makes our build system probe for
help2man, and use it to generate a manpage automatically for each
utility. :-)

They can be a good substitute for the info manual we don't have yet, or
(in the future) a complement to it.

-- 
Robert Millan

<GPLv2> I know my rights; I want my phone call!
<DRM> What use is a phone call… if you are unable to speak?
(as seen on /.)

[-- Attachment #2: manpages.diff --]
[-- Type: text/x-diff, Size: 6766 bytes --]

2008-02-08  Robert Millan  <rmh@aybabtu.com>

	* configure.ac: Probe for `help2man'.
	* Makefile.in (builddir): New variable.
	(HELP2MAN): Likewise.  Set to `true' when @HELP2MAN@ doesn't provide it.
	(install-local): For every executable
	utility or script that is installed, invoke $(HELP2MAN) to install a
	manpage based on --help output.

	* util/i386/pc/grub-install.in: Move down `update-grub_lib' sourcing, so
	that it doesn't prevent --help from working in build tree.

	* util/i386/pc/grub-mkrescue.in (usage): Replace `grub-devel@gnu.org'
	with `bug-grub@gnu.org'.
	* util/powerpc/ieee1275/grub-mkrescue.in (usage): Likewise.
	* util/update-grub.in (usage): New function.
	Implement proper argument check, with support for --help and --version
	(as well as existing -y).

diff -x configure -x config.h.in -x CVS -x '*~' -x '*.mk' -urp ../grub2/configure.ac ./configure.ac
--- ../grub2/configure.ac	2008-02-04 20:56:11.000000000 +0100
+++ ./configure.ac	2008-02-08 20:51:30.000000000 +0100
@@ -115,8 +115,9 @@ AC_PROG_INSTALL
 AC_PROG_AWK
 AC_PROG_MAKE_SET
 
-# This is not a "must".
+# These are not a "must".
 AC_PATH_PROG(RUBY, ruby)
+AC_PATH_PROG(HELP2MAN, help2man)
 
 #
 # Checks for host programs.
diff -x configure -x config.h.in -x CVS -x '*~' -x '*.mk' -urp ../grub2/Makefile.in ./Makefile.in
--- ../grub2/Makefile.in	2008-02-04 20:56:11.000000000 +0100
+++ ./Makefile.in	2008-02-08 22:14:45.000000000 +0100
@@ -20,6 +20,7 @@ SHELL = /bin/sh
 transform = @program_transform_name@
 
 srcdir = @srcdir@
+builddir = @builddir@
 top_srcdir = @top_srcdir@
 VPATH = @srcdir@
 prefix = @prefix@
@@ -71,6 +72,10 @@ OBJCOPY = @OBJCOPY@
 STRIP = @STRIP@
 NM = @NM@
 RUBY = @RUBY@
+HELP2MAN = @HELP2MAN@
+ifeq (, $(HELP2MAN))
+HELP2MAN = true
+endif
 AWK = @AWK@
 LIBCURSES = @LIBCURSES@
 LIBLZO = @LIBLZO@
@@ -157,27 +162,31 @@ install-local: all
 	  dest="`echo $$file | sed 's,.*/,,'`"; \
 	  $(INSTALL_DATA) $$dir$$file $(DESTDIR)$(pkgdatadir)/$$dest; \
 	done
-	$(mkinstalldirs) $(DESTDIR)$(bindir)
+	$(mkinstalldirs) $(DESTDIR)$(bindir) $(DESTDIR)$(mandir)
 	@list='$(bin_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)$(bindir)/$$dest; \
+	  $(HELP2MAN) --no-info $(builddir)/$$file > $(DESTDIR)$(mandir)/$$dest.1; \
 	done
-	$(mkinstalldirs) $(DESTDIR)$(sbindir)
+	$(mkinstalldirs) $(DESTDIR)$(sbindir) $(DESTDIR)$(mandir)
 	@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) --no-info $(builddir)/$$file > $(DESTDIR)$(mandir)/$$dest.8; \
 	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) --no-info $(builddir)/$$file > $(DESTDIR)$(mandir)/$$dest.1; \
 	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) --no-info $(builddir)/$$file > $(DESTDIR)$(mandir)/$$dest.8; \
 	done
 	$(mkinstalldirs) $(DESTDIR)$(sysconfdir)/grub.d
 	@list='$(update-grub_SCRIPTS)'; for file in $$list; do \
diff -x configure -x config.h.in -x CVS -x '*~' -x '*.mk' -urp ../grub2/util/i386/pc/grub-install.in ./util/i386/pc/grub-install.in
--- ../grub2/util/i386/pc/grub-install.in	2008-01-12 16:11:57.000000000 +0100
+++ ./util/i386/pc/grub-install.in	2008-02-08 22:03:01.000000000 +0100
@@ -45,9 +45,6 @@ force_lba=
 recheck=no
 debug=no
 
-# for make_system_path_relative_to_its_root()
-. ${libdir}/grub/update-grub_lib
-
 # Usage: usage
 # Print the usage.
 usage () {
@@ -120,6 +117,9 @@ for option in "$@"; do
     esac
 done
 
+# for make_system_path_relative_to_its_root()
+. ${libdir}/grub/update-grub_lib
+
 if test "x$install_device" = x; then
     echo "install_device not specified." 1>&2
     usage
diff -x configure -x config.h.in -x CVS -x '*~' -x '*.mk' -urp ../grub2/util/i386/pc/grub-mkrescue.in ./util/i386/pc/grub-mkrescue.in
--- ../grub2/util/i386/pc/grub-mkrescue.in	2008-02-03 19:31:02.000000000 +0100
+++ ./util/i386/pc/grub-mkrescue.in	2008-02-08 22:12:09.000000000 +0100
@@ -49,7 +49,7 @@ Make GRUB rescue image.
 
 grub-mkimage generates a bootable rescue image of the specified type.
 
-Report bugs to <grub-devel@gnu.org>.
+Report bugs to <bug-grub@gnu.org>.
 EOF
 }
 
diff -x configure -x config.h.in -x CVS -x '*~' -x '*.mk' -urp ../grub2/util/powerpc/ieee1275/grub-mkrescue.in ./util/powerpc/ieee1275/grub-mkrescue.in
--- ../grub2/util/powerpc/ieee1275/grub-mkrescue.in	2008-01-31 18:09:39.000000000 +0100
+++ ./util/powerpc/ieee1275/grub-mkrescue.in	2008-02-08 22:12:26.000000000 +0100
@@ -48,7 +48,7 @@ Make GRUB rescue image.
 
 grub-mkimage generates a bootable rescue CD image for PowerMac and CHRP.
 
-Report bugs to <grub-devel@gnu.org>.
+Report bugs to <bug-grub@gnu.org>.
 EOF
 }
 
diff -x configure -x config.h.in -x CVS -x '*~' -x '*.mk' -urp ../grub2/util/update-grub.in ./util/update-grub.in
--- ../grub2/util/update-grub.in	2008-01-12 16:11:56.000000000 +0100
+++ ./util/update-grub.in	2008-02-08 22:05:29.000000000 +0100
@@ -31,6 +31,41 @@ platform=@platform@
 grub_mkdevicemap=${sbindir}/`echo grub-mkdevicemap | sed ${transform}`
 grub_probe=${sbindir}/`echo grub-probe | sed ${transform}`
 
+# Usage: usage
+# Print the usage.
+usage () {
+    cat <<EOF
+Usage: $0 [OPTION]
+Generate /boot/grub/grub.cfg
+
+  -h, --help              print this message and exit
+  -v, --version           print the version information and exit
+  -y                      ignored for compatibility
+
+Report bugs to <bug-grub@gnu.org>.
+EOF
+}
+
+# Check the arguments.
+for option in "$@"; do
+    case "$option" in
+    -h | --help)
+	usage
+	exit 0 ;;
+    -v | --version)
+	echo "$0 (GNU GRUB ${PACKAGE_VERSION})"
+	exit 0 ;;
+    -y)
+        echo "$0: warning: Ignoring -y option (no longer needed)." >&2
+        ;;
+    -*)
+	echo "Unrecognized option \`$option'" 1>&2
+	usage
+	exit 1
+	;;
+    esac
+done
+
 # for convert_system_path_to_grub_path(), font_path()
 . ${libdir}/grub/update-grub_lib
 
@@ -43,10 +78,6 @@ if [ "$UID" != 0 ] ; then
   exit 1
 fi
 
-if [ "$1" = "-y" ] ; then
-  echo "$0: warning: Ignoring -y option (no longer needed)." >&2
-fi
-
 set $grub_mkdevicemap dummy
 if test -f "$1"; then
     :

Re: [PATCH] manpages for everything

[Robert Millan]

On Fri, Feb 08, 2008 at 10:29:00PM +0100, Robert Millan wrote:
> +	  $(HELP2MAN) --no-info $(builddir)/$$file > $(DESTDIR)$(mandir)/$$dest.1; \

I think I missed --section here.  Possibly other options as well. --source=FSF ?

-- 
Robert Millan

<GPLv2> I know my rights; I want my phone call!
<DRM> What use is a phone call… if you are unable to speak?
(as seen on /.)

Re: [PATCH] manpages for everything

[Jordi Mallach]

On Sat, Feb 09, 2008 at 01:17:16AM +0100, Robert Millan wrote:
> I think I missed --section here.  Possibly other options as well. --source=FSF ?

Yes. For reference, I use this for GNU mailutils.

#!/bin/sh

## mangen.sh
## Copyright (C) 2004 Free Software Foundation, Inc.
##
## GNU Mailutils is free software; you can redistribute it and/or
## modify it under the terms of the GNU General Public License as
## published by the Free Software Foundation; either version 2, or (at
## your option) any later version.
##
## This program is distributed in the hope that it will be useful, but
## WITHOUT ANY WARRANTY; without even the implied warranty of
## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
## General Public License for more details.
##
## You should have received a copy of the GNU General Public License
## along with this program; if not, write to the Free Software
## Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
##
## All mail utilities must be already installed!
## Requires `help2man'. Assume standard `/usr/local' by default.

set -e

if test -z "$1"; then
  prefix="/usr/local"
else
  prefix=$1
fi

export LD_LIBRARY_PATH="$prefix/lib"

help2man="help2man"

bin1="dotlock.mailutils frm.mailutils from.mailutils guimb mail mailutils-config messages.mailutils mimeview movemail.mailutils popauth readmsg.mailutils sieve"
sbin8="comsatd imap4d pop3d"
libexec8="mail.local mail.remote"

for program in $bin1; do
  echo "Creating $program.1..."
  desc=`$prefix/bin/$program --help | sed -n '2s/.*-- //p'`
  $help2man -N -i debian/mangen.inc -s 1 -S FSF -n "$desc" $prefix/bin/$program >$program.1
done

for program in $sbin8; do
  desc=`$prefix/sbin/$program --help | sed -n '2s/.*-- //p'`
  echo "Creating $program.8..."
  $help2man -N -i debian/mangen.inc -s 8 -S FSF -n "$desc" $prefix/sbin/$program >$program.8
done

for program in $libexec8; do
  desc=`$prefix/lib/mailutils/$program --help | sed -n '2s/.*-- //p'`
  echo "Creating $program.8..."
  $help2man -N -i debian/mangen.inc -s 8mailutils -S FSF -n "$desc" $prefix/lib/mailutils/$program >$program.8
done

exit 0

mangen.inc just includes the following, which doesn't apply to GRUB2:

[see also]
The complete GNU mailutils manual is not available in Debian systems
due to licensing reasons. You can find this manual online in the
GNU mailutils webpage:
.br
http://www.gnu.org/software/mailutils/manual/index.html.

Jordi
-- 
Jordi Mallach Pérez  --  Debian developer     http://www.debian.org/
jordi@sindominio.net     jordi@debian.org     http://www.sindominio.net/
GnuPG public key information available at http://oskuro.net/

Re: [PATCH] manpages for everything

[Robert Millan]

On Sat, Feb 09, 2008 at 04:02:06AM +0100, Jordi Mallach wrote:
>   desc=`$prefix/bin/$program --help | sed -n '2s/.*-- //p'`
>   $help2man -N -i debian/mangen.inc -s 1 -S FSF -n "$desc" $prefix/bin/$program >$program.1

Do we need $desc/-n ?  It looks like a workaround for a limitation in help2man
(or for some oddness in mailutils output).

Btw, what will we need when we support l10n in those utils' --help output?  LANG=C
for English manpages, plus some logic to enable each other supported language?  Do
we have to take something into account right now?

-- 
Robert Millan

<GPLv2> I know my rights; I want my phone call!
<DRM> What use is a phone call… if you are unable to speak?
(as seen on /.)

Re: [PATCH] manpages for everything

[Robert Millan]

On Fri, Feb 08, 2008 at 10:29:00PM +0100, Robert Millan wrote:

> 2008-02-08  Robert Millan  <rmh@aybabtu.com>
> 
> 	* configure.ac: Probe for `help2man'.
> 	* Makefile.in (builddir): New variable.
> 	(HELP2MAN): Likewise.  Set to `true' when @HELP2MAN@ doesn't provide it.
> 	(install-local): For every executable
> 	utility or script that is installed, invoke $(HELP2MAN) to install a
> 	manpage based on --help output.
> 
> 	* util/i386/pc/grub-install.in: Move down `update-grub_lib' sourcing, so
> 	that it doesn't prevent --help from working in build tree.
> 
> 	* util/i386/pc/grub-mkrescue.in (usage): Replace `grub-devel@gnu.org'
> 	with `bug-grub@gnu.org'.
> 	* util/powerpc/ieee1275/grub-mkrescue.in (usage): Likewise.
> 	* util/update-grub.in (usage): New function.
> 	Implement proper argument check, with support for --help and --version
> 	(as well as existing -y).

Committed, with some minor corrections.

-- 
Robert Millan

<GPLv2> I know my rights; I want my phone call!
<DRM> What use is a phone call… if you are unable to speak?
(as seen on /.)

Re: [PATCH] manpages for everything

[Jordi Mallach]

On Sat, Feb 09, 2008 at 11:30:42AM +0100, Robert Millan wrote:
> >   desc=`$prefix/bin/$program --help | sed -n '2s/.*-- //p'`
> >   $help2man -N -i debian/mangen.inc -s 1 -S FSF -n "$desc" $prefix/bin/$program >$program.1
> Do we need $desc/-n ?  It looks like a workaround for a limitation in help2man
> (or for some oddness in mailutils output).

If I remember correctly, the default description in help2man manpages is
a generic one, not useful at all.

readmsg --help gives me:
jordi@nubol:~$ readmsg --help
Forma d'ús: readmsg [OPCIÓ...]
GNU readmsg -- mostra missatges

I extract the "show messages part" from this and use it as the
description.

I now found a bug report: #368628. In short, I think we need this here
too.

> Btw, what will we need when we support l10n in those utils' --help output?  LANG=C
> for English manpages, plus some logic to enable each other supported language?  Do
> we have to take something into account right now?

Not for now. When we do have utils translations, the tricky part will be
assuring the --help output is translated, or it'll be of little use, or
will be half in English, half translated, etc. So we'd have to make some
kind of rule, like "only generate l10n'd manpages if the po is up to
date and 100% translated".

This, if we want to go with autogenerated manpages forever. If we'd use
the autogenerated manpages as a base for manually maintained manpages,
then we would use "po4a" to maintain translations of the original
documents.

Jordi
-- 
Jordi Mallach Pérez  --  Debian developer     http://www.debian.org/
jordi@sindominio.net     jordi@debian.org     http://www.sindominio.net/
GnuPG public key information available at http://oskuro.net/

Re: [PATCH] manpages for everything

[Robert Millan]

On Sat, Feb 09, 2008 at 02:16:10PM +0100, Jordi Mallach wrote:
> On Sat, Feb 09, 2008 at 11:30:42AM +0100, Robert Millan wrote:
> > >   desc=`$prefix/bin/$program --help | sed -n '2s/.*-- //p'`
> > >   $help2man -N -i debian/mangen.inc -s 1 -S FSF -n "$desc" $prefix/bin/$program >$program.1
> > Do we need $desc/-n ?  It looks like a workaround for a limitation in help2man
> > (or for some oddness in mailutils output).
> 
> If I remember correctly, the default description in help2man manpages is
> a generic one, not useful at all.
> 
> readmsg --help gives me:
> jordi@nubol:~$ readmsg --help
> Forma d'ús: readmsg [OPCIÓ...]
> GNU readmsg -- mostra missatges
> 
> I extract the "show messages part" from this and use it as the
> description.
> 
> I now found a bug report: #368628. In short, I think we need this here
> too.

I see.  Well, I didn't do the $dest part this time since I'm short in time atm.
:-/

> Not for now. When we do have utils translations, the tricky part will be
> assuring the --help output is translated, or it'll be of little use, or
> will be half in English, half translated, etc. So we'd have to make some
> kind of rule, like "only generate l10n'd manpages if the po is up to
> date and 100% translated".

Ok.

-- 
Robert Millan

<GPLv2> I know my rights; I want my phone call!
<DRM> What use is a phone call… if you are unable to speak?
(as seen on /.)