Improve docs for StoreConfig Lifecycle Listener

Author: dsoumis

webapps/docs/config/listeners.xml

@@ -509,10 +509,23 @@
 
   <subsection name="StoreConfig Lifecycle Listener - org.apache.catalina.storeconfig.StoreConfigLifecycleListener">
 
-    <p>The <strong>StoreConfig Lifecycle Listener</strong> configures a
-    StoreConfig MBean that may be used to save the current server configuration
-    in server.xml or the current configuration for a web application in a
-    context.xml file.</p>
+    <p>The <strong>StoreConfig Lifecycle Listener</strong> enables persisting
+      runtime configuration changes. When Tomcat's configuration is
+      modified at runtime, for example, adding or removing a virtual host
+      through the Host Manager, those changes only exist in memory and are lost
+      on restart. This listener provides the ability to write the current
+      in-memory configuration to <code>server.xml</code> (or an individual web
+      application's <code>context.xml</code>), so that runtime changes are
+      preserved across restarts.</p>
+
+    <p>When this listener is enabled, configuration persistence can be
+      triggered through the
+      <a href="../host-manager-howto.html#Persist_command">Host Manager</a> and
+      <a href="../manager-howto.html#Save_Configuration">Manager</a> applications.
+      The listener compares the current configuration against
+      default values and only writes attributes that differ from the defaults.
+      Before overwriting <code>server.xml</code>, a backup of the existing file
+      is created.</p>
 
     <p>This listener must only be nested within <a href="server.html">Server</a>
     elements.</p>
@@ -523,16 +536,18 @@
     <attributes>
 
       <attribute name="storeConfigClass" required="false">
-        <p>The name of the <code>IStoreConfig</code> implementation to use. If
+        <p>The name of the <code>IStoreConfig</code> implementation to use.
+        This is an extension point for custom implementations. If
         not specified the default of
         <code>org.apache.catalina.storeconfig.StoreConfig</code> will be
         used.</p>
       </attribute>
 
       <attribute name="storeRegistry" required="false">
-        <p>The URL of the configuration file that configures how the
-        <code>IStoreConfig</code> is to save the configuration. If not specified
-        the built in resource
+        <p>The URL of the configuration file that defines how each server
+          component type (connectors, hosts, realms, valves, etc.) should be
+          serialized to XML. This is an extension point for custom serialization
+          rules. If not specified the built in resource
         <code>/org/apache/catalina/storeconfig/server-registry.xml</code> will
         be used.</p>
       </attribute>