adding URL to --help output

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

What do you think of these patches?  A recent discussion among GNU
developers suggested that we should provide a URL for package home pages
as part of --help output.  The first patch does that for autoconf itself,
while the second takes care of generated configure files.  If everyone
likes the direction these patches are headed, I can also fix config.status
and testsuite to use this information.  The second patch also shows, using
autoconf as an example, how we can make life easier for GNU packages that
have a URL computable from the package name.

Also, does anyone see an easy way to factor out some of the redundancy in
specifying the URL in the first patch, or making it easier to AC_SUBST the
bug-reporting address so that a distro could substitute in their address?
 The problem is that the expansion is shared between both shell and perl
scripts, where the text is encountered under slightly different quoting
rules (for example, whether you use @ or \@).

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkl/Ap0ACgkQ84KuGfSFAYDq0wCgp9WVtpVgv0LZmhf0BqjU492g
bgMAoNFzInbXk0G3h5EYSpj8AhoaW8Ji
=NWTc
-----END PGP SIGNATURE-----

>From 8d2dc7285e9f05ed0878a9724a61afdf3cbd0571 Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Mon, 26 Jan 2009 11:39:43 -0700
Subject: [PATCH] Improve --help output to call out some URLs, part 1.

* bin/autoconf.as (usage): Make output consistent with recent
change in gnulib version-etc module.
* bin/autoheader.in ($help): Likewise.
* bin/autom4te.in ($help): Likewise.
* bin/autoreconf.in ($help): Likewise.
* bin/autoscan.in ($help): Likewise.
* bin/autoupdate.in ($help): Likewise.
* bin/ifnames.in ($help): Likewise.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog         |   12 ++++++++++++
 bin/autoconf.as   |    6 ++++--
 bin/autoheader.in |    5 ++++-
 bin/autom4te.in   |    6 ++++--
 bin/autoreconf.in |    4 +++-
 bin/autoscan.in   |    7 +++++--
 bin/autoupdate.in |    4 +++-
 bin/ifnames.in    |    4 +++-
 8 files changed, 38 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index e7d833f..582cff9 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2009-01-26  Eric Blake  <address@hidden>
 
+       Improve --help output to call out some URLs, part 1.
+       * bin/autoconf.as (usage): Make output consistent with recent
+       change in gnulib version-etc module.
+       * bin/autoheader.in ($help): Likewise.
+       * bin/autom4te.in ($help): Likewise.
+       * bin/autoreconf.in ($help): Likewise.
+       * bin/autoscan.in ($help): Likewise.
+       * bin/autoupdate.in ($help): Likewise.
+       * bin/ifnames.in ($help): Likewise.
+
+2009-01-26  Eric Blake  <address@hidden>
+
        Improve AC_DEFUN_ONCE semantics.
        * lib/m4sugar/m4sugar.m4 (m4_defun_once): Rewrite to be no-op,
        rather than warning, on second use, and make sure first use never
diff --git a/bin/autoconf.as b/bin/autoconf.as
index dcd8ae0..3f4ba3f 100644
--- a/bin/autoconf.as
+++ b/bin/autoconf.as
@@ -4,7 +4,7 @@ m4_divert_push([HEADER-COPYRIGHT])dnl
 # autoconf -- create `configure' using m4 macros
 
 # Copyright (C) 1992, 1993, 1994, 1996, 1999, 2000, 2001, 2002, 2003,
-# 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+# 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -63,7 +63,9 @@ Tracing:
 In tracing mode, no configuration script is created.  FORMAT defaults
 to \`\$f:\$l:\$n:\$%'; see \`autom4te --help' for information about FORMAT.
 
-Report bugs to <address@hidden>."]
+Report bugs to <address@hidden>.
+GNU Autoconf home page: http://www.gnu.org/software/autoconf/
+General help using GNU software: http://www.gnu.org/gethelp/";]
 
 version=["\
 autoconf (@PACKAGE_NAME@) @VERSION@
diff --git a/bin/autoheader.in b/bin/autoheader.in
index ab5bfce..3a38294 100644
--- a/bin/autoheader.in
+++ b/bin/autoheader.in
@@ -8,7 +8,8 @@ eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S 
"$0" "$@";; esac'
 # autoheader -- create `config.h.in' from `configure.ac'
 
 # Copyright (C) 1992, 1993, 1994, 1996, 1998, 1999, 2000, 2001, 2002,
-# 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+# 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation,
+# Inc.
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -81,6 +82,8 @@ Library directories:
   -I, --include=DIR          append directory DIR to search path
 
 Report bugs to <address@hidden>.
+GNU Autoconf home page: http://www.gnu.org/software/autoconf/
+General help using GNU software: http://www.gnu.org/gethelp/
 ";
 
 
