completed the site conversion to ReST, glossary updated, cleanup/maintenance improvements

conf.py

@@ -185,3 +185,37 @@
 
 # A list of files that should not be packed into the epub file.
 epub_exclude_files = ['search.html']
+
+# These ReST entries are included in every doc and are used to build
+# aliases to commonly-referenced items. For example, the use of 
+# :ref:`p2p-network-header` would produce the link text "P2P Network"
+# despite general use in documentation being "network". These aliases
+# improve readability and prevent unexpected content changes.
+#rst_prolog = ''
+rst_epilog = '''
+.. reference aliases
+.. |network| replace:: :ref:`network<dev-p2p-network-header>`
+.. |peer-to-peer network| replace:: :ref:`peer-to-peer network<dev-p2p-network-header>`
+
+.. frequently-used terms with links
+.. |ECDSA| replace:: `ECDSA <https://en.wikipedia.org/wiki/Elliptic_Curve_DSA>`__
+.. |secp256k1| replace:: `secp256k1 <http://www.secg.org/sec2-v2.pdf>`__
+
+.. OP codes
+.. |OP_CHECKMULTISIG| replace:: :term:`"OP_CHECKMULTISIG" <OP_CHECKMULTISIG>`
+.. |OP_CHECKSIG| replace:: :term:`"OP_CHECKSIG" <OP_CHECKSIG>`
+.. |OP_DUP| replace:: :term:`"OP_DUP" <OP_DUP>`
+.. |OP_EQUAL| replace:: :term:`"OP_EQUAL" <OP_EQUAL>`
+.. |OP_EQUALVERIFY| replace:: :term:`"OP_EQUALVERIFY" <OP_EQUALVERIFY>`
+.. |OP_HASH160| replace:: :term:`"OP_HASH160" <OP_HASH160>`
+.. |OP_RETURN| replace:: :term:`"OP_RETURN" <OP_RETURN>`
+.. |OP_VERIFY| replace:: :term:`"OP_VERIFY" <OP_VERIFY>`
+
+.. other
+.. |Bitcoin URI| replace:: :term:`"bitcoin:" URI <bitcoin uri>`
+.. |Bitcoin URIs| replace:: :term:`"bitcoin:" URIs <bitcoin uri>`
+.. |PaymentDetails| replace:: :term:`PaymentDetails`
+.. |PaymentRequest| replace:: :term:`PaymentRequest`
+.. |PaymentRequests| replace:: :term:`PaymentRequests <PaymentRequest>`
+.. |r| replace:: :term:`"r" <r>`
+'''

devguide/contracts.rst

@@ -1,3 +1,5 @@
+.. _dev-contracts-header:
+
 Contracts
 =========
 
@@ -17,9 +19,9 @@ Charlie-the-customer wants to buy a product from Bob-the-businessman, but neithe
 
 A simple contract could say that Charlie will spend satoshis to an output which can only be spent if Charlie and Bob both sign the input spending it. That means Bob won’t get paid unless Charlie gets his merchandise, but Charlie can’t get the merchandise and keep his payment.
 
-This simple contract isn’t much help if there’s a dispute, so Bob and Charlie enlist the help of Alice-the-arbitrator to create an :term:`escrow contract <Escrow contract>`. Charlie spends his satoshis to an output which can only be spent if two of the three people sign the input. Now Charlie can pay Bob if everything is ok, Bob can `refund <../devguide/payment_processing.html#issuing-refunds>`__ Charlie’s money if there’s a problem, or Alice can arbitrate and decide who should get the satoshis if there’s a dispute.
+This simple contract isn’t much help if there’s a dispute, so Bob and Charlie enlist the help of Alice-the-arbitrator to create an :term:`escrow contract`. Charlie spends his satoshis to an output which can only be spent if two of the three people sign the input. Now Charlie can pay Bob if everything is ok, Bob can `refund <../devguide/payment_processing.html#issuing-refunds>`_ Charlie’s money if there’s a problem, or Alice can arbitrate and decide who should get the satoshis if there’s a dispute.
 
-To create a multiple-signature (:term:`multisig <Multisig>`) output, they each give the others a public key. Then Bob creates the following :term:`P2SH multisig <P2SH multisig>` redeem script:
+To create a multiple-signature (:term:`multisig`) output, they each give the others a public key. Then Bob creates the following :term:`P2SH multisig` redeem script:
 
 ::
 
@@ -31,19 +33,19 @@ To create a multiple-signature (:term:`multisig <Multisig>`) output, they each g
 
 Bob gives the redeem script to Charlie, who checks to make sure his public key and Alice’s public key are included. Then he hashes the redeem script to create a P2SH redeem script and pays the satoshis to it. Bob sees the payment get added to the block chain and ships the merchandise.
 
-Unfortunately, the merchandise gets slightly damaged in transit. Charlie wants a full `refund <../devguide/payment_processing.html#issuing-refunds>`__, but Bob thinks a 10% `refund <../devguide/payment_processing.html#issuing-refunds>`__ is sufficient. They turn to Alice to resolve the issue. Alice asks for photo evidence from Charlie along with a copy of the redeem script Bob created and Charlie checked.
+Unfortunately, the merchandise gets slightly damaged in transit. Charlie wants a full refund_, but Bob thinks a 10% refund_ is sufficient. They turn to Alice to resolve the issue. Alice asks for photo evidence from Charlie along with a copy of the redeem script Bob created and Charlie checked.
 
