rewrite docs - gh 2567 master merge march 2019

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

@@ -0,0 +1,37 @@
+[[community]]
+= Spring Security Community
+
+Welcome to the Spring Security Community!
+This section discusses how you can make the most of our vast community.
+
+
+[[community-help]]
+== Getting Help
+If you need help with Spring Security, we are here to help.
+The following are some of the best ways to get help:
+
+* Read through this documentation.
+* Try one of our many <<samples,sample applications>>.
+* Ask a question on https://stackoverflow.com/questions/tagged/spring-security[https://stackoverflow.com] with the `spring-security` tag.
+* Report bugs and enhancement requests at https://github.com/spring-projects/spring-security/issues
+
+[[community-becoming-involved]]
+== Becoming Involved
+We welcome your involvement in the Spring Security project.
+There are many ways to contribute, including answering questions on StackOverflow, writing new code, improving existing code, assisting with documentation, developing samples or tutorials, reporting bugs, or simply making suggestions.
+For more information, see our https://github.com/spring-projects/spring-security/blob/master/CONTRIBUTING.md[Contributing] documentation.
+
+[[community-source]]
+== Source Code
+
+You can find Spring Security's source code on GitHub at https://github.com/spring-projects/spring-security/
+
+[[community-license]]
+== Apache 2 License
+
+Spring Security is Open Source software released under the http://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].
+
+== Social Media
+
+You can follow https://twitter.com/SpringSecurity[@SpringSecurity] and the https://twitter.com/SpringSecurity/lists/team[Spring Security team] on Twitter to stay up to date with the latest news.
+You can also follow https://twitter.com/SpringCentral[@SpringCentral] to keep up to date with the entire Spring portfolio.

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

@@ -0,0 +1,17 @@
+= About
+
+// FIXME: guidance on getting started
+Spring Security provides first class authentication, authorization, and protection against common attacks for web applications deployed in <<servlet,servlet container>> and <<reactive,reactive>> applications.
+Continue reading to learn more about the <<prerequisites,prerequisites>>, <<new,what's new>>, <<getting, getting Spring Security>>, and our extensive collection of <<samples,samples>>.
+
+include::prerequisites.adoc[leveloffset=+1]
+
+include::community.adoc[leveloffset=+1]
+
+include::whats-new.adoc[]
+
+include::getting-spring-security.adoc[leveloffset=+1]
+
+include::modules.adoc[leveloffset=+1]
+
+include::samples.adoc[leveloffset=+1]

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

