Full editing pass plus linking

I made a complete editing pass plus another pass to see where I could add more links, both within the document and to other parts of Spring. The result was a thorough edit (though I'm sure I missed things, purely due to the size of the thing).

spring-boot-project/spring-boot-docs/src/main/asciidoc/build-tool-plugins.adoc

@@ -67,8 +67,9 @@ as the original jar in the `target` directory:
 ----
 
 
-If you do not include the `<execution/>` configuration as shown in the prior example, you
-can run the plugin on its own (but only if the package goal is used as well). For example:
+If you do not include the `<execution/>` configuration, as shown in the prior example, you
+can run the plugin on its own (but only if the package goal is used as well), as shown in
+the following example:
 
 [indent=0]
 ----
@@ -78,7 +79,7 @@ can run the plugin on its own (but only if the package goal is used as well). Fo
 ----
 
 If you use a milestone or snapshot release, you also need to add the appropriate
-`pluginRepository` elements as shown in the following listing:
+`pluginRepository` elements, as shown in the following listing:
 
 [source,xml,indent=0,subs="verbatim,attributes"]
 ----
@@ -115,7 +116,7 @@ the usual `packaging` element, as shown in the following example:
 ----
 
 Your existing archive is enhanced by Spring Boot during the `package` phase. The main
-class that you want to launch can either be specified by using a configuration option or
+class that you want to launch can be specified either by using a configuration option or
 by adding a `Main-Class` attribute to the manifest in the usual way. If you do not specify
 a main class, the plugin searches for a class with a
 `public static void main(String[] args)` method.
@@ -229,7 +230,7 @@ attributes are supported by the task:
 
 |`start-class`
 |The main application class to run
-|No _(default is first class found declaring a `main` method)_
+|No _(the default is the first class found that declares a `main` method)_
 |====
 
 The following nested elements can be used with the task:
@@ -252,6 +253,9 @@ of the application.
 
 
 ==== Examples
+
+This section shows two examples of Ant tasks.
+
 .Specify +start-class+
 [source,xml,indent=0]
 ----
@@ -280,7 +284,7 @@ of the application.
 [[spring-boot-ant-findmainclass]]
 === `spring-boot:findmainclass`
 The `findmainclass` task is used internally by `exejar` to locate a class declaring a
-`main`. You can also use this task directly in your build, if needed. The following
+`main`. If necessary, you can also use this task directly in your build. The following
 attributes are supported:
 
 [cols="1,2,2"]
@@ -303,6 +307,9 @@ attributes are supported:
 
 
 ==== Examples
+
+This section contains three examples of using `findmainclass`.
+
 .Find and log
 [source,xml,indent=0]
 ----
@@ -367,7 +374,7 @@ candidate is found.
 
 [[build-tool-plugins-repackage-implementation]]
 === Example Repackage Implementation
-The following listing shows a typical example repackage:
+The following example shows a typical repackage implementation:
 
 [source,java,indent=0]
 ----

spring-boot-project/spring-boot-docs/src/main/asciidoc/getting-started.adoc

@@ -3,7 +3,7 @@
 
 [partintro]
 --
-If you are getting started with Spring Boot, or "Spring" in general, start by reading
+If you are getting started with Spring Boot, or "`Spring`" in general, start by reading
 this section. It answers the basic "`what?`", "`how?`" and "`why?`" questions. It
 includes an introduction to Spring Boot, along with installation instructions. We then
 walk you through building your first Spring Boot application, discussing some core
@@ -14,7 +14,7 @@ principles as we go.
 
 [[getting-started-introducing-spring-boot]]
 == Introducing Spring Boot
-Spring Boot makes it easy to create stand-alone, production-grade Spring based
+Spring Boot makes it easy to create stand-alone, production-grade Spring-based
 Applications that you can run. We take an opinionated view of the Spring platform and
 third-party libraries, so that you can get started with minimum fuss. Most Spring Boot
 applications need very little Spring configuration.
@@ -25,7 +25,7 @@ runs "`spring scripts`".
 
 Our primary goals are:
 
-* Provide a radically faster and widely accessible getting started experience for all
+* Provide a radically faster and widely accessible getting-started experience for all
 Spring development.
 * Be opinionated out of the box but get out of the way quickly as requirements start to
 diverge from the defaults.
@@ -38,15 +38,15 @@ configuration).
 
 [[getting-started-system-requirements]]
 == System Requirements