diff --git a/bin/autom4te.in b/bin/autom4te.in
index 50c410c..38af018 100644
--- a/bin/autom4te.in
+++ b/bin/autom4te.in
@@ -6,8 +6,8 @@ eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S 
"$0" "$@";; esac'
     if 0;
 
 # autom4te - Wrapper around M4 libraries.
-# Copyright (C) 2001, 2002, 2003, 2005, 2006, 2007, 2008 Free Software
-# Foundation, Inc.
+# Copyright (C) 2001, 2002, 2003, 2005, 2006, 2007, 2008, 2009 Free
+# Software Foundation, Inc.
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -198,6 +198,8 @@ SEP can be empty for the default (comma for \@ and *, colon 
for %),
 a single character for that character, or {STRING} to use a string.
 
 Report bugs to <address@hidden>.
+GNU Autoconf home page: http://www.gnu.org/software/autoconf/
+General help using GNU software: http://www.gnu.org/gethelp/
 ";
 
 # $VERSION
diff --git a/bin/autoreconf.in b/bin/autoreconf.in
index 86e8826..4f04a41 100644
--- a/bin/autoreconf.in
+++ b/bin/autoreconf.in
@@ -7,7 +7,7 @@ eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S 
"$0" "$@";; esac'
 
 # autoreconf - install the GNU Build System in a directory tree
 # Copyright (C) 1994, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-# 2007, 2008  Free Software Foundation, Inc.
+# 2007, 2008, 2009 Free Software Foundation, Inc.
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -92,6 +92,8 @@ The environment variables AUTOCONF, AUTOHEADER, AUTOMAKE, 
ACLOCAL,
 AUTOPOINT, LIBTOOLIZE, M4, and MAKE are honored.
 
 Report bugs to <address@hidden>.
+GNU Autoconf home page: http://www.gnu.org/software/autoconf/
+General help using GNU software: http://www.gnu.org/gethelp/
 ";
 
 # $VERSION
diff --git a/bin/autoscan.in b/bin/autoscan.in
index 18d9ac1..8008364 100644
--- a/bin/autoscan.in
+++ b/bin/autoscan.in
@@ -4,7 +4,7 @@
 
 # autoscan - Create configure.scan (a preliminary configure.ac) for a package.
 # Copyright (C) 1994, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-#  2007, 2008 Free Software Foundation, Inc.
+# 2007, 2008, 2009 Free Software Foundation, Inc.
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -118,7 +118,10 @@ Library directories:
   -B, --prepend-include=DIR  prepend directory DIR to search path
   -I, --include=DIR          append directory DIR to search path
 
-Report bugs to <address@hidden>.\n";
+Report bugs to <address@hidden>.
+GNU Autoconf home page: http://www.gnu.org/software/autoconf/
+General help using GNU software: http://www.gnu.org/gethelp/
+";
 
 # $version
 # --------
diff --git a/bin/autoupdate.in b/bin/autoupdate.in
index c923559..acffbac 100644
--- a/bin/autoupdate.in
+++ b/bin/autoupdate.in
@@ -4,7 +4,7 @@
 
 # autoupdate - modernize an Autoconf file.
 # Copyright (C) 1994, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
-# 2007, 2008 Free Software Foundation, Inc.
+# 2007, 2008, 2009 Free Software Foundation, Inc.
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -79,6 +79,8 @@ Library directories:
   -I, --include=DIR          append directory DIR to search path
 
 Report bugs to <address@hidden>.
+GNU Autoconf home page: http://www.gnu.org/software/autoconf/
+General help using GNU software: http://www.gnu.org/gethelp/
 ";
 
 # $VERSION
diff --git a/bin/ifnames.in b/bin/ifnames.in
index 5ee70d7..1d1710f 100644
--- a/bin/ifnames.in
+++ b/bin/ifnames.in
@@ -8,7 +8,7 @@ eval 'case $# in 0) exec @PERL@ -S "$0";; *) exec @PERL@ -S 
"$0" "$@";; esac'
 # ifnames - print the identifiers used in C preprocessor conditionals
 
 # Copyright (C) 1994, 1995, 1999, 2000, 2001, 2002, 2003, 2005, 2006,
-# 2007, 2008 Free Software Foundation, Inc.
+# 2007, 2008, 2009 Free Software Foundation, Inc.
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -61,6 +61,8 @@ space-separated list of the files in which that identifier 
occurs.
   -V, --version   print version number, then exit
 
 Report bugs to <address@hidden>.
+GNU Autoconf home page: http://www.gnu.org/software/autoconf/
+General help using GNU software: http://www.gnu.org/gethelp/
 ";
 
 
-- 
1.6.0.4


