Re: 06-config-man-pages.patch

[Akim Demaille]

| Hi Akim,

Hi Ben!

| I have finally got around to reviewing your patches.  I'm sorry for the
| delay, but I've been really busy.  I wish I could work in academia and hack
| all day.  ;-)

I understand!

|    Here are the patches I was referring to.  There was no real consensus
|    over the second one which makes it possible for a package that
|    installs config.* to sign, so I'll leave it up to you.  Another more
|    or less pending issue was deciding whether Autoconf should ship them.
|    I think that it's wrong that Automake ships them, Autoconf should.
| 
| I don't think *any* package should ship them (well, not with exclusive
| ownership).  These scripts are now maintained autonomously.  Autoconf and
| Automake are merely users of these scripts, like other GNU packages.

I just agree.  My point was ``there are packages that ship them, so
let cope with reality cleanly''.  But I agree they should not be
distributed by other packages.

| If you mean packaging these scripts, then I think it's correct for Automake
| to ensure that new projects include these files -- and encourage users to
| fetch the latest versions prior to shipping.  I guess that means I agree
| with Alexandre.

We all do.

| I should point out that I don't agree with all of your patches, so I have
| selectively applied hunks.  Here is a step-by-step review of the patches so
| you're aware of why I rejected some changes:
| 
| @@ -3,7 +3,7 @@
|  #   Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000
|  #   Free Software Foundation, Inc.
| 
| -version='2000-06-13'
| +timestamp='2000-07-22'
| 
|  # This file is free software; you can redistribute it and/or modify it
|  # under the terms of the GNU General Public License as published by
| 
| Applied.

Ok.

| @@ -32,7 +32,7 @@
|  # exits with 0.  Otherwise, it exits with 1.
|  #
|  # The plan is that this can be called by configure scripts if you
| -# don't specify an explicit system type (host/target name).
| +# don't specify an explicit build system type.
|  #
|  # Only a few systems have been added to this list; please add others
|  # (but try to keep the structure clean).
| 
| Applied.

OK.

| @@ -43,11 +43,42 @@
|  usage="\
|  Usage: $0 [OPTION]
| 
| -Output the configuration name of this system.
| +Output the configuration name of the system \`$me' is run on.
| 
|  Operation modes:
| -  -h, --help               print this help, then exit
| -  -V, --version            print version number, then exit"
| +  -h, --help         print this help, then exit
| +  -V, --version      print version number, then exit
| +  -t, --time-stamp   print time stamp, then exit
| +
| +
| +Environment variables:
| +  CC_FOR_BUILD    a native C compiler, defaults to \`cc'
| +  CC              a native C compiler, the previous variable is preferred
| +
| +The GNU build system distinguishes three types of machines, the
| +\`build' machine on which the compilers are run, the \`host' machine
| +on which the package being built will run, and, exclusively when you
| +build a compiler, assembler etc., the \`target' machine, for which the
| +compiler being built will produce code.
| +
| +This script will guess the type of the \`build' machine.
| +
| +Since it might need to compile and run C code, it needs a compiler for
| +the \`build' machine: use the environment variable \`CC_FOR_BUILD' to
| +specify the compiler for the build machine.  If \`CC_FOR_BUILD' is not
| +specified, \`CC' will be used.  Be sure to specify \`CC_FOR_BUILD' is
| +\`CC' is a cross-compiler to the \`host' machine.
| +
| +Report bugs and patches to <address@hidden>."
| +
| +version="\
| +config.guess (GNU Config) $timestamp
| +Written by Per Bothner.
| +
| +Copyright (C) 1992, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software 
Foundation,
| +Inc.
| +This is free software; see the source for copying conditions.  There is NO
| +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."
| 
|  help="
|  Try \`$me --help' for more information."
| 
| I applied the copyleft notice, the attribution to Per and the bug reporting
| address.  Everything else belongs in a manual page, not in the --help
| output.  If you would like to write a manual page, I'd gladly accept and
| maintain it.

I think you missed some point: this is in order to generate the man
page.  The choice is yours: if you decide to maintain a full package
with man pages, then set one up, which means a Makefile.am,
configure.in and all the rest.

If you want to stick to the simple model (three unpackaged files), I
think it is just fine to have a long --help.  In itself, a long --help
is not wrong.  And for small stuff like config.guess which will
*always* be more present as is than its man page, I think it's a
mistake to move the documentation into a man page.

Frankly, do you think that Joe who installs a GNU package will have
config.guess.1 on his system?  No.  But config.guess is just there, in
the middle of the package he is installing.  What should he do?  Run
./config.guess --help, or download the package Config and install it
to be able to man config.guess?


| The help output now reflects the current set of options (see below).
| 
| @@ -57,6 +88,8 @@
|    case "$1" in
|      --version | --vers* | -V )
|         echo "$version" ; exit 0 ;;
| +    --time-stamp | --time* | -t )
| +       echo "$timestamp" ; exit 0 ;;
|      --help | --h* | -h )
|         echo "$usage"; exit 0 ;;
|      -- )     # Stop option processing
| 
| Accepted, but I deleted --version.  I don't believe there is a place for
| both --version and --time-stamp and I think that --time-stamp better
| indicates what the output really is.

You miss the point: --version is a standard option, and it should be
supported for conformance.  In addition, you just break the interface
with help2man.  Since it's made to be human readable, I introduced
--time-stamp to ease automated processing.

| @@ -64,9 +97,7 @@
|      - )      # Use stdin as input.
|         break ;;
|      -* )
| -       exec >&2
| -       echo "$me: invalid option $1"
| -       echo "$help"
| +       echo "$me: invalid option $1$help" >&2
|         exit 1 ;;
|      * )
|         break ;;
| 
| Applied.
| 
| @@ -78,18 +109,14 @@
|    exit 1
|  fi
| 
| -# Use $HOST_CC if defined. $CC may point to a cross-compiler
| -if test x"$CC_FOR_BUILD" = x; then
| -  if test x"$HOST_CC" != x; then
| -    CC_FOR_BUILD="$HOST_CC"
| -  else
| -    if test x"$CC" != x; then
| -      CC_FOR_BUILD="$CC"
| -    else
| -      CC_FOR_BUILD=cc
| -    fi
| -  fi
| -fi
| +# CC_FOR_BUILD -- compiler used by this script.
| +# Historrorically `CC_FOR_BUILD' used to be named `HOST_CC'.  We still
| +# use `HOST_CC' if defined, but it is deprecated.
| +case $CC_FOR_BUILD,$HOST_CC,$CC in
| + ,,)   CC_FOR_BUILD=cc;;
| + ,,*)  CC_FOR_BUILD=$CC;;
| + ,*,*) CC_FOR_BUILD=$HOST_CC;;
| +esac
| 
| 
|  # This is needed to find uname on a Pyramid OSx when run in the BSD universe.
| 
| This is very clever!  I like it.  I must remember this idiom in my own
| future shell programming. :-)  I applied this hunk and merged in a recent
| change that locates a working C compiler if necessary (this is good for pure
| GNU systems that have gcc, but not cc, for example).

case is usually a excellent means to factor hairy if's.

| @@ -100,7 +127,7 @@
|  UNAME_MACHINE=`(uname -m) 2>/dev/null` || UNAME_MACHINE=unknown
|  UNAME_RELEASE=`(uname -r) 2>/dev/null` || UNAME_RELEASE=unknown
| -UNAME_SYSTEM=`(uname -s) 2>/dev/null` || UNAME_SYSTEM=unknown
| +UNAME_SYSTEM=`(uname -s) 2>/dev/null`  || UNAME_SYSTEM=unknown
|  UNAME_VERSION=`(uname -v) 2>/dev/null` || UNAME_VERSION=unknown
| 
| Applied.
| 
| @@ -1267,7 +1294,7 @@
| 
|  # Local variables:
|  # eval: (add-hook 'write-file-hooks 'time-stamp)
| -# time-stamp-start: "version='"
| +# time-stamp-start: "timestamp='"
|  # time-stamp-format: "%:y-%02m-%02d"
|  # time-stamp-end: "'"
|  # End:
| 
| Applied.

Now for config.sub.

| @@ -1,9 +1,9 @@
|  #! /bin/sh
| -# Configuration validation subroutine script, version 1.1.
| +# Configuration validation subroutine script.
|  #   Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000
|  #   Free Software Foundation, Inc.
| 
| -version='2000-07-06'
| +timestamp='2000-07-22'
| 
|  # This file is (in principle) common to ALL GNU software.
|  # The presence of a machine in this file suggests that SOME GNU software
| 
| Applied.
| 
| @@ -60,8 +60,19 @@
|  Canonicalize a configuration name.
| 
|  Operation modes:
| -  -h, --help               print this help, then exit
| -  -V, --version            print version number, then exit"
| +  -h, --help         print this help, then exit
| +  -V, --version      print version number, then exit
| +  -t, --time-stamp   print time stamp, then exit
| +
| +Report bugs and patches to <address@hidden>."
| +
| +version="\
| +config.sub (GNU Config) $timestamp
| +
| +Copyright (C) 1992, 93, 94, 95, 96, 97, 98, 99, 2000 Free Software 
Foundation,
| +Inc.
| +This is free software; see the source for copying conditions.  There is NO
| +warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE."
| 
|  help="
|  Try \`$me --help' for more information."
| 
| Applied, insofar as I did for config.guess.

Same remarks :)

| @@ -71,6 +82,8 @@
|    case "$1" in
|      --version | --vers* | -V )
|         echo "$version" ; exit 0 ;;
| +    --time-stamp | --time* | -t )
| +       echo "$timestamp" ; exit 0 ;;
|      --help | --h* | -h )
|         echo "$usage"; exit 0 ;;
|      -- )     # Stop option processing
| 
| Applied, again, as I did for config.guess.
| 
| @@ -78,9 +91,7 @@
|      - )      # Use stdin as input.
|         break ;;
|      -* )
| -       exec >&2
| -       echo "$me: invalid option $1"
| -       echo "$help"
| +       echo "$me: invalid option $1$help"
|         exit 1 ;;
| 
|      *local*)
| 
| Applied.
| 
| @@ -1318,7 +1329,7 @@
| 
|  # Local variables:
|  # eval: (add-hook 'write-file-hooks 'time-stamp)
| -# time-stamp-start: "version='"
| +# time-stamp-start: "timestamp='"
|  # time-stamp-format: "%:y-%02m-%02d"
|  # time-stamp-end: "'"
|  # End:
| 
| Applied.
| 
| Thanks -- this little bit of cleanup has been long deserved.  I have some
| whitespace changes slated to clean up config.sub in the near future.

Thanks for the parts you applied, but I do believe you still should
apply what remains, in particular the long usage and --version support.