-Spring Boot {spring-boot-version} requires http://www.java.com[Java 8] and Spring
-Framework {spring-version} or above. Explicit build support is provided for Maven 3.2+
-and Gradle 4.
+Spring Boot {spring-boot-version} requires http://www.java.com[Java 8] and
+{spring-reference}[Spring Framework {spring-version}] or above. Explicit build support is
+provided for Maven 3.2+ and Gradle 4.
 
 
 
 [[getting-started-system-requirements-servlet-containers]]
 === Servlet Containers
-The following embedded servlet containers are supported out of the box:
+Spring Boot supports the following embedded servlet containers:
 
 |===
 |Name |Servlet Version
@@ -78,7 +78,7 @@ begin, you should check your current Java installation by using the following co
 
 If you are new to Java development or if you want to experiment with Spring Boot, you
 might want to try the <<getting-started-installing-the-cli, Spring Boot CLI>> (Command
-Line Interface) first, otherwise, read on for "`classic`" installation instructions.
+Line Interface) first. Otherwise, read on for "`classic`" installation instructions.
 
 
 
@@ -102,8 +102,8 @@ Maven installed, you can follow the instructions at http://maven.apache.org.
 
 TIP: On many operating systems, Maven can be installed with a package manager. If you use
 OSX Homebrew, try `brew install maven`. Ubuntu users can run
-`sudo apt-get install maven`. Windows users with Chocolatey can run `choco install maven`
-from an elevated (administrator) prompt.
+`sudo apt-get install maven`. Windows users with https://chocolatey.org/[Chocolatey] can
+run `choco install maven` from an elevated (administrator) prompt.
 
 Spring Boot dependencies use the `org.springframework.boot` `groupId`. Typically, your
 Maven POM file inherits from the `spring-boot-starter-parent` project and declares
@@ -298,7 +298,7 @@ commands:
 	Spring Boot v{spring-boot-version}
 ----
 
-If you are developing features for the CLI and want easy access to the version you built,
+If you develop features for the CLI and want easy access to the version you built,
 use the following commands:
 
 [indent=0,subs="verbatim,quotes,attributes"]
@@ -372,8 +372,8 @@ http://en.wikipedia.org/wiki/Zsh[zsh] shells. You can `source` the script (also
 `spring`) in any shell or put it in your personal or system-wide bash completion
 initialization. On a Debian system, the system-wide scripts are in
 `/shell-completion/bash` and all scripts in that directory are executed when a new shell
-starts. For example, to run the script manually if you have installed using SDKMAN!, use
-the following commands:
+starts. For example, to run the script manually if you have installed by using SDKMAN!,
+use the following commands:
 
 [indent=0]
 ----
@@ -415,7 +415,7 @@ Then run it from a shell, as follows:
 NOTE: The first run of your application is slow, as dependencies are downloaded.
 Subsequent runs are much quicker.
 
-Open http://localhost:8080 in your favorite web browser. You should see the following
+Open `http://localhost:8080` in your favorite web browser. You should see the following
 output:
 
 [indent=0]
@@ -427,13 +427,13 @@ output:
 
 [[getting-started-upgrading-from-an-earlier-version]]
 === Upgrading from an Earlier Version of Spring Boot
-If you are upgrading from an earlier release of Spring Boot check the "`release notes`"
-hosted on the {github-wiki}[project wiki]. You'll find upgrade instructions along with a
+If you are upgrading from an earlier release of Spring Boot, check the "`release notes`"
+hosted on the {github-wiki}[project wiki]. You can find upgrade instructions along with a
 list of "`new and noteworthy`" features for each release.
 