-After looking at the evidence, Alice thinks a 40% `refund <../devguide/payment_processing.html#issuing-refunds>`__ is sufficient, so she creates and signs a transaction with two outputs, one that spends 60% of the satoshis to Bob’s public key and one that spends the remaining 40% to Charlie’s public key.
+After looking at the evidence, Alice thinks a 40% refund_ is sufficient, so she creates and signs a transaction with two outputs, one that spends 60% of the satoshis to Bob’s public key and one that spends the remaining 40% to Charlie’s public key.
 
 In the signature script Alice puts her signature and a copy of the unhashed serialized redeem script that Bob created. She gives a copy of the incomplete transaction to both Bob and Charlie. Either one of them can complete it by adding his signature to create the following signature script:
 
 ::
 
    OP_0 [A's signature] [B's or C's signature] [serialized redeem script]
 
-(Opcodes to push the signatures and redeem script onto the stack are not shown. ``OP_0`` is a workaround for an off-by-one error in the original implementation which must be preserved for compatibility. Note that the signature script must provide signatures in the same order as the corresponding public keys appear in the redeem script. See the description in :ref:`“OP_CHECKMULTISIG” <term-op-checkmultisig>` for details.)
+(Opcodes to push the signatures and redeem script onto the stack are not shown. ``OP_0`` is a workaround for an off-by-one error in the original implementation which must be preserved for compatibility. Note that the signature script must provide signatures in the same order as the corresponding public keys appear in the redeem script. See the description in |OP_CHECKMULTISIG| for details.)
 
-When the transaction is broadcast to the `network <../devguide/p2p_network.html>`__, each peer checks the signature script against the P2SH output Charlie previously paid, ensuring that the redeem script matches the redeem script hash previously provided. Then the redeem script is evaluated, with the two signatures being used as input data. Assuming the redeem script validates, the two transaction outputs show up in Bob’s and Charlie’s wallets as spendable balances.
+When the transaction is broadcast to the |network|, each peer checks the signature script against the P2SH output Charlie previously paid, ensuring that the redeem script matches the redeem script hash previously provided. Then the redeem script is evaluated, with the two signatures being used as input data. Assuming the redeem script validates, the two transaction outputs show up in Bob’s and Charlie’s wallets as spendable balances.
 
 However, if Alice created and signed a transaction neither of them would agree to, such as spending all the satoshis to herself, Bob and Charlie can find a new arbitrator and sign a transaction spending the satoshis to another 2-of-3 multisig redeem script hash, this one including a public key from that second arbitrator. This means that Bob and Charlie never need to worry about their arbitrator stealing their money.
 
@@ -52,26 +54,26 @@ However, if Alice created and signed a transaction neither of them would agree t
 Micropayment Channel
 --------------------
 
-Alice also works part time moderating forum posts for Bob. Every time someone posts to Bob’s busy forum, Alice skims the post to make sure it isn’t offensive or spam. Alas, Bob often forgets to pay her, so Alice demands to be paid immediately after each post she approves or rejects. Bob says he can’t do that because hundreds of small payments will cost him thousands of satoshis in transaction fees, so Alice suggests they use a :ref:`micropayment channel <term-micropayment-channel>`.
+Alice also works part time moderating forum posts for Bob. Every time someone posts to Bob’s busy forum, Alice skims the post to make sure it isn’t offensive or spam. Alas, Bob often forgets to pay her, so Alice demands to be paid immediately after each post she approves or rejects. Bob says he can’t do that because hundreds of small payments will cost him thousands of satoshis in transaction fees, so Alice suggests they use a :term:`micropayment channel`.
 
 Bob asks Alice for her public key and then creates two transactions. The first transaction pays 100 millibitcoins to a P2SH output whose 2-of-2 multisig redeem script requires signatures from both Alice and Bob. This is the bond transaction. Broadcasting this transaction would let Alice hold the millibitcoins hostage, so Bob keeps this transaction private for now and creates a second transaction.
 
-The second transaction spends all of the first transaction’s millibitcoins (minus a transaction fee) back to Bob after a 24 hour delay enforced by locktime. This is the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction. Bob can’t sign the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction by himself, so he gives it to Alice to sign, as shown in the illustration below.
+The second transaction spends all of the first transaction’s millibitcoins (minus a transaction fee) back to Bob after a 24 hour delay enforced by locktime. This is the refund_ transaction. Bob can’t sign the refund_ transaction by himself, so he gives it to Alice to sign, as shown in the illustration below.
 
 .. figure:: /img/dev/en-micropayment-channel.svg
    :alt: Micropayment Channel Example
 
    Micropayment Channel Example
 
-Alice checks that the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction’s locktime is 24 hours in the future, signs it, and gives a copy of it back to Bob. She then asks Bob for the bond transaction and checks that the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction spends the output of the bond transaction. She can now broadcast the bond transaction to the `network <../devguide/p2p_network.html>`__ to ensure Bob has to wait for the time lock to expire before further spending his millibitcoins. Bob hasn’t actually spent anything so far, except possibly a small transaction fee, and he’ll be able to broadcast the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction in 24 hours for a full `refund <../devguide/payment_processing.html#issuing-refunds>`__.
+Alice checks that the refund_ transaction’s locktime is 24 hours in the future, signs it, and gives a copy of it back to Bob. She then asks Bob for the bond transaction and checks that the refund_ transaction spends the output of the bond transaction. She can now broadcast the bond transaction to the |network| to ensure Bob has to wait for the time lock to expire before further spending his millibitcoins. Bob hasn’t actually spent anything so far, except possibly a small transaction fee, and he’ll be able to broadcast the refund_ transaction in 24 hours for a full refund_.
 
-Now, when Alice does some work worth 1 millibitcoin, she asks Bob to create and sign a new version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction. Version two of the transaction spends 1 millibitcoin to Alice and the other 99 back to Bob; it does not have a locktime, so Alice can sign it and spend it whenever she wants. (But she doesn’t do that immediately.)
+Now, when Alice does some work worth 1 millibitcoin, she asks Bob to create and sign a new version of the refund_ transaction. Version two of the transaction spends 1 millibitcoin to Alice and the other 99 back to Bob; it does not have a locktime, so Alice can sign it and spend it whenever she wants. (But she doesn’t do that immediately.)
 
-Alice and Bob repeat these work-and-pay steps until Alice finishes for the day, or until the time lock is about to expire. Alice signs the final version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction and broadcasts it, paying herself and refunding any remaining balance to Bob. The next day, when Alice starts work, they create a new :ref:`micropayment channel <term-micropayment-channel>`.
+Alice and Bob repeat these work-and-pay steps until Alice finishes for the day, or until the time lock is about to expire. Alice signs the final version of the refund_ transaction and broadcasts it, paying herself and refunding any remaining balance to Bob. The next day, when Alice starts work, they create a new :term:`micropayment channel`.
 
-If Alice fails to broadcast a version of the `refund <../devguide/payment_processing.html#issuing-refunds>`__ transaction before its time lock expires, Bob can broadcast the first version and receive a full `refund <../devguide/payment_processing.html#issuing-refunds>`__. This is one reason :ref:`micropayment channels <term-micropayment-channel>` are best suited to small payments—if Alice’s Internet service goes out for a few hours near the time lock expiry, she could be cheated out of her payment.
+If Alice fails to broadcast a version of the refund_ transaction before its time lock expires, Bob can broadcast the first version and receive a full refund_. This is one reason :term:`micropayment channels <micropayment channel>` are best suited to small payments—if Alice’s Internet service goes out for a few hours near the time lock expiry, she could be cheated out of her payment.
 
-Transaction malleability, discussed above in the Transactions section, is another reason to limit the value of :ref:`micropayment channels <term-micropayment-channel>`. If someone uses transaction malleability to break the link between the two transactions, Alice could hold Bob’s 100 millibitcoins hostage even if she hadn’t done any work.
+Transaction malleability, discussed above in the Transactions section, is another reason to limit the value of :term:`micropayment channels <micropayment channel>`. If someone uses transaction malleability to break the link between the two transactions, Alice could hold Bob’s 100 millibitcoins hostage even if she hadn’t done any work.
 
 For larger payments, Bitcoin transaction fees are very low as a percentage of the total transaction value, so it makes more sense to protect payments with immediately-broadcast separate transactions.
 

devguide/index.rst

@@ -1,3 +1,5 @@
+.. _dev-index-header:
+
 Developer Guides
 ================
 

devguide/mining.rst

@@ -1,3 +1,5 @@
+.. _dev-mining-header:
+
 Mining
 ======
 
@@ -15,7 +17,7 @@ Mining today takes on two forms:
 Solo Mining
 -----------
 
-As illustrated below, solo miners typically use ``bitcoind`` to get new transactions from the `network <../devguide/p2p_network.html>`__. Their mining software periodically polls ``bitcoind`` for new transactions using the `“getblocktemplate” RPC <../reference/rpc/getblocktemplate.html>`__, which provides the list of new transactions plus the public key to which the coinbase transaction should be sent.
+As illustrated below, solo miners typically use ``bitcoind`` to get new transactions from the |network|. Their mining software periodically polls ``bitcoind`` for new transactions using the `“getblocktemplate” RPC <../reference/rpc/getblocktemplate.html>`__, which provides the list of new transactions plus the public key to which the coinbase transaction should be sent.
 
 .. figure:: /img/dev/en-solo-mining-overview.svg
    :alt: Solo Bitcoin Mining
@@ -26,25 +28,25 @@ The mining software constructs a block using the template (described below) and
 
 If none of the hashes are below the threshold, the mining hardware gets an updated block header with a new merkle root from the mining software; this new block header is created by adding extra nonce data to the coinbase field of the coinbase transaction.
 
-On the other hand, if a hash is found below the target threshold, the mining hardware returns the block header with the successful nonce to the mining software. The mining software combines the header with the block and sends the completed block to ``bitcoind`` to be broadcast to the `network <../devguide/p2p_network.html>`__ for addition to the block chain.
+On the other hand, if a hash is found below the target threshold, the mining hardware returns the block header with the successful nonce to the mining software. The mining software combines the header with the block and sends the completed block to ``bitcoind`` to be broadcast to the |network| for addition to the block chain.
 
 Pool Mining
 -----------
 
-Pool miners follow a similar workflow, illustrated below, which allows mining pool operators to pay miners based on their share of the work done. The mining pool gets new transactions from the `network <../devguide/p2p_network.html>`__ using ``bitcoind``. Using one of the methods discussed later, each miner’s mining software connects to the pool and requests the information it needs to construct block headers.
+Pool miners follow a similar workflow, illustrated below, which allows mining pool operators to pay miners based on their share of the work done. The mining pool gets new transactions from the |network| using ``bitcoind``. Using one of the methods discussed later, each miner’s mining software connects to the pool and requests the information it needs to construct block headers.
 
 .. figure:: /img/dev/en-pooled-mining-overview.svg
    :alt: Pooled Bitcoin Mining
 
    Pooled Bitcoin Mining
 
-In pooled mining, the mining pool sets the target threshold a few orders of magnitude higher (less difficult) than the `network <../devguide/p2p_network.html>`__ difficulty. This causes the mining hardware to return many block headers which don’t hash to a value eligible for inclusion on the block chain but which do hash below the pool’s target, proving (on average) that the miner checked a percentage of the possible hash values.
+In pooled mining, the mining pool sets the target threshold a few orders of magnitude higher (less difficult) than the |network| difficulty. This causes the mining hardware to return many block headers which don’t hash to a value eligible for inclusion on the block chain but which do hash below the pool’s target, proving (on average) that the miner checked a percentage of the possible hash values.
 
 The miner then sends to the pool a copy of the information the pool needs to validate that the header will hash below the target and that the block of transactions referred to by the header merkle root field is valid for the pool’s purposes. (This usually means that the coinbase transaction must pay the pool.)
 
-The information the miner sends to the pool is called a share because it proves the miner did a share of the work. By chance, some shares the pool receives will also be below the `network <../devguide/p2p_network.html>`__ target—the mining pool sends these to the `network <../devguide/p2p_network.html>`__ to be added to the block chain.
+The information the miner sends to the pool is called a share because it proves the miner did a share of the work. By chance, some shares the pool receives will also be below the |network| target—the mining pool sends these to the |network| to be added to the block chain.
 
-The block reward and transaction fees that come from mining that block are paid to the mining pool. The mining pool pays out a portion of these proceeds to individual miners based on how many shares they generated. For example, if the mining pool’s target threshold is 100 times lower than the `network <../devguide/p2p_network.html>`__ target threshold, 100 shares will need to be generated on average to create a successful block, so the mining pool can pay 1/100th of its payout for each share received. Different mining pools use different reward distribution systems based on this basic share system.
+The block reward and transaction fees that come from mining that block are paid to the mining pool. The mining pool pays out a portion of these proceeds to individual miners based on how many shares they generated. For example, if the mining pool’s target threshold is 100 times lower than the |network| target threshold, 100 shares will need to be generated on average to create a successful block, so the mining pool can pay 1/100th of its payout for each share received. Different mining pools use different reward distribution systems based on this basic share system.
 
 Block Prototypes
 ----------------
@@ -67,7 +69,7 @@ An improved method is the Bitcoin Core `“getblocktemplate” RPC <../reference
 
 3. Other information necessary to construct a block header for the next block: the block version, previous block hash, and bits (target).
 
-4. The mining pool’s current target threshold for accepting shares. (For solo miners, this is the `network <../devguide/p2p_network.html>`__ target.)
+4. The mining pool’s current target threshold for accepting shares. (For solo miners, this is the |network| target.)
 
 Using the transactions received, the mining software adds a nonce to the coinbase extra nonce field and then converts all the transactions into a merkle tree to derive a merkle root it can use in a block header. Whenever the extra nonce field needs to be changed, the mining software rebuilds the necessary parts of the merkle tree and updates the time and merkle root fields in the block header.
 

devguide/operating_modes.rst

@@ -1,3 +1,5 @@
+.. _dev-operating-modes-header:
+
 Operating Modes
 ===============
 
@@ -11,9 +13,9 @@ Currently there are two primary methods of validating the block chain as a clien
 Full Node
 ---------
 
-The first and most secure model is the one followed by Bitcoin Core, also known as a “thick” or “full chain” client. This security model assures the validity of the block chain by downloading and validating blocks from the genesis block all the way to the most recently discovered block. This is known as using the *height* of a particular block to verify the client’s view of the `network <../devguide/p2p_network.html>`__.
+The first and most secure model is the one followed by Bitcoin Core, also known as a “thick” or “full chain” client. This security model assures the validity of the block chain by downloading and validating blocks from the genesis block all the way to the most recently discovered block. This is known as using the *height* of a particular block to verify the client’s view of the |network|.
 
-For a client to be fooled, an adversary would need to give a complete alternative block chain history that is of greater difficulty than the current “true” chain, which is computationally expensive (if not impossible) due to the fact that the chain with the most cumulative proof of work is by definition the “true” chain. Due to the computational difficulty required to generate a new block at the tip of the chain, the ability to fool a full node becomes very expensive after 6 confirmations. This form of verification is highly resistent to sybil attacks—only a single honest `network <../devguide/p2p_network.html>`__ peer is required in order to receive and verify the complete state of the “true” block chain.
+For a client to be fooled, an adversary would need to give a complete alternative block chain history that is of greater difficulty than the current “true” chain, which is computationally expensive (if not impossible) due to the fact that the chain with the most cumulative proof of work is by definition the “true” chain. Due to the computational difficulty required to generate a new block at the tip of the chain, the ability to fool a full node becomes very expensive after 6 confirmations. This form of verification is highly resistent to sybil attacks—only a single honest |network| peer is required in order to receive and verify the complete state of the “true” block chain.
 
 .. figure:: /img/dev/en-block-height-vs-depth.svg
    :alt: Block Height Compared To Block Depth
@@ -34,7 +36,7 @@ Potential SPV Weaknesses
 
 If implemented naively, an SPV client has a few important weaknesses.
 
-First, while the SPV client can not be easily fooled into thinking a transaction is in a block when it is not, the reverse is not true. A full node can simply lie by omission, leading an SPV client to believe a transaction has not occurred. This can be considered a form of Denial of Service. One mitigation strategy is to connect to a number of full nodes, and send the requests to each node. However this can be defeated by `network <../devguide/p2p_network.html>`__ partitioning or Sybil attacks, since identities are essentially free, and can be bandwidth intensive. Care must be taken to ensure the client is not cut off from honest nodes.
+First, while the SPV client can not be easily fooled into thinking a transaction is in a block when it is not, the reverse is not true. A full node can simply lie by omission, leading an SPV client to believe a transaction has not occurred. This can be considered a form of Denial of Service. One mitigation strategy is to connect to a number of full nodes, and send the requests to each node. However this can be defeated by |network| partitioning or Sybil attacks, since identities are essentially free, and can be bandwidth intensive. Care must be taken to ensure the client is not cut off from honest nodes.
 
 Second, the SPV client only requests transactions from full nodes corresponding to keys it owns. If the SPV client downloads all blocks and then discards unneeded ones, this can be extremely bandwidth intensive. If they simply ask full nodes for blocks with specific transactions, this allows full nodes a complete view of the public addresses that correspond to the user. This is a large privacy leak, and allows for tactics such as denial of service for clients, users, or addresses that are disfavored by those running full nodes, as well as trivial linking of funds. A client could simply spam many fake transaction requests, but this creates a large strain on the SPV client, and can end up defeating the purpose of thin clients altogether.
 
@@ -69,7 +71,7 @@ Bloom filters were standardized for use via `BIP37 <https://github.com/bitcoin/b
 Future Proposals
 ----------------
 
-There are future proposals such as Unspent Transaction Output (UTXO) commitments in the block chain to find a more satisfactory middle-ground for clients between needing a complete copy of the block chain, or trusting that a majority of your connected peers are not lying. UTXO commitments would enable a very secure client using a finite amount of storage using a data structure that is authenticated in the block chain. These type of proposals are, however, in very early stages, and will require soft forks in the `network <../devguide/p2p_network.html>`__.
+There are future proposals such as Unspent Transaction Output (UTXO) commitments in the block chain to find a more satisfactory middle-ground for clients between needing a complete copy of the block chain, or trusting that a majority of your connected peers are not lying. UTXO commitments would enable a very secure client using a finite amount of storage using a data structure that is authenticated in the block chain. These type of proposals are, however, in very early stages, and will require soft forks in the |network|.
 
 Until these types of operating modes are implemented, modes should be chosen based on the likely threat model, computing and bandwidth constraints, and liability in bitcoin value.
 

examples/index.rst

@@ -1,3 +1,5 @@
+.. _examples-index-header:
+
 Examples
 ========
 

examples/intro.rst

@@ -1,3 +1,5 @@
+.. _examples-intro-header:
+
 Introduction
 ============
 
@@ -31,7 +33,7 @@ You should also make the ``bitcoin.conf`` file only readable to its owner. On Li
 
    chmod 0600 bitcoin.conf
 
-For development, it’s safer and cheaper to use Bitcoin’s test `network <../devguide/p2p_network.html>`__ (testnet) or regression test mode (regtest) described below.
+For development, it’s safer and cheaper to use Bitcoin’s test |network| (testnet) or regression test mode (regtest) described below.
 
 Questions about Bitcoin use are best sent to the `BitcoinTalk forum <https://bitcointalk.org/index.php?board=4.0>`__ and `IRC channels <https://en.bitcoin.it/wiki/IRC_channels>`__. Errors or suggestions related to documentation on Bitcoin.org can be `submitted as an issue <https://github.com/bitcoin-dot-org/bitcoin.org/issues>`__ or posted to the `bitcoin-documentation mailing list <https://groups.google.com/forum/#!forum/bitcoin-documentation>`__.
 

examples/p2p_networking.rst

@@ -1,3 +1,5 @@
+.. _examples-p2p-networking-header:
+
 P2P Network
 -----------
 
@@ -203,7 +205,7 @@ Testing the filter against an arbitrary element, we get the failure output below
 Retrieving A MerkleBlock
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-For the `“merkleblock” message <../reference/p2p_networking.html#merkleblock>`__ documentation on the reference page, an actual merkle block was retrieved from the `network <../devguide/p2p_network.html>`__ and manually processed. This section walks through each step of the process, demonstrating basic `network <../devguide/p2p_network.html>`__ communication and merkle block processing.
+For the `“merkleblock” message <../reference/p2p_networking.html#merkleblock>`__ documentation on the reference page, an actual merkle block was retrieved from the |network| and manually processed. This section walks through each step of the process, demonstrating basic |network| communication and merkle block processing.
 
 .. highlight:: python
 
@@ -238,7 +240,7 @@ For the `“merkleblock” message <../reference/p2p_networking.html#merkleblock
        )
        sys.stdout.flush()
 
-To connect to the P2P `network <../devguide/p2p_network.html>`__, the trivial Python function above was developed to compute message headers and send payloads decoded from hex.
+To connect to the P2P |network|, the trivial Python function above was developed to compute message headers and send payloads decoded from hex.
 
 .. highlight:: python
 
@@ -261,7 +263,7 @@ To connect to the P2P `network <../devguide/p2p_network.html>`__, the trivial Py
        + "00" # .............................. Relay transactions: false
    )
 
-Peers on the `network <../devguide/p2p_network.html>`__ will not accept any requests until you send them a `“version” message <../reference/p2p_networking.html#version>`__. The receiving node will reply with their `“version” message <../reference/p2p_networking.html#version>`__ and a `“verack” message <../reference/p2p_networking.html#verack>`__.
+Peers on the |network| will not accept any requests until you send them a `“version” message <../reference/p2p_networking.html#version>`__. The receiving node will reply with their `“version” message <../reference/p2p_networking.html#version>`__ and a `“verack” message <../reference/p2p_networking.html#verack>`__.
 
 .. highlight:: python
 
@@ -313,7 +315,7 @@ Part of the response is shown in the section below.
 Parsing A MerkleBlock
 ~~~~~~~~~~~~~~~~~~~~~
 
-In the section above, we retrieved a merkle block from the `network <../devguide/p2p_network.html>`__; now we will parse it. Most of the block header has been omitted. For a more complete hexdump, see the example in the ```merkleblock`` message section <../reference/p2p_networking.html#merkleblock>`__.
+In the section above, we retrieved a merkle block from the |network|; now we will parse it. Most of the block header has been omitted. For a more complete hexdump, see the example in the ```merkleblock`` message section <../reference/p2p_networking.html#merkleblock>`__.
 
 .. highlight:: text
 

examples/testing.rst

@@ -1,3 +1,5 @@
+.. _examples-testing-header:
+
 Testing Applications
 --------------------
 
@@ -6,7 +8,7 @@ Bitcoin Core provides testing tools designed to let developers test their applic
 Testnet
 ~~~~~~~
 
-When run with no arguments, all Bitcoin Core programs default to Bitcoin’s main `network <../devguide/p2p_network.html>`__ (:term:`mainnet <Mainnet>`). However, for development, it’s safer and cheaper to use Bitcoin’s test `network <../devguide/p2p_network.html>`__ (testnet) where the satoshis spent have no real-world value. Testnet also relaxes some restrictions (such as standard transaction checks) so you can test functions which might currently be disabled by default on mainnet.
+When run with no arguments, all Bitcoin Core programs default to Bitcoin’s main |network| (:term:`mainnet`). However, for development, it’s safer and cheaper to use Bitcoin’s test |network| (testnet) where the satoshis spent have no real-world value. Testnet also relaxes some restrictions (such as standard transaction checks) so you can test functions which might currently be disabled by default on mainnet.
 
 To use testnet, use the argument ``-testnet`` with ``bitcoin-cli``, ``bitcoind`` or ``bitcoin-qt`` or add ``testnet=1`` to your ``bitcoin.conf`` file as `described earlier <../examples/index.html>`__. To get free satoshis for testing, use `Piotr Piasecki’s testnet faucet <https://tpfaucet.appspot.com/>`__. Testnet is a public resource provided for free by members of the community, so please don’t abuse it.
 

examples/transactions.rst

@@ -1,3 +1,5 @@
+.. _examples-transactions-header:
+
 Transactions
 ------------
 
@@ -165,7 +167,7 @@ This subsection covers one of the simplest possible raw transactions.
       > UTXO_TXID=3f4fa19803dec4d6a84fae3821da7ac7577080ef75451294e71f[...]
       > UTXO_VOUT=0
 
-Re-run `“listunspent” <../reference/rpc/listunspent.html>`__. We now have three UTXOs: the two transactions we created before plus the coinbase transaction from block #2. We save the txid and :ref:`output index <term-output-index>` number (vout) of that coinbase UTXO to shell variables.
+Re-run `“listunspent” <../reference/rpc/listunspent.html>`__. We now have three UTXOs: the two transactions we created before plus the coinbase transaction from block #2. We save the txid and :term:`output index` number (vout) of that coinbase UTXO to shell variables.
 
 .. highlight:: bash
 
@@ -288,7 +290,7 @@ Use the `“decoderawtransaction” RPC <../reference/rpc/decoderawtransaction.h
 
 Use the ``signrawtransaction`` `RPC <../reference/rpc/index.html>`__ to sign the transaction created by `“createrawtransaction” <../reference/rpc/createrawtransaction.html>`__ and save the returned “hex” raw format signed transaction to a shell variable.
 
-Even though the transaction is now complete, the Bitcoin Core node we’re connected to doesn’t know anything about the transaction, nor does any other part of the `network <../devguide/p2p_network.html>`__. We’ve created a spend, but we haven’t actually spent anything because we could simply unset the ``$SIGNED_RAW_TX`` variable to eliminate the transaction.
+Even though the transaction is now complete, the Bitcoin Core node we’re connected to doesn’t know anything about the transaction, nor does any other part of the |network|. We’ve created a spend, but we haven’t actually spent anything because we could simply unset the ``$SIGNED_RAW_TX`` variable to eliminate the transaction.
 
 .. highlight:: bash
 
@@ -391,7 +393,7 @@ In this example, we’ll create a transaction with two inputs and two outputs. W
       > UTXO2_VOUT=0
       > UTXO2_ADDRESS=muhtvdmsnbQEPFuEmxcChX58fGvXaaUoVt
 
-For our two inputs, we select two UTXOs by placing the txid and :ref:`output index <term-output-index>` numbers (vouts) in shell variables. We also save the addresses corresponding to the public keys (hashed or unhashed) used in those transactions. We need the addresses so we can get the corresponding private keys from our wallet.
+For our two inputs, we select two UTXOs by placing the txid and :term:`output index` numbers (vouts) in shell variables. We also save the addresses corresponding to the public keys (hashed or unhashed) used in those transactions. We need the addresses so we can get the corresponding private keys from our wallet.
 
 .. highlight:: bash
 
@@ -682,7 +684,7 @@ Put the previously signed (but not sent) transaction into a shell variable.
       > UTXO_VALUE=10.00000000
       > UTXO_OUTPUT_SCRIPT=76a914fa5139067622fd7e1e722a05c17c2bb7d5fd6[...]
 
-Decode the signed raw transaction so we can get its txid. Also, choose a specific one of its UTXOs to spend and save that UTXO’s :ref:`output index <term-output-index>` number (vout) and hex pubkey script (scriptPubKey) into shell variables.
+Decode the signed raw transaction so we can get its txid. Also, choose a specific one of its UTXOs to spend and save that UTXO’s :term:`output index` number (vout) and hex pubkey script (scriptPubKey) into shell variables.
 
 .. highlight:: bash
 
@@ -748,7 +750,7 @@ Attempt to sign the raw transaction without any special arguments, the way we su
 
 As illustrated above, the data that gets signed includes the txid and vout from the previous transaction. That information is included in the `“createrawtransaction” <../reference/rpc/createrawtransaction.html>`__ raw transaction. But the data that gets signed also includes the pubkey script from the previous transaction, even though it doesn’t appear in either the unsigned or signed transaction.
 
-In the other raw transaction subsections above, the previous output was part of the UTXO set known to the wallet, so the wallet was able to use the txid and :ref:`output index <term-output-index>` number to find the previous pubkey script and insert it automatically.
+In the other raw transaction subsections above, the previous output was part of the UTXO set known to the wallet, so the wallet was able to use the txid and :term:`output index` number to find the previous pubkey script and insert it automatically.
 
 In this case, you’re spending an output which is unknown to the wallet, so it can’t automatically insert the previous pubkey script.
 
@@ -1038,7 +1040,7 @@ We save that txid to a shell variable as the txid of the UTXO we plan to spend n
       > UTXO_VOUT=0
       > UTXO_OUTPUT_SCRIPT=a9149af61346ce0aa2dffcf697352b4b704c84dcbaff87
 
-We use the `“getrawtransaction” RPC <../reference/rpc/getrawtransaction.html>`__ with the optional second argument (*true*) to get the decoded transaction we just created with `“sendtoaddress” <../reference/rpc/sendtoaddress.html>`__. We choose one of the outputs to be our UTXO and get its :ref:`output index <term-output-index>` number (vout) and pubkey script (scriptPubKey).
+We use the `“getrawtransaction” RPC <../reference/rpc/getrawtransaction.html>`__ with the optional second argument (*true*) to get the decoded transaction we just created with `“sendtoaddress” <../reference/rpc/sendtoaddress.html>`__. We choose one of the outputs to be our UTXO and get its :term:`output index` number (vout) and pubkey script (scriptPubKey).
 
 .. highlight:: bash
 

reference/block_chain.rst

@@ -1,3 +1,5 @@
+.. _reference-block-chain-header:
+
 Block Chain
 -----------
 
@@ -13,7 +15,7 @@ Block headers are serialized in the 80-byte format described below and then hash
 +=======+==========================================================================================+===========+=================================================================================================================================================================================================================================================================================================================================================+
 | 4     | version                                                                                  | int32_t   | The :term:`block version <Block>` number indicates which set of block validation rules to follow. See the list of block versions below.                                                                                                                                                                                                         |
 +-------+------------------------------------------------------------------------------------------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| 32    | :ref:`previous block header hash <term-previous-block-header-hash>`                      | char[32]  | A SHA256(SHA256()) hash in internal byte order of the previous block’s header. This ensures no previous block can be changed without also changing this block’s header.                                                                                                                                                                         |
+| 32    | :term:`previous block header hash`                                                       | char[32]  | A SHA256(SHA256()) hash in internal byte order of the previous block’s header. This ensures no previous block can be changed without also changing this block’s header.                                                                                                                                                                         |
 +-------+------------------------------------------------------------------------------------------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 | 32    | merkle root hash                                                                         | char[32]  | A SHA256(SHA256()) hash in internal byte order. The merkle root is derived from the hashes of all transactions included in this block, ensuring that none of those transactions can be modified without modifying the header. See the `merkle trees section <../reference/block_chain.html#merkle-trees>`__ below.                              |
 +-------+------------------------------------------------------------------------------------------+-----------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -48,9 +50,9 @@ Block Versions
 
 -  **Version 1** was introduced in the genesis block (January 2009).
 
--  :ref:`Version 2 <term-v2-block>` was introduced in `Bitcoin Core 0.7.0 <https://bitcoin.org/en/release/v0.7.0>`__ (September 2012) as a soft fork. As described in `BIP34 <https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki>`__, valid :ref:`version 2 blocks <term-v2-block>` require a :ref:`block height parameter in the coinbase <term-coinbase-block-height>`. Also described in `BIP34 <https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki>`__ are rules for rejecting certain blocks; based on those rules, `Bitcoin Core 0.7.0 <https://bitcoin.org/en/release/v0.7.0>`__ and later versions began to reject :ref:`version 2 blocks <term-v2-block>` without the block height in coinbase at block height 224,412 (March 2013) and began to reject new version 1 blocks three weeks later at block height 227,930.
+-  **Version 2** was introduced in `Bitcoin Core 0.7.0 <https://bitcoin.org/en/release/v0.7.0>`__ (September 2012) as a soft fork. As described in `BIP34 <https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki>`__, valid version 2 blocks require a :term:`block height parameter in the coinbase <coinbase block height>`. Also described in `BIP34 <https://github.com/bitcoin/bips/blob/master/bip-0034.mediawiki>`__ are rules for rejecting certain blocks; based on those rules, `Bitcoin Core 0.7.0 <https://bitcoin.org/en/release/v0.7.0>`__ and later versions began to reject version 2 blocks without the block height in coinbase at block height 224,412 (March 2013) and began to reject new version 1 blocks three weeks later at block height 227,930.
 
--  **Version 3** blocks were introduced in `Bitcoin Core 0.10.0 <https://bitcoin.org/en/release/v0.10.0>`__ (February 2015) as a soft fork. When the fork reached full enforcement (July 2015), it required strict `DER <https://en.wikipedia.org/wiki/X.690#DER_encoding>`__ encoding of all `ECDSA <https://en.wikipedia.org/wiki/Elliptic_Curve_DSA>`__ signatures in new blocks as described in `BIP66 <https://github.com/bitcoin/bips/blob/master/bip-0066.mediawiki>`__. Transactions that do not use strict `DER <https://en.wikipedia.org/wiki/X.690#DER_encoding>`__ encoding had previously been non-standard since `Bitcoin Core 0.8.0 <https://bitcoin.org/en/release/v0.8.0>`__ (February 2012).
+-  **Version 3** blocks were introduced in `Bitcoin Core 0.10.0 <https://bitcoin.org/en/release/v0.10.0>`__ (February 2015) as a soft fork. When the fork reached full enforcement (July 2015), it required strict `DER <https://en.wikipedia.org/wiki/X.690#DER_encoding>`__ encoding of all |ECDSA| signatures in new blocks as described in `BIP66 <https://github.com/bitcoin/bips/blob/master/bip-0066.mediawiki>`__. Transactions that do not use strict `DER <https://en.wikipedia.org/wiki/X.690#DER_encoding>`__ encoding had previously been non-standard since `Bitcoin Core 0.8.0 <https://bitcoin.org/en/release/v0.8.0>`__ (February 2012).
 
 -  **Version 4** blocks specified in BIP65 and introduced in `Bitcoin Core 0.11.2 <https://bitcoin.org/en/release/v0.11.2>`__ (November 2015) as a soft fork became active in December 2015. These blocks now support the new ``OP_CHECKLOCKTIMEVERIFY`` opcode described in that BIP.
 

reference/index.rst

@@ -1,3 +1,5 @@
+.. _reference-index-header:
+
 Reference
 =========
 

reference/intro.rst

@@ -1,3 +1,5 @@
+.. _reference-intro-header:
+
 Introduction
 ============
 
@@ -14,9 +16,9 @@ Not A Specification
 
 The Bitcoin.org Developer Documentation describes how Bitcoin works to help educate new Bitcoin developers, but it is not a specification—and it never will be.
 
-Bitcoin security depends on consensus. Should your program diverge from consensus, its security is weakened or destroyed. The cause of the divergence doesn’t matter: it could be a bug in your program, it could be an `error in this documentation <https://github.com/bitcoin-dot-org/bitcoin.org/issues?q=is%3Aissue+label%3A%22Dev+Docs%22>`__ which you implemented as described, or it could be you do everything right but other software on the `network <../devguide/p2p_network.html>`__ `behaves unexpectedly <https://bitcoin.org/en/alert/2013-03-11-chain-fork>`__. The specific cause will not matter to the users of your software whose wealth is lost.
+Bitcoin security depends on consensus. Should your program diverge from consensus, its security is weakened or destroyed. The cause of the divergence doesn’t matter: it could be a bug in your program, it could be an `error in this documentation <https://github.com/bitcoin-dot-org/bitcoin.org/issues?q=is%3Aissue+label%3A%22Dev+Docs%22>`__ which you implemented as described, or it could be you do everything right but other software on the |network| `behaves unexpectedly <https://bitcoin.org/en/alert/2013-03-11-chain-fork>`__. The specific cause will not matter to the users of your software whose wealth is lost.
 
-The only correct specification of consensus behavior is the actual behavior of programs on the `network <../devguide/p2p_network.html>`__ which maintain consensus. As that behavior is subject to arbitrary inputs in a large variety of unique environments, it cannot ever be fully documented here or anywhere else.
+The only correct specification of consensus behavior is the actual behavior of programs on the |network| which maintain consensus. As that behavior is subject to arbitrary inputs in a large variety of unique environments, it cannot ever be fully documented here or anywhere else.
 
 However, the Bitcoin Core developers are working on making their consensus code portable so other implementations can use it. `Bitcoin Core 0.10.0 <https://bitcoin.org/en/release/v0.10.0>`__ provided ``libbitcoinconsensus``, as the first attempt at exporting some consensus code. Future versions of Bitcoin Core also provided consensus code that is more complete, more portable, and more consistent in diverse environments.
 

reference/wallets.rst

@@ -1,3 +1,5 @@
+.. _reference-wallets-header:
+
 Wallets
 -------