Restructured docs, faq and removed use of docbkx plugin

src/docbkx/basic-authentication.xml → docs/manual/src/docbook/basic-authentication.xml

@@ -27,7 +27,7 @@
         <literal>BasicProcessingFilter</literal> and its required
         collaborator:</para>
     
-    <para><programlisting>
+    <para><programlisting language="xml">
         &lt;bean id="basicProcessingFilter" class="org.springframework.security.web.authentication.www.BasicProcessingFilter"&gt;
         &lt;property name="authenticationManager"&gt;&lt;ref bean="authenticationManager"/&gt;&lt;/property&gt;
         &lt;property name="authenticationEntryPoint"&gt;&lt;ref bean="authenticationEntryPoint"/&gt;&lt;/property&gt;

docs/manual/src/docbook/html-titlepage.xml

@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
+             xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
+             xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+<!-- ==================================================================== -->
+
+<t:titlepage t:element="book" t:wrapper="div" class="titlepage">
+  <t:titlepage-content t:side="recto">
+    <title/>
+    <subtitle/>
+    <corpauthor/>
+    <authorgroup/>
+    <author/>
+    <mediaobject/>
+    <othercredit/>
+    <productname/>
+    <releaseinfo/>
+    <copyright/>
+    <pubdate/>
+    <revision/>
+    <revhistory/>
+    <abstract/>
+  </t:titlepage-content>
+
+  <t:titlepage-content t:side="verso">
+	<legalnotice/>
+  </t:titlepage-content>
+
+  <t:titlepage-separator>
+    <hr/>
+  </t:titlepage-separator>
+
+  <t:titlepage-before t:side="recto">
+  </t:titlepage-before>
+
+  <t:titlepage-before t:side="verso">
+  </t:titlepage-before>
+</t:titlepage>
+
+</t:templates>

src/docbkx/namespace-config.xml → docs/manual/src/docbook/namespace-config.xml

@@ -29,7 +29,7 @@
       you try out the <link xlink:href="http://www.springsource.com/products/sts">SpringSource Tool
         Suite</link> as it has special features for working with standard Spring namespaces. </para>
     <para> To start using the security namespace in your application context, all you need to do is