-To upgrade an existing CLI installation use the appropriate package manager command (for
+To upgrade an existing CLI installation, use the appropriate package manager command (for
 example, `brew upgrade`) or, if you manually installed the CLI, follow the
-<<getting-started-manual-cli-installation, standard instructions>> remembering to update
+<<getting-started-manual-cli-installation, standard instructions>>, remembering to update
 your `PATH` environment variable to remove any older references.
 
 
@@ -477,7 +477,7 @@ valid versions of Java and Maven installed:
 ----
 
 NOTE: This sample needs to be created in its own folder. Subsequent instructions assume
-that you have created a suitable folder and that it is your "`current directory`".
+that you have created a suitable folder and that it is your current directory.
 
 
 
@@ -646,7 +646,7 @@ accordingly.
 ****
 Auto-configuration is designed to work well with "`Starters`", but the two concepts are
 not directly tied. You are free to pick and choose jar dependencies outside of the
-starters and Spring Boot still does its best to auto-configure your application.
+starters. Spring Boot still does its best to auto-configure your application.
 ****
 
 
@@ -687,7 +687,7 @@ application. You should see output similar to the following:
 	........ Started Example in 2.222 seconds (JVM running for 6.514)
 ----
 
-If you open a web browser to http://localhost:8080, you should see the following output:
+If you open a web browser to `http://localhost:8080`, you should see the following output:
 
 [indent=0]
 ----
@@ -718,7 +718,7 @@ can also be problematic if the same filename is used (but with different content
 multiple jars.
 
 Spring Boot takes a <<appendix-executable-jar-format.adoc#executable-jar, different
-approach>> and allows you to actually nest jars directly.
+approach>> and lets you actually nest jars directly.
 ****
 
 To create an executable jar, we need to add the `spring-boot-maven-plugin` to our

spring-boot-project/spring-boot-docs/src/main/asciidoc/index.adoc

@@ -39,15 +39,24 @@ Phillip Webb; Dave Syer; Josh Long; Stéphane Nicoll; Rob Winch; Andy Wilkinson;
 :spring-boot-maven-plugin-site: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/maven-plugin/
 :spring-boot-gradle-plugin: http://docs.spring.io/spring-boot/docs/{spring-boot-docs-version}/gradle-plugin/
 :spring-reference: http://docs.spring.io/spring/docs/{spring-docs-version}/spring-framework-reference/
+:spring-rest-docs: http://projects.spring.io/spring-restdocs/
+:spring-integration: http://projects.spring.io/spring-integration/
+:spring-session: https://projects.spring.io/spring-session/
+:spring-framework: http://projects.spring.io/spring-framework/
+:spring-security: http://projects.spring.io/spring-security/
+:spring-data-jpa: http://projects.spring.io/spring-data-jpa/
 :spring-security-reference: http://docs.spring.io/spring-security/site/docs/{spring-security-docs-version}/reference/htmlsingle
 :spring-security-oauth2-reference: http://projects.spring.io/spring-security-oauth/docs/oauth2.html
 :spring-webservices-reference: http://docs.spring.io/spring-ws/docs/{spring-webservices-docs-version}/reference/
 :spring-javadoc: http://docs.spring.io/spring/docs/{spring-docs-version}/javadoc-api/org/springframework
+:spring-framework-javadoc: https://docs.spring.io/spring-framework/docs/{spring-docs-version}/javadoc-api/org/springframework/
 :spring-amqp-javadoc: http://docs.spring.io/spring-amqp/docs/current/api/org/springframework/amqp
 :spring-batch-javadoc: http://docs.spring.io/spring-batch/apidocs/org/springframework/batch
 :spring-data-javadoc: http://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa
 :spring-data-commons-javadoc: http://docs.spring.io/spring-data/commons/docs/current/api/org/springframework/data
 :spring-data-mongo-javadoc: http://docs.spring.io/spring-data/mongodb/docs/current/api/org/springframework/data/mongodb
+:spring-data-mongo: http://projects.spring.io/spring-data-mongodb/
+:spring-data: http://projects.spring.io/spring-data/
 :spring-data-rest-javadoc: http://docs.spring.io/spring-data/rest/docs/current/api/org/springframework/data/rest
 :gradle-userguide: http://www.gradle.org/docs/current/userguide
 :propdeps-plugin: https://github.com/spring-projects/gradle-plugins/tree/master/propdeps-plugin

spring-boot-project/spring-boot-docs/src/main/asciidoc/spring-boot-cli.adoc

@@ -79,7 +79,7 @@ using, as follows:
 [[cli-run]]
 === Running Applications with the CLI
 You can compile and run Groovy source code by using the `run` command. The Spring Boot CLI
-is completely self-contained, so you don't need any external Groovy installation.
+is completely self-contained, so you do not need any external Groovy installation.
 
 The following example shows a "`hello world`" web application written in Groovy:
 
@@ -97,14 +97,14 @@ The following example shows a "`hello world`" web application written in Groovy:
 	}
 ----
 
-To compile and run the application type the following command:
+To compile and run the application, type the following command:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
 	$ spring run hello.groovy
 ----
 
-To pass command-line arguments to the application, use a `--` to separate the commands
+To pass command-line arguments to the application, use `--` to separate the commands
 from the "`spring`" command arguments, as shown in the following example:
 
 [indent=0,subs="verbatim,quotes,attributes"]
@@ -186,10 +186,11 @@ in the Spring Boot CLI source code to understand exactly how customizations are
 ==== Deduced "`grab`" Coordinates
 Spring Boot extends Groovy's standard `@Grab` support by letting you specify a dependency
 without a group or version (for example, `@Grab('freemarker')`). Doing so consults Spring
-Boot's default dependency metadata to deduce the artifact's group and version. Note that
-the default metadata is tied to the version of the CLI that you use – it changes only when
-you move to a new version of the CLI, putting you in control of when the versions of your
-dependencies may change. A table showing the dependencies and their versions that are
+Boot's default dependency metadata to deduce the artifact's group and version.
+
+NOTE: The default metadata is tied to the version of the CLI that you use. it changes only
+when you move to a new version of the CLI, putting you in control of when the versions of
+your dependencies may change. A table showing the dependencies and their versions that are
 included in the default metadata can be found in the <<appendix-dependency-versions,
 appendix>>.
 
@@ -242,8 +243,8 @@ as shown in the following example:
 			"com.example.another-bom:1.0.0"])
 ----
 
