more documentation

README.md

@@ -30,6 +30,8 @@ It is still OK to connect `gh-ost` directly on master; you will need to confirm
 
 #### Testing on replica
 
+Newcomer? We think you would enjoy building trust with this tool. You can ask `gh-ost` to simulate a migration on a replica -- this will not affect data on master and will not actually do a complete migration. It will operate on a replica, and end up with two tables: the original (untouched), and the migrated. You will have your chance to compare the two and verify the tool works to your satisfaction.
+
 ```
 gh-ost --conf=.my.cnf --database=mydb --table=mytable --verbose --alter="engine=innodb" --execute --initially-drop-ghost-table --initially-drop-old-table -max-load=Threads_connected=30 --switch-to-rbr --chunk-size=2500 --cut-over=two-step --exact-rowcount --test-on-replica --verbose
 ```
@@ -41,10 +43,24 @@ Please read more on [testing on replica](testing-on-replica.md)
 gh-ost --conf=.my.cnf --database=mydb --table=mytable --verbose --alter="engine=innodb" --execute --initially-drop-ghost-table --initially-drop-old-table -max-load=Threads_connected=30 --switch-to-rbr --chunk-size=2500 --cut-over=two-step --exact-rowcount --verbose
 ```
 
-#### Recommended parameters
+Note: "executing on master" does not mean you need to _connect_ to the master. `gh-ost` is happy if you connect to a replica; it then figures out the identity of the master and makes the connection itself.
+
+#### Notable parameters
 
 Run `gh-ost --help` to get full list of parameters. We like the following:
 
+- `--conf=/path/to/my.cnf`: file where credentials are specified. Should be in (or contain) the following format:
+
+  ```
+[client]
+user=gromit
+password=123456
+  ```
+
+- `--user`, `--password`: alternatively, supply these as arguments
+
+- `--host`, `--port`: where to connect to. `gh-ost` prefers to connect to a replica, see above.
+
 - `--exact-rowcount`: actually `select count(*)` from your table prior to migration, and heuristically maintain the updating table size while migrating. This makes for quite accurate assumption on progress. When `gh-ost` says it's `99.8%` done, it really there or very closely there.
 
 - `--execute`: without this parameter, migration is a _noop_: testing table creation and validity of migration, but not touching data.

doc/command-line-flags.md

@@ -2,6 +2,16 @@
 
 A more in-depth discussion of various `gh-ost` command line flags: implementation, implication, use cases.
 
+##### conf
+
+`--conf=/path/to/my.cnf`: file where credentials are specified. Should be in (or contain) the following format:
+
+  ```
+[client]
+user=gromit
+password=123456
+  ```
+
 ##### cut-over
 
 Required. You are asked to explicitly state which cut-over algorithm you wish to use. Please see more discussion on [cut-over](cut-over.md)
@@ -19,9 +29,19 @@ A `gh-ost` execution need to copy whatever rows you have in your existing table
 
 While the ongoing estimated number of rows is still heuristic, it's almost exact, such that the reported  [ETA](understanding-output.md) or percentage progress is typically accurate to the second throughout a multiple-hour operation.
 
-##### noop
+##### execute
 
-Do cheks; create ghost table and verify migration would be valid, but do not actually migrate and do not touch data.
+Without this parameter, migration is a _noop_: testing table creation and validity of migration, but not touching data.
+
+##### initially-drop-ghost-table
+
+`gh-ost` maintains two tables while migrating: the _ghost_ table (which is synced from your original table and finally replaces it) and a changelog table, which is used internally for bookkeeping. By default, it panics and aborts if it sees those tables upon startup. Provide `--initially-drop-ghost-table` and `--initially-drop-old-table` to let `gh-ost` know it's OK to drop them beforehand.
+
+We think `gh-ost` should not take chances or make assumptions about the user's tables. Dropping tables can be a dangerous, locking operation. We let the user explicitly approve such operations.
+
+##### initially-drop-old-table
+
+See #initially-drop-ghost-table
 
 ##### test-on-replica
 

doc/throttle.md

@@ -57,7 +57,9 @@ In addition to the above, you are able to take control and throttle the operatio
 
 - `throttle` command via [interactive interface](interactive-commands.md).
 
-  Example: ```
+  Example:
+
+  ```
     echo throttle | nc -U /tmp/gh-ost.test.sample_data_0.sock
     echo no-throttle | nc -U /tmp/gh-ost.test.sample_data_0.sock
   ```
@@ -73,6 +75,7 @@ The first check to suggest throttling stops the search; the status message will
 ### Throttle status
 
 The throttle status is printed as part of the periodic [status message](understanding-output.md):
+
 ```
 Copy: 0/2915 0.0%; Applied: 0; Backlog: 0/100; Elapsed: 41s(copy), 41s(total); streamer: mysql-bin.000551:47983; ETA: throttled, flag-file
 Copy: 0/2915 0.0%; Applied: 0; Backlog: 0/100; Elapsed: 42s(copy), 42s(total); streamer: mysql-bin.000551:49370; ETA: throttled, commanded by user