>From f3b1e961506d82f02c2e642dfee9ad58c99e942c Mon Sep 17 00:00:00 2001
From: Eric Blake <address@hidden>
Date: Mon, 26 Jan 2009 16:43:20 -0700
Subject: [PATCH] Improve --help output to call out some URLs, part 2.

* lib/autoconf/general.m4 (_AC_INIT_PACKAGE): Support optional URL
parameter, mapped to AC_PACKAGE_URL.
(_AC_INIT_DEFAULTS, _AC_INIT_PREPARE): Substitute it.
(_AC_INIT_HELP): Use it in './configure --help' output.
* doc/autoconf.texi (Initializing configure) <AC_INIT>: Document
new parameter.
* NEWS: Likewise.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog               |   11 +++++++++++
 NEWS                    |    4 ++++
 doc/autoconf.texi       |   18 ++++++++++++++----
 lib/autoconf/general.m4 |   34 ++++++++++++++++++++++++++++------
 4 files changed, 57 insertions(+), 10 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 582cff9..460ffa0 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2009-01-26  Eric Blake  <address@hidden>
+
+       Improve --help output to call out some URLs, part 2.
+       * lib/autoconf/general.m4 (_AC_INIT_PACKAGE): Support optional URL
+       parameter, mapped to AC_PACKAGE_URL.
+       (_AC_INIT_DEFAULTS, _AC_INIT_PREPARE): Substitute it.
+       (_AC_INIT_HELP): Use it in './configure --help' output.
+       * doc/autoconf.texi (Initializing configure) <AC_INIT>: Document
+       new parameter.
+       * NEWS: Likewise.
+
 2009-01-26  Eric Blake  <address@hidden>
 
        Improve --help output to call out some URLs, part 1.
diff --git a/NEWS b/NEWS
index d5c7ed2..ba006cd 100644
--- a/NEWS
+++ b/NEWS
@@ -25,6 +25,10 @@ GNU Autoconf NEWS - User visible changes.
 ** AC_HEADER_ASSERT is fixed so that './configure --enable-assert' no
    longer mistakenly disables assertions.
 