@@ -0,0 +1,108 @@
+// FIXME: This might make sense in Getting Spring Security along with the artifact information
+
+[[modules]]
+= Project Modules
+In Spring Security 3.0, the codebase was sub-divided into separate jars that more clearly separate different functionality areas and third-party dependencies.
+If you use Maven to build your project, these are the modules you should add to your `pom.xml`.
+Even if you do not use Maven, we recommend that you consult the `pom.xml` files to get an idea of third-party dependencies and versions.
+Another good idea is to examine the libraries that are included in the sample applications.
+
+
+[[spring-security-core]]
+== Core -- `spring-security-core.jar`
+This module contains core authentication and access-contol classes and interfaces, remoting support, and basic provisioning APIs.
+It is required by any application that uses Spring Security.
+It supports standalone applications, remote clients, method (service layer) security, and JDBC user provisioning.
+It contains the following top-level packages:
+
+* `org.springframework.security.core`
+* `org.springframework.security.access`
+* `org.springframework.security.authentication`
+* `org.springframework.security.provisioning`
+
+[[spring-security-remoting]]
+== Remoting -- `spring-security-remoting.jar`
+This module provides intergration with Spring Remoting.
+You do not need this unless you are writing a remote client that uses Spring Remoting.
+The main package is `org.springframework.security.remoting`.
+
+
+[[spring-security-web]]
+== Web -- `spring-security-web.jar`
+This module contains filters and related web-security infrastructure code.
+It contains anything with a servlet API dependency.
+You need it if you require Spring Security web authentication services and URL-based access-control.
+The main package is `org.springframework.security.web`.
+
+
+[[spring-security-config]]
+== Config -- `spring-security-config.jar`
+This module contains the security namespace parsing code and Java configuration code.
+You need it if you use the Spring Security XML namespace for configuration or Spring Security's Java Configuration support.
+The main package is `org.springframework.security.config`.
+None of the classes are intended for direct use in an application.
+
+
+[[spring-security-ldap]]
+== LDAP -- `spring-security-ldap.jar`
+This module provides LDAP authentication and provisioning code.
+It is required if you need to use LDAP authentication or manage LDAP user entries.
+The top-level package is `org.springframework.security.ldap`.
+
+
+[[spring-security-oauth2-core]]
+== OAuth 2.0 Core -- `spring-security-oauth2-core.jar`
+`spring-security-oauth2-core.jar` contains core classes and interfaces that provide support for the OAuth 2.0 Authorization Framework and for OpenID Connect Core 1.0.
+It is required by applications that use OAuth 2.0 or OpenID Connect Core 1.0, such as client, resource server, and authorization server.
+The top-level package is `org.springframework.security.oauth2.core`.
+
+
+[[spring-security-oauth2-client]]
+== OAuth 2.0 Client -- `spring-security-oauth2-client.jar`
+`spring-security-oauth2-client.jar` contains Spring Security's client support for OAuth 2.0 Authorization Framework and OpenID Connect Core 1.0.
+It is required by applications that use OAuth 2.0 Login or OAuth Client support.
+The top-level package is `org.springframework.security.oauth2.client`.
+
+
+[[spring-security-oauth2-jose]]
+== OAuth 2.0 JOSE -- `spring-security-oauth2-jose.jar`
+`spring-security-oauth2-jose.jar` contains Spring Security's support for the JOSE (Javascript Object Signing and Encryption) framework.
+The JOSE framework is intended to provide a method to securely transfer claims between parties.
+It is built from a collection of specifications:
+
+* JSON Web Token (JWT)
+* JSON Web Signature (JWS)
+* JSON Web Encryption (JWE)
+* JSON Web Key (JWK)
+
+It contains the following top-level packages:
+
+* `org.springframework.security.oauth2.jwt`
+* `org.springframework.security.oauth2.jose`
+
+
+[[spring-security-acl]]
+== ACL -- `spring-security-acl.jar`
+This module contains a specialized domain object ACL implementation.
+It is used to apply security to specific domain object instances within your application.
+The top-level package is `org.springframework.security.acls`.
+
+
+[[spring-security-cas]]
+== CAS -- `spring-security-cas.jar`
+This module contains Spring Security's CAS client integration.
+You should use it if you want to use Spring Security web authentication with a CAS single sign-on server.
+The top-level package is `org.springframework.security.cas`.
+
+
+[[spring-security-openid]]
+== OpenID -- `spring-security-openid.jar`
+This module contains OpenID web authentication support.
+It is used to authenticate users against an external OpenID server.
+The top-level package is `org.springframework.security.openid`.
+It requires OpenID4Java.
+
+
+[[spring-security-test]]
+== Test -- `spring-security-test.jar`
+This module contains support for testing with Spring Security.

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

@@ -0,0 +1,12 @@
+[[prerequisites]]
+= Prerequisites
+
+Spring Security requires a Java 8 or higher Runtime Environment.
+
+As Spring Security aims to operate in a self-contained manner, you do not need to place any special configuration files in your Java Runtime Environment.
+In particular, you need not configure a special Java Authentication and Authorization Service (JAAS) policy file or place Spring Security into common classpath locations.
+
+Similarly, if you use an EJB Container or Servlet Container, you need not put any special configuration files anywhere nor include Spring Security in a server classloader.
+All the required files are contained within your application.
+
+This design offers maximum deployment time flexibility, as you can copy your target artifact (be it a JAR, WAR, or EAR) from one system to another and it immediately works.

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

@@ -0,0 +1,3 @@
+= Samples
+
+Spring Security includes many {gh-samples-url}[samples] applications.

docs/manual/src/docs/asciidoc/_includes/preface/whats-new.adoc → docs/manual/src/docs/asciidoc/_includes/about/whats-new.adoc

@@ -4,6 +4,7 @@
 Spring Security 5.1 provides a number of new features.
 Below are the highlights of the release.
 
+[[new-servlet]]
 === Servlet
 
 * Automatic password storage upgrades through {security-api-url}org/springframework/security/core/userdetails/UserDetailsPasswordService.html[UserDetailsPasswordService]
@@ -20,6 +21,7 @@ Below are the highlights of the release.
 * Added {security-api-url}core/src/main/java/org/springframework/security/core/Transient.java[@Transient] authentication tokens
 * A modern look-and-feel for the default log in page
 
+[[new-webflux]]
 === WebFlux
 
 * Automatic password storage upgrades through {security-api-url}org/springframework/security/core/userdetails/ReactiveUserDetailsPasswordService.html[ReactiveUserDetailsPasswordService]
@@ -38,6 +40,7 @@ Below are the highlights of the release.
 ** Support for resolving beans
 ** Support for resolving `errorOnInvalidType`
 
+[[new-integrations]]
 === Integrations
 
 * <<jackson,Jackson Support>> works with `BadCredentialsException`