Clean up Reference Documentation

buildSrc/build.gradle

@@ -80,8 +80,8 @@ dependencies {
 	implementation 'io.spring.gradle:propdeps-plugin:0.0.10.RELEASE'
 	implementation 'io.spring.javaformat:spring-javaformat-gradle-plugin:0.0.15'
 	implementation 'io.spring.nohttp:nohttp-gradle:0.0.8'
-	implementation 'org.asciidoctor:asciidoctor-gradle-jvm:3.1.0'
-	implementation 'org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.1.0'
+	implementation 'org.asciidoctor:asciidoctor-gradle-jvm:3.3.0'
+	implementation 'org.asciidoctor:asciidoctor-gradle-jvm-pdf:3.3.0'
 	implementation 'org.hidetake:gradle-ssh-plugin:2.10.1'
 	implementation 'org.jfrog.buildinfo:build-info-extractor-gradle:4.9.10'
 	implementation 'org.sonarsource.scanner.gradle:sonarqube-gradle-plugin:2.7.1'

docs/manual/src/docs/asciidoc/_includes/about/authentication/supported.adoc

@@ -1,5 +1,5 @@
 [[authentication-support]]
 = Authentication Support
 
-Spring Security provides built in support for authenticating users.
-Refer to the sections on authentication for <<servlet-authentication,Servlet>> and WebFlux for details on what is supported for each stack.
+Spring Security provides built-in support for authenticating users.
+See the sections on authentication for <<servlet-authentication,Servlet>> and <<jc-webflux,WebFlux>> for details on what is supported for each stack.

docs/manual/src/docs/asciidoc/_includes/about/exploits/http.adoc

@@ -1,15 +1,15 @@
 [[http]]
 = HTTP
 
-All HTTP based communication, including https://www.troyhunt.com/heres-why-your-static-website-needs-https/[static resources], should be protected https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Protection_Cheat_Sheet.html[using TLS].
+All HTTP-based communication, including https://www.troyhunt.com/heres-why-your-static-website-needs-https/[static resources], should be protected by https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Protection_Cheat_Sheet.html[using TLS].
 
 As a framework, Spring Security does not handle HTTP connections and thus does not provide support for HTTPS directly.
 However, it does provide a number of features that help with HTTPS usage.
 
 [[http-redirect]]
 == Redirect to HTTPS
 
-When a client uses HTTP, Spring Security can be configured to redirect to HTTPS both <<servlet-http-redirect,Servlet>> and <<webflux-http-redirect,WebFlux>> environments.
+When a client uses HTTP, you can configure Spring Security to redirect to HTTPS in both <<servlet-http-redirect,Servlet>> and <<webflux-http-redirect,WebFlux>> environments.
 
 [[http-hsts]]
 == Strict Transport Security
@@ -19,14 +19,14 @@ Spring Security provides support for <<headers-hsts,Strict Transport Security>>
 [[http-proxy-server]]
 == Proxy Server Configuration
 
-When using a proxy server it is important to ensure that you have configured your application properly.
-For example, many applications will have a load balancer that responds to request for https://example.com/ by forwarding the request to an application server at https://192.168.1:8080
-Without proper configuration, the application server will not know that the load balancer exists and treat the request as though https://192.168.1:8080 was requested by the client.
+When using a proxy server, it is important to ensure that you have configured your application properly.
+For example, many applications have a load balancer that responds to request for https://example.com/ by forwarding the request to an application server at https://192.168.1:8080
+Without proper configuration, the application server can not know that the load balancer exists and treats the request as though https://192.168.1:8080 was requested by the client.
 
-To fix this you can use https://tools.ietf.org/html/rfc7239[RFC 7239] to specify that a load balancer is being used.
-To make the application aware of this, you need to either configure your application server aware of the X-Forwarded headers.
-For example Tomcat uses the https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/valves/RemoteIpValve.html[RemoteIpValve] and Jetty uses https://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[ForwardedRequestCustomizer].
-Alternatively, Spring users can leverage https://github.com/spring-projects/spring-framework/blob/v4.3.3.RELEASE/spring-web/src/main/java/org/springframework/web/filter/ForwardedHeaderFilter.java[ForwardedHeaderFilter].
+To fix this, you can use https://tools.ietf.org/html/rfc7239[RFC 7239] to specify that a load balancer is being used.
+To make the application aware of this, you need to configure your application server to be aware of the X-Forwarded headers.
+For example, Tomcat uses https://tomcat.apache.org/tomcat-8.0-doc/api/org/apache/catalina/valves/RemoteIpValve.html[`RemoteIpValve`] and Jetty uses https://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/server/ForwardedRequestCustomizer.html[`ForwardedRequestCustomizer`].
+Alternatively, Spring users can use https://github.com/spring-projects/spring-framework/blob/v4.3.3.RELEASE/spring-web/src/main/java/org/springframework/web/filter/ForwardedHeaderFilter.java[`ForwardedHeaderFilter`].
 
-Spring Boot users may use the `server.use-forward-headers` property to configure the application.
+Spring Boot users can use the `server.use-forward-headers` property to configure the application.
 See the https://docs.spring.io/spring-boot/docs/current/reference/htmlsingle/#howto-use-tomcat-behind-a-proxy-server[Spring Boot documentation] for further details.

docs/manual/src/docs/asciidoc/_includes/about/exploits/index.adoc

@@ -3,7 +3,7 @@
 
 Spring Security provides protection against common exploits.
 Whenever possible, the protection is enabled by default.
-Below you will find high level description of the various exploits that Spring Security protects against.
+This section describes the various exploits that Spring Security protects against.
 
 include::csrf.adoc[leveloffset=+1]
 

docs/manual/src/docs/asciidoc/_includes/about/features.adoc

@@ -1,6 +1,7 @@
 [[features]]
 = Features
 
+// FIXME: Add a link for authorization
 Spring Security provides comprehensive support for <<authentication,authentication>>, authorization, and protection against <<exploits,common exploits>>.
 It also provides integration with other libraries to simplify its usage.
 

docs/manual/src/docs/asciidoc/_includes/about/getting-spring-security.adoc

@@ -1,7 +1,7 @@
 [[getting]]
 = Getting Spring Security
 
-This section discusses all you need to know about getting the Spring Security binaries.
+This section describes how to get the Spring Security binaries.
 See <<community-source>> for how to obtain the source code.
 
 == Release Numbering
@@ -10,21 +10,21 @@ Spring Security versions are formatted as MAJOR.MINOR.PATCH such that:
 
 * MAJOR versions may contain breaking changes.
 Typically, these are done to provide improved security to match modern security practices.
-* MINOR versions contain enhancements but are considered passive updates
+* MINOR versions contain enhancements but are considered passive updates.
 * PATCH level should be perfectly compatible, forwards and backwards, with the possible exception of changes that fix bugs.
 
 
 [[maven]]
 == Usage with Maven
 
 As most open source projects, Spring Security deploys its dependencies as Maven artifacts.
-The topics in this section provide detail on how to consume Spring Security when using Maven.
+The topics in this section describe how to consume Spring Security when using Maven.
 
 [[getting-maven-boot]]
 === Spring Boot with Maven
 
-Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security-related dependencies together.
-The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
+Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security-related dependencies.
+The simplest and preferred way to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration in (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse] or https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
 
 Alternatively, you can manually add the starter, as the following example shows:
 
@@ -44,7 +44,7 @@ Alternatively, you can manually add the starter, as the following example shows:
 ====
 
 Since Spring Boot provides a Maven BOM to manage dependency versions, you do not need to specify a version.
-If you wish to override the Spring Security version, you may do so by providing a Maven property, as the following example shows:
+If you wish to override the Spring Security version, you can do so by providing a Maven property:
 
 .pom.xml
 ====
@@ -57,9 +57,9 @@ If you wish to override the Spring Security version, you may do so by providing
 ----
 ====
 
-Since Spring Security makes breaking changes only in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
+Since Spring Security makes breaking changes only in major releases, you can safely use a newer version of Spring Security with Spring Boot.
 However, at times, you may need to update the version of Spring Framework as well.
-You can do so by adding a Maven property, as the following example shows:
+You can do so by adding a Maven property:
 
 .pom.xml
 ====
@@ -72,12 +72,12 @@ You can do so by adding a Maven property, as the following example shows:
 ----
 ====
 
-If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules,modules>>.
 
 [[getting-maven-no-boot]]
 === Maven Without Spring Boot
 
-When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project. The following example shows how to do so:
+When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure that a consistent version of Spring Security is used throughout the entire project. The following example shows how to do so:
 
 .pom.xml
 ====
@@ -98,7 +98,7 @@ When you use Spring Security without Spring Boot, the preferred way is to use Sp
 ----
 ====
 
-A minimal Spring Security Maven set of dependencies typically looks like the following:
+A minimal Spring Security Maven set of dependencies typically looks like the following example:
 
 .pom.xml
 ====
@@ -118,11 +118,11 @@ A minimal Spring Security Maven set of dependencies typically looks like the fol
 ----
 ====
 
-If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules,modules>>.
 
 Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x.
 Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems.
-The easiest way to resolve this is to use the `spring-framework-bom` within the `<dependencyManagement>` section of your `pom.xml` as the following example shows:
+The easiest way to resolve this is to use the `spring-framework-bom` within the `<dependencyManagement>` section of your `pom.xml`:
 
 .pom.xml
 ====
@@ -145,14 +145,17 @@ The easiest way to resolve this is to use the `spring-framework-bom` within the
 
 The preceding example ensures that all the transitive dependencies of Spring Security use the Spring {spring-core-version} modules.
 
-NOTE: This approach uses Maven's "`bill of materials`" (BOM) concept and is only available in Maven 2.0.9+.
+[NOTE]
+====
+This approach uses Maven's "`bill of materials`" (BOM) concept and is only available in Maven 2.0.9+.
 For additional details about how dependencies are resolved, see https://maven.apache.org/guides/introduction/introduction-to-dependency-mechanism.html[Maven's Introduction to the Dependency Mechanism documentation].
+====
 
 [[maven-repositories]]
 === Maven Repositories
-All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so no additional Maven repositories need to be declared in your pom.
+All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so you need not declare additional Maven repositories in your pom.
 
-If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined, as the following example shows:
+If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined:
 
 .pom.xml
 ====
@@ -190,15 +193,15 @@ If you use a milestone or release candidate version, you need to ensure that you
 == Gradle
 
 As most open source projects, Spring Security deploys its dependencies as Maven artifacts, which allows for first-class Gradle support.
-The following topics provide detail on how to consume Spring Security when using Gradle.
+The following topics describe how to consume Spring Security when using Gradle.
 
 [[getting-gradle-boot]]
 === Spring Boot with Gradle
 
-Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security related dependencies together.
-The simplest and preferred method to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse], https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
+Spring Boot provides a `spring-boot-starter-security` starter that aggregates Spring Security related dependencies.
+The simplest and preferred method to use the starter is to use https://docs.spring.io/initializr/docs/current/reference/htmlsingle/[Spring Initializr] by using an IDE integration in (https://joshlong.com/jl/blogPost/tech_tip_geting_started_with_spring_boot.html[Eclipse] or https://www.jetbrains.com/help/idea/spring-boot.html#d1489567e2[IntelliJ], https://github.com/AlexFalappa/nb-springboot/wiki/Quick-Tour[NetBeans]) or through https://start.spring.io.
 
