Minor docs cleanup (#2472)

* docs: link consensus to blockchain spec. closes #2422

* docs: deprecate research section. closes #2401

* docs: fix some links

* docs: fix some markdown lists

* docs: fix more links

docs/.vuepress/config.js

@@ -106,14 +106,6 @@ module.exports = {
           "/spec/abci/apps",
           "/spec/abci/client-server"
         ]
-      },
-      {
-        title: "Research",
-        collapsable: false,
-        children: [
-	  "/research/determinism",
-	  "/research/transactional-semantics"
-	]
       }
     ]
   }

docs/app-dev/getting-started.md

@@ -7,7 +7,7 @@ application you want to run. So, to run a complete blockchain that does
 something useful, you must start two programs: one is Tendermint Core,
 the other is your application, which can be written in any programming
 language. Recall from [the intro to
-ABCI](../introduction/introduction.md#ABCI-Overview) that Tendermint Core handles all
+ABCI](../introduction/introduction.html#abci-overview) that Tendermint Core handles all
 the p2p and consensus stuff, and just forwards transactions to the
 application when they need to be validated, or when they're ready to be
 committed to a block.

docs/research/determinism.md

@@ -1,3 +1,3 @@
 # On Determinism
 
-Arguably, the most difficult part of blockchain programming is determinism - that is, ensuring that sources of indeterminism do not creep into the design of such systems.
+See [Determinism](../spec/abci/abci.md#determinism).

docs/research/transactional-semantics.md

@@ -1,25 +1,5 @@
 # Transactional Semantics
 
-In [Using Tendermint](../tendermint-core/using-tendermint.md#broadcast-api) we
+See details of the [broadcast API](../tendermint-core/using-tendermint.md#broadcast-api)
-discussed different API endpoints for sending transactions and
+and the [mempool WAL](../tendermint-core/running-in-production.md#mempool-wal).
-differences between them.
 
-What we have not yet covered is transactional semantics.
-
-When you send a transaction using one of the available methods, it first
-goes to the mempool. Currently, it does not provide strong guarantees
-like "if the transaction were accepted, it would be eventually included
-in a block (given CheckTx passes)."
-
-For instance a tx could enter the mempool, but before it can be sent to
-peers the node crashes.
-
-We are planning to provide such guarantees by using a WAL and replaying
-transactions (See
-[this issue](https://github.com/tendermint/tendermint/issues/248)), but
-it's non-trivial to do this all efficiently.
-
-The temporary solution is for clients to monitor the node and resubmit
-transaction(s) and/or send them to more nodes at once, so the
-probability of all of them crashing at the same time and losing the msg
-decreases substantially.

docs/spec/abci/apps.md

@@ -114,8 +114,8 @@ should halt before it can use more resources than it requested.
 
 When `MaxGas > -1`, Tendermint enforces the following rules:
 
-    - `GasWanted <= MaxGas` for all txs in the mempool
+- `GasWanted <= MaxGas` for all txs in the mempool
-    - `(sum of GasWanted in a block) <= MaxGas` when proposing a block
+- `(sum of GasWanted in a block) <= MaxGas` when proposing a block
 
 If `MaxGas == -1`, no rules about gas are enforced.
 
@@ -124,8 +124,9 @@ This means it does not guarantee that committed blocks satisfy these rules!
 It is the application's responsibility to return non-zero response codes when gas limits are exceeded.
 
 The `GasUsed` field is ignored compltely by Tendermint. That said, applications should enforce:
-    - `GasUsed <= GasWanted` for any given transaction
+
-    - `(sum of GasUsed in a block) <= MaxGas` for every block
+- `GasUsed <= GasWanted` for any given transaction
+- `(sum of GasUsed in a block) <= MaxGas` for every block
 
 In the future, we intend to add a `Priority` field to the responses that can be
 used to explicitly prioritize txs in the mempool for inclusion in a block

docs/spec/consensus/consensus.md

@@ -17,7 +17,7 @@
   vote](https://godoc.org/github.com/tendermint/tendermint/types#FirstPrecommit)
   for something.
 - A vote _at_ `(H,R)` is a vote signed with the bytes for `H` and `R`
-  included in its [sign-bytes](../blockchain/blockchain.md).
+  included in its [sign-bytes](../blockchain/blockchain.md#vote).
 - _+2/3_ is short for "more than 2/3"
 - _1/3+_ is short for "1/3 or more"
 - A set of +2/3 of prevotes for a particular block or `<nil>` at

docs/tendermint-core/running-in-production.md

@@ -6,7 +6,7 @@ By default, Tendermint uses the `syndtr/goleveldb` package for it's in-process
 key-value database. Unfortunately, this implementation of LevelDB seems to suffer under heavy load (see
 [#226](https://github.com/syndtr/goleveldb/issues/226)). It may be best to
 install the real C-implementaiton of LevelDB and compile Tendermint to use
-that using `make build_c`. See the [install instructions](../introduction/install) for details.
+that using `make build_c`. See the [install instructions](../introduction/install.md) for details.
 
 Tendermint keeps multiple distinct LevelDB databases in the `$TMROOT/data`:
 
@@ -20,11 +20,11 @@ Tendermint keeps multiple distinct LevelDB databases in the `$TMROOT/data`:
 - `tx_index.db`: Indexes txs (and their results) by tx hash and by DeliverTx result tags.
 
 By default, Tendermint will only index txs by their hash, not by their DeliverTx
-result tags. See [indexing transactions](../app-dev/indexing-transactions) for
+result tags. See [indexing transactions](../app-dev/indexing-transactions.md) for
 details.
 
 There is no current strategy for pruning the databases. Consider reducing
-block production by [controlling empty blocks](../tendermint-core/using-tendermint#No-Empty-Blocks)
+block production by [controlling empty blocks](../tendermint-core/using-tendermint.md#no-empty-blocks)
 or by increasing the `consensus.timeout_commit` param. Note both of these are
 local settings and not enforced by the consensus.
 
@@ -50,7 +50,9 @@ logging level, you can do so by running tendermint with
 ## Write Ahead Logs (WAL)
 
 Tendermint uses write ahead logs for the consensus (`cs.wal`) and the mempool
-(`mempool.wal`). Both WALs have a max size of 1GB and are automatically rotated..
+(`mempool.wal`). Both WALs have a max size of 1GB and are automatically rotated.
+
+### Consensus WAL
 
 The `consensus.wal` is used to ensure we can recover from a crash at any point
 in the consensus state machine.
@@ -60,7 +62,9 @@ validator. Since Tendermint validators are expected to never sign a conflicting
 WAL ensures we can always recover deterministically to the latest state of the consensus without
 using the network or re-signing any consensus messages.
 
-If your `consensus.wal` is corrupted, see [below](#WAL-Corruption).
+If your `consensus.wal` is corrupted, see [below](#wal-corruption).
+
+### Mempool WAL
 
 The `mempool.wal` logs all incoming txs before running CheckTx, but is
 otherwise not used in any programmatic way. It's just a kind of manual

docs/tendermint-core/using-tendermint.md

@@ -305,6 +305,12 @@ can take on the order of a second. For a quick result, use
 `broadcast_tx_sync`, but the transaction will not be committed until
 later, and by that point its effect on the state may change.
 
+Note the mempool does not provide strong guarantees - just because a tx passed
+CheckTx (ie. was accepted into the mempool), doesn't mean it will be committed,
+as nodes with the tx in their mempool may crash before they get to propose.
+For more information, see the [mempool
+write-ahead-log](../tendermint-core/running-in-production.md#mempool-wal)
+
 ## Tendermint Networks
 
 When `tendermint init` is run, both a `genesis.json` and