Create a "Testing Applications" subsection in devel-examples

Move existing "regtest / testnet" texts to the new subsection and link to it
Move Bitcoin Core setup instructions in devel-examples
Add a consistent introduction for devel-(guide/ref/examples)
Fix autocrossref.rb to not add links inside {% highlight %} code blocks

_autocrossref.yaml

@@ -157,6 +157,8 @@ recurrent rebilling:
 redeemScript:
 refund: 
 refunds: refund
+regression test mode:
+regtest: regression test mode
 root certificate:
 root seed:
 RPCs: rpc

_includes/example_intro.md

@@ -0,0 +1,45 @@
+{% autocrossref %}
+
+The following guide aims to provide examples to help you start
+building Bitcoin-based applications. To make the best use of this document,
+you may want to install the current version of Bitcoin Core, either from
+[source][core git] or from a [pre-compiled executable][core executable].
+
+Once installed, you'll have access to three programs: `bitcoind`,
+`bitcoin-qt`, and `bitcoin-cli`.
+
+* `bitcoin-qt` provides a combination full Bitcoin peer and wallet
+  frontend. From the Help menu, you can access a console where you can
+  enter the RPC commands used throughout this document.
+
+* `bitcoind` is more useful for programming: it provides a full peer
+  which you can interact with through RPCs to port 8332 (or 18332
+  for testnet).
+
+* `bitcoin-cli` allows you to send RPC commands to `bitcoind` from the
+  command line.  For example, `bitcoin-cli help`
+
+All three programs get settings from `bitcoin.conf` in the `Bitcoin`
+application directory:
+
+* Windows: `%APPDATA%\Bitcoin\`
+
+* OSX: `$HOME/Library/Application Support/Bitcoin/`
+
+* Linux: `$HOME/.bitcoin/`
+
+For development, it's safer and cheaper to use Bitcoin's test network (testnet)
+or regression test mode (regtest) described below.
+
+Questions about Bitcoin development are best sent to the Bitcoin [Forum][forum
+tech support] and [IRC channels][]. Errors or suggestions related to
+documentation on Bitcoin.org can be [submitted as an issue][docs issue]
+or posted to the [bitcoin-documentation mailing list][].
+
+In the following documentation, some strings have been shortened or wrapped: "[...]"
+indicates extra data was removed, and lines ending in a single backslash "\\"
+are continued below. If you hover your mouse over a paragraph, cross-reference
+links will be shown in blue.  If you hover over a cross-reference link, a brief
+definition of the term will be displayed in a tooltip.
+
+{% endautocrossref %}

_includes/example_payment_processing.md

@@ -7,6 +7,8 @@
 To request payment using the payment protocol, you use an extended (but
 backwards-compatible) `bitcoin:` URI.  For example:
 
+{% endautocrossref %}
+
 ~~~
 bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\
 ?amount=0.10\
@@ -15,6 +17,8 @@ bitcoin:mjSk1Ny9spzU2fouzYgLqGUD8U41iR35QN\
 &r=https://example.com/pay.php/invoice%3Dda39a3ee
 ~~~
 
+{% autocrossref %}
+
 The browser, QR code reader, or other program processing the URI opens
 the spender's Bitcoin wallet program on the URI. If the wallet program is
 aware of the payment protocol, it accesses the URL specified in the `r`

_includes/example_testing.md

@@ -0,0 +1,91 @@
+## Testing Applications
+
+{% autocrossref %}
+
+Bitcoin Core provides testing tools designed to let developers
+test their applications with reduced risks and limitations.
+
+{% endautocrossref %}
+
+### Testnet
+
+{% autocrossref %}
+
+When run with no arguments, all Bitcoin Core programs default to Bitcoin's main
+network ([mainnet][mainnet]{:#term-mainnet}{:.term}). 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.  To get
+free satoshis for testing, use [Piotr Piasecki's testnet faucet][].
+Testnet is a public resource provided for free by members of the
+community, so please don't abuse it.
+
+{% endautocrossref %}
+
+### Regtest Mode
+
+{% autocrossref %}
+
+For situations
+where interaction with random peers and blocks is unnecessary or
+unwanted, Bitcoin Core's regression test mode (regtest mode) lets you
+instantly create a brand-new private block chain with the same basic
+rules as testnet---but one major difference: you choose when to create
+new blocks, so you have complete control over the environment.
+
+Many developers consider regtest mode the preferred way to develop new
+applications. The following example will let you create a regtest
+environment.
+
+{% endautocrossref %}
+
+{% highlight bash %}
+> bitcoind -regtest -daemon
+Bitcoin server starting
+{% endhighlight %}
+
+{% autocrossref %}
+
+Start `bitcoind` in regtest mode to create a private block chain.
+
+{% endautocrossref %}
+
+~~~
+bitcoin-cli -regtest setgenerate true 101
+~~~
+
+{% autocrossref %}
+
+Generate 101 blocks using a special version of the `setgenerate` RPC
+which is only available in regtest mode. This takes about 30 seconds on
+a generic PC. Because this is a new block chain using Bitcoin's default
+rules, the first 210,000 blocks pay a block reward of 50 bitcoins.
+However, a block must have 100 confirmations before that reward can be
+spent, so we generate 101 blocks to get access to the coinbase
+transaction from block #1.
+
+{% endautocrossref %}
+
+{% highlight bash %}
+bitcoin-cli -regtest getbalance
+50.00000000
+{% endhighlight %}
+
+{% autocrossref %}
+
+Verify that we now have 50 bitcoins available to spend.
+
+You can now use Bitcoin Core RPCs prefixed with <!--[-->`bitcoin-cli -regtest`<!--]-->.
+
+Regtest wallets and block chain state (chainstate) are saved in the <!--[-->`regtest`<!--]-->
+subdirectory of the Bitcoin Core configuration directory. You can safely
+delete the <!--[-->`regtest`<!--]--> subdirectory and restart Bitcoin Core to
+start a new regtest. (See the [Developer Examples Introduction][devexamples] for default
+configuration directory locations on various operating systems. Always back up
+mainnet wallets before performing dangerous operations such as deleting.)
+
+{% endautocrossref %}

_includes/example_transactions.md

@@ -13,67 +13,8 @@ transactions, but in any system, you will need to provide the same kinds
 of data to create transactions with the same attributes as those
 described below.
 
-You are encouraged to try the following examples on your own using the
+In order to use this tutorial, you will need to setup [Bitcoin Core][core executable]
-regtest mode described below.
+and create a [regression test mode][] environment.
-
-Note: as in other parts of the documentation, we wrap long strings with
-"\\" and indicate omissions with "[...]".
-
-{% endautocrossref %}
-
-#### Regtest Mode
-
-{% autocrossref %}
-
-Bitcoin's testnet provides an excellent way to test Bitcoin
-functionality without risking real satoshis. However, for situations
-where interaction with random peers and blocks is unnecessary or
-unwanted, Bitcoin Core's regression test (regtest) mode lets you
-instantly create a brand-new private block chain with the same basic
-rules as testnet---but one major difference: you choose when to create
-new blocks, so you have complete control over the environment.
-
-Many developers consider regtest mode the preferred way to develop new
-applications, and this tutorial will use it exclusively. 
-
-{% highlight bash %}
-> bitcoind -regtest -daemon
-Bitcoin server starting
-{% endhighlight %}
-
-Start `bitcoind` in regtest mode to create a private block chain.
-
-{% highlight bash %}
-> bitcoin-cli -regtest getbalance
-0.00000000
-{% endhighlight %}
-
-Check our starting balance with the `getbalance` RPC. Regtest wallets
-and block chain state (chainstate) are saved in the `regtest`
-subdirectory of the Bitcoin Core configuration directory. You can safely
-delete the `regtest` subdirectory and restart Bitcoin Core to start a
-new regtest. (See the [Guide Introduction][devguide] for default configuration
-directory locations on various operating systems. Always back up mainnet
-wallets before performing dangerous operations such as deleting.)
-
-~~~
-bitcoin-cli -regtest setgenerate true 101
-~~~
-
-Generate 101 blocks using a special version of the `setgenerate` RPC
-which is only available in regtest mode. This takes about 30 seconds on
-a generic PC. Because this is a new block chain using Bitcoin's default
-rules, the first 210,000 blocks pay a block reward of 50 bitcoins.
-However, a block must have 100 confirmations before that reward can be
-spent, so we generate 101 blocks to get access to the coinbase
-transaction from block #1.
-
-{% highlight bash %}
-bitcoin-cli -regtest getbalance
-50.00000000
-{% endhighlight %}
-
-Verify that we now have 50 bitcoins available to spend.
 
 {% endautocrossref %}
 
@@ -163,11 +104,11 @@ the spend to the address we provided. If we had spent those satoshis to
 someone else, that second transaction would not be displayed in our
 list of UTXOs.
 
-~~~
+{% highlight bash %}
 > bitcoin-cli -regtest setgenerate true 1
 
 > unset NEW_ADDRESS
-~~~
+{% endhighlight %}
 
 Create a new block to confirm the transaction above (takes less than a
 second) and clear the shell variable.
@@ -379,11 +320,11 @@ Send the signed transaction to the connected node using the
 would usually then broadcast it to other peers, but we're not currently
 connected to other peers because we started in regtest mode.
 
-~~~
+{% highlight bash %}
 > bitcoin-cli -regtest setgenerate true 1
 
 > unset UTXO_TXID UTXO_VOUT NEW_ADDRESS RAW_TX SIGNED_RAW_TX
-~~~
+{% endhighlight %}
 
 Generate a block to confirm the transaction and clear our shell
 variables.

_includes/guide_intro.md

@@ -1,62 +1,19 @@
 {% autocrossref %}
 
-The Developer Guide aims to provide the information you need to start
+The Developer Guide aims to provide the explanations you need to understand
-building Bitcoin-based applications. To make the best use of this guide,
+Bitcoin and start building Bitcoin-based applications. To make the best use of
-you may want to install the current version of Bitcoin Core, either from
+this documentation, you may want to install the current version of Bitcoin
-[source][core git] or from a [pre-compiled executable][core executable].
+Core, either from [source][core git] or from a [pre-compiled executable][core executable].
-
-Once installed, you'll have access to three programs: `bitcoind`,
-`bitcoin-qt`, and `bitcoin-cli`.  When run with no arguments, all three
-programs default to Bitcoin's main network ([mainnet][mainnet]{:#term-mainnet}{:.term}) which will require
-you purchase satoshis in order to generate transactions.
-
-However, for development, it's safer and cheaper to use Bitcoin's test
-network ([testnet][testnet]{:#term-testnet}{:.term}) 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`<!--noref--> with each program or add
-`testnet=1`<!--noref--> to your `bitcoin.conf` file.  To get
-free satoshis for testing, use [Piotr Piasecki's testnet faucet][].
-Testnet is a public resource provided for free by members of the
-community, so please don't abuse it.  
-
-You can speed up development further using the [regression test mode][]
-which creates a new testnet local to your computer. This regtest mode
-will let you generate blocks almost instantly with a RPC command so you
-can generate your own satoshis and add transactions to the block chain
-immediately.
-
-* `bitcoin-qt` provides a combination full Bitcoin peer and wallet
-  frontend. From the Help menu, you can access a console where you can
-  enter the RPC commands used throughout this document.
-
-* `bitcoind` is more useful for programming: it provides a full peer
-  which you can interact with through RPCs to port 8332 (or 18332
-  for testnet).
-
-* `bitcoin-cli` allows you to send RPC commands to `bitcoind` from the
-  command line.  For example, `bitcoin-cli help`
-
-All three programs get settings from `bitcoin.conf` in the `Bitcoin`
-application directiory:
-
-* Windows: `%APPDATA%\Bitcoin\`
-
-* OSX: `$HOME/Library/Application Support/Bitcoin/`
-
-* Linux: `$HOME/.bitcoin/`
 
 Questions about Bitcoin development are best sent to the Bitcoin [Forum][forum
 tech support] and [IRC channels][]. Errors or suggestions related to
 documentation on Bitcoin.org can be [submitted as an issue][docs issue]
 or posted to the [bitcoin-documentation mailing list][].
 
-In the following guide, 
+In the following documentation, some strings have been shortened or wrapped: "[...]"
-some strings have been shortened or wrapped: "[...]" indicates extra data was removed, and lines ending in a single backslash "\\" are continued below.
+indicates extra data was removed, and lines ending in a single backslash "\\"
-If you hover your mouse over a paragraph, cross-reference links will be
+are continued below. If you hover your mouse over a paragraph, cross-reference
-shown in blue.  If you hover over a cross-reference link, a brief
+links will be shown in blue.  If you hover over a cross-reference link, a brief
 definition of the term will be displayed in a tooltip.
 
 {% endautocrossref %}

_includes/ref_intro.md

@@ -0,0 +1,19 @@
+{% autocrossref %}
+
+The Developer Reference aims to provide specifications and APIs information
+to help you start building Bitcoin-based applications. To make the best use of
+this documentation, you may want to install the current version of Bitcoin
+Core, either from [source][core git] or from a [pre-compiled executable][core executable].
+
+Questions about Bitcoin development are best sent to the Bitcoin [Forum][forum
+tech support] and [IRC channels][]. Errors or suggestions related to
+documentation on Bitcoin.org can be [submitted as an issue][docs issue]
+or posted to the [bitcoin-documentation mailing list][].
+
+In the following documentation, some strings have been shortened or wrapped: "[...]"
+indicates extra data was removed, and lines ending in a single backslash "\\"
+are continued below. If you hover your mouse over a paragraph, cross-reference
+links will be shown in blue.  If you hover over a cross-reference link, a brief
+definition of the term will be displayed in a tooltip.
+
+{% endautocrossref %}

_includes/ref_transactions.md

@@ -101,8 +101,6 @@ Nolan provided the following example encoding algorithm to the Bitcoin
 Wiki [Base58Check
 encoding](https://en.bitcoin.it/wiki/Base58Check_encoding) page:
 
-{% endautocrossref %}
-
 {% highlight c %}
 code_string = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz"
 x = convert_bytes_to_big_integer(hash_result)
@@ -123,8 +121,6 @@ repeat(number_of_leading_zero_bytes_in_hash)
 output_string.reverse();
 {% endhighlight %}
 
-{% autocrossref %}
-
 Bitcoin's own code can be traced using the [base58 header
 file][core base58.h].
 

_includes/references.md

@@ -52,7 +52,7 @@
 [leaf certificate]: /en/developer-examples#term-leaf-certificate "The end-node in a certificate chain; in the payment protocol, it is the certificate belonging to the receiver of satoshis"
 [locktime]: /en/developer-guide#term-locktime "Part of a transaction which indicates the earliest time or earliest block when that transaction can be added to the block chain"
 [long-term fork]: /en/developer-guide#term-long-term-fork "When a series of blocks have corresponding block heights, indicating a possibly serious problem"
-[mainnet]: /en/developer-guide#term-mainnet "The Bitcoin main network used to transfer satoshis (compare to testnet, the test network)"
+[mainnet]: /en/developer-examples#term-mainnet "The Bitcoin main network used to transfer satoshis (compare to testnet, the test network)"
 [master chain code]: /en/developer-guide#term-master-chain-code "The chain code derived from the root seed"
 [master private key]: /en/developer-guide#term-master-private-key "A private key derived from the root seed"
 [merge]: /en/developer-guide#term-merge "Spending, in the same transaction, multiple outputs which can be traced back to different previous spenders, leaking information about how many satoshis you control"
@@ -116,6 +116,7 @@
 [recurrent rebilling]: /en/developer-guide#rebilling-recurring-payments "Billing a spender on a regular schedule"
 [redeemScript]: /en/developer-guide#term-redeemscript "A script created by the recipient, hashed, and given to the spender for use in a P2SH output"
 [refund]: /en/developer-guide#issuing-refunds "A transaction which refunds some or all satoshis received in a previous transaction"
+[regression test mode]: /en/developer-examples#regtest-mode "A local testing environment in which developers can control blocks"
 [root certificate]: /en/developer-examples#term-root-certificate "A certificate belonging to a certificate authority (CA)"
 [root seed]: /en/developer-guide#term-root-seed "A potentially-short value used as a seed to generate a master private key and master chain code for an HD wallet"
 [satoshi]: /en/developer-guide#term-satoshi "The smallest unit of Bitcoin value; 0.00000001 bitcoins.  Also used generically for any value of bitcoins"
@@ -139,7 +140,7 @@
 [stack]: /en/developer-guide#term-stack "An evaluation stack used in Bitcoin's script language"
 [standard script]: /en/developer-guide#standard-transactions "An output script which matches the isStandard() patterns specified in Bitcoin Core---or a transaction containing only standard outputs. Only standard transactions are mined or broadcast by peers running the default Bitcoin Core software"
 [target]: /en/developer-guide#term-target "The threshold below which a block header hash must be in order for the block to be added to the block chain"
-[testnet]: /en/developer-guide#term-testnet "A Bitcoin-like network where the satoshis have no real-world value to allow risk-free testing"
+[testnet]: /en/developer-examples#testnet "A Bitcoin-like network where the satoshis have no real-world value to allow risk-free testing"
 [transaction fee]: /en/developer-guide#term-transaction-fee "The amount remaining when all outputs are subtracted from all inputs in a transaction; the fee is paid to the miner who includes that transaction in a block"
 [transaction fees]: /en/developer-guide#term-transaction-fee "The amount remaining when all outputs are subtracted from all inputs in a transaction; the fee is paid to the miner who includes that transaction in a block"
 [transaction malleability]: /en/developer-guide#transaction-malleability "The ability of an attacker to change the transaction identifier (txid) of unconfirmed transactions, making dependent transactions invalid"
@@ -179,6 +180,7 @@
 [DER]: https://en.wikipedia.org/wiki/Abstract_Syntax_Notation_One
 [devex complex raw transaction]: /en/developer-examples#complex-raw-transaction
 [devex payment protocol]: /en/developer-examples#payment-protocol
+[devexamples]: /en/developer-examples
 [devguide]: /en/developer-guide
 [devguide avoiding key reuse]: /en/developer-guide#avoiding-key-reuse
 [devguide hardened keys]: /en/developer-guide#hardened-keys
@@ -200,7 +202,6 @@
 [prime symbol]: https://en.wikipedia.org/wiki/Prime_%28symbol%29
 [protobuf]: https://developers.google.com/protocol-buffers/
 [raw transaction format]: /en/developer-reference#raw-transaction-format
-[regression test mode]: https://bitcoinj.github.io/testing
 [rpc addmultisigaddress]: /en/developer-reference#addmultisigaddress
 [rpc addnode]: /en/developer-reference#addnode
 [rpc backupwallet]: /en/developer-reference#backupwallet

_plugins/autocrossref.rb

@@ -63,8 +63,8 @@ require 'yaml'
             (?![^\[]*\])  ## No subst if key inside [brackets]
             (?![^\{]*\})  ## No subst if key inside {braces}
             (?![^\s]*<!--noref-->)  ## No subst if <!--noref--> after key
-            (?![\S ]*<\/span>)      ## No subst on a line with a close span. This 
+            (?!((?!<pre>).)*(<\/pre>))  ## No subst on a line with a closing pre tag. This 
-                                    ## prevents matching in highlight blocks
+                                        ## prevents matching in {% highlight %} code blocks.
             (?![^\(]*(\.svg|\.png))  ## No subst if key inside an image name. This 
 		     ## simple regex has the side effect that we can't
 		     ## use .svg or .png in non-image base text; if that

en/developer-examples.md

@@ -22,6 +22,10 @@ title: "Developer Examples - Bitcoin"
 
 {% include fragment_reviews_needed.md %}
 
+{% include example_intro.md %}
+
+{% include example_testing.md %}
+
 {% include example_transactions.md %}
 
 {% include example_payment_processing.md %}

en/developer-reference.md

@@ -22,6 +22,8 @@ title: "Developer Reference - Bitcoin"
 
 {% include fragment_reviews_needed.md %}
 
+{% include ref_intro.md %}
+
 {% include ref_block_chain.md %}
 
 {% include ref_transactions.md %}