docs: comb through step by step

cmd/tendermint/commands/root_test.go

@@ -28,8 +28,6 @@ const (
 func isolate(cmds ...*cobra.Command) cli.Executable {
 	os.Unsetenv("TMHOME")
 	os.Unsetenv("TM_HOME")
-	os.Unsetenv("TMROOT")
-	os.Unsetenv("TM_ROOT")
 
 	viper.Reset()
 	config = cfg.DefaultConfig()
@@ -70,7 +68,7 @@ func TestRootConfig(t *testing.T) {
 		{nil, nil, defaultRoot, defaults.Moniker, defaults.FastSync, dmax},
 		// try multiple ways of setting root (two flags, cli vs. env)
 		{[]string{"--home", conf}, nil, conf, cvals["moniker"], cfast, dmax},
-		{nil, map[string]string{"TMROOT": conf}, conf, cvals["moniker"], cfast, dmax},
+		{nil, map[string]string{"TMHOME": conf}, conf, cvals["moniker"], cfast, dmax},
 		// check setting p2p subflags two different ways
 		{[]string{"--p2p.max_num_peers", "420"}, nil, defaultRoot, defaults.Moniker, defaults.FastSync, 420},
 		{nil, map[string]string{"TM_P2P_MAX_NUM_PEERS": "17"}, defaultRoot, defaults.Moniker, defaults.FastSync, 17},

docs/abci-cli.rst

@@ -80,8 +80,19 @@ In another terminal, run
     abci-cli echo hello
     abci-cli info
 
-The application should echo ``hello`` and give you some information
-about itself.
+You'll see something like:
+
+::
+
+    -> data: hello
+    -> data.hex: 68656C6C6F
+
+and:
+
+::
+
+    -> data: {"size":0}
+    -> data.hex: 7B2273697A65223A307D
 
 An ABCI application must provide two things:
 
@@ -96,7 +107,7 @@ The server may be generic for a particular language, and we provide a
 `reference implementation in
 Golang <https://github.com/tendermint/abci/tree/master/server>`__. See
 the `list of other ABCI
-implementations <https://tendermint.com/ecosystem>`__ for servers in
+implementations <./ecosystem.html>`__ for servers in
 other languages.
 
 The handler is specific to the application, and may be arbitrary, so

docs/deploy-testnets.rst

@@ -13,7 +13,7 @@ It's relatively easy to setup a Tendermint cluster manually. The only
 requirements for a particular Tendermint node are a private key for the
 validator, stored as ``priv_validator.json``, and a list of the public
 keys of all validators, stored as ``genesis.json``. These files should
-be stored in ``~/.tendermint``, or wherever the ``$TMROOT`` variable
+be stored in ``~/.tendermint``, or wherever the ``$TMHOME`` variable
 might be set to.
 
 Here are the steps to setting up a testnet manually:

docs/getting-started.rst

@@ -148,7 +148,7 @@ The result should look like:
 Note the ``value`` in the result (``61626364``); this is the
 hex-encoding of the ASCII of ``abcd``. You can verify this in
 a python shell by running ``"61626364".decode('hex')``. Stay
-tuned for a future release that makes this output more human-readable.
+tuned for a future release that `makes this output more human-readable <https://github.com/tendermint/abci/issues/32`__.
 
 Now let's try setting a different key and value:
 
@@ -170,7 +170,7 @@ Counter - Another Example
 -------------------------
 
 Now that we've got the hang of it, let's try another application, the
-"counter" app.
+**counter** app.
 
 The counter app doesn't use a Merkle tree, it just counts how many times
 we've sent a transaction, or committed the state.
@@ -198,7 +198,7 @@ a flag:
 
 ::
 
-    counter --serial
+    abci-cli counter --serial
 
 In another window, reset then start Tendermint:
 
@@ -282,6 +282,7 @@ keep all our code under the ``$GOPATH``, so run:
     go get github.com/tendermint/js-abci &> /dev/null
     cd $GOPATH/src/github.com/tendermint/js-abci/example
     npm install
+    cd ..
 
 Kill the previous ``counter`` and ``tendermint`` processes. Now run the
 app:
@@ -315,9 +316,9 @@ Basecoin - A More Interesting Example
 We saved the best for last; the `Cosmos SDK <https://github.com/cosmos/cosmos-sdk>`__ is a general purpose framework for building cryptocurrencies. Unlike the ``dummy`` and ``counter``, which are strictly for example purposes. The reference implementation of Cosmos SDK is ``basecoin``, which demonstrates how to use the building blocks of the Cosmos SDK.
 
 The default ``basecoin`` application is a multi-asset cryptocurrency
-that supports inter-blockchain communication. For more details on how
+that supports inter-blockchain communication (IBC). For more details on how
 basecoin works and how to use it, see our `basecoin
-guide <https://github.com/cosmos/cosmos-sdk/blob/develop/docs/guide/basecoin-basics.md>`__
+guide <http://cosmos-sdk.readthedocs.io/en/latest/basecoin-basics.html>`__
 
 In this tutorial you learned how to run applications using Tendermint
 on a single node. You saw how applications could be written in different

docs/install.rst

@@ -9,7 +9,7 @@ To download pre-built binaries, see the `Download page <https://tendermint.com/d
 From Source
 -----------
 
-You'll need `go`, maybe `glide` and the tendermint source code.
+You'll need ``go``, maybe ``glide``, and the tendermint source code.
 
 Install Go
 ^^^^^^^^^^

docs/introduction.rst

@@ -146,11 +146,11 @@ The ABCI consists of 3 primary message types that get delivered from the core to
 
 The messages are specified here: `ABCI Message Types <https://github.com/tendermint/abci#message-types>`__.
 
-The `DeliverTx` message is the work horse of the application.  Each transaction in the blockchain is delivered with this message. The application needs to validate each transaction received with the `DeliverTx` message against the current state, application protocol, and the cryptographic credentials of the transaction. A validated transaction then needs to update the application state — by binding a value into a key values store, or by updating the UTXO database, for instance.
+The **DeliverTx** message is the work horse of the application. Each transaction in the blockchain is delivered with this message. The application needs to validate each transaction received with the **DeliverTx** message against the current state, application protocol, and the cryptographic credentials of the transaction. A validated transaction then needs to update the application state — by binding a value into a key values store, or by updating the UTXO database, for instance.
 
-The `CheckTx` message is similar to `DeliverTx`, but it's only for validating transactions.  Tendermint Core's mempool first checks the validity of a transaction with `CheckTx`, and only relays valid transactions to its peers.  For instance, an application may check an incrementing sequence number in the transaction and return an error upon `CheckTx` if the sequence number is old. Alternatively, they might use a capabilities based system that requires capabilities to be renewed with every transaction.
+The **CheckTx** message is similar to **DeliverTx**, but it's only for validating transactions. Tendermint Core's mempool first checks the validity of a transaction with **CheckTx**, and only relays valid transactions to its peers. For instance, an application may check an incrementing sequence number in the transaction and return an error upon **CheckTx** if the sequence number is old. Alternatively, they might use a capabilities based system that requires capabilities to be renewed with every transaction.
 
-The `Commit` message is used to compute a cryptographic commitment to the current application state, to be placed into the next block header. This has some handy properties. Inconsistencies in updating that state will now appear as blockchain forks which catches a whole class of programming errors. This also simplifies the development of secure lightweight clients, as Merkle-hash proofs can be verified by checking against the block hash, and that the block hash is signed by a quorum.
+The **Commit** message is used to compute a cryptographic commitment to the current application state, to be placed into the next block header. This has some handy properties. Inconsistencies in updating that state will now appear as blockchain forks which catches a whole class of programming errors. This also simplifies the development of secure lightweight clients, as Merkle-hash proofs can be verified by checking against the block hash, and that the block hash is signed by a quorum.
 
 There can be multiple ABCI socket connections to an application. Tendermint Core creates three ABCI connections to the application; one for the validation of transactions when broadcasting in the mempool, one for the consensus engine to run block proposals, and one more for querying the application state.
 
@@ -169,7 +169,7 @@ Solidity on Ethereum is a great language of choice for blockchain applications b
  * race conditions on threads (or avoiding threads altogether)
  * the system clock
  * uninitialized memory (in unsafe programming languages like C or C++)
- * `floating point arithmetic <http://gafferongames.com/networking-for-game-programmers/floating-point-determinism/>`__.
+ * `floating point arithmetic <http://gafferongames.com/networking-for-game-programmers/floating-point-determinism/>`__
  * language features that are random (e.g. map iteration in Go)
 
 While programmers can avoid non-determinism by being careful, it is also possible to create a special linter or static analyzer for each language to check for determinism.  In the future we may work with partners to create such tools.
@@ -182,17 +182,17 @@ The protocol follows a simple state machine that looks like this:
 
 .. figure:: assets/consensus_logic.png
 
-Participants in the protocol are called "validators";
+Participants in the protocol are called **validators**;
 they take turns proposing blocks of transactions and voting on them.
-Blocks are committed in a chain, with one block at each "height".
-A block may fail to be committed, in which case the protocol moves to the next "round",
+Blocks are committed in a chain, with one block at each **height**.
+A block may fail to be committed, in which case the protocol moves to the next **round**,
 and a new validator gets to propose a block for that height.
 Two stages of voting are required to successfully commit a block;
-we call them "pre-vote" and "pre-commit".
+we call them **pre-vote** and **pre-commit**.
 A block is committed when more than 2/3 of validators pre-commit for the same block in the same round.
 
 There is a picture of a couple doing the polka because validators are doing something like a polka dance.
-When more than two-thirds of the validators pre-vote for the same block, we call that a "polka".
+When more than two-thirds of the validators pre-vote for the same block, we call that a **polka**.
 Every pre-commit must be justified by a polka in the same round.
 
 Validators may fail to commit a block for a number of reasons; 
@@ -204,8 +204,8 @@ However, the rest of the protocol is asynchronous, and validators only make prog
 A simplifying element of Tendermint is that it uses the same mechanism to commit a block as it does to skip to the next round.
 
 Assuming less than one-third of the validators are Byzantine, Tendermint guarantees that safety will never be violated - that is, validators will never commit conflicting blocks at the same height.
-To do this it introduces a few "locking" rules which modulate which paths can be followed in the flow diagram.
-Once a validator precommits a block, it is "locked" on that block. 
+To do this it introduces a few **locking** rules which modulate which paths can be followed in the flow diagram.
+Once a validator precommits a block, it is locked on that block.
 Then, 
 
 1) it must prevote for the block it is locked on

docs/specification/genesis.rst

@@ -1,7 +1,7 @@
 Genesis
 =======
 
-The genesis.json file in ``$TMROOT`` defines the initial TendermintCore
+The genesis.json file in ``$TMHOME`` defines the initial TendermintCore
 state upon genesis of the blockchain (`see
 definition <https://github.com/tendermint/tendermint/blob/master/types/genesis.go>`__).
 

docs/using-tendermint.rst

@@ -12,7 +12,7 @@ Directory Root
 --------------
 
 The default directory for blockchain data is ``~/.tendermint``. Override
-this by setting the ``TMROOT`` environment variable.
+this by setting the ``TMHOME`` environment variable.
 
 Initialize
 ----------
@@ -39,7 +39,7 @@ To run a tendermint node, use
 
     tendermint node
 
-By default, Tendermint will try to connect to a abci appliction on
+By default, Tendermint will try to connect to an ABCI application on
 `127.0.0.1:46658 <127.0.0.1:46658>`__. If you have the ``dummy`` ABCI
 app installed, run it in another window. If you don't, kill tendermint
 and run an in-process version with
@@ -49,9 +49,7 @@ and run an in-process version with
     tendermint node --proxy_app=dummy
 
 After a few seconds you should see blocks start streaming in. Note that
-blocks are produced regularly, even if there are no transactions. This
-changes `with this pull
-request <https://github.com/tendermint/tendermint/pull/584>`__.
+blocks are produced regularly, even if there are no transactions. See *No Empty Blocks*, below, to modify this setting.
 
 Tendermint supports in-process versions of the dummy, counter, and nil
 apps that ship as examples in the `ABCI
@@ -59,7 +57,7 @@ repository <https://github.com/tendermint/abci>`__. It's easy to compile
 your own app in-process with tendermint if it's written in Go. If your
 app is not written in Go, simply run it in another process, and use the
 ``--proxy_app`` flag to specify the address of the socket it is
-listening on, for instance
+listening on, for instance:
 
 ::
 
@@ -117,7 +115,7 @@ Configuration
 -------------
 
 Tendermint uses a ``config.toml`` for configuration. For details, see
-`the documentation <./specification/configuration.html>`__.
+`the config specification <./specification/configuration.html>`__.
 
 Notable options include the socket address of the application
 (``proxy_app``), the listenting address of the tendermint peer
@@ -283,7 +281,7 @@ specify peers for a running node to connect to:
 
 Additionally, the peer-exchange protocol can be enabled using the
 ``--pex`` flag, though this feature is `still under
-development <https://github.com/tendermint/tendermint/issues/598>`__ If
+development <https://github.com/tendermint/tendermint/issues/598>`__. If
 ``--pex`` is enabled, peers will gossip about known peers and form a
 more resilient network.
 
@@ -388,7 +386,7 @@ Additionally, you must set ``addrbook_strict=false`` in the
 connections to peers with the same IP address.
 
 Upgrading
-~~~~~~~~
+~~~~~~~~~
 
 The tendermint development cycle includes a lot of breaking changes. Upgrading from
 an old version to a new version usually means throwing away the chain data. Try out