Merge lp:~pbeaman/akiban-persistit/fix_doc_20120611 into lp:akiban-persistit

[Peter Beaman]

Fixes typos, grammar and formatting issues noted in

https://docs.google.com/a/akiban.com/document/d/1MPmUVtB-81mqJzu6_4BRw8FJ7iXFAJV_rFldjIjn2nw/edit

on 6/8/2012. No code other than SphinxDocPrep is modified.

[Nathan Williams (nwilliams)]

Skimmed doc changes (looks good) and no code changes so sending through.

review: Approve

=== modified file 'doc/BasicAPI.rst'
--- doc/BasicAPI.rst	2012-05-31 18:51:41 +0000
+++ doc/BasicAPI.rst	2012-06-11 21:28:19 +0000
@@ -3,7 +3,7 @@
 Basic API
 =========
 
-Akiban Persistit stores data as key-value pairs in highly optimized B+Tree. (Actually, implements `B-Link Tree <http://www.cs.cornell.edu/courses/cs4411/2009sp/blink.pdf>`_ trees for greater concurrency). Like a Java Map implementation, Persistit associates at most one value with each unique instance of a Key value.
+Akiban Persistit stores data as key-value pairs in highly optimized B+Tree. (Actually, Akiban Persistit implements `B-Link Tree <http://www.cs.cornell.edu/courses/cs4411/2009sp/blink.pdf>`_ architecture for greater concurrency). Like a Java Map implementation, Persistit associates at most one value with each unique instance of a Key value.
 
 Persistit provides classes and methods to access and modify keys and their associated values. Application code calls Persistit API methods to store, fetch, traverse and remove keys and records to and from the database.
 
@@ -170,7 +170,7 @@
 
 The primary low-level interface for interacting with Persistit is ``com.persistit.Exchange``. The Exchange class provides all methods for storing, deleting, fetching and traversing key/value pairs. These methods are summarized here and described in detail in the Javadoc API documentation.
 
-An Exchange instance contains references to a ``Key`` and a ``Value``. The methods ``com.persistit.Exchange.getKey()`` and ``com.persistit.Exchange.getValue()`` access these instances.
+An Exchange instance contains references to a ``Key`` and a ``Value``. The methods ``com.persistit.Exchange#getKey()`` and ``com.persistit.Exchange#getValue()`` access these instances.
 
 To construct an Exchange you specify a Volume (or alias) and a tree name in its constructor. The constructor will optionally create a new tree in that Volume if a tree having the specified name has not already been created. An application may construct an arbitrary number of Exchange objects. Creating a new Exchange has no effect on the database if the specified tree already exists. Tree creation is thread-safe: multiple threads concurrently constructing Exchanges using the same Tree name will safely result in the creation of only one new tree.
 
@@ -183,7 +183,7 @@
 Concurrent Operations on Exchanges
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Although the underlying Persistit database is designed for highly concurrent multi-threaded operation, the ``Exchange`` class and its associated ``Key`` and ``Value`` instances are *not* thread-safe. Each thread should acquire and use its own Exchange objects when accessing the database. Nonetheless, multiple threads can execute database operations on overlapping data concurrently using their thread-private ``Exchange`` instances.
+Although the underlying Persistit database is designed for highly concurrent multi-threaded operation, the ``Exchange`` class and its associated ``Key`` and ``Value`` instances are *not* thread-safe. Each thread should acquire and use its own Exchange object when accessing the database. Nonetheless, multiple threads can execute database operations on overlapping data concurrently using their thread-private ``Exchange`` instances.
 
 Because Persistit permits concurrent operations by multiple threads, there is no guarantee that the underlying database will remain unchanged after an Exchange fetches or modifies its data. However, each operation on an Exchange is atomic, meaning that the inputs and outputs of each method are consistent with some valid state of the underlying Persistit backing store at some instant in time. The Exchange’s Value and Key objects represent that consistent state even if another thread subsequently modifies the database. Transactions, described below, allow multiple database operations to be performed atomically and consistently.
 
@@ -252,7 +252,7 @@
                	dbex.getValue().get());
        	}
 
-In general, the traversal methods let you find a key in a tree related to the key you supply. In Persistit programs you frequently prime a key value by appending either ``com.persistit.Key#BEFORE`` or ``com.persistit.Key#AFTER``. A key containing either of these special values can never be stored in a tree; these are reserved to represent positions in key traversal order before the first valid key and after the last valid key, respectively. You then invoke next or previous, or any of the other traverse family variants, to enumerate keys within the tree.
+In general, the traversal methods let you find a key in a tree related to the key you supply. In Persistit programs you frequently prime a key value by appending either ``Key#BEFORE`` or ``Key#AFTER``. A key containing either of these special values can never be stored in a tree; these are reserved to represent positions in key traversal order before the first valid key and after the last valid key, respectively. You then invoke next or previous, or any of the other traverse family variants, to enumerate keys within the tree.
 
 You can specify whether traversal is *deep* or *shallow*.  Deep traversal traverses the logical children (see com.persistit.Key) of a key. Shallow traversal traverses only the logical siblings.
 
@@ -270,13 +270,13 @@
 .. code-block:: java
 
   Exchange ex = new Exchange("myVolume", "myTree", true);
-  KeyFilter kf = new KeyFilter("{\"Bellini\":\"Britten\"}");
+  KeyFilter kf = new KeyFilter("{\"Beethoven\":\"Britten\"}");
   ex.append(Key.BEFORE);
   while (ex.next(kf)){
       System.out.println(ex.getKey().reset().decodeString());
   }
 
-This simple example emits the string-valued keys within Tree “myTree” whose values fall alphabetically between “Bellini” and “Britten”, inclusive.
+This simple example emits the string-valued keys within Tree “myTree” whose values fall alphabetically between “Beethoven” and “Britten”, inclusive.
 
 
 You will find an example with a KeyFilter in the examples/FindFileDemo directory.
 
=== modified file 'doc/Configuration.rst'
--- doc/Configuration.rst	2012-05-31 18:49:39 +0000
+++ doc/Configuration.rst	2012-06-11 21:28:19 +0000
@@ -70,7 +70,7 @@
   memoryToUse = fraction * (maxHeap - reservedMemory)
   memoryToUse = min(memoryToUse, maximumMemory)
   bufferCount = memoryToUse / bufferSizeWithOverhead
-  bufferCount = max(minimumCount, min(maximumCount, count))
+  bufferCount = max(minimumCount, min(maximumCount, bufferCount))
   if (bufferCount * bufferSize > maximumMemory) then FAIL
   if ((bufferCount + 1) * bufferSize < minimumMemory) then FAIL
   allocate bufferCount buffers
@@ -214,7 +214,7 @@
       ``com.persistit.Management`` interface at the specified external registry. The ``rmihost`` and ``rmiport`` 
       properties are mutually exclusive.
 
-  ``jmx``: (``com.persistit.Configuration#setJmxEnabled``), True or false (default). 
+  ``jmx``: (``com.persistit.Configuration#setJmxEnabled``), True (default) or false. 
       Specifies whether Persistit registers MXBeans with the platform MBean server. Set this value to ``true`` to enable 
       access from ``jconsole`` and other management tools.
 
 
=== modified file 'doc/GettingStarted.rst'
--- doc/GettingStarted.rst	2012-05-31 19:16:14 +0000
+++ doc/GettingStarted.rst	2012-06-11 21:28:19 +0000
@@ -234,6 +234,7 @@
 Persistit creates one or more background threads that lazily write data to the Volume files and perform other maintenance activities. Be sure to invoke the ``com.persistit.Persistit#close`` method to allow these threads to finish their work and exit properly. The pattern illustrated in ``HelloWorld.java``, using a *try/finally* block to invoke ``close``, is strongly recommended.
 
 The ``com.persistit.Persistit#close(boolean)`` method optionally flushes all data to disk from the buffer pool before shutting down. Specifying the ``false`` option will close Persistit more quickly will lose recent updates if they were not performed inside of transactions, or will potentially require a longer recovery process during the next startup to reapply committed transactions.
+
 Additional Topics
 -----------------
 
@@ -251,7 +252,7 @@
 Transactions
 ^^^^^^^^^^^^
 
-Persistit provides ACID Transaction support with multi-version concurrency control (MCC) and adjustable durability policy.
+Persistit provides ACID Transaction support with multi-version concurrency control (MVCC) and adjustable durability policy.
 
 See :ref:`Transactions`.
 
 
=== modified file 'doc/Management.rst'
--- doc/Management.rst	2012-05-31 18:49:39 +0000
+++ doc/Management.rst	2012-06-11 21:28:19 +0000
@@ -15,30 +15,37 @@
 
 where classpath includes the Persistit ``com.persistit.ui`` package. 
 
-The JMX interface can be used by third-party management utilities, from applications such as ``jconsole`` and ``visualvm``, and from command-line JMX clients such as ``jmxterm``. To enable JMX access, the configuration must specify the property ``jmx=true``.  This causes Persistit to register several MBeans with the platform MBean server during initialization.
-
 MXBeans
 -------
+
+The JMX interface can be used by third-party management utilities, from applications such as ``jconsole`` and ``visualvm``, and from command-line JMX clients such as ``jmxterm``. To enable JMX access, the configuration must specify the property ``jmx=true``.  This causes Persistit to register several MBeans with the platform MBean server during initialization.
+
 The following JMX MXBeans are available:
 
   ``com.persistit:type=Persistit``
       See ``com.persistit.mxbeans.ManagementMXBean``
   ``com.persistit:type=Persistit,class=AlertMonitorMXBean``
+      See ``com.persistit.mxbeans.AlertMonitorMXBean``.
       Accumulates, logs and emits notifications about abnormal events such as IOExceptions and measurements outside of 
       expected thresholds.
   ``com.persistit:type=Persistit,class=CleanupManagerMXBean``
+      See ``com.persistit.mxbeans.CleanupManagerMXBean``.
       View current state of the Cleanup Manager. The Cleanup Manager performs background pruning and tree maintenance 
       activities.
   ``com.persistit:type=Persistit,class=IOMeter``
+      See ``com.persistit.mxbeans.IOMeterMXBean``.
       Maintains statistics on file system I/O operations.
   ``com.persistit.type=Persistit,class=JournalManager``
+      See ``com.persistit.mxbeans.JournalManagerMXBean``.
       Views current journal status.
   ``com.persistit.type=Persistit,class=RecoveryManager``
+      See ``com.persistit.mxbeans.RecoveryManagerMXBean``.
       Views current status of the recovery process. Attributes of this MXBean change only during the recovery process.
   ``com.persistit:type=Persistit,class=TransactionIndexMXBean``
+      See ``com.persistit.mxbeans.TransactionIndexMXBean``.
       View internal state of transaction index queues and tables.
   ``com.persistit.type=Persistit,class=BufferPool.*SSSS*``
-      where *SSSS* is a buffer size (512, 1024, 2048, 4096 or 16394). View utilization statistics for buffers of the 
+      where *SSSS* is a buffer size (512, 1024, 2048, 4096 or 16394). See ``com.persistit.mxbeans.BufferPoolMXBean``. View utilization statistics for buffers of the 
       selected size.
 
 
 
=== modified file 'doc/Miscellaneous.rst'
--- doc/Miscellaneous.rst	2012-05-30 16:25:09 +0000
+++ doc/Miscellaneous.rst	2012-06-11 21:28:19 +0000
@@ -22,9 +22,10 @@
 Logging
 -------
 
-By default Persistit emits log messages to a file called persistit.log  and also writes high level log messages to System.out.  You can change this behavior by plugging in a different logging implementation. In particular, Persistit provides pluggable adapters for various other logging implementations, including Log4J, SLF4J, and the Java logging API introduced in JDK 1.4. For details see the API documentation for com.persistit.logging.AbstractPersistitLogger.
+By default Persistit emits log messages to a file called persistit.log  and also writes high level log messages to System.out.  You can change this behavior by plugging in a different logging implementation. In particular, Persistit provides pluggable adapters for various other logging implementations, including Log4J, SLF4J, and the Java logging API introduced in JDK 1.4.
+An adapter must implement the interface ``com.persistit.logging.PersistitLogger``. For example, see source code for ``com.persistit.logging.Slf4jAdapter``.
 
-Using one of these logging frameworks is simple.  For example, the following code connects Persistit to an application-supplied SLF4J logger:
+Using one of these logging frameworks is simple. For example, the following code connects Persistit to an application-supplied SLF4J logger:
 
 .. code-block:: java
 
 
=== modified file 'doc/PhysicalStorage.rst'
--- doc/PhysicalStorage.rst	2012-05-31 18:51:41 +0000
+++ doc/PhysicalStorage.rst	2012-06-11 21:28:19 +0000
@@ -26,7 +26,7 @@
 
 The *journal* is a set of files containing variable length records. The journal is append-only. New records are written only at the end; existing records are never overwritten. The journal consists of a numbered series of files having a configurable maximum size. When a journal file becomes full Persistit closes it and begins a new file with the next counter value. The maximum size of a journal file is determined by a configuration property called its block size.  The default block size value is 1,000,000,000 bytes which works well with today’s standard server hardware.
 
-Every record in the journal has a 64-bit integer *journal address*. The journal address denotes which file contains the record and the record’s offset within that file. Journal addresses start at zero in a new database instance and grow perpetually. footnote:[Even on a system executing 1 million transactions per second the address space is large enough to last for hundreds of years.]
+Every record in the journal has a 64-bit integer *journal address*. The journal address denotes which file contains the record and the record’s offset within that file. Journal addresses start at zero in a new database instance and grow perpetually [#f1]_.
 
 Persistit writes two major types of records to journal files.
 
@@ -60,7 +60,7 @@
 Data Pages
 ^^^^^^^^^^
 
-A data page contains a representation of one or more variable-length key/value pairs. The number of key/value pairs depends on the page size, and the sizes of the serialized keys and values. The first key in each data page is stored in its entirety, while subsequent keys are stored with *prefix compression* to reduce storage footprint and accelerate searches. Therefore the storage size of the second and subsequent keys in a data page depend on how many of the leading bytes of its serialized form match its predecessor. (See :ref:`Key` and :ref:`Value` for information on how Persistit encodes logical Java values into the byte arrays stored in a data page.)
+A data page contains a representation of one or more variable-length key/value pairs. The number of key/value pairs depends on the page size, and the sizes of the serialized keys and values. The first key in each data page is stored in its entirety, while subsequent keys are stored with *prefix compression* to reduce storage footprint and accelerate searches. Therefore the storage sizes of the second and subsequent keys in a data page depend on how many of the leading bytes of their serialized form match their predecessors. (See :ref:`Key` and :ref:`Value` for information on how Persistit encodes logical Java values into the byte arrays stored in a data page.)
 
 Index Pages
 ^^^^^^^^^^^
@@ -78,13 +78,13 @@
 
 To do this, Persistit performs a process called *recovery* every time it starts up.  The recovery process is generally very fast after a normal shutdown. However, it can take a considerable amount of time after a crash because many committed transactions may need to be executed.
 
-Recovery performs two major activities:
+Recovery performs three major activities:
 
 - Restores all B+Trees to an internally consistent state with a known timestamp.
 - Replays all transaction that committed after that timestamp.
 - Prunes multi-version values belonging to certain aborted transactions (see :ref:`Pruning`).
 
-To accomplish this, Persistit writes all updates first to the :ref:`Journal`. Persistit also periodically writes *checkpoint* records to the journal. During recovery, Persistit finds the last valid checkpoint written before shutdown or crash, restores B+Trees to state consistent with that checkpoint, and then replays transactions that committed after the checkpoint.
+To accomplish this, Persistit writes all updates first to the journal. Persistit also periodically writes *checkpoint* records to the journal. During recovery, Persistit finds the last valid checkpoint written before shutdown or crash, restores B+Trees to state consistent with that checkpoint, and then replays transactions that committed after the checkpoint.
 
 Recovery depends on the availability of the volume and journal files as they existed prior to abrupt termination. If these are modified or destroyed outside of Persistit, successful recovery is unlikely.
 
@@ -111,7 +111,7 @@
 
   ``com.persistit.Persistit#flush``
       causes Persistit to write all pending updates to the journal. Upon successful completion of flush any pages that needed writing prior to the call to flush are 
-      guaranteed to have been written to their respective volume files.
+      guaranteed to have been written to the journal or their respective volume files.
   ``com.persistit.Persistit#force``
       forces the underlying operating system to write pending updates from the operating system’s write-behind cache to the actual disk. (This operation relies on 
       the underlying ``java.io.Filechannel#force(boolean)`` method.)
@@ -139,4 +139,6 @@
 
 The command-line interface (see :ref:`CLI`) includes tools you can use to examine pages in volumes and records in the journal. Two of these include the ``jview`` and ``pview`` tasks. The ``jview`` command displays journal records selected within an address range, by type, by page address, and using other selection criteria in a readable form.  The ``pview`` command displays the contents of pages selected by page address or key from a volume, or by journal address from the journal.
 
+.. rubric:: Footnotes
 
+.. [#f1] Even on a system executing 1 million transactions per second the address space is large enough to last for hundreds of years.
 
=== modified file 'doc/Security.rst'
--- doc/Security.rst	2012-05-31 18:49:39 +0000
+++ doc/Security.rst	2012-06-11 21:28:19 +0000
@@ -5,11 +5,12 @@
 
 Akiban Persistit provides no built-in data access control because it is intended for embedded use in applications that provide their own logical access control. Security-conscious applications must also prevent unauthorized access to Persistit's physical files and to the Persistit API. The following resources must be protected from unauthorized access:
 
-- Persistit volume files
+- volume and journal files
 - configuration properties file, if one is used
 - access by unauthorized code to the API exposed by the Persistit library
 - the port opened and exposed by Persistit when either the ``com.persistit.rmiport`` or ``com.persistit.rmihost`` property is set. If you are using Persistit's remote administration feature, be sure to block unauthorized access to the RMI port.
-- the :ref:`cliserver` if instantiated
+- access to MXBeans via JMX
+- the CLI server (see :ref:`cliserver`) if instantiated
 
 In addition to these general deployment considerations, Persistit requires certain permissions in an environment controlled by a security manager.
 
@@ -18,7 +19,7 @@
 Security Domains
 ----------------
 
-This section assumes a basic understanding of the Java security model. See http://download.oracle.com/javase/1.5.0/docs/guide/security/spec/security-spec.doc2.html[New Protection Mechanisms - Overview of Basic Concepts] for further information.
+This section assumes a basic understanding of the Java security model. See `New Protection Mechanisms - Overview of Basic Concepts <http://docs.oracle.com/javase/1.5.0/docs/guide/security/spec/security-spec.doc2.html>`_ for further information.
 
 Note that when Java is started from the command line, as is often the case in server applications, all security privileges are granted by default. The information in this section is intended for cases where security privileges need to be controlled.
 
 
=== modified file 'doc/Serialization.rst'
--- doc/Serialization.rst	2012-05-31 18:49:39 +0000
+++ doc/Serialization.rst	2012-06-11 21:28:19 +0000
@@ -16,7 +16,7 @@
 
 * An application can register a custom ``com.persistit.encoding.ValueCoder`` to handle serialization of a particular class
 * Default serialization using Persistit's built-in serialization mechanism described below, or
-* Standard Java serialization as described in http://download.oracle.com/javase/1.5.0/docs/guide/serialization/spec/serial-arch.html[Java Object Serialization Specification].
+* Standard Java serialization as described in `Java Object Serialization Specification <http://docs.oracle.com/javase/7/docs/platform/serialization/spec/serialTOC.html>`_.
 
 Persistit's default serialization method serializes objects into approximately 33% fewer bytes, and depending on the structure of objects being serialized, is about 40% faster than Java serialization.
 
@@ -39,7 +39,7 @@
 
 The resulting MyClass instance is a newly constructed object instance that is equivalent - subject to the accuracy of the serialization code - to the original object. This process is equivalent to the serialization and deserialization capabilities provided by java.io.ObjectOutputStream and java.io.ObjectInputStream.
 
-Persistit makes use of helper classes called “coders” to marshal data between live objects and their stored byte-array representations. Value coders, which implement ``com.persistit.encoding.ValueCoder``, marshal data to and from Value objects; ``com.persistit.encoding.KeyCoder`` implementations do the same for ``com.persistit.Key``s. A value coder provides capability somewhat like the custom serialization logic implemented through ``readObject``, ``writeObject``, ``readExternal`` and ``writeExternal``. However, a value coder can provide this logic for any class without modifying the class itself, which may be important if the class is part of a closed library.
+Persistit makes use of helper classes called “coders” to marshal data between live objects and their stored byte-array representations. Value coders, which implement ``com.persistit.encoding.ValueCoder``, marshal data to and from Value objects; ``com.persistit.encoding.KeyCoder`` implementations do the same for instances of ``com.persistit.Key``. A ``ValueCoder`` provides capability somewhat like the custom serialization logic implemented through ``readObject``, ``writeObject``, ``readExternal`` and ``writeExternal``. However, a ``ValueCoder`` can provide this logic for any class without modifying the class itself, which may be important if the class is part of a closed library.
 
 You may create and register a value coder for almost any class, including classes that are not marked Serializable. The exceptions are those listed which have built-in, non-overridable serialization logic.
 
 
=== modified file 'doc/Transactions.rst'
--- doc/Transactions.rst	2012-05-31 18:49:39 +0000
+++ doc/Transactions.rst	2012-06-11 21:28:19 +0000
@@ -5,7 +5,7 @@
 
 Akiban Persistit supports transactions with multi-version concurrency control (MVCC) using a protocol called Snapshot Isolation (SI). An application calls ``com.persistit.Transaction#begin``, ``com.persistit.Transaction#commit``, ``com.persistit.Transaction#rollback`` and ``com.persistit.Transaction#end`` methods to control the current transaction scope explicitly.  A Transaction allows an application to execute multiple database operations in an atomic, consistent, isolated and durable (ACID) manner.
 
-Applications manage transactions through an instance of a ``com.persistit.Transaction`` object. ``Transaction`` does not represent a single transaction, but is instead a context in which a thread may perform many sequential transactions. The general pattern is that the application gets the current thread’s ``Transaction`` instance, calls its ``begin`` method, performs work, calls ``commit`` and finally ``end``.  The thread uses the same ``Transaction`` instance repeatedly. Generally each thread has one ``Transaction`` that lasts for the entire life of the thread (but see com.persistit.Transaction#_threadManagement for a mechanism that allows a transaction to be serviced by multiple threads). 
+Applications manage transactions through an instance of a ``com.persistit.Transaction`` object. ``Transaction`` does not represent a single transaction, but is instead a context in which a thread may perform many sequential transactions. The general pattern is that the application gets the current thread’s ``Transaction`` instance, calls its ``begin`` method, performs work, calls ``commit`` and finally ``end``.  The thread uses the same ``Transaction`` instance repeatedly. Generally each thread has one ``Transaction`` that lasts for the entire life of the thread (but see com.persistit.Transaction for a mechanism that allows a transaction to be serviced by multiple threads). 
 
 Using Transactions
 ------------------
@@ -152,7 +152,7 @@
 
 Persistit provides the ``com.persistit.Accumulator`` class to avoid this problem.  An accumulator is designed to manage contributions from multiple concurrent transactions without causing write-write dependencies. Accumulators are durable in the sense that each transaction’s contribution is made durable with the transaction itself, and Persistit automatically recovers a correct state for each Accumulator in the event of a system crash.
 
-There are four types of accumulator in Persistit. Each a concrete subclass of the abstract ``com.persistit.Accumulator`` class:
+There are four types of accumulator in Persistit. Each is a concrete subclass of the abstract ``com.persistit.Accumulator`` class:
 
   ``SUM``
       Tallies a count or sum of contributions by each transaction
 
=== modified file 'doc/build/build-doc.sh'
--- doc/build/build-doc.sh	2012-05-31 19:16:14 +0000
+++ doc/build/build-doc.sh	2012-06-11 21:28:19 +0000
@@ -36,7 +36,7 @@
 #
 
 APIDOC_INDEX="../../target/site/apidocs/index-all.html"
-APIDOC_URL=${APIDOC_URL:-"http://www.akiban.com/ak-docs/admin/persistit-api"}
+APIDOC_URL=${APIDOC_URL:-"http://www.akiban.com/sites/all/libraries/persistit-api"}
 DOCPREP_CLASS="SphinxDocPrep"
 DOCPREP_CLASSPATH="../../target/sphinx/classes:../../target/classes"
 
 
=== modified file 'doc/build/src/SphinxDocPrep.java'
--- doc/build/src/SphinxDocPrep.java	2012-05-30 16:25:09 +0000
+++ doc/build/src/SphinxDocPrep.java	2012-06-11 21:28:19 +0000
@@ -68,7 +68,7 @@
     }
 
     private void processLine(final String line) throws Exception {
-        if (line.contains(".. code-block:")) {
+        if (line.contains(".. code-block:") || line.endsWith("::")) {
             block = BlockState.WAIT_FIRST_BLANK_LINE;
         } else if (line.isEmpty()) {
             switch (block) {