-The preceding example indicates that dependency management in `another-bom` overrides the
-dependency management in `custom-bom`.
+The preceding example indicates that the dependency management in `another-bom` overrides
+the dependency management in `custom-bom`.
 
 You can use `@DependencyManagementBom` anywhere that you can use `@Grab`. However, to
 ensure consistent ordering of the dependency management, you can use
@@ -282,10 +283,10 @@ jar file, as shown in the following example:
 
 The resulting jar contains the classes produced by compiling the application and all of
 the application's dependencies so that it can then be run by using `java -jar`. The jar
-file also contains entries from the application's classpath. You can add explicit paths to
-the jar by using `--include` and `--exclude`. Both are comma-separated, and both accept
-prefixes, in the form of "`+`" and "`-`", to signify that they should be removed from the
-defaults. The default includes are as follows:
+file also contains entries from the application's classpath. You can add and remove
+explicit paths to the jar by using `--include` and `--exclude`. Both are comma-separated,
+and both accept prefixes, in the form of "`+`" and "`-`", to signify that they should be
+removed from the defaults. The default includes are as follows:
 
 [indent=0]
 ----
@@ -399,8 +400,8 @@ In addition to installing the artifacts identified by the coordinates you supply
 the artifacts' dependencies are also installed.
 
 To uninstall a dependency, use the `uninstall` command. As with the `install` command, it
