Re: [PATCH 2/6] maint: consolidate Introductions of README and README.alpha.

[Gary V. Vaughan]

[[top-post re-ordered]]

Hi Bob,

Thanks for the reviews.

> On Sat, 18 Sep 2010, Gary V. Vaughan wrote:
> 
>> * README (Introduction): Rewritten to a more logical order for
>> first time users, incorporating some additional text that was
>> previously only in README.alpha.
>> * README.alpha (Introduction): Adjust to match.
>> ---
>> ChangeLog    |    6 ++++++
>> README       |   30 ++++++++++++++++++++----------
>> README.alpha |   37 ++++++++++++++++++++++++++++---------
>> 3 files changed, 54 insertions(+), 19 deletions(-)
>> 
>> diff --git a/ChangeLog b/ChangeLog
>> index 3e1cb95..9db58e1 100644
>> --- a/ChangeLog
>> +++ b/ChangeLog
>> @@ -1,5 +1,11 @@
>> 2010-09-18  Gary V. Vaughan  <address@hidden>
>> 
>> +    maint: consolidate Introductions of README and README.alpha.
>> +    * README (Introduction): Rewritten to a more logical order for
>> +    first time users, incorporating some additional text that was
>> +    previously only in README.alpha.
>> +    * README.alpha (Introduction): Adjust to match.
>> +
>>      maint: copy the Version Numbering section into README.alpha.
>>      * README.alpha (Version Numbering): No less useful for users
>>      of alpha releases.  Copied from README.
>> diff --git a/README b/README
>> index 16328bb..acf8f8b 100644
>> --- a/README
>> +++ b/README
>> @@ -8,22 +8,32 @@ This is GNU Libtool, a generic library support script.  
>> Libtool hides
>> the complexity of using shared libraries behind a consistent, portable
>> interface.
>> 
>> -To use Libtool, add the new generic library building commands to your
>> -Makefile, Makefile.in, or Makefile.am.  See the documentation for
>> -details.
>> -
>> Libtool's home page is:
>> 
>> -  http://www.gnu.org/software/libtool/libtool.html
>> +    http://www.gnu.org/software/libtool/libtool.html
>> 
>> See the file NEWS for a description of recent changes to Libtool.
>> 
>> -See the file INSTALL for generic instructions on how to build and install
>> -Libtool.  Please see the file doc/notes.txt for some platform-specific
>> -information.  Please note that you need GNU make to build Libtool.
>> +See the file INSTALL for generic instructions on how to build and
>> +install Libtool.  Please see the file doc/notes.txt for some platform-
>> +specific information.  Please note that you need GNU make to build
>> +Libtool.
>> +
>> +See the info node (libtool)Tested Platforms. (or the file doc/PLATFORMS)
>> +for a list of platforms that Libtool already supports.
>> 
>> -See the info node (libtool)Tested Platforms. (or the file
>> -doc/PLATFORMS) for a list of platforms that Libtool supports.
>> +Please try it on all the platforms you have access to:
>> +
>> + * If it builds and passes the test suite (`gmake check'), please send
>> +   a short note to the libtool mailing list <address@hidden> with a
>> +   subject line including the string `[PLATFORM]', and containing the
>> +   details from the end of `./libtool --help' in the body.
>> + * Otherwise, see `Reporting Bugs' below for how to help us fix any
>> +   problems you discover.
>> +
>> +To use Libtool, add the new generic library building commands to your
>> +Makefile, Makefile.in, or Makefile.am.  See the documentation for
>> +details.
>> 
>> 
>> 2. Reporting Bugs
>> diff --git a/README.alpha b/README.alpha
>> index 8c72c03..6f4ed3b 100644
>> --- a/README.alpha
>> +++ b/README.alpha
>> @@ -4,17 +4,36 @@ GNU Libtool
>> 1. Introduction
>> ===============
>> 
>> -This is an alpha testing release of GNU Libtool, please try it on all
>> -the platforms you have access to.  Using it more or less implicitly
>> -signs you up to help us find whatever problems you report.
>> +This is an alpha testing release of GNU Libtool, a generic library
>> +support script.  Libtool hides the complexity of using shared libraries
>> +behind a consistent, portable interface.
>> 
>> -See the file INSTALL for generic instructions on how to build and install
>> -Libtool.  Please see the file doc/notes.txt for some platform-specific
>> -information.  Please note that you need GNU make to build Libtool.
>> +Libtool's home page is:
>> 
>> -If it builds and passes the test suite (`gmake check'), please send
>> -notification to the libtool mailing list <address@hidden> with a
>> -subject line including the string `[PLATFORM]'.
>> +    http://www.gnu.org/software/libtool/libtool.html
>> +
>> +See the file NEWS for a description of recent changes to Libtool.
>> +
>> +See the file INSTALL for generic instructions on how to build and
>> +install Libtool.  Please see the file doc/notes.txt for some platform-
>> +specific information.  Please note that you need GNU make to build
>> +Libtool.
>> +
>> +See the info node (libtool)Tested Platforms. (or the file doc/PLATFORMS)
>> +for a list of platforms that Libtool already supports.
>> +
>> +Please try it on all the platforms you have access to:
>> +
>> + * If it builds and passes the test suite (`gmake check'), please send
>> +   a short note to the libtool mailing list <address@hidden> with a
>> +   subject line including the string `[PLATFORM]', and containing the
>> +   details from the end of `./libtool --help' in the body.
>> + * Otherwise, see `Reporting Bugs' below for how to help us fix any
>> +   problems you discover.
>> +
>> +To use Libtool, add the new generic library building commands to your
>> +Makefile, Makefile.in, or Makefile.am.  See the documentation for
>> +details.

On 18 Sep 2010, at 21:47, Bob Friesenhahn wrote:
> This patch seems fine to me except that the doc/PLATFORMS information 
> referred to is totally archaic.  It does not really matter if libtool 0.8 
> worked on alpha-dec-osf3.2 because we have no clue if modern libtool does so 
> and probably don't really care if it does.  It seems to me that doc/PLATFORMS 
> should refer to the most recently verified version, and not to the first 
> version which worked.  Given this, we should plan on re-starting 
> doc/PLATFORMS from scratch.

Actually, I have a patch in my TODO to ditch PLATFORMS altogether.  And the 
current rewording was just a cleanup of the existing text (which I guess no one 
is reading, because I've *never* seen a '[Platform]' subject on the libtool 
lists.

In due course, I'd rather try to encourage people to install autobuild, and 
submit results there, than waste time maintaining a parallel list in PLATFORMS 
manually.  But I won't have time to get to that for a while, nor is it urgent 
while our autobuild support in the libtool tree is still incomplete.

Cheers,
-- 
Gary V. Vaughan (address@hidden)

PGP.sig
Description: This is a digitally signed message part