ZOOKEEPER-2690: Update documentation source for ZOOKEEPER-2574

ZOOKEEPER-2690: Update documentation source for ZOOKEEPER-2574

Added the documentation changes from PR #111 to the source (zookeeperAdmin.xml) and generated the new version of the html and pdf documents.

Note: I have not updated the 2nd paragraph from ZOOKEEPER-2574 as change "ZOOKEEPER-2349: Update documentation for snapCount" has a more recent version of that part of the text. (ZOOKEEPER-2349 was committed on Sep 11, 2017 while ZOOKEEPER-2574 was committed on Jan 23, 2017.)

Author: Mark Fenes <mfenes@cloudera.com>

Reviewers: phunt@apache.org

Closes #406 from mfenes/ZOOKEEPER-2690_master and squashes the following commits:

ba933658 [Mark Fenes] ZOOKEEPER-2690: Update documentation source for ZOOKEEPER-2574
b152f04d [Mark Fenes] ZOOKEEPER-2690: Update documentation source for ZOOKEEPER-2574

Change-Id: Ibfda946d7b25230308086969011fb2ecb10128d2

docs/zookeeperAdmin.html

@@ -956,10 +956,14 @@ server.3=zoo3:2888:3888</pre>
           of the znodes stored by a particular serving ensemble. These
           are the snapshot and transactional log files. As changes are
           made to the znodes these changes are appended to a
-          transaction log, occasionally, when a log grows large, a
+          transaction log. Occasionally, when a log grows large, a
           snapshot of the current state of all znodes will be written
-          to the filesystem. This snapshot supersedes all previous
-          logs.
+          to the filesystem and a new transaction log file is created
+          for future transactions. During snapshotting, ZooKeeper may
+          continue appending incoming transactions to the old log file.
+          Therefore, some transactions which are newer than a snapshot
+          may be found in the last transaction log preceding the
+          snapshot.
         </p>
 <p>A ZooKeeper server <strong>will not remove
         old snapshots and log files</strong> when using the default
@@ -2468,8 +2472,11 @@ server.3=zoo3:2888:3888</pre>
 <p>The Log Directory contains the ZooKeeper transaction logs.
         Before any update takes place, ZooKeeper ensures that the transaction
         that represents the update is written to non-volatile storage. A new
-        log file is started each time a snapshot is begun. The log file's
-        suffix is the first zxid written to that log.</p>
+        log file is started when the number of transactions written to the
+        current log file reaches a (variable) threshold. The threshold is
+        computed using the same parameter which influences the frequency of
+        snapshotting (see snapCount above). The log file's suffix is the first
+        zxid written to that log.</p>
 <a name="sc_filemanagement"></a>
 <h4>File Management</h4>
 <p>The format of snapshot and log files does not change between
@@ -2484,8 +2491,12 @@ server.3=zoo3:2888:3888</pre>
 <p>The ZooKeeper server creates snapshot and log files, but
         never deletes them. The retention policy of the data and log
         files is implemented outside of the ZooKeeper server. The
-        server itself only needs the latest complete fuzzy snapshot
-        and the log files from the start of that snapshot. See the
+        server itself only needs the latest complete fuzzy snapshot, all log
+        files following it, and the last log file preceding it.  The latter
+        requirement is necessary to include updates which happened after this
+        snapshot was started but went into the existing log file at that time.
+        This is possible because snapshotting and rolling over of logs
+        proceed somewhat independently in ZooKeeper. See the
         <a href="#sc_maintenance">maintenance</a> section in
         this document for more details on setting a retention policy
         and maintenance of ZooKeeper storage.

src/docs/src/documentation/content/xdocs/zookeeperAdmin.xml

@@ -522,10 +522,14 @@ server.3=zoo3:2888:3888</programlisting>
           of the znodes stored by a particular serving ensemble. These
           are the snapshot and transactional log files. As changes are
           made to the znodes these changes are appended to a
-          transaction log, occasionally, when a log grows large, a
+          transaction log. Occasionally, when a log grows large, a
           snapshot of the current state of all znodes will be written
-          to the filesystem. This snapshot supersedes all previous
-          logs.
+          to the filesystem and a new transaction log file is created
+          for future transactions. During snapshotting, ZooKeeper may
+          continue appending incoming transactions to the old log file.
+          Therefore, some transactions which are newer than a snapshot
+          may be found in the last transaction log preceding the
+          snapshot.
         </para>
 
         <para>A ZooKeeper server <emphasis role="bold">will not remove
@@ -2113,8 +2117,11 @@ server.3=zoo3:2888:3888</programlisting>
         <para>The Log Directory contains the ZooKeeper transaction logs.
         Before any update takes place, ZooKeeper ensures that the transaction
         that represents the update is written to non-volatile storage. A new
-        log file is started each time a snapshot is begun. The log file's
-        suffix is the first zxid written to that log.</para>
+        log file is started when the number of transactions written to the
+        current log file reaches a (variable) threshold. The threshold is
+        computed using the same parameter which influences the frequency of
+        snapshotting (see snapCount above). The log file's suffix is the first
+        zxid written to that log.</para>
       </section>
 
       <section id="sc_filemanagement">
@@ -2134,8 +2141,12 @@ server.3=zoo3:2888:3888</programlisting>
         <para>The ZooKeeper server creates snapshot and log files, but
         never deletes them. The retention policy of the data and log
         files is implemented outside of the ZooKeeper server. The
-        server itself only needs the latest complete fuzzy snapshot
-        and the log files from the start of that snapshot. See the
+        server itself only needs the latest complete fuzzy snapshot, all log
+        files following it, and the last log file preceding it.  The latter
+        requirement is necessary to include updates which happened after this
+        snapshot was started but went into the existing log file at that time.
+        This is possible because snapshotting and rolling over of logs
+        proceed somewhat independently in ZooKeeper. See the
         <ulink url="#sc_maintenance">maintenance</ulink> section in
         this document for more details on setting a retention policy
         and maintenance of ZooKeeper storage.