docs: various small improvements (part 2) (backport cometbft#1683) (c…

…ometbft#1686)

* docs: various small improvements (part 2) (cometbft#1683)

* docs: fix the number of connections CometBFT opens

to the ABCI app

* docs: fix link formatting

* docs: make it explicit that default is TCP for ABCI

* docs: replace 'supermajority' with 2/3+

2/3+ is easier to understand. also this is the first time the reader is
seeing the word 'supermajority', which might be confusing without the
defition. The defition for supermajority is absent (maybe it's in the
spec though)

* add a link to jq

* suggestions from Lasaro

(cherry picked from commit 96abada)

# Conflicts:
#	docs/app-dev/indexing-transactions.md
#	docs/core/block-structure.md

* fixes after merge

---------

Co-authored-by: Anton Kaliaev <anton.kalyaev@gmail.com>

docs/app-dev/abci-cli.md

@@ -259,7 +259,7 @@ You could put the commands in a file and run
 
 Note that the `abci-cli` is designed strictly for testing and debugging. In a real
 deployment, the role of sending messages is taken by CometBFT, which
-connects to the app using three separate connections, each with its own
+connects to the app using four separate connections, each with its own
 pattern of messages.
 
 For examples of running an ABCI app with CometBFT, see the

docs/app-dev/indexing-transactions.md

@@ -14,11 +14,7 @@ the block itself is never stored.
 
 Each event contains a type and a list of attributes, which are key-value pairs
 denoting something about what happened during the method's execution. For more
-details on `Events`, see the
-
-[ABCI](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#events)
-
-documentation.
+details on `Events`, see the [ABCI][abci-events] documentation.
 
 An `Event` has a composite key associated with it. A `compositeKey` is
 constructed by its type and key separated by a dot.
@@ -36,7 +32,7 @@ would be equal to the composite key of `jack.account.number`.
 By default, CometBFT will index all transactions by their respective hashes
 and height and blocks by their height.
 
-CometBFT allows for different events within the same height to have 
+CometBFT allows for different events within the same height to have
 equal attributes.
 
 ## Configuration
@@ -74,16 +70,17 @@ entirely in the future.
 
 **Implementation and data layout**
 
-The kv indexer stores each attribute of an event individually, by creating a composite key 
+The kv indexer stores each attribute of an event individually, by creating a composite key
 with
+
 - event type,
 - attribute key,
 - attribute value,
 - event generator (e.g. `EndBlock` and `BeginBlock`)
 - the height, and
 - event counter.
  For example the following events:
- 
+
 ```
 Type: "transfer",
   Attributes: []abci.EventAttribute{
@@ -94,7 +91,7 @@ Type: "transfer",
    },
  
 ```
- 
+
 ```
 Type: "transfer",
   Attributes: []abci.EventAttribute{
@@ -105,7 +102,7 @@ Type: "transfer",
    },
 ```
 
-will be represented as follows in the store, assuming these events result from the EndBlock call for height 1: 
+will be represented as follows in the store, assuming these events result from the EndBlock call for height 1:
 
 ```
 Key                                 value
@@ -121,10 +118,11 @@ transferBalance200EndBlock12         1
 transferNodeNothingEndblock12        1
  
 ```
-The event number is a local variable kept by the indexer and incremented when a new event is processed. 
-It is an `int64` variable and has no other semantics besides being used to associate attributes belonging to the same events within a height. 
+
+The event number is a local variable kept by the indexer and incremented when a new event is processed.
+It is an `int64` variable and has no other semantics besides being used to associate attributes belonging to the same events within a height.
 This variable is not atomically incremented as event indexing is deterministic. **Should this ever change**, the event id generation
-will be broken. 
+will be broken.
 
 #### PostgreSQL
 
@@ -237,18 +235,22 @@ curl "localhost:26657/block_search?query=\"block.height > 10 AND val_set.num_cha
 ```
 
 
-Storing the event sequence was introduced in CometBFT 0.34.26. Before that, up until Tendermint Core 0.34.26, 
-the event sequence was not stored in the kvstore and events were stored only by height. That means that queries 
-returned blocks and transactions whose event attributes match within the height but can match across different 
-events on that height. 
+Storing the event sequence was introduced in CometBFT 0.34.26. Before that, up until Tendermint Core 0.34.26,
+the event sequence was not stored in the kvstore and events were stored only by height. That means that queries
+returned blocks and transactions whose event attributes match within the height but can match across different
+events on that height.
 This behavior was fixed with CometBFT 0.34.26+. However, if the data was indexed with earlier versions of
 Tendermint Core and not re-indexed, that data will be queried as if all the attributes within a height
 occurred within the same event.
 
 # Event attribute value types
+
 Users can use anything as an event value. However, if the even attrbute value is a number, the following restrictions apply:
+
 - Negative numbers will not be properly retrieved when querying the indexer
 - When querying the events using `tx_search` and `block_search`, the value given as part of the condition cannot be a float.
 - Any event value retrieved from the database will be represented as a `BigInt` (from `math/big`)
-- Floating point values are not read from the database even with the introduction of `BigInt`. This was intentionally done 
-to keep the same beheaviour as was historically present and not introduce breaking  changes. This will be fixed in the 0.38 series.
+- Floating point values are not read from the database even with the introduction of `BigInt`. This was intentionally done
+to keep the same beheaviour as was historically present and not introduce breaking  changes. This will be fixed in the 0.38 series.
+
+[abci-events]: https://github.com/cometbft/cometbft/blob/v0.37.x/spec/abci/abci++_basic_concepts.md#events

docs/core/block-structure.md

@@ -4,13 +4,16 @@ order: 8
 
 # Block Structure
 
-The CometBFT consensus engine records all agreements by a
-supermajority of nodes into a blockchain, which is replicated among all
-nodes. This blockchain is accessible via various RPC endpoints, mainly
-`/block?height=` to get the full block, as well as
-`/blockchain?minHeight=_&maxHeight=_` to get a list of headers. But what
-exactly is stored in these blocks?
+The CometBFT consensus engine records all agreements by a 2/3+ of nodes
+into a blockchain, which is replicated among all nodes. This blockchain is
+accessible via various RPC endpoints, mainly `/block?height=` to get the full
+block, as well as `/blockchain?minHeight=_&maxHeight=_` to get a list of
+headers. But what exactly is stored in these blocks?
 
-The [specification](https://github.com/cometbft/cometbft/blob/v0.37.x/spec/core/data_structures.md) contains a detailed description of each component - that's the best place to get started.
+The [specification][data_structures] contains a detailed description of each
+component - that's the best place to get started.
 
-To dig deeper, check out the [types package documentation](https://godoc.org/github.com/cometbft/cometbft/types).
+To dig deeper, check out the [types package documentation][types].
+
+[data_structures]: https://github.com/cometbft/cometbft/blob/v0.37.x/spec/core/data_structures.md
+[types]: https://pkg.go.dev/github.com/cometbft/cometbft/types

docs/core/state-sync.md

@@ -30,7 +30,7 @@ The next information you will need to acquire it through publicly exposed RPC's
 - `trust_period`: Trust period is the period in which headers can be verified. 
   > :warning: This value should be significantly smaller than the unbonding period.
 
-If you are relying on publicly exposed RPC's to get the need information, you can use `curl`.
+If you are relying on publicly exposed RPC's to get the need information, you can use `curl` and [`jq`][jq].
 
 Example: 
 
@@ -46,3 +46,5 @@ The response will be:
   "hash": "188F4F36CBCD2C91B57509BBF231C777E79B52EE3E0D90D06B1A25EB16E6E23D"
 }
 ```
+
+[jq]: https://jqlang.github.io/jq/

docs/core/using-cometbft.md

@@ -130,7 +130,7 @@ cometbft node
 ```
 
 By default, CometBFT will try to connect to an ABCI application on
-`127.0.0.1:26658`. If you have the `kvstore` ABCI app installed, run it in
+`tcp://127.0.0.1:26658`. If you have the `kvstore` ABCI app installed, run it in
 another window. If you don't, kill CometBFT and run an in-process version of
 the `kvstore` app:
 
@@ -139,8 +139,8 @@ cometbft node --proxy_app=kvstore
 ```
 
 After a few seconds, you should see blocks start streaming in. Note that blocks
-are produced regularly, even if there are no transactions. See _No Empty
-Blocks_, below, to modify this setting.
+are produced regularly, even if there are no transactions. See [No Empty
+Blocks](#no-empty-blocks), below, to modify this setting.
 
 CometBFT supports in-process versions of the `counter`, `kvstore`, and `noop`
 apps that ship as examples with `abci-cli`. It's easy to compile your app