[PATCH] doc: README: split out ancillary information

[Pádraig Brady]

The README was becoming too long and contained
quite a bit of info only pertaining to rarely used systems, so...

* README: Split out install specific info to README-install.
Also remove a few stale lines, and reorder a few items.
* README-install: A new file split from README.
* Makefile.am [EXTRA_DIST]: Explicitly reference new README-install
file for distribution, since automake only auto adds README.
* TODO: Reference the HPUX info now in README-install.
---
 Makefile.am    |   1 +
 README         | 136 +++++++------------------------------------------
 README-install | 111 ++++++++++++++++++++++++++++++++++++++++
 TODO           |   2 +-
 4 files changed, 130 insertions(+), 120 deletions(-)
 create mode 100644 README-install

diff --git a/Makefile.am b/Makefile.am
index 733b32214..346ed3674 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -24,6 +24,7 @@ EXTRA_DIST =                          \
   .prev-version                                \
   .version                             \
   .vg-suppressions                     \
+  README-install                       \
   THANKS.in                            \
   THANKS-to-translators                        \
   THANKStt.in                          \
diff --git a/README b/README
index a18fcf611..954c8190c 100644
--- a/README
+++ b/README
@@ -21,7 +21,8 @@ See the file NEWS for a list of major changes in the current 
release.
 
 If you obtained this file as part of a "git clone", then see the
 README-hacking file.  If this file came to you as part of a tar archive,
-then see the file INSTALL for compilation and installation instructions.
+then see the file INSTALL for general compilation and installation
+instructions, or README-install for system and coreutils specific instructions.
 
 Like the rest of the GNU system, these programs mostly conform to
 POSIX, with BSD and other extensions.  For closer conformance, or
