manpages for everything
PATCH 1/1 manpages for everything
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.
Signature · 5 lines
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 /.)
2008-02-08 Robert Millan <[email protected]>
* 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 [email protected]' with [email protected]'.
* 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).
configure.ac renamed from grub2/configure.ac +2 -1
@@ -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.
Makefile.in renamed from grub2/Makefile.in +11 -2
@@ -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 \
util/i386/pc/grub-install.in renamed from grub2/util/i386/pc/grub-install.in +3 -3
@@ -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
util/i386/pc/grub-mkrescue.in renamed from grub2/util/i386/pc/grub-mkrescue.in +1 -1
@@ -49,7 +49,7 @@ Make GRUB rescue image. grub-mkimage generates a bootable rescue image of the specified type. -Report bugs to <[email protected]>. +Report bugs to <[email protected]>. EOF }
util/powerpc/ieee1275/grub-mkrescue.in renamed from grub2/util/powerpc/ieee1275/grub-mkrescue.in +1 -1
@@ -48,7 +48,7 @@ Make GRUB rescue image. grub-mkimage generates a bootable rescue CD image for PowerMac and CHRP. -Report bugs to <[email protected]>. +Report bugs to <[email protected]>. EOF }
util/update-grub.in renamed from grub2/util/update-grub.in +35 -4
@@ -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 <[email protected]>. +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 :
Review
Quoted 1 line · Robert Millan
(quoted diff) +1
-0+ $(HELP2MAN) --no-info $(builddir)/$$file > $(DESTDIR)$(mandir)/$$dest.1; \
I think I missed --section here. Possibly other options as well. --source=FSF ?
Signature · 5 lines
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 /.)
Quoted 1 line · Robert Millan
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
Signature · 3 lines
Jordi Mallach Pérez -- Debian developer http://www.debian.org/ [email protected] [email protected] http://www.sindominio.net/ GnuPG public key information available at http://oskuro.net/
Quoted 2 lines · Jordi Mallach
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?
Signature · 5 lines
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 /.)
Quoted 4 lines · Robert Millan
Quoted 2 lines
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.1Do 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.
Quoted 3 lines
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
Signature · 3 lines
Jordi Mallach Pérez -- Debian developer http://www.debian.org/ [email protected] [email protected] http://www.sindominio.net/ GnuPG public key information available at http://oskuro.net/
Quoted 14 lines · Jordi Mallach
Quoted 4 lines · Robert Millan
Quoted 2 lines
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.1Do 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
Quoted 5 lines
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. :-/
Quoted 5 lines
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.
Signature · 5 lines
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 /.)
Quoted 12 lines · Robert Millan
2008-02-08 Robert Millan <[email protected]>
* 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.
Quoted 6 lines
* util/i386/pc/grub-mkrescue.in (usage): Replace
[email protected]' with[email protected]'.
* 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.
Signature · 5 lines
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 /.)