+** AC_INIT now takes an optional fifth parameter that can be used to
+   set AC_PACKAGE_URL, a URL for the package's home page; the URL is
+   used in `configure --help' and is also available via AC_DEFINE.
+
 ** Autotest testsuites accept an option --jobs[=N] for parallel testing.
 
 ** Autotest testsuites do not attempt to write startup error messages
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index fc7d42b..bc58070 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -1756,7 +1756,7 @@ Initializing configure
 
 @anchor{AC_INIT}
 @defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @
-  @ovar{tarname})
+  @ovar{tarname}, @ovar{url})
 @acindex{INIT}
 Process any command-line arguments and perform various initializations
 and verifications.
@@ -1769,7 +1769,8 @@ Initializing configure
 package name (e.g., @samp{GNU Autoconf}), while the former is meant for
 distribution tar ball names (e.g., @samp{autoconf}).  It defaults to
 @var{package} with @samp{GNU } stripped, lower-cased, and all characters
-other than alphanumerics and underscores are changed to @samp{-}.
+other than alphanumerics and underscores are changed to @samp{-}.  If
+provided, @var{url} should be the home page for the package.
 
 It is preferable that the arguments of @code{AC_INIT} be static, i.e.,
 there should not be any shell computation, but they can be computed by
@@ -1790,7 +1791,7 @@ Initializing configure
 @acindex{PACKAGE_TARNAME}
 @ovindex PACKAGE_TARNAME
 @cvindex PACKAGE_TARNAME
-Exactly @var{tarname}.
+Exactly @var{tarname}, possibly generated from @var{package}.
 
 @item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION}
 @acindex{PACKAGE_VERSION}
@@ -1808,7 +1809,16 @@ Initializing configure
 @acindex{PACKAGE_BUGREPORT}
 @ovindex PACKAGE_BUGREPORT
 @cvindex PACKAGE_BUGREPORT
-Exactly @var{bug-report}.
+Exactly @var{bug-report}, if one was provided.
+
address@hidden @code{AC_PACKAGE_URL}, @code{PACKAGE_URL}
address@hidden
address@hidden PACKAGE_URL
address@hidden PACKAGE_URL
+Exactly @var{url}, if one was provided.  If @var{url} was empty, but
address@hidden begins with @samp{GNU }, then this defaults to
address@hidden://www.gnu.org/software/@var{tarname}/}, otherwise, no URL is
+assumed.
 @end table
 @end defmac
 
diff --git a/lib/autoconf/general.m4 b/lib/autoconf/general.m4
index bcf8720..c527138 100644
--- a/lib/autoconf/general.m4
+++ b/lib/autoconf/general.m4
@@ -1,7 +1,8 @@
 # This file is part of Autoconf.                       -*- Autoconf -*-
 # Parameterized macros.
 # Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001,
-# 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+# 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software
+# Foundation, Inc.
 
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -245,8 +246,8 @@ AU_ALIAS([AC_HELP_STRING], [AS_HELP_STRING])
 
 
 
-# _AC_INIT_PACKAGE(PACKAGE-NAME, VERSION, BUG-REPORT, [TARNAME])
-# --------------------------------------------------------------
+# _AC_INIT_PACKAGE(PACKAGE-NAME, VERSION, BUG-REPORT, [TARNAME], [URL])
+# ---------------------------------------------------------------------
 m4_define([_AC_INIT_PACKAGE],
 [AS_LITERAL_IF([$1], [], [m4_warn([syntax], [AC_INIT: not a literal: $1])])
 AS_LITERAL_IF([$2], [],  [m4_warn([syntax], [AC_INIT: not a literal: $2])])
@@ -266,6 +267,11 @@ m4_ifndef([AC_PACKAGE_STRING],
          [m4_define([AC_PACKAGE_STRING],    [$1 $2])])
 m4_ifndef([AC_PACKAGE_BUGREPORT],
          [m4_define([AC_PACKAGE_BUGREPORT], [$3])])
+m4_ifndef([AC_PACKAGE_URL],
+         [m4_define([AC_PACKAGE_URL],
+  m4_if([$5], [], [m4_if(m4_index([$1], [GNU ]), [0],
+         [[http://www.gnu.org/software/]m4_defn([AC_PACKAGE_TARNAME])[/]])],
+       [[$5]]))])
 ])
 
 
@@ -431,6 +437,8 @@ AC_SUBST([PACKAGE_STRING],
         [m4_ifdef([AC_PACKAGE_STRING],    ['AC_PACKAGE_STRING'])])dnl
 AC_SUBST([PACKAGE_BUGREPORT],
         [m4_ifdef([AC_PACKAGE_BUGREPORT], ['AC_PACKAGE_BUGREPORT'])])dnl
+AC_SUBST([PACKAGE_URL],
+        [m4_ifdef([AC_PACKAGE_URL],       ['AC_PACKAGE_URL'])])dnl
 
 m4_divert_pop([DEFAULTS])dnl
 m4_wrap_lifo([m4_divert_text([DEFAULTS],
@@ -1118,7 +1126,12 @@ m4_ifset([AC_PACKAGE_STRING],
 m4_divert_pop([HELP_ENABLE])dnl
 m4_divert_push([HELP_END])dnl
 m4_ifset([AC_PACKAGE_BUGREPORT], [
-Report bugs to <AC_PACKAGE_BUGREPORT>.])
+Report bugs to <AC_PACKAGE_BUGREPORT>.
+m4_n(m4_ifset([AC_PACKAGE_URL],
+ [AC_PACKAGE_NAME home page: AC_PACKAGE_URL]))dnl
+m4_n(m4_if(m4_index(m4_defn([AC_PACKAGE_NAME]), [GNU ]), [0],
+ [General help using GNU software: http://www.gnu.org/gethelp/]))dnl
+])dnl
 _ACEOF
 ac_status=$?
 fi
@@ -1343,6 +1356,8 @@ AC_DEFINE_UNQUOTED([PACKAGE_STRING], ["$PACKAGE_STRING"],
 AC_DEFINE_UNQUOTED([PACKAGE_BUGREPORT], ["$PACKAGE_BUGREPORT"],
                   [Define to the address where bug reports for this package
                    should be sent.])dnl
+AC_DEFINE_UNQUOTED([PACKAGE_URL], ["$PACKAGE_URL"],
+                  [Define to the home page for this package.])
 
 # Let the site file select an alternate cache file if it wants to.
 AC_SITE_LOAD
@@ -1362,10 +1377,17 @@ AC_CONFIG_SRCDIR([$1])], [[AC_INIT]])])[]dnl
 ])
 
 
-# AC_INIT([PACKAGE, VERSION, [BUG-REPORT])
-# ----------------------------------------
+# AC_INIT([PACKAGE, VERSION, [BUG-REPORT], [TARNAME], [URL])
+# ----------------------------------------------------------
 # Include the user macro files, prepare the diversions, and output the
 # preamble of the `configure' script.
+#
+# If BUG-REPORT is omitted, do without (unless the user previously
+# defined the m4 macro AC_PACKAGE_BUGREPORT).  If TARNAME is omitted,
+# use PACKAGE to seed it.  If URL is omitted, use
+# `http://www.gnu.org/software/TARNAME/' if PACKAGE begins with `GNU',
+# otherwise, do without.
+#
 # Note that the order is important: first initialize, then set the
 # AC_CONFIG_SRCDIR.
 m4_define([AC_INIT],
-- 
1.6.0.4