@@ -57,97 +58,17 @@ files (man/*.x) are welcome.  However, the authoritative 
documentation
 is in texinfo form in the doc directory.
 
 
-*********************
-Pre-C99 build failure
----------------------
-
-In 2009 we added this requirement:
-To build the coreutils from source, you must have a C99-conforming
-compiler, due to the use of declarations after non-declaration statements
-in several files in src/.  There is code in configure to find and, if
-possible, enable an appropriate compiler.  However, if configure doesn't
-find a C99 compiler, it continues nonetheless, and your build will fail.
-There used to be a "c99-to-c89.diff" patch you could apply to convert
-to code that even an old pre-c99 compiler can handle, but it was too
-tedious to maintain, so has been removed.
-
-
-***********************
-HPUX 11.x build failure
------------------------
-
-A known problem exists when compiling on HPUX on both hppa and ia64
-in 64-bit mode (i.e., +DD64) on HP-UX 11.0, 11.11, and 11.23.  This
-is not due to a bug in the package but instead due to a bug in the
-system header file which breaks things in 64-bit mode.  The default
-compilation mode is 32-bit and the software compiles fine using the
-default mode.  To build this software in 64-bit mode you will need
-to fix the system /usr/include/inttypes.h header file.  After
-correcting that file the software also compiles fine in 64-bit mode.
-Here is one possible patch to correct the problem:
-
---- /usr/include/inttypes.h.orig       Thu May 30 01:00:00 1996
-+++ /usr/include/inttypes.h    Sun Mar 23 00:20:36 2003
-@@ -489 +489 @@
--#ifndef __STDC_32_MODE__
-+#ifndef __LP64__
-
-
-************************
-OSF/1 4.0d and AIX build failures
-------------------------
-
-If you use /usr/bin/make on these systems, the build will fail due
-to the presence of the "[" target.  OSF/1 make(1) appears to
-treat "[" as some syntax relating to locks, while AIX make(1)
-appears to skip the "[" target.  To work around these issues
-the best solution is to use GNU make.  Otherwise, simply remove
-all mention of "[$(EXEEXT)" from src/Makefile.
-
-
-************************
-32 bit time_t build failures
-------------------------
-
-On systems where it's determined that 64 bit time_t is supported
-(indicated by touch -t <some time after 2038>), but that coreutils
-would be built with a narrower time_t, the build will fail.
-This can be allowed by passing TIME_T_32_BIT_OK=yes to configure,
-or avoided by enabling 64 bit builds.  For example GCC on AIX defaults
-to 32 bit, and to enable the 64 bit ABI one can use:
-./configure CFLAGS=-maix64 LDFLAGs=-maix64 AR='ar -X64'
-
-
-*************************************************
-"make check" failure on IRIX 6.5 and Solaris <= 9
--------------------------------------------------
-
-Using the vendor make program to run "make check" fails on these two systems.
-If you want to run all of the tests there, use GNU make.
-
-
-
-**********************
-Running tests as root:
-----------------------
-
-If you run the tests as root, note that a few of them create files
-and/or run programs as a non-root user, 'nobody' by default.
-If you want to use some other non-root username, specify it via
-the NON_ROOT_USERNAME environment variable.  Depending on the
-permissions with which the working directories have been created,
-using 'nobody' may fail, because that user won't have the required
-read and write access to the build and test directories.
-I find that it is best to unpack and build as a non-privileged
-user, and then to run the following command as that user in order
-to run the privilege-requiring tests:
-
-  sudo env PATH="$PATH" NON_ROOT_USERNAME=$USER make -k check-root
+***************
+Feature requests:
+---------------
 
-If you can run the tests as root, please do so and report any
-problems.  We get much less test coverage in that mode, and it's
-arguably more important that these tools work well when run by
-root than when run by less privileged users.
+If you would like to add a new feature, please try to get some sort of
+consensus that it is a worthwhile change.  One way to do that is to send
+mail to coreutils@gnu.org including as much description and justification
+as you can.  Based on the feedback that generates, you may be able to
+convince us that it's worth adding.  Please also consult the list of
+previously discussed but ultimately rejected feature requests at:
+https://www.gnu.org/software/coreutils/rejected_requests.html
 
 
 ***************
@@ -157,6 +78,10 @@ Reporting bugs:
 Send bug reports, questions, comments, etc. to bug-coreutils@gnu.org.
 To suggest a patch, see the files README-hacking and HACKING for tips.
 
+All of these programs except 'test' recognize the '--version' option.
+When reporting bugs, please include in the subject line both the package
+name/version and the name of the program for which you found a problem.
+
 If you have a problem with 'sort', try running 'sort --debug', as it
 can often help find and fix problems without having to wait for an
 answer to a bug report.  If the debug output does not suffice to fix
@@ -181,7 +106,7 @@ There are many tests, but nowhere near as many as we need.
 Additions and corrections are very welcome.
 
 If you see a problem that you've already reported, feel free to re-report
-it -- it won't bother me to get a reminder.  Besides, the more messages I
+it -- it won't bother us to get a reminder.  Besides, the more messages we
 get regarding a particular problem the sooner it'll be fixed -- usually.
 If you sent a complete patch and, after a couple weeks you haven't
 received any acknowledgement, please ping us.  A complete patch includes
@@ -195,30 +120,6 @@ Here are instructions for checking out the latest 
development sources:
 
   https://savannah.gnu.org/git/?group=coreutils
 
-If your patch adds a new feature, please try to get some sort of consensus
-that it is a worthwhile change.  One way to do that is to send mail to
-coreutils@gnu.org including as much description and justification
-as you can.  Based on the feedback that generates, you may be able to
-convince us that it's worth adding.  Please also consult the list of
-previously discussed but ultimately rejected feature requests at:
-https://www.gnu.org/software/coreutils/rejected_requests.html
-
-
-WARNING:  Now that we use the ./bootstrap script, you should not run
-autoreconf manually.  Doing that will overwrite essential source files
-with older versions, which may make the package unbuildable or introduce
-subtle bugs.
-
-
-WARNING:  If you modify files like configure.in, m4/*.m4, aclocal.m4,
-or any Makefile.am, then don't be surprised if what gets regenerated no
-longer works.  To make things work, you'll have to be using appropriate
-versions of the tools listed in bootstrap.conf's buildreq string.
-
-All of these programs except 'test' recognize the '--version' option.
-When reporting bugs, please include in the subject line both the package
-name/version and the name of the program for which you found a problem.
-
 For general documentation on the coding and usage standards
 this distribution follows, see the GNU Coding Standards at:
 https://www.gnu.org/prep/standards/
@@ -226,9 +127,6 @@ https://www.gnu.org/prep/standards/
 For any copyright year range specified as YYYY-ZZZZ in this package
 note that the range specifies every single year in that closed interval.
 
-Mail suggestions and bug reports for these programs to
-the address on the last line of --help output.
-
 
 ========================================================================
 
diff --git a/README-install b/README-install
new file mode 100644
index 000000000..0c5bcf470
--- /dev/null
+++ b/README-install
@@ -0,0 +1,111 @@
+Please see the file INSTALL for generic build and installation instructions.
+This file details coreutils and system specific build instructions.
+
+
+*********************
+Pre-C99 build failure
+---------------------
+
+In 2009 we added this requirement:
+To build the coreutils from source, you must have a C99-conforming
+compiler, due to the use of declarations after non-declaration statements
+in several files in src/.  There is code in configure to find and, if
+possible, enable an appropriate compiler.  However, if configure doesn't
+find a C99 compiler, it continues nonetheless, and your build will fail.
+There used to be a "c99-to-c89.diff" patch you could apply to convert
+to code that even an old pre-c99 compiler can handle, but it was too
+tedious to maintain, so has been removed.
+
+
+***********************
+HPUX 11.x build failure
+-----------------------
+
+A known problem exists when compiling on HPUX on both hppa and ia64
+in 64-bit mode (i.e., +DD64) on HP-UX 11.0, 11.11, and 11.23.  This
+is not due to a bug in the package but instead due to a bug in the
+system header file which breaks things in 64-bit mode.  The default
+compilation mode is 32-bit and the software compiles fine using the
+default mode.  To build this software in 64-bit mode you will need
+to fix the system /usr/include/inttypes.h header file.  After
+correcting that file the software also compiles fine in 64-bit mode.
+Here is one possible patch to correct the problem:
+
+--- /usr/include/inttypes.h.orig       Thu May 30 01:00:00 1996
++++ /usr/include/inttypes.h    Sun Mar 23 00:20:36 2003
+@@ -489 +489 @@
+-#ifndef __STDC_32_MODE__
++#ifndef __LP64__
+
+
+************************
+OSF/1 4.0d and AIX build failures
+------------------------
+
+If you use /usr/bin/make on these systems, the build will fail due
+to the presence of the "[" target.  OSF/1 make(1) appears to
+treat "[" as some syntax relating to locks, while AIX make(1)
+appears to skip the "[" target.  To work around these issues
+the best solution is to use GNU make.  Otherwise, simply remove
+all mention of "[$(EXEEXT)" from src/Makefile.
+
+
+************************
+32 bit time_t build failures
+------------------------
+
+On systems where it's determined that 64 bit time_t is supported
+(indicated by touch -t <some time after 2038>), but that coreutils
+would be built with a narrower time_t, the build will fail.
+This can be allowed by passing TIME_T_32_BIT_OK=yes to configure,
+or avoided by enabling 64 bit builds.  For example GCC on AIX defaults
+to 32 bit, and to enable the 64 bit ABI one can use:
+./configure CFLAGS=-maix64 LDFLAGs=-maix64 AR='ar -X64'
+
+
+*************************************************
+"make check" failure on IRIX 6.5 and Solaris <= 9
+-------------------------------------------------
+
+Using the vendor make program to run "make check" fails on these two systems.
+If you want to run all of the tests there, use GNU make.
+
+
+
+**********************
+Running tests as root:
+----------------------
+
+If you run the tests as root, note that a few of them create files
+and/or run programs as a non-root user, 'nobody' by default.
+If you want to use some other non-root username, specify it via
+the NON_ROOT_USERNAME environment variable.  Depending on the
+permissions with which the working directories have been created,
+using 'nobody' may fail, because that user won't have the required
+read and write access to the build and test directories.
+I find that it is best to unpack and build as a non-privileged
+user, and then to run the following command as that user in order
+to run the privilege-requiring tests:
+
+  sudo env PATH="$PATH" NON_ROOT_USERNAME=$USER make -k check-root
+
+If you can run the tests as root, please do so and report any
+problems.  We get much less test coverage in that mode, and it's
+arguably more important that these tools work well when run by
+root than when run by less privileged users.
+
+
+
+**********************
+autotools considerations:
+----------------------
+
+WARNING:  Now that we use the ./bootstrap script, you should not run
+autoreconf manually.  Doing that will overwrite essential source files
+with older versions, which may make the package unbuildable or introduce
+subtle bugs.
+
+WARNING:  If you modify files like configure.in, m4/*.m4, aclocal.m4,
+or any Makefile.am, then don't be surprised if what gets regenerated no
+longer works.  To make things work, you'll have to be using appropriate
+versions of the tools listed in bootstrap.conf's buildreq string.
diff --git a/TODO b/TODO
index e1348f0f1..6c141b644 100644
--- a/TODO
+++ b/TODO
@@ -49,7 +49,7 @@ no longer incurs the overhead of saving src. dev/ino and 
dest. filename
 in the hash table.
 
 Write an autoconf test to work around build failure in HPUX's 64-bit mode.
-See notes in README -- and remove them once there's a work-around.
+See notes in README-install -- and remove them once there's a work-around.
 
 Integrate use of sendfile, suggested here:
   https://lists.gnu.org/r/bug-fileutils/2003-03/msg00030.html
-- 
2.26.2