Doc: small improvements and fixes

docs/index.rst

@@ -49,6 +49,26 @@ The Community
 The Networks
 ------------
 
+.. _betanet:
+
+Betanet
+~~~~~~~
+
+The Tezos Beta (experimental) network is the current incarnation of
+the Tezos blockchain.
+It runs with real tezzies that have been allocated to the
+donors of July 2017 ICO (see :ref:`activate_fundraiser_account`).
+It is the step before the full Tezos mainnet, with a `few caveats
+<https://tezosfoundation.ch/news/tezos-betanet-expectations>`_.
+
+The Tezos Beta (experimental) network has been live and open since
+`June 30th 2018 <https://tezosfoundation.ch/news/tezos-betanet-launch>`_.
+
+All the instructions in this documentation are valid for Betanet
+however we **strongly** encourage users to first try all the
+introduction tutorials on Alphanet to familiarize themselves without
+risks.
+
 .. _alphanet:
 
 Alphanet
@@ -56,8 +76,8 @@ Alphanet
 
 Tezos Alphanet is a test network for the Tezos blockchain with a
 faucet to obtain free tezzies (see :ref:`faucet`).
-It is updated and rebooted rarely and it is either running the same
+It is updated and rebooted rarely and it is running the same code as
-code as beta or the next version that will become beta in a few weeks.
+the Betanet.
 It is the reference network for developers wanting to test their
 software before going to beta and for users who want to familiarize
 themselves with Tezos before using their real tezzies.
@@ -75,26 +95,11 @@ Zeronet
 Zeronet is the most cutting-edge development network of Tezos. It is
 restarted without notice, possibly several times a day.
 This network is mostly used internally by the Tezos developers and may
-have *different constants* that Alphanet or Betanet.
+have *different constants* that Alphanet or Betanet, for example it
+has shorter cycles and a shorter interval between blocks.
 We offer no support for the Zeronet.
 
 
-.. _betanet:
-
-Betanet
-~~~~~~~
-
-The Tezos Beta (experimental) network is the current incarnation of
-the Tezos blockchain.
-There is no faucet but real tezzies that have been allocated to the
-donors of July 2017 ICO (see :ref:`activate_fundraiser_account`).
-It is the step before the full Tezos mainnet, with a `few caveats
-<https://tezosfoundation.ch/news/tezos-betanet-expectations>`_.
-
-The Tezos Beta (experimental) network has been live and open since
-`June 30th 2018 <https://tezosfoundation.ch/news/tezos-betanet-launch>`_.
-
-
 Getting started
 ---------------
 

docs/introduction/howtoget.rst

@@ -24,8 +24,9 @@ architecture **x86_64**.
 Although we only officially support Linux, the script has been tested
 with success in the past on windows/mac/linux.
 
-The same script can be used to run Alphanet or Zeronet, it suffices to
+The same script can be used to run Alphanet, Betanet or Zeronet, it
-rename it, it downloads a different image based on its name.
+suffices to rename it as it downloads a different image based on its
+name.
 For example, to run Alphanet:
 
 ::
@@ -33,15 +34,14 @@ For example, to run Alphanet:
     wget https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh
     chmod +x alphanet.sh
 
-Alternatively, to run Zeronet:
+Alternatively, to run Betanet:
 
 ::
 
-    wget -O zeronet.sh https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh
+    wget -O betanet.sh https://gitlab.com/tezos/tezos/raw/master/scripts/alphanet.sh
-    chmod +x zeronet.sh
+    chmod +x betanet.sh
 
 In the following we assume you are running Alphanet.
-
 You are now one step away from a working node:
 
 ::
@@ -83,7 +83,7 @@ Build from sources
 
 ::
 
-   sudo apt install -y git m4 build-essential patch unzip bubblewrap wget
+   sudo apt install -y rsync git m4 build-essential patch unzip bubblewrap wget
    wget https://github.com/ocaml/opam/releases/download/2.0.0/opam-2.0.0-x86_64-linux
    sudo cp opam-2.0.0-x86_64-linux /usr/local/bin/opam
    sudo chmod a+x /usr/local/bin/opam
@@ -113,6 +113,8 @@ The following OSes are reported to work:
 
 A Windows port is feasible and might be developed in the future.
 
+If ``bubblewrap`` is not available in your distribution you can also
+skip it and init opam with ``--disable-sandbox``.
 
 Get the sources
 ~~~~~~~~~~~~~~~
@@ -179,4 +181,5 @@ To add the default opam repository at a lower priority (for example to
 install or test other opam packages), you can use the following command:
 
 ::
-  opam repo add default --rank=-1
+
+   opam repo add default --rank=-1

docs/introduction/howtouse.rst

@@ -18,8 +18,13 @@ After a successful compilation, you should have the following binaries:
   and accuse on the Tezos network (see :ref:`howtorun`);
 - ``tezos-signer``: a client to remotely sign operations or blocks
   (see :ref:`signer`);
-- ``tezos-protocol-compiler``: a protocol compiler used for developing
+
-  new version of the economic protocol.
+Note that Alphanet and Zeronet only support the last version of the
+protocol which is always called `alpha` while Betanet must also
+support all past protocols.
+For this reason the name of the 3 daemons in Betanet contains the
+incremental number and the partial hash of the protocol they are bound
+to, such as ``tezos-{baker,endorser,accuser}-002-PsYLVpVv``.
 
 
 Read The Friendly Manual
@@ -111,12 +116,14 @@ default.  A more detailed documentation can be found in the :ref:`RPC index.
 <rpc>` The RPC interface must be enable in order for the clients
 to communicate with the node, but is should not be publically accessible on the
 internet. With the following command it is available uniquely on the
-`localhost` address of your machine.
+`localhost` address of your machine, on the default port ``8732``.
 
 ::
 
-   tezos-node run --rpc-addr [::]
+   tezos-node run --rpc-addr 127.0.0.1
 
+The node listens by default on port ``19732`` so it is advisable to
+open incoming connections to that port.
 You can read more about the :ref:`node configuration <node-conf>` and
 its :ref:`private mode <private-mode>`.
 
@@ -227,12 +234,22 @@ be included in one block.
 If you want to simulate a transaction without actually sending it to
 the network you can use the ``--dry-run`` option.
 As in any block-chain it is advisable to wait several blocks to
-consider the transaction as final, we can do that with:
+consider the transaction as final, for an important operation we
+advice to wait 60 blocks.
+We can do that with:
 
 ::
 
    tezos-client wait for <operation hash> to be included
 
+In the rare case when an operation is lost, how can we be sure that it
+will not be included in any future block and re-emit it?
+After 60 blocks a transaction is considered invalid and can't be
+included anymore in a block.
+Furthermore each operation has a counter (explained in more detail
+later) that prevents replays so it is usually safe to re-emit an
+operation that seems lost.
+
 
 Receipts for operations and blocks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -256,10 +273,7 @@ signed by that account and enforces some good intuitive properties:
 - each operation is applied once: for example if the transfer above
   reaches two peers and they both send it to a third peer, it will not
   apply the transaction twice.
-- operations are applied in order: if we emit a transaction towards
+- operations are applied in order.
-  *bob* and a transaction from *bob* to *test3*, we can be sure
-  that the second transaction will be applied only after *bob*
-  received its funds otherwise it may fail for insufficient balance.
 - all previous operations have been applied: if we emit operation *n*
   and *n+1*, and *n* gets lost then *n+1* cannot be applied.
 
@@ -419,11 +433,11 @@ It's RPCs all the way down
 The client communicates with the node uniquely through RPC calls so
 make sure that the node is listening and that the ports are
 correct.
-For example the ``bootstrapped`` command above is a shortcut for:
+For example the ``get timestamp`` command above is a shortcut for:
 
 ::
 
-   tezos-client rpc get /monitor/bootstrapped
+   tezos-client rpc get /chains/main/blocks/head/header/shell
 
 The client tries to simplify common tasks as much as possible, however
 if you want to query the node for more specific informations you'll