-Alternatively, you can manually add the starter, as the following example shows:
+Alternatively, you can manually add the starter:
 
 .build.gradle
 ====
@@ -212,7 +215,7 @@ dependencies {
 ====
 
 Since Spring Boot provides a Maven BOM to manage dependency versions, you need not specify a version.
-If you wish to override the Spring Security version, you may do so by providing a Gradle property, as the following example shows:
+If you wish to override the Spring Security version, you can do so by providing a Gradle property:
 
 .build.gradle
 ====
@@ -223,9 +226,9 @@ ext['spring-security.version']='{spring-security-version}'
 ----
 ====
 
-Since Spring Security makes breaking changes only in major releases, it is safe to use a newer version of Spring Security with Spring Boot.
+Since Spring Security makes breaking changes only in major releases, you can safely use a newer version of Spring Security with Spring Boot.
 However, at times, you may need to update the version of Spring Framework as well.
-You can do so by adding a Gradle property, as the following example shows:
+You can do so by adding a Gradle property:
 
 .build.gradle
 ====
@@ -236,12 +239,12 @@ ext['spring.version']='{spring-core-version}'
 ----
 ====
 
-If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules,modules>>.
 
 === Gradle Without Spring Boot
 
 When you use Spring Security without Spring Boot, the preferred way is to use Spring Security's BOM to ensure a consistent version of Spring Security is used throughout the entire project.
-You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows:
+You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin]:
 
 .build.gradle
 ====
@@ -260,7 +263,7 @@ dependencyManagement {
 ----
 ====
 
-A minimal Spring Security Maven set of dependencies typically looks like the following:
+A minimal Spring Security Maven set of dependencies typically looks like the following example:
 
 .build.gradle
 ====
@@ -274,12 +277,12 @@ dependencies {
 ----
 ====
 
-If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules>>.
+If you use additional features (such as LDAP, OpenID, and others), you need to also include the appropriate <<modules,modules>>.
 
 Spring Security builds against Spring Framework {spring-core-version} but should generally work with any newer version of Spring Framework 5.x.
 Many users are likely to run afoul of the fact that Spring Security's transitive dependencies resolve Spring Framework {spring-core-version}, which can cause strange classpath problems.
 The easiest way to resolve this is to use the `spring-framework-bom` within your `<dependencyManagement>` section of your `pom.xml`.
-You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin], as the following example shows:
+You can do so by using the https://github.com/spring-gradle-plugins/dependency-management-plugin[Dependency Management Plugin]:
 
 .build.gradle
 ====
@@ -302,7 +305,7 @@ The preceding example ensures that all the transitive dependencies of Spring Sec
 
 [[gradle-repositories]]
 === Gradle Repositories
-All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so using the mavenCentral() repository is sufficient for GA releases. The following example shows how to do so:
+All GA releases (that is, versions ending in .RELEASE) are deployed to Maven Central, so using the `mavenCentral()` repository is sufficient for GA releases. The following example shows how to do so:
 
 .build.gradle
 ====
@@ -314,7 +317,7 @@ repositories {
 ----
 ====
 
-If you use a SNAPSHOT version, you need to ensure you have the Spring Snapshot repository defined, as the following example shows:
+If you use a SNAPSHOT version, you need to ensure that you have the Spring Snapshot repository defined:
 
 .build.gradle
 ====
@@ -326,7 +329,7 @@ repositories {
 ----
 ====
 
-If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined, as the following example shows:
+If you use a milestone or release candidate version, you need to ensure that you have the Spring Milestone repository defined:
 
 .build.gradle
 ====