-      add the schema declaration to your application context file: <programlisting>
+      add the schema declaration to your application context file: <programlisting language="xml">
   <![CDATA[
 <beans xmlns="http://www.springframework.org/schema/beans"
   xmlns:security="http://www.springframework.org/schema/security"
@@ -43,7 +43,7 @@
       omit the prefix on all the security namespace elements, making the context easier to read. You
       may also want to do this if you have your application context divided up into separate files
       and have most of your security configuration in one of them. Your security application context
-      file would then start like this <programlisting><![CDATA[
+      file would then start like this <programlisting language="xml"><![CDATA[
 <beans:beans xmlns="http://www.springframework.org/schema/security"
   xmlns:beans="http://www.springframework.org/schema/beans"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -109,7 +109,7 @@
     <section xml:id="ns-web-xml">
       <title><literal>web.xml</literal> Configuration</title>
       <para> The first thing you need to do is add the following filter declaration to your
-          <literal>web.xml</literal> file: <programlisting>
+        <literal>web.xml</literal> file: <programlisting language="xml">
         <![CDATA[  
 <filter>
   <filter-name>springSecurityFilterChain</filter-name>
@@ -132,7 +132,7 @@
     </section>
     <section xml:id="ns-minimal">
       <title>A Minimal <literal>&lt;http&gt;</literal> Configuration</title>
-      <para> All you need to enable web security to begin with is <programlisting><![CDATA[
+      <para> All you need to enable web security to begin with is <programlisting language="xml"><![CDATA[
   <http auto-config='true'>
     <intercept-url pattern="/**" access="ROLE_USER" />
   </http>
@@ -145,7 +145,7 @@
           the order listed and the first match will be used. So you must put the most specific
           matches at the top.</para>
       </note>
-      <para> To add some users, you can define a set of test data directly in the namespace: <programlisting><![CDATA[
+      <para> To add some users, you can define a set of test data directly in the namespace: <programlisting language="xml"><![CDATA[
   <authentication-provider>
     <user-service>
       <user name="jimi" password="jimispassword" authorities="ROLE_USER, ROLE_ADMIN" />
@@ -184,7 +184,7 @@
       <section xml:id="ns-auto-config">
         <title>What does <literal>auto-config</literal> Include?</title>
         <para> The <literal>auto-config</literal> attribute, as we have used it above, is just a
-          shorthand syntax for: <programlisting><![CDATA[
+          shorthand syntax for: <programlisting language="xml"><![CDATA[
   <http>
     <form-login />
     <http-basic />
@@ -210,7 +210,7 @@
           based on the features that are enabled and using standard values for the URL which
           processes the submitted login, the default target URL the user will be sent to and so on.
           However, the namespace offers plenty of suppport to allow you to customize these options.
-          For example, if you want to supply your own login page, you could use: <programlisting><![CDATA[
+          For example, if you want to supply your own login page, you could use: <programlisting language="xml"><![CDATA[
   <http auto-config='true'>
     <intercept-url pattern="/login.jsp*" filters="none"/>  
     <intercept-url pattern="/**" access="ROLE_USER" />
@@ -223,7 +223,7 @@
           requests for the login page should be excluded from processing by the security filters.
           Otherwise the request would be matched by the pattern <literal>/**</literal> and it
           wouldn't be possible to access the login page itself! If you want to use basic
-          authentication instead of form login, then change the configuration to <programlisting><![CDATA[
+          authentication instead of form login, then change the configuration to <programlisting language="xml"><![CDATA[
   <http auto-config='true'>
     <intercept-url pattern="/**" access="ROLE_USER" />
     <http-basic />
@@ -241,7 +241,7 @@
             that they user <emphasis>always</emphasis> ends up at this page (regardless of whether
             the login was "on-demand" or they explicitly chose to log in) by setting the
               <literal>always-use-default-target</literal> attribute to "true". This is useful if
-            your application always requires that the user starts at a "home" page, for example: <programlisting><![CDATA[
+            your application always requires that the user starts at a "home" page, for example: <programlisting language="xml"><![CDATA[
   <http>
     <intercept-url pattern='/login.htm*' filters='none'/>  
     <intercept-url pattern='/**' access='ROLE_USER' />
@@ -260,10 +260,10 @@
         dealt with in the <link xlink:href="#ldap">LDAP chapter</link>, so we won't cover it here.
         If you have a custom implementation of Spring Security's
           <classname>UserDetailsService</classname>, called "myUserDetailsService" in your
-        application context, then you can authenticate against this using <programlisting><![CDATA[
+        application context, then you can authenticate against this using <programlisting language="xml"><![CDATA[
   <authentication-provider user-service-ref='myUserDetailsService'/>
   ]]>
-        </programlisting> If you want to use a database, then you can use <programlisting><![CDATA[
+        </programlisting> If you want to use a database, then you can use <programlisting language="xml"><![CDATA[
   <authentication-provider>
     <jdbc-user-service data-source-ref="securityDataSource"/>
   </authentication-provider>
@@ -273,7 +273,7 @@
         containing the standard Spring Security <link xlink:href="#db_schema_users_authorities">user
           data tables</link>. Alternatively, you could configure a Spring Security
           <classname>JdbcDaoImpl</classname> bean and point at that using the
-          <literal>user-service-ref</literal> attribute: <programlisting><![CDATA[
+        <literal>user-service-ref</literal> attribute: <programlisting language="xml"><![CDATA[
   <authentication-provider user-service-ref='myUserDetailsService'/>
   
   <beans:bean id="myUserDetailsService" class="org.springframework.security.core.userdetails.jdbc.JdbcDaoImpl">
@@ -288,7 +288,7 @@
         <title>Adding a Password Encoder</title>
         <para> Often your password data will be encoded using a hashing algorithm. This is supported
           by the <literal>&lt;password-encoder&gt;</literal> element. With SHA encoded passwords,
-          the original authentication provider configuration would look like this: <programlisting><![CDATA[
+          the original authentication provider configuration would look like this: <programlisting language="xml"><![CDATA[
 <authentication-provider>
   <password-encoder hash="sha"/>
   <user-service>
@@ -325,7 +325,7 @@
       <title>Adding HTTP/HTTPS Channel Security</title>
       <para>If your application supports both HTTP and HTTPS, and you require that particular URLs
         can only be accessed over HTTPS, then this is directly supported using the
-          <literal>requires-channel</literal> attribute on <literal>&lt;intercept-url&gt;</literal>: <programlisting><![CDATA[
+        <literal>requires-channel</literal> attribute on <literal>&lt;intercept-url&gt;</literal>: <programlisting language="xml"><![CDATA[
   <http>
     <intercept-url pattern="/secure/**" access="ROLE_USER" requires-channel="https"/>
     <intercept-url pattern="/**" access="ROLE_USER" requires-channel="any"/>  
@@ -352,19 +352,19 @@
       <para> If you wish to place constraints on a single user's ability to log in to your
         application, Spring Security supports this out of the box with the following simple
         additions. First you need to add the following listener to your <filename>web.xml</filename>
-        file to keep Spring Security updated about session lifecycle events: <programlisting>        
+        file to keep Spring Security updated about session lifecycle events: <programlisting language="xml">        
           <![CDATA[         
 <listener>
   <listener-class>org.springframework.security.web.session.HttpSessionEventPublisher</listener-class>
 </listener>
-]]></programlisting> Then add the following line to your application context: <programlisting><![CDATA[     
+]]></programlisting> Then add the following line to your application context: <programlisting language="xml"><![CDATA[     
   <http>
     ...
     <concurrent-session-control max-sessions="1" />
   </http>]]>
         </programlisting> This will prevent a user from logging in multiple times - a
         second login will cause the first to be invalidated. Often you would prefer to prevent a
-        second login, in which case you can use <programlisting><![CDATA[     
+        second login, in which case you can use <programlisting language="xml"><![CDATA[     
   <http>
     ...
     <concurrent-session-control max-sessions="1" exception-if-maximum-exceeded="true"/>
@@ -376,7 +376,7 @@
     <section xml:id="ns-openid">
       <title>OpenID Login</title>
       <para>The namespace supports <link xlink:href="http://openid.net/">OpenID</link> login either
-        instead of, or in addition to normal form-based login, with a simple change: <programlisting><![CDATA[
+        instead of, or in addition to normal form-based login, with a simple change: <programlisting language="xml"><![CDATA[
   <http>
     <intercept-url pattern="/**" access="ROLE_USER" />
     <openid-login />
@@ -500,7 +500,7 @@
           </tgroup>
         </table> You can add your own filter to the stack, using the
           <literal>custom-filter</literal> element and one of these names to specify the position
-        your filter should appear at: <programlisting><![CDATA[
+        your filter should appear at: <programlisting language="xml"><![CDATA[
   <beans:bean id="myFilter" class="com.mycompany.MySpecialAuthenticationFilter">
     <custom-filter position="AUTHENTICATION_PROCESSING_FILTER"/>
   </beans:bean>
@@ -588,7 +588,7 @@
           <interfacename>AccessDecisionManager</interfacename> for it to make the actual decision.
         This example is taken from the <link xlink:href="#tutorial-sample">tutorial sample</link>,
         which is a good starting point if you want to use method security in your application:
-        <programlisting>
+        <programlisting language="java">
   public interface BankService {
   
     @Secured("IS_AUTHENTICATED_ANONYMOUSLY")
@@ -605,7 +605,7 @@
         <title>Adding Security Pointcuts using <literal>protect-pointcut</literal></title>
         <para> The use of <literal>protect-pointcut</literal> is particularly powerful, as it allows
           you to apply security to many beans with only a simple declaration. Consider the following
-          example: <programlisting><![CDATA[
+          example: <programlisting language="xml"><![CDATA[
   <global-method-security>
     <protect-pointcut expression="execution(* com.mycompany.*Service.*(..))" access="ROLE_USER"/>
   </global-method-security>
@@ -620,7 +620,7 @@
     <section xml:id="ns-intercept-methods">
       <title>The <literal>intercept-methods</literal> Bean Decorator</title>
       <para> This alternative syntax allows you to specify security for a specific bean by adding
-        this element within the bean itself. <programlisting><![CDATA[
+        this element within the bean itself. <programlisting language="xml"><![CDATA[
 <bean:bean id="target" class="com.mycompany.myapp.MyBean">
     <intercept-methods>
         <protect method="set*" access="ROLE_ADMIN" />
@@ -654,7 +654,7 @@
       <para> For method security, you do this by setting the
           <literal>access-decision-manager-ref</literal> attribute on
           <literal>global-method-security</literal>to the Id of the appropriate
-          <interfacename>AccessDecisionManager</interfacename> bean in the application context: <programlisting><![CDATA[
+        <interfacename>AccessDecisionManager</interfacename> bean in the application context: <programlisting language="xml"><![CDATA[
   <global-method-security access-decision-manager-ref="myAccessDecisionManagerBean">
     ... 
   </global-method-security>
@@ -678,7 +678,7 @@
     <para> You may want to register additional <classname>AuthenticationProvider</classname> beans
       with the <classname>ProviderManager</classname> and you can do this using the
         <literal>&lt;custom-authentication-provider&gt;</literal> element within the bean. For
-      example: <programlisting><![CDATA[
+      example: <programlisting language="xml"><![CDATA[
   <bean id="casAuthenticationProvider" 
       class="org.springframework.security.cas.authentication.CasAuthenticationProvider">
     <security:custom-authentication-provider />
@@ -688,7 +688,7 @@
     <para> Another common requirement is that another bean in the context may require a reference to
       the <interfacename>AuthenticationManager</interfacename>. There is a special element which
       lets you register an alias for the <interfacename>AuthenticationManager</interfacename> and
-      you can then use this name elsewhere in your application context. <programlisting><![CDATA[        
+      you can then use this name elsewhere in your application context. <programlisting language="xml"><![CDATA[        
   <security:authentication-manager alias="authenticationManager"/>
 
   <bean id="customizedFormLoginFilter" class="org.springframework.security.web.authentication.UsernamePasswordAuthenticationProcessingFilter">

docs/manual/src/docbook/pdf-titlepage.xml

@@ -0,0 +1,101 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements.  See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership.  The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License.  You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied.  See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<!DOCTYPE t:templates [
+<!ENTITY hsize0 "10pt">
+<!ENTITY hsize1 "12pt">
+<!ENTITY hsize2 "14.4pt">
+<!ENTITY hsize3 "17.28pt">
+<!ENTITY hsize4 "20.736pt">
+<!ENTITY hsize5 "24.8832pt">
+<!ENTITY hsize0space "7.5pt"> <!-- 0.75 * hsize0 -->
+<!ENTITY hsize1space "9pt"> <!-- 0.75 * hsize1 -->
+<!ENTITY hsize2space "10.8pt"> <!-- 0.75 * hsize2 -->
+<!ENTITY hsize3space "12.96pt"> <!-- 0.75 * hsize3 -->
+<!ENTITY hsize4space "15.552pt"> <!-- 0.75 * hsize4 -->
+<!ENTITY hsize5space "18.6624pt"> <!-- 0.75 * hsize5 -->
+]>
+<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0"
+             xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param"
+             xmlns:fo="http://www.w3.org/1999/XSL/Format"
+             xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+
+  <t:titlepage t:element="book" t:wrapper="fo:block">
+    <t:titlepage-content t:side="recto">
+    	<title
+             t:named-template="division.title"
+             param:node="ancestor-or-self::book[1]"
+             text-align="center"
+             font-size="&hsize5;"
+             space-before="&hsize5space;"
+             font-weight="bold"
+             font-family="{$title.fontset}"
+		/>
+      	<subtitle
+                text-align="center"
+                font-size="&hsize4;"
+                space-before="&hsize4space;"
+                font-family="{$title.fontset}"
+		/>
+
+      	<corpauthor space-before="0.5em"
+                  font-size="&hsize2;"
+		/>
+      	
+		<authorgroup space-before="0.5em"
+                   font-size="&hsize2;"
+		/>
+      	
+		<author space-before="0.5em" font-size="&hsize2;"/>
+    	<mediaobject space-before="2em" space-after="2em"/>   
+    	<releaseinfo space-before="5em" font-size="&hsize2;"/>
+
+    	<othercredit space-before="2em" font-weight="normal" font-size="8"/>
+    	<pubdate space-before="0.5em"/>
+    	<revision space-before="0.5em"/>
+    	<revhistory space-before="0.5em"/>
+    	
+		<abstract space-before="0.5em"
+                  text-align="start"
+                  margin-left="0.1in"
+                  margin-right="0.1in"
+                  font-family="{$body.fontset}"
+		/>
+  	</t:titlepage-content>
+
+    <t:titlepage-content t:side="verso" text-align="start">
+    	<copyright space-before="1.5em"/>
+    	<legalnotice space-before="15em"/>    
+	</t:titlepage-content>
+
+    <t:titlepage-separator>
+    </t:titlepage-separator>
+
+    <t:titlepage-before t:side="recto">
+    </t:titlepage-before>
+
+    <t:titlepage-before t:side="verso">
+    </t:titlepage-before>
+  </t:titlepage>
+
+<!-- ==================================================================== -->
+
+</t:templates>

src/docbkx/technical-overview.xml → docs/manual/src/docbook/technical-overview.xml

@@ -8,11 +8,8 @@
       <title>Runtime Environment</title>
     </info>
 
-    <para>Spring Security is written to execute within a standard Java 1.4
-    Runtime Environment. It also supports Java 5.0, although the Java
-    types which are specific to this release are packaged in a separate
-    package with the suffix "tiger" in their JAR filename. As Spring
-    Security aims to operate in a self-contained manner, there is no need
+    <para>Spring Security 3.0 requires a Java 5.0 Runtime Environment or higher.
+      As Spring Security aims to operate in a self-contained manner, there is no need
     to place any special configuration files into your Java Runtime
     Environment. In particular, there is no need to configure a special
     Java Authentication and Authorization Service (JAAS) policy file or
@@ -20,7 +17,8 @@
 
     <para>Similarly, if you are using an EJB Container or Servlet
     Container there is no need to put any special configuration files
-    anywhere, nor include Spring Security in a server classloader.</para>
+    anywhere, nor include Spring Security in a server classloader. All the required
+    files will be contained within your application.</para>
 
     <para>This design offers maximum deployment time flexibility, as
     you can simply copy your target artifact (be it a JAR, WAR or EAR)
@@ -184,23 +182,32 @@ if (obj instanceof UserDetails) {
     authenticate a user). Of course, Spring Security is expressly designed
     to handle this common requirement, but you'd instead use the project's
     domain object security capabilities for this purpose.</para>
-
-    <para>Last but not least, sometimes you will need to store the
-    <interfacename>SecurityContext</interfacename> between HTTP requests. Other times
-    the principal will re-authenticate on every request, although most of
-    the time it will be stored. The
-    <classname>HttpSessionContextIntegrationFilter</classname> is responsible
-    for storing a <interfacename>SecurityContext</interfacename> between HTTP
-    requests. As suggested by the name of the class, the
-    <literal>HttpSession</literal> is used to store this information. You
-    should never interact directly with the <literal>HttpSession</literal>
-    for security purposes. There is simply no justification for doing so -
-    always use the <classname>SecurityContextHolder</classname>
-    instead.</para>
-      
     </section>
     
-    
+    <section xml:id="tech-sec-context-persistence">
+      <title>Storing the <interfacename>SecurityContext</interfacename></title>
+      <para>Last but not least, depending on the type of application, there may need to be
+        a strategy in place to store the security context between user operations. 
+        In a typical web application, for example, a user logs in once and is subsequently identified
+        by their session Id. The server caches the principal information for the duration session.
+        In Spring Security, the responsibility for storing the <interfacename>SecurityContext</interfacename>
+        between requests falls to the <classname>SecurityContextPersistenceFilter</classname>, which
+        by default stores the context as an <literal>HttpSession</literal> attribute between HTTP
+        requests. It restores the context to the <classname>SecurityContextHolder</classname> for each request
+        and, crucially, clears the <classname>SecurityContextHolder</classname> when the request completes.
+        You should never interact directly with the <literal>HttpSession</literal> for security purposes. 
+        There is simply no justification for doing so - always use the <classname>SecurityContextHolder</classname> 
+        instead.
+      </para>
+      <para>
+        Many other types of application (for example, a stateless RESTful web service) do not use HTTP sessions and
+        will re-authenticate on every request. However, it is still important that the
+        <classname>SecurityContextPersistenceFilter</classname> is included in the
+        chain to make sure that the <classname>SecurityContextHolder</classname> is cleared after each request,
+        even if 
+      </para>
+    </section>
+        
     <section>
       <title>Summary</title>
     <para>Just to recap, the major building blocks of Spring Security
@@ -219,9 +226,9 @@ if (obj instanceof UserDetails) {
       </listitem>
 
       <listitem>
-        <para><classname>HttpSessionContextIntegrationFilter</classname>, to
-        store the <interfacename>SecurityContext</interfacename> in the
-        <literal>HttpSession</literal> between web requests.</para>
+        <para><classname>SecurityContextPersistenceFilter</classname>, to
+        store the <interfacename>SecurityContext</interfacename> (typically in the
+        <literal>HttpSession</literal>) between web requests.</para>
       </listitem>
 
       <listitem>
@@ -562,18 +569,18 @@ if (obj instanceof UserDetails) {
 
     <section>
       <title>Extending the Secure Object Model</title>
-    <para>Only developers contemplating an entirely new way of
-    intercepting and authorizing requests would need to use secure objects
-    directly. For example, it would be possible to build a new secure
-    object to secure calls to a messaging system. Anything that requires
-    security and also provides a way of intercepting a call (like the AOP
-    around advice semantics) is capable of being made into a secure
-    object. Having said that, most Spring applications will simply use the
-    three currently supported secure object types (AOP Alliance
-    <classname>MethodInvocation</classname>, AspectJ
-    <literal>JoinPoint</literal> and web request
-    <classname>FilterInvocation</classname>) with complete
-    transparency.</para>
+      <para>Only developers contemplating an entirely new way of
+      intercepting and authorizing requests would need to use secure objects
+      directly. For example, it would be possible to build a new secure
+      object to secure calls to a messaging system. Anything that requires
+      security and also provides a way of intercepting a call (like the AOP
+      around advice semantics) is capable of being made into a secure
+      object. Having said that, most Spring applications will simply use the
+      three currently supported secure object types (AOP Alliance
+      <classname>MethodInvocation</classname>, AspectJ
+      <literal>JoinPoint</literal> and web request
+      <classname>FilterInvocation</classname>) with complete
+      transparency.</para>
     </section>
   </section>
   </section>

pom.xml

@@ -431,65 +431,6 @@
                     </dependenciesAsLibraries>
                 </configuration>
             </plugin>
-            <!-- Site -->
-            <plugin>
-                <groupId>org.apache.maven.plugins</groupId>
-                <artifactId>maven-site-plugin</artifactId>
-                <version>2.0</version>
-            </plugin>
-
-            <plugin>
-                <groupId>com.agilejava.docbkx</groupId>
-                <artifactId>docbkx-maven-plugin</artifactId>
-                <version>2.0.7</version>
-                <executions>
-                    <execution>
-                        <goals>
-                            <goal>generate-html</goal>
-                            <goal>generate-pdf</goal>
-                        </goals>
-                        <phase>pre-site</phase>
-                    </execution>
-                </executions>
-                <dependencies>
-                    <dependency>
-                        <groupId>org.docbook</groupId>
-                        <artifactId>docbook-xml</artifactId>
-                        <version>4.4</version>
-                        <scope>runtime</scope>
-                    </dependency>
-                </dependencies>
-                <configuration>
-                    <includes>springsecurity.xml</includes>
-                    <chunkedOutput>true</chunkedOutput>
-                    <htmlStylesheet>css/html.css</htmlStylesheet>
-                    <xincludeSupported>true</xincludeSupported>
-                    <htmlCustomization>src/docbkx/resources/xsl/html_chunk.xsl</htmlCustomization>
-                    <foCustomization>src/docbkx/resources/xsl/fopdf.xsl</foCustomization>
-                    <entities>
-                        <entity>
-                            <name>version</name>
-                            <value>${pom.version}</value>
-                        </entity>
-                    </entities>
-                    <postProcess>
-                        <copy todir="target/site/reference">
-                            <fileset dir="target/docbkx">
-                                <include name="**/*.html" />
-                                <include name="**/*.pdf" />
-                            </fileset>
-                        </copy>
-                        <copy todir="target/site/reference/html">
-                            <fileset dir="src/docbkx/resources">
-                                <include name="**/*.css" />
-                                <include name="**/*.png" />
-                                <include name="**/*.gif" />
-                                <include name="**/*.jpg" />
-                            </fileset>
-                        </copy>
-                    </postProcess>
-                </configuration>
-            </plugin>
         </plugins>
     </build>
 
@@ -825,10 +766,7 @@
     <properties>
         <spring.version>3.0.0.M3</spring.version>
         <jstl.version>1.1.2</jstl.version>
-        <jetty.version>6.1.15</jetty.version>
-
-        <docbook.source>${basedir}/src/docbkx</docbook.source>
-        <docbook.target>${basedir}/target/site/guide</docbook.target>
+        <jetty.version>6.1.18</jetty.version>
     </properties>
 
 </project>

src/docbkx/resources/xsl/html.xsl

@@ -7,7 +7,7 @@
                 xmlns:fo="http://www.w3.org/1999/XSL/Format"
                 version="1.0">
 
-    <xsl:import href="urn:docbkx:stylesheet"/>
+    <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/>
 
     <!--###################################################
                     HTML Settings
@@ -70,6 +70,7 @@
         table before
         procedure before
     </xsl:param>
+<!--    
     <xsl:template match="author" mode="titlepage.mode">
         <xsl:if test="name(preceding-sibling::*[1]) = 'author'">
             <xsl:text>, </xsl:text>
@@ -80,6 +81,7 @@
             <xsl:apply-templates mode="titlepage.mode" select="./affiliation"/>
         </span>
     </xsl:template>
+   
     <xsl:template match="authorgroup" mode="titlepage.mode">
         <div class="{name(.)}">
             <h2>Authors</h2>
@@ -87,5 +89,5 @@
             <xsl:apply-templates mode="titlepage.mode"/>
         </div>
     </xsl:template>
-
+--> 
 </xsl:stylesheet>

src/site/fml/faq.fml

@@ -8,28 +8,28 @@
     <faq id="other-concerns">
     	<question>Will Spring Security take care of all my application security requirements?</question>
     	<answer>
-    		<p>Spring Security provides you with a very flexible framework for
+    		<para>Spring Security provides you with a very flexible framework for
     			your authentication and authorization requirements, but there are many other considerations
     			for building a secure application that are outside its scope. Web applications are
     			vulnerable to all kinds of attacks which you should be familiar with, preferably before you 
     			start development so you can design and code with them in mind from the beginning. 
-    			Check out the <a href="http://www.owasp.org/">OWASP web site</a>
+    			Check out the <link xlink:href="http://www.owasp.org/">OWASP web site</link>
     			for information on the major issues facing web application developers and the countermeasures
     			you can use against them.
-    		</p>
+    		</para>
     	</answer>
     </faq>
     <faq id="web-xml">
 	    <question>Why not just use web.xml security?</question>
 	    <answer>
 	    
-	    <p>Let's assume you're developing an enterprise application based on Spring.
+	    <para>Let's assume you're developing an enterprise application based on Spring.
 		There are four security concerns you typically need to address: authentication,
 		web request security, service layer security (i.e. your methods that implement
 		business logic), and domain object instance security (i.e. different domain objects
 		have different permissions). With these typical requirements in mind:
-		<ol>
-			<li><b>Authentication</b>: The servlet specification provides an approach
+		<orderedlist>
+			<listitem><para><b>Authentication</b>: The servlet specification provides an approach
 				to authentication. However, you will need to configure the container
 				to perform authentication which typically requires editing of
 				container-specific "realm" settings. This makes a non-portable
@@ -40,8 +40,8 @@
 				authentication providers and mechanisms, meaning you can switch your
 				authentication approaches at deployment time. This is particularly
 				valuable for software vendors writing products that need to work in
-				an unknown target environment.<br></br><br></br></li>
-			<li><b>Web request security:</b> The servlet specification provides an
+				an unknown target environment.</para></listitem>
+			<listitem><para><b>Web request security:</b> The servlet specification provides an
 				approach to secure your request URIs. However, these URIs can only be
 				expressed in the servlet specification's own limited URI path format.
 				Spring Security provides a far more comprehensive approach. For instance,
@@ -49,29 +49,29 @@
 				URI other than simply the requested page (eg you can consider HTTP GET
 				parameters), and you can implement your own runtime source of configuration
 				data. This means your web request security can be dynamically changed during
-				the actual execution of your webapp.<br></br><br></br></li>
-			<li><b>Service layer and domain object security:</b> The absence of support
+				the actual execution of your webapp.</para></listitem>
+			<listitem><para><b>Service layer and domain object security:</b> The absence of support
 				in the servlet specification for services layer security or domain object
 				instance security represent serious limitations for multi-tiered
 				applications. Typically developers either ignore these requirements, or
 				implement security logic within their MVC controller code (or even worse,
 				inside the views). There are serious disadvantages with this approach:<br/><br/>
-					<ol>
-						<li><i>Separation of concerns:</i> Authorization is a
+					<orderedlist>
+						<listitem><para><i>Separation of concerns:</i> Authorization is a
 							crosscutting concern and should be implemented as such.
 							MVC controllers or views implementing authorization code
 							makes it more difficult to test both the controller and
 							authorization logic, more difficult to debug, and will
-							often lead to code duplication.</li>
-						<li><i>Support for rich clients and web services:</i> If an
+							often lead to code duplication.</para></listitem>
+						<listitem><para><i>Support for rich clients and web services:</i> If an
 							additional client type must ultimately be supported, any
 							authorization code embedded within the web layer is
 							non-reusable. It should be considered that Spring remoting
 							exporters only export service layer beans (not MVC
 							controllers). As such authorization logic needs to be
 							located in the services layer to support a multitude of
-							client types.</li>
-						<li><i>Layering issues:</i> An MVC controller or view is simply
+							client types.</para></listitem>
+						<listitem><para><i>Layering issues:</i> An MVC controller or view is simply
 							the incorrect architectural layer to implement authorization
 							decisions concerning services layer methods or domain object
 							instances. Whilst the Principal may be passed to the services
@@ -81,8 +81,8 @@
 							to hold the Principal, although this would likely increase
 							development time to a point where it would become more
 							economical (on a cost-benefit basis) to simply use a dedicated
-							security framework.</li>
-						<li><i>Authorisation code quality:</i> It is often said of web
+							security framework.</para></listitem>
+						<listitem><para><i>Authorisation code quality:</i> It is often said of web
 							frameworks that they "make it easier to do the right things,
 							and harder to do the wrong things". Security frameworks are
 							the same, because they are designed in an abstract manner for
@@ -91,17 +91,17 @@
 							would offer, and in-house authorization code will typically
 							lack the improvements that emerge from widespread deployment,
 							peer review and new versions.
-					</li></ol>
-					</li>
-		</ol>
-		</p>
-		<p>
+					</para></listitem></orderedlist>
+					</para></listitem>
+		</orderedlist>
+		</para>
+		<para>
 		For simple applications, servlet specification security may just be enough.
 		Although when considered within the context of web container portability,
 		configuration requirements, limited web request security flexibility, and
 		non-existent services layer and domain object instance security, it becomes
 		clear why developers often look to alternative solutions.
-		</p>            
+		</para>            
 		</answer>
 		
     </faq>
@@ -118,24 +118,24 @@
      	<title>Common Problems</title>
  	    <faq id="login-loop">
  	    	<question>My application goes into an "endless loop" when I try to login, what's going on?</question>
- 	    	<answer><p>A common user problem with infinite loop and redirecting to the login page is caused 
+ 	    	<answer><para>A common user problem with infinite loop and redirecting to the login page is caused 
  	    		by accidently configuring the login page as a "secured" resource. Make sure your configuration
  	    		allows anonymous access to the login page, either by excluding it from the security filter
- 	    		chain or marking it as requiring ROLE_ANONYMOUS.</p>
- 	    		<p>If your AccessDecisionManager includes an AutheticatedVoter, you can use the attribute
+ 	    		chain or marking it as requiring ROLE_ANONYMOUS.</para>
+ 	    		<para>If your AccessDecisionManager includes an AutheticatedVoter, you can use the attribute
  	    			"IS_AUTHENTICATED_ANONYMOUSLY". This is automatically available if you are using the
  	    			standard namespace configuration setup.
- 	    		</p>
- 	    		<p>
+ 	    		</para>
+ 	    		<para>
  	    			From Spring Security 2.0.1 onwards, when you are using namespace-based configuration, a check will be made 
  	    			on loading the application context and a warning message logged if your login page appears to be protected.
- 	    		</p>
+ 	    		</para>
  	    	</answer>
  	    </faq>
     	<faq id="anon-access-denied">
     		<question>I get an exception with the message "Access is denied (user is anonymous);". What's wrong?</question>
     		<answer>
-    			<p>
+    			<para>
     			This is a debug level message which occurs the first time an anonymous user attempts to access a protected
     			resource.
     			<pre>
@@ -145,13 +145,13 @@ org.springframework.security.AccessDeniedException: Access is denied
     at org.springframework.security.intercept.AbstractSecurityInterceptor.beforeInvocation(AbstractSecurityInterceptor.java:262)    				
     			</pre>
     				It is normal and shouldn't be anything to worry about.
-    			</p>
+    			</para>
     		</answer>
     	</faq>
     	<faq id="auth-exception-credentials-not-found">
     		<question>I get an exception with the message "An Authentication object was not found in the SecurityContext". What's wrong?</question>
     		<answer>
-    			<p>
+    			<para>
     				This is a another debug level message which occurs the first time an anonymous user attempts to access a protected
     				resource, but when you do not have an AnonymousProcessingFilter in your filter chain configuration.
     				<pre>
@@ -161,7 +161,7 @@ org.springframework.security.AccessDeniedException: Access is denied
     					at org.springframework.security.intercept.AbstractSecurityInterceptor.beforeInvocation(AbstractSecurityInterceptor.java:254)
     				</pre>
     				It is normal and shouldn't be anything to worry about.
-    			</p>
+    			</para>
     		</answer>
     	</faq>    	
     	<faq id="tomcat-https-session">
@@ -170,10 +170,10 @@ org.springframework.security.AccessDeniedException: Access is denied
     			end up back at the login page after authenticating.
     		</question>
     		<answer>
-    			<p>
+    			<para>
     			This happens because Tomcat sessions created under HTTPS cannot subsequently be used under HTTP and any session state is lost (including 
     			the security context information). Starting in HTTP first should work.
-    			</p>
+    			</para>
     		</answer>
     	</faq>
     	<faq id="no-security-on-forward">
@@ -205,34 +205,34 @@ org.springframework.security.AccessDeniedException: Access is denied
 	  	<faq id="extra-login-fields">
 	  		<question>I need to login in with more information than just the username. How do I add support for extra login fields (e.g. a company name)?</question>
 	  		<answer>
-	  			<p>This question comes up repeatedly in the Spring Security forum so you will find more information there by searching the archives (or through google).</p>
-	  			<p>
+	  			<para>This question comes up repeatedly in the Spring Security forum so you will find more information there by searching the archives (or through google).</para>
+	  			<para>
 	  			The submitted login information is processed by an instance of <i>AuthenticationProcessingFilter</i>. You will need to customize this class to handle
 	  				the extra data field(s). One option is to use your own customized authentication token class (rather than the standard <i>UsernamePasswordAuthenticationToken</i>),
 	  				another is simply to concatenate the extra fields with the username (for example, using a ":" as the separator) and pass them in the username property of
 	  				<i>UsernamePasswordAuthenticationToken</i>.
-	  			</p>
-	  			<p>
+	  			</para>
+	  			<para>
 	  				You will also need to customize the actual authentication process. If you are using a custom authentication token class, for example, you will have to write an 
 	  				<i>AuthenticationProvider</i> to handle it (or extend the standard <i>DaoAuthenticationProvider</i>). 
 	  			  If you have concatenated the fields, you can implement your own <i>UserDetailsService</i> which splits them up and loads the appropriate user data for
 	  				authentication.
-	  			</p>
+	  			</para>
 	  		</answer>
 	  	</faq>
 	  	<faq id="what-dependencies">
 	  		<question>How do I know what dependencies to add to my application to work with Spring Security?</question>
 	  		<answer>
-	  			<p>
+	  			<para>
 	  				There is no definite answer here, (it will depend on what features you are using), but a good starting point is to copy those from one of the 
 	  				pre-built sample applications WEB-INF/lib directories. For a basic application, you can start with the tutorial sample. If you want to 
 	  				use LDAP, with an embedded test server, then use the LDAP sample as a starting point.
-	  			</p>
-	  			<p>
+	  			</para>
+	  			<para>
 	  				If you are building your project with maven, then adding the appropriate Spring Security modules to your pom.xml will automatically pull in
 	  				the core jars that the framework requires. Any which are marked as "optional" in the Spring Security POM files will have to be added 
 	  				to your own pom.xml file if you need them.
-	  			</p>
+	  			</para>
 	  		</answer>
 	  	</faq>
 	  </part>