-takes one or more sets of artifact coordinates in the format `group:artifact:version`, as
-shown in the following example:
+takes one or more sets of artifact coordinates in the format of `group:artifact:version`,
+as shown in the following example:
 
 [indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -462,14 +463,14 @@ The Spring Boot CLI uses Aether, Maven's dependency resolution engine, to resolv
 dependencies. The CLI makes use of the Maven configuration found in `~/.m2/settings.xml`
 to configure Aether. The following configuration settings are honored by the CLI:
 
- * Offline
- * Mirrors
- * Servers
- * Proxies
- * Profiles
- ** Activation
- ** Repositories
- * Active profiles
+* Offline
+* Mirrors
+* Servers
+* Proxies
+* Profiles
+** Activation
+** Repositories
+* Active profiles
 
 See https://maven.apache.org/settings.html[Maven's settings documentation] for further
 information.

spring-boot-project/spring-boot-docs/src/main/asciidoc/using-spring-boot.adoc

@@ -30,7 +30,7 @@ systems (Ant, for example), but they are not particularly well supported.
 === Dependency Management
 Each release of Spring Boot provides a curated list of dependencies that it supports. In
 practice, you do not need to provide a version for any of these dependencies in your
-build configuration, as Spring Boot is managing that for you. When you upgrade Spring
+build configuration, as Spring Boot manages that for you. When you upgrade Spring
 Boot itself, these dependencies are upgraded as well in a consistent way.
 
 NOTE: You can still specify a version and override Spring Boot's recommendations if you
@@ -76,8 +76,8 @@ style placeholders (`${...}`), the Maven filtering is changed to use `@..@` plac
 
 [[using-boot-maven-parent-pom]]
 ==== Inheriting the Starter Parent
-To configure your project to inherit from the `spring-boot-starter-parent` set the
-`parent`, as follows:
+To configure your project to inherit from the `spring-boot-starter-parent`, set the
+`parent` as follows:
 
 [source,xml,indent=0,subs="verbatim,quotes,attributes"]
 ----
@@ -273,7 +273,7 @@ _<<howto.adoc#howto-build-an-executable-archive-with-ant>>_ "`How-to`" .
 [[using-boot-starter]]
 === Starters
 Starters are a set of convenient dependency descriptors that you can include in your
-application. You get a one-stop shop for all the Spring and related technology that you
+application. You get a one-stop shop for all the Spring and related technologies that you
 need without having to hunt through sample code and copy-paste loads of dependency
 descriptors. For example, if you want to get started using Spring and JPA for database
 access, include the `spring-boot-starter-data-jpa` dependency in your project.
@@ -285,9 +285,9 @@ running quickly and with a consistent, supported set of managed transitive depen
 ****
 All **official** starters follow a similar naming pattern; `+spring-boot-starter-*+`,
 where `+*+` is a particular type of application. This naming structure is intended to
-help when you need to find a starter. The Maven integration in many IDEs allow you to
+help when you need to find a starter. The Maven integration in many IDEs lets you
 search dependencies by name. For example, with the appropriate Eclipse or STS plugin
-installed, you can simply hit `ctrl-space` in the POM editor and type
+installed, you can press `ctrl-space` in the POM editor and type
 "`spring-boot-starter`" for a complete list.
 
 As explained in the "`<<spring-boot-features#boot-features-custom-starter,Creating Your
@@ -636,6 +636,7 @@ following example:
 === Using the Maven Plugin
 The Spring Boot Maven plugin includes a `run` goal that can be used to quickly compile
 and run your application. Applications run in an exploded form, as they do in your IDE.
+The following example shows a typical Maven command to run a Spring Boot application:
 
 [indent=0,subs="attributes"]
 ----
@@ -682,7 +683,7 @@ http://zeroturnaround.com/software/jrebel/[JRebel] can be used.
 
 The
 `spring-boot-devtools` module also includes support for quick application restarts.
-See the <<using-boot-devtools>> section below and the
+See the <<using-boot-devtools>> section later in this chapter and the
 <<howto.adoc#howto-hotswapping, Hot swapping "`How-to`">> for details.
 
 
@@ -716,10 +717,10 @@ listings for Maven and Gradle:
 ----
 
 NOTE: Developer tools are automatically disabled when running a fully packaged
-application. If your application is launched using `java -jar` or if it is started from a
+application. If your application is launched from `java -jar` or if it is started from a
 special classloader, then it is considered a "`production application`". Flagging the
 dependency as optional is a best practice that prevents devtools from being transitively
-applied to other modules using your project. Gradle does not support `optional`
+applied to other modules that use your project. Gradle does not support `optional`
 dependencies out-of-the-box, so you may want to have a look at the
 {propdeps-plugin}[`propdeps-plugin`].
 
@@ -852,7 +853,7 @@ You may want your application to be restarted or reloaded when you make changes
 that are not on the classpath. To do so, use the
 `spring.devtools.restart.additional-paths` property to configure additional paths to
 watch for changes. You can use the `spring.devtools.restart.exclude` property
-<<using-boot-devtools-restart-exclude, described above>> to control whether changes
+<<using-boot-devtools-restart-exclude, described earlier>> to control whether changes
 beneath the additional paths trigger a full restart or a
 <<using-boot-devtools-livereload, live reload>>.
 
@@ -865,7 +866,7 @@ If you do not want to use the restart feature, you can disable it by using the
 your `application.properties` (doing so still initializes the restart classloader, but it
 does not watch for file changes).
 
-If you need to _completely_ disable restart support (for example, because it doesn't work
+If you need to _completely_ disable restart support (for example, because it does not work
 with a specific library), you need to set the `spring.devtools.restart.enabled` `System`
 property to `false` before calling `SpringApplication.run(...)`, as shown in the
 following example:
@@ -885,7 +886,7 @@ following example:
 If you work with an IDE that continuously compiles changed files, you might prefer to
 trigger restarts only at specific times. To do so, you can use a "`trigger file`", which
 is a special file that must be modified when you want to actually trigger a restart
-check. Changing the file only triggers the check and the restart will only occur if
+check. Changing the file only triggers the check and the restart only occurs if
 Devtools has detected it has to do something. The trigger file can be updated manually or
 with an IDE plugin.
 
@@ -900,9 +901,9 @@ in the same way.
 
 [[using-boot-devtools-customizing-classload]]
 ==== Customizing the Restart Classloader
-As described in the <<using-spring-boot-restart-vs-reload>> section above, restart
+As described earlier in the <<using-spring-boot-restart-vs-reload>> section, restart
 functionality is implemented by using two classloaders. For most applications, this
-approach works well. However, sometimes it can cause classloading issues.
+approach works well. However, it can sometimes cause classloading issues.
 
 By default, any open project in your IDE is loaded with the "`restart`" classloader, and
 any regular `.jar` file is loaded with the "`base`" classloader. If you work on a
@@ -924,7 +925,7 @@ pattern that is applied to the classpath, as shown in the following example:
 NOTE: All property keys must be unique. As long as a property starts with
 `restart.include.` or `restart.exclude.` it is considered.
 
-TIP: All `META-INF/spring-devtools.properties` from the classpath will be loaded. You can
+TIP: All `META-INF/spring-devtools.properties` from the classpath are loaded. You can
 package files inside your project, or in the libraries that the project consumes.
 
 
@@ -977,7 +978,7 @@ property:
 
 [[using-boot-devtools-remote]]
 === Remote Applications
-The Spring Boot developer tools are not just limited to local development. You can also
+The Spring Boot developer tools are not limited to local development. You can also
 use several features when running applications remotely. Remote support is opt-in. To
 enable it, you need to make sure that `devtools` is included in the repackaged archive,
 as shown in the following listing: