diff --git a/src/docbkx/appendix-namespace.xml b/src/docbkx/appendix-namespace.xml
index 9101e17959..a1c6d3e0a1 100644
--- a/src/docbkx/appendix-namespace.xml
+++ b/src/docbkx/appendix-namespace.xml
@@ -8,16 +8,134 @@
- This provides a reference to the elements available in the security namespace and infromation on
- the underlying beans they create. If you haven't used the namespace before, please read the
- introductory chapter.
+ This provides a reference to the elements available in the security namespace and information on
+ the underlying beans they create (a knowledge of the individual classes and how they work together is assumed -
+ you can find more information in the project Javadoc and elsewhere in this document).
+ If you haven't used the namespace before, please read the
+ introductory chapter. Using a good quality XML editor while
+ editing a configuration based on the schema is recommended as this will provide contextual information on
+ which elements and attributes are available and comments explaining their purpose.
-
+ The <literal><http></literal> Element
- This element encapsulates the security configuration for the web layer of your application.
+ This element encapsulates the security configuration for the web layer of your application. It creates a
+ FilterChainProxy bean named "springSecurityFilterChain" which maintains the stack of
+ security filters which make up the web security configuration See the
+ introductory chapter for how to set up the mapping from
+ your web.xml. Some core filters are always created and others will
+ be added to the stack depending on the attributes child elements which are present. The positions of the standard
+ filters are fixed (see the filter order table in the namespace introduction),
+ removing a common source of errors with previous versions of the framework when users had to configure the
+ filter chain explicitly in theFilterChainProxy bean. You can, of course, still do this
+ if you need full control of the configuration.
+
+ The <http> namespace block always creates an HttpSessionContextIntegrationFilter,
+ an ExceptionTranslationFilter and a FilterSecurityInterceptor. These are fixed
+ and cannot be replaced with alternatives.
+
+
+
+ <literal><http></literal> Attributes
+
+ The attributes on the <http> element control some of the properties on the
+ core filters.
+
+
+ <literal>servlet-api-provision</literal>
+
+ Provides versions of HttpServletRequest security methods such as
+ isUserInRole() and getPrincipal() which are implemented by
+ adding a SecurityContextHolderAwareRequestFilter bean to the stack. Defaults to "true".
+
+
+
+
+ <literal>path-type</literal>
+
+ Controls whether URL patterns are interpreted as ant paths (the default) or regular expressions. In practice
+ this sets a particular UrlMatcher instance on the FilterChainProxy.
+
+
+
+
+ <literal>lowercase-comparisons</literal>
+
+ Whether test URLs should be converted to lower case prior to comparing with defined path patterns. If unspecified,
+ defaults to "true"
+
+
+
+
+ <literal>session-fixation-protection</literal>
+
+ Indicates whether an existing session should be invalidated when a user authenticates and a new session started.
+ If set to "none" no change will be made. "newSession" will create a new empty session.
+ "migrateSession" will create a new session and copy the session attributes to the new session. Defaults to "migrateSession".
+
+
+ If enabled this will add a SessionFixationProtectionFilter to the stack. The session fixation protection
+ options on namespace-created instances of AbstractProcessingFilter will also be set appropriately.
+
+
+
+
+ <literal>realm</literal>
+
+ Sets the realm name used for basic authentication (if enabled). Corresponds to the realmName proerty on
+ BasicProcessingFilterEntryPoint.
+
+
+
+
+ <literal>entry-point-ref</literal>
+
+ Normally the AuthenticationEntryPoint used will be set depending on which
+ authentication mechanisms have been configured. This attribute allows this behaviour to be overridden
+ by defining a customized AuthenticationEntryPoint bean which will start the authentication
+ process.
+
+
+
+
+ <literal>access-decision-manager-ref</literal>
+
+ Optional attribute specifying the ID of the AccessDecisionManager implementation which should be
+ used for authorizing HTTP requests. By default an AffirmativeBased implementation is used for with
+ a RoleVoter and an AuthenticatedVoter.
+
+
+
+
+ <literal>access-denied-page</literal>
+
+ Allows the access denied page to be set (the user will be redirected here if an AccessDeniedException is raised).
+
+
+
+
+ <literal>once-per-request</literal>
+
+ Corresponds to the observeOncePerRequest property of
+ FilterSecurityInterceptor. Defaults to "true".
+
+
+
+
+
+
+
+
+
+
+ The <literal><intercept-url></literal> Element
+
+
+
+
+
\ No newline at end of file