LUCENE-10163: clean up and remove some old cruft in readme files. Move binary release only README.md to the distribution project so that it doesn't look weird in the source tree. (#406)

README.md

@@ -38,8 +38,8 @@ comprehensive documentation, visit:
 
 ### Basic steps:
   
-  0. Install OpenJDK 11 (or greater up until version 15)
+  0. Install OpenJDK 11 (or greater).
-  1. Download Lucene from Apache and unpack it (or clone the git repository).
+  1. Clone Lucene's git repository (or download the source distribution).
   2. Run gradle launcher script (`gradlew`).
 
 ### Step 0) Set up your development environment (OpenJDK 11 or greater)
@@ -51,10 +51,10 @@ Java 11 or later.
 
 Lucene uses [Gradle](https://gradle.org/) for build control. Gradle is itself Java-based
 and may be incompatible with newer Java versions; you can still build and test 
-Lucene with these Java releases, see help/tests.txt for more information.
+Lucene with these Java releases, see [jvms.txt](./help/jvms.txt) for more information.
 
-NOTE: Lucene changed from Ant to Gradle as of release 9.0. Prior releases
+NOTE: Lucene changed from Apache Ant to Gradle as of release 9.0. Prior releases
-still use Ant.
+still use Apache Ant.
 
 ### Step 1) Checkout/Download Lucene source code
 
@@ -66,8 +66,7 @@ or get Lucene source archives for a particular release from:
 
   https://lucene.apache.org/core/downloads.html
 
-Download either a zip or a tarred/gzipped version of the archive, and
+Download the source archive and uncompress it into a directory of your choice.
-uncompress it into a directory of your choice.
 
 ### Step 2) Run Gradle
 
@@ -80,28 +79,31 @@ If you want to build Lucene, type:
 ./gradlew assemble
 ```
 
-NOTE: DO NOT use `gradle` command that is already installed on your machine (unless you know what you'll do).
+NOTE: DO NOT use the `gradle` command that is perhaps installed on your machine. This may
-The "gradle wrapper" (gradlew) does the job - downloads the correct version of it, setups necessary configurations.
+result in using a different gradle version than the project requires and this is known
+to lead to very cryptic errors. The "gradle wrapper" (gradlew script) does everything
+required to build the project from scratch: it downloads the correct version of gradle,
+sets up sane local configurations and is tested on multiple environments.
 
-The first time you run Gradle, it will create a file "gradle.properties" that
+The first time you run gradlew, it will create a file "gradle.properties" that
 contains machine-specific settings. Normally you can use this file as-is, but it
 can be modified if necessary.
 
 `./gradlew check` will assemble Lucene and run all validation
-  tasks (including unit tests).
+  tasks (including tests).
 
-`./gradlew help` will print a list of help guides that help understand how
+`./gradlew help` will print a list of help guides that introduce and explain
-  the build and typical workflow works.
+  various parts of the build system, including typical workflow tasks.
 
-If you want to build the documentation, type:
+If you want to just build the documentation, type:
 
 ```
 ./gradlew documentation
 ```
 
-### Gradle build and IDE support
+### IDE support
 
-- *IntelliJ* - IntelliJ idea can import the project out of the box.
+- *IntelliJ* - IntelliJ idea can import and build gradle-based projects out of the box.
 - *Eclipse*  - Basic support ([help/IDEs.txt](https://github.com/apache/lucene/blob/main/help/IDEs.txt#L7)).
 - *Netbeans* - Not tested.
 

lucene/JRE_VERSION_MIGRATION.md

@@ -20,37 +20,25 @@
 If possible, use the same JRE major version at both index and search time.
 When upgrading to a different JRE major version, consider re-indexing. 
 
-Different JRE major versions may implement different versions of Unicode,
+Different Java versions may implement different versions of Unicode,
 which will change the way some parts of Lucene treat your text.
 
-For example: with Java 1.4, `LetterTokenizer` will split around the character U+02C6,
+An (outdated) example: with Java 1.4, `LetterTokenizer` will split around the 
-but with Java 5 it will not.
+character U+02C6, but with Java 5 it will not. This is because Java 1.4 
-This is because Java 1.4 implements Unicode 3, but Java 5 implements Unicode 4.
+implements Unicode 3, but Java 5 implements Unicode 4.
 
-For reference, JRE major versions with their corresponding Unicode versions:
+The version of Unicode supported by Java is listed in the documentation
+of java.lang.Character class. For reference, Java versions after Java 11
+support the following Unicode versions:
 
- * Java 1.4, Unicode 3.0
+ * Java 11, Unicode 10.0
- * Java 5, Unicode 4.0
+ * Java 12, Unicode 11.0
- * Java 6, Unicode 4.0
+ * Java 13, Unicode 12.1
- * Java 7, Unicode 6.0
+ * Java 15, Unicode 13.0
- * Java 8, Unicode 6.2
+ * Java 16, Unicode 13.0
- * Java 9, Unicode 8.0
+ * Java 17, Unicode 13.0
 
 In general, whether you need to re-index largely depends upon the data that
 you are searching, and what was changed in any given Unicode version. For example, 
 if you are completely sure your content is limited to the "Basic Latin" range
 of Unicode, you can safely ignore this. 
-
-## Special Notes: LUCENE 2.9 TO 3.0, JAVA 1.4 TO JAVA 5 TRANSITION
-
-* `StandardAnalyzer` will return the same results under Java 5 as it did under 
-Java 1.4. This is because it is largely independent of the runtime JRE for
-Unicode support, (except for lowercasing).  However, no changes to
-casing have occurred in Unicode 4.0 that affect StandardAnalyzer, so if you are 
-using this Analyzer you are NOT affected.
-
-* `SimpleAnalyzer`, `StopAnalyzer`, `LetterTokenizer`, `LowerCaseFilter`, and 
-`LowerCaseTokenizer` may return different results, along with many other `Analyzer`s
-and `TokenStream`s in Lucene's analysis modules. If you are using one of these 
-components, you may be affected.
-

lucene/distribution/binary-release.gradle

@@ -60,29 +60,26 @@ configure(project(":lucene:distribution")) {
       copy.setMode(0755)
     }
 
-    // Cherry-picked root-level files.
+    // Attach binary release exclusive files.
+    from(file("src/binary-release"), {
+    })
+
+    // Cherry-pick certain files from the root.
     from(project(':').projectDir, {
         include "LICENSE.txt"
         include "NOTICE.txt"
     })
 
-    // Cherry-picked lucene-level files.
+    // Cherry-pick certain files from the lucene module.
     from(project(':lucene').projectDir, {
       include "CHANGES.txt"
       include "JRE_VERSION_MIGRATION.md"
       include "MIGRATE.md"
-      include "README.md"
       include "SYSTEM_REQUIREMENTS.md"
 
       include "licenses/*"
     })
 
-    // Analysis container is not a submodule but include its readme file.
-    from(project(':lucene:analysis').projectDir) {
-      include "README.txt"
-      into 'analysis'
-    }
-
     // The documentation.
     from(configurations.docs, {
       into 'docs'

lucene/distribution/src/binary-release/README.md

@@ -19,9 +19,9 @@
 
 ## Introduction
 
-Lucene is a Java full-text search engine.  Lucene is not a complete
+This is a binary distribution of Lucene. Lucene is a Java full-text 
-application, but rather a code library and API that can easily be used
+search engine. Lucene is not a complete application, but rather a code library 
-to add search capabilities to applications.
+and an API that can easily be used to add search capabilities to applications.
 
  * The Lucene web site is at: https://lucene.apache.org/
  * Please join the Lucene-User mailing list by sending a message to: