Merge pull request #5 from twitter/lahosken_doc

fix things that tripped me up while learning Parrot

Make some multi-line code examples really be multi-line so that they don't make a table so wide it gets clipped.

Mention more prominently that you probably want >= 1000 sample logs

maven package-run cycle (Plagiarized from Trisha's post on the group)

fix logger example to something that compiles.

README.md

@@ -25,9 +25,9 @@
 
 ## Iago Quick Start
 
-NOTE: This repo has only recently been made public and our velocity is high at the moment, with significant work being done on documentation in particular. Please join iago-users@googlegroups.com (https://groups.google.com/d/forum/iago-users) for updates and to ask pressing questions.
+NOTE: This repo has only recently been made public and our velocity is high at the moment. Please join [iago-users@googlegroups.com](https://groups.google.com/d/forum/iago-users) for updates and to ask questions.
 
-If you are already familiar with the Iago Load Generation tool, follow these steps to get started; otherwise, start with the <a href="#Iago Overview">Iago Overview</a>. For questions, please contact <a href="mailto:iago-users@googlegroups.com">iago-users@googlegroups.com</a>.
+If you are already familiar with the Iago Load Generation tool, follow these steps to get started; otherwise, start with the <a href="http://twitter.github.com/iago/">Iago Overview</a> and perhaps <a href="http://twitter.github.com/iago/philosophy.html">Iago Philosophy</a>, also known as "Why Iago?". For questions, please contact [iago-users@googlegroups.com](https://groups.google.com/d/forum/iago-users).
 
 <a name="Iago Prerequisites"></a>
 
@@ -36,7 +36,7 @@ If you are already familiar with the Iago Load Generation tool, follow these ste
 1. Download and unpack the Iago distribution.
 We support Scala 2.9 and recommend you clone the latest master: <a href="https://github.com/twitter/iago/zipball/master">master</a>.
 
-2. Read the documentation. We'll be adding more recommended steps here shortly.
+2. Read the documentation.
 
 <a name="Preparing Your Test"></a>
 
@@ -50,7 +50,18 @@ We support Scala 2.9 and recommend you clone the latest master: <a href="https:/
 
 ### Executing Your Test
 
-Launch Iago from the distribution with `java` `-jar` *iago_jar* `-f` *your_config*. This will create the Iago processes for you and configure it to use your transactions. To kill a running job, add `-k` to your launch parameters: `java` `-jar` *parrot_jar* `-f` *your_config* `-k`.
+Launch Iago from the distribution with `java` `-jar` *iago_jar* `-f` *your_config*. This will create the Iago processes for you and configure it to use your transactions. To kill a running job, add `-k` to your launch parameters: `java` `-jar` *iago_jar* `-f` *your_config* `-k`.
+
+If you launch your Iago job on your local machine and an old Iago job is still running, it probably won't get far: it will attempt to re-user a port and fail. You want to kill the running job, as described above.
+
+<em>If you build via Maven,</em> then you might wonder "How do I launch Iago 'from the distribution'?" The steps are:
+<pre>
+% <kbd>mvn package -DskipTests</kbd>
+% <kbd>mkdir tmp; cd tmp</kbd>
+% <kbd>unzip ../target/iago-<var>version</var>-package-dist.zip</kbd>
+% <kbd>java -jar iago-<var>version</var>.jar -f config/<var>my_config</var>.scala</kbd>
+</pre>
+Don't assume that you can skip the package/unzip steps if you're just changing a config file. You need to re-package and unzip again.
 
 If you are using Iago as a library, for example, in the case of testing over the Thrift protocol or building more complex tests with HTTP or Memcached/Kestrel, you should instead add a task to your project's configuration. See <a href="#Configuring Your Test">Configuring Your Test</a> for more information.
 
@@ -92,6 +103,8 @@ For replay, Iago recommends you scrub your logs to only include requests which m
 * **Idempotent**, meaning that re-execution of a transaction any number of times yields the same result as the initial execution.
 * **Commutative**, meaning that transaction order is not important. Although transactions are initiated in replay order, Iago's internal behavior may change the actual execution order to guarantee the transaction rate. Also, transactions that implement `Future` responses are executed asynchronously. You can achieve ordering, if required, by using Iago as a library and initiating new requests in response to previous ones. Examples of this are available.
 
+Unless you change your configuration's <code>reuseFile</code> parameter, make sure that your sample log has at least 1000 items.
+
 [Top](#Top)
 
 <a name="Sources of Transactions"></a>
@@ -363,7 +376,7 @@ You can specify any of the following parameters:
 </tr>
 <tr>
     <td><code>log</code></td>
-    <td><p>A string value that specifies the complete path to the log you want Iago to replay. The log should be on your local file system.</p>
+    <td><p>A string value that specifies the complete path to the log you want Iago to replay. The log should be on your local file system. The log should have at least 1000 items or you should change the <code>reuseFile</code> parameter.</p>
     <p><b>Example: </b><code>log = "logs/yesterday.log"</code></p></td>
     <td><b>Required</b></td>
 </tr>
@@ -441,17 +454,24 @@ You can specify any of the following parameters:
 <tr>
     <td><code>loggers</code></td>
     <td><p>A List of LoggerFactories; allows you to define the type and level of logging you want</p>
-    <p><b>Example: </b><code>loggers = new LoggerFactory(
-    level = Level.DEBUG
-    handlers = ConsoleHandler
-  ) = "preflight"</code></p></td>
+    <p><b>Example:</b></p>
+<pre>import com.twitter.logging.LoggerFactory
+import com.twitter.logging.config._
+
+new ParrotLauncherConfig {
+  ...
+  loggers = new LoggerFactory(
+    level = Level.DEBUG,
+    handlers = new ConsoleHandlerConfig()
+  )
+} </pre></td>
     <td><i>Nil</i></td>
 </tr>
 <tr>
     <td><code>numFeederInstances</code></td>
     <td><p>Will bring up the specified number of feeder instances</p>
     <p><b>Example: </b><code>numFeederInstances = 2</code></p></td>
-    <td><i>1</i></td>
+    <td>1</td>
 </tr>
 <tr>
     <td><code>numInstances</code></td>
@@ -539,7 +559,9 @@ You can specify any of the following parameters:
 <tr>
     <td><code>createDistribution</code></td>
     <td><p>You can use this field to create your own distribution rate, instead of having a constant flow. You will need to create a subclass of RequestDistribution and import it.</p>
-    <p><b>Example: </b><code>createDistribution = "createDistribution = { rate => new MyDistribution(rate) }"</code></p></td>
+    <p><b>Example: </b><pre>createDistribution = """createDistribution = {
+    rate => new MyDistribution(rate)
+}"""</pre></p></td>
     <td><i>""</i></td>
 </tr>
 </tbody>