From 217ddb0701c2e31b5d6ccbbe712b9e0a74167180 Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Fri, 28 Nov 2014 15:53:23 -0500 Subject: [PATCH 1/4] Dev Docs (Formatting Only): Convert Fake Subheadings To Real Subheadings Converts fake subheadings created using **bold** to real HTML subheadings without adding them to the table of contents. Also fixes a link broken by commit 4e067ac89e74b and adds a Makefile test to catch future similar breakage. --- Makefile | 24 +++++++++++++++++++++++- _includes/guide_transactions.md | 27 ++++++++++++++++++--------- _includes/ref_core_rpcs-opqrst.md | 2 +- _includes/ref_p2p_networking.md | 6 ++++-- _includes/ref_transactions.md | 15 +++++++++++---- _includes/references.md | 4 ++-- 6 files changed, 59 insertions(+), 19 deletions(-) diff --git a/Makefile b/Makefile index e7e8745b..8b7fe4af 100644 --- a/Makefile +++ b/Makefile @@ -38,7 +38,8 @@ pre-build-tests-fast: check-for-non-ascii-urls ## Post-build tests which, aggregated together, take less than 5 seconds to run on a typical PC post-build-tests-fast: check-for-build-errors ensure-each-svg-has-a-png check-for-liquid-errors \ check-for-missing-anchors check-for-broken-markdown-reference-links \ - check-for-broken-kramdown-tables + check-for-broken-kramdown-tables check-for-duplicate-header-ids \ + check-for-headers-with-hrefs ## All pre-build tests, including those which might take multiple minutes pre-build-tests: pre-build-tests-fast @@ -114,3 +115,24 @@ check-for-broken-kramdown-tables: ## paragraph starting with a | (pipe). I can't imagine any reason we'd ## have a regular paragraph starting with a pipe, so error on any occurences. $S grep '

|' _site/en/developer-* | eval $(ERROR_ON_OUTPUT) + + +check-for-duplicate-header-ids: +## When Kramdown automatically creates header id tags, it avoids using +## the same id="" as a previous header by silently appending '-1' to the +## second-occuring header. We want an error when this happens because +## all links which previously pointed to the second-occuring header now +## point to the first-occuring header. (Example: before this test was +## written, links pointing to the ping RPC were silently redirected when +## the P2P ping message was added to the page.) The pattern below will +## report a false positive if we legitimately have an id ending in '-1', +## but that should be easy to work around if it ever happens. + $S grep ']\+id="[^"]\+-1"' _site/en/developer-* | eval $(ERROR_ON_OUTPUT) + +check-for-headers-with-hrefs: +## Subheadings with Kramdown-generated id tags break anchor link +## affordance if their text includes any links (hrefs), so error if any +## links are detectd between and header tags. If we +## ever do need a header with a link, we can revise the pattern below to +## only match Kramdown-generated id tags + $S grep '<\(h[2-6]\).*\?>[^>]\+href=.*' _site/en/developer-* | eval $(ERROR_ON_OUTPUT) diff --git a/_includes/guide_transactions.md b/_includes/guide_transactions.md index 3d8ab975..6208efc4 100644 --- a/_includes/guide_transactions.md +++ b/_includes/guide_transactions.md @@ -320,7 +320,12 @@ backwards-incompatible features. As of Bitcoin Core 0.9, the standard pubkey script types are: -**Pay To Public Key Hash (P2PKH)** +{% endautocrossref %} + +#### Pay To Public Key Hash (P2PKH) +{:.no_toc} + +{% autocrossref %} P2PKH is the most common form of pubkey script used to send a transaction to one or multiple Bitcoin addresses. @@ -332,9 +337,10 @@ Pubkey script: OP_DUP OP_HASH160 OP_EQUALVERIFY OP_CHECKSIG Signature script: ~~~ -{% autocrossref %} +#### Pay To Script Hash (P2SH) +{:.no_toc} -**Pay To Script Hash (P2SH)** +{% autocrossref %} P2SH is used to send a transaction to a script hash. Each of the standard pubkey scripts can be used as a P2SH redeem script, but in practice only the @@ -347,9 +353,10 @@ Pubkey script: OP_HASH160 OP_EQUAL Signature script: [sig] [sig...] ~~~ -{% autocrossref %} +#### Multisig +{:.no_toc} -**Multisig** +{% autocrossref %} Although P2SH multisig is now generally used for multisig transactions, this base script can be used to require multiple signatures before a UTXO can be spent. @@ -389,9 +396,10 @@ Redeem script: OP_CHECKMULTISIG Signature script: OP_0 ~~~ -{% autocrossref %} +#### Pubkey +{:.no_toc} -**Pubkey** +{% autocrossref %} [Pubkey][]{:#term-pubkey}{:.term} scripts are a simplified form of the P2PKH pubkey script, but they aren’t as @@ -405,9 +413,10 @@ Pubkey script: OP_CHECKSIG Signature script: ~~~ -{% autocrossref %} +#### Null Data +{:.no_toc} -**Null Data** +{% autocrossref %} [Null data][]{:#term-null-data}{:.term} pubkey scripts let you add a small amount of arbitrary data to the block chain in exchange for paying a transaction fee, but doing so is discouraged. diff --git a/_includes/ref_core_rpcs-opqrst.md b/_includes/ref_core_rpcs-opqrst.md index 541e7cd1..fd10cb09 100644 --- a/_includes/ref_core_rpcs-opqrst.md +++ b/_includes/ref_core_rpcs-opqrst.md @@ -3,7 +3,7 @@ This file is licensed under the MIT License (MIT) available on http://opensource.org/licenses/MIT. {% endcomment %} -#### ping +#### ping {#ping-rpc} ~~~ ping diff --git a/_includes/ref_p2p_networking.md b/_includes/ref_p2p_networking.md index f8e2a584..7bef004d 100644 --- a/_includes/ref_p2p_networking.md +++ b/_includes/ref_p2p_networking.md @@ -412,7 +412,8 @@ traffic dump this output was taken from, the full transaction belonging to that TXID was sent immediately after the `merkleblock` message as a `tx` message. -**Parsing A MerkleBlock** +##### Parsing A MerkleBlock Message +{:.no_toc} As seen in the annotated hexdump above, the `merkleblock` message provides three special data types: a transaction count, a list of @@ -483,7 +484,8 @@ For a detailed example of parsing a `merkleblock` message, please see the corresponding [merkle block examples section][section merkleblock example]. -**Creating A MerkleBlock** +##### Creating A MerkleBlock Message +{:.no_toc} It's easier to understand how to create a `merkleblock` message after you understand how to parse an already-created message, so we recommend diff --git a/_includes/ref_transactions.md b/_includes/ref_transactions.md index 7d2ce568..13933c43 100644 --- a/_includes/ref_transactions.md +++ b/_includes/ref_transactions.md @@ -228,7 +228,8 @@ the [CompactSize section][CompactSize unsigned integer]. {% endautocrossref %} -**TxIn: A Transaction Input (Non-Coinbase)** +##### TxIn: A Transaction Input (Non-Coinbase) {#txin} +{:.no_toc} {% autocrossref %} @@ -244,7 +245,8 @@ Each non-coinbase input spends an outpoint from a previous transaction. {% endautocrossref %} -**[Outpoint][]{:#term-outpoint}{:.term}: The Specific Part Of A Specific Output** +##### Outpoint: The Specific Part Of A Specific Output {#outpoint} +{:.no_toc} {% autocrossref %} @@ -259,7 +261,8 @@ specific output. {% endautocrossref %} -**TxOut: A Transaction Output** +##### TxOut: A Transaction Output {#txout} +{:.no_toc} {% autocrossref %} @@ -313,8 +316,12 @@ to a new pay-to-pubkey-hash (P2PKH) output. 00000000 ................................... locktime: 0 (a block height) {% endhighlight %} +{% endautocrossref %} -**Coinbase Input: The Input Of The First Transaction In A Block** +##### Coinbase Input: The Input Of The First Transaction In A Block {#coinbase} +{:.no_toc} + +{% autocrossref %} The first transaction in a block, called the coinbase transaction, must have exactly one input, called a coinbase. The coinbase input currently diff --git a/_includes/references.md b/_includes/references.md index 2e633f62..47e2f9d5 100644 --- a/_includes/references.md +++ b/_includes/references.md @@ -112,7 +112,7 @@ http://opensource.org/licenses/MIT. [op_hash160]: /en/developer-reference#term-op-hash160 "Operation which converts the entry below it on the stack into a RIPEMD(SHA256()) hashed version of itself" [op_return]: /en/developer-reference#term-op-return "Operation which terminates the script in failure" [op_verify]: /en/developer-reference#term-op-verify "Operation which terminates the script if the entry below it on the stack is non-true (zero)" -[outpoint]: /en/developer-reference#term-outpoint "The structure used to refer to a particular transaction output, consisting of a 32-byte TXID and a 4-byte output index number (vout)." +[outpoint]: /en/developer-reference#outpoint "The structure used to refer to a particular transaction output, consisting of a 32-byte TXID and a 4-byte output index number (vout)." [output]: /en/developer-guide#term-output "The output of a transaction which transfers value to a pubkey script" [output index]: /en/developer-guide#term-output-index "The sequentially-numbered index of outputs in a single transaction starting from 0" [P2PKH]: /en/developer-guide#term-p2pkh "A pubkey script which Pays To PubKey Hashes (P2PKH), allowing spending of satoshis to anyone with a Bitcoin address" @@ -258,7 +258,7 @@ http://opensource.org/licenses/MIT. [rpc listunspent]: /en/developer-reference#listunspent [rpc lockunspent]: /en/developer-reference#lockunspent [rpc move]: /en/developer-reference#move -[rpc ping]: /en/developer-reference#ping +[rpc ping]: /en/developer-reference#ping-rpc [rpc sendfrom]: /en/developer-reference#sendfrom [rpc sendmany]: /en/developer-reference#sendmany [rpc sendrawtransaction]: /en/developer-reference#sendrawtransaction From 1652bc6edaf8767cba2ec67eac614f6eb277d03a Mon Sep 17 00:00:00 2001 From: Saivann Date: Fri, 28 Nov 2014 20:06:12 -0500 Subject: [PATCH 2/4] Ignore .no_toc titles when selecting active toc entry --- js/main.js | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/js/main.js b/js/main.js index 84c33f78..92a81e9a 100644 --- a/js/main.js +++ b/js/main.js @@ -319,11 +319,14 @@ var setenv = function() { first = [fallback, getTop(fallback)]; last = [fallback, getTop(fallback)]; closer = [fallback, getTop(fallback)]; - // Find all titles. + // Find all titles in toc. var nodes = []; var tags = ['H2', 'H3', 'H4', 'H5', 'H6']; for (var i = 0, n = tags.length; i < n; i++) { - for (var ii = 0, t = document.getElementsByTagName(tags[i]), nn = t.length; ii < nn; ii++) nodes.push(t[ii]); + for (var ii = 0, t = document.getElementsByTagName(tags[i]), nn = t.length; ii < nn; ii++) { + if (t[ii].className.indexOf('no_toc')!==-1) continue; + nodes.push(t[ii]); + } } // Find first title, last title and closer title. for (var i = 0, n = nodes.length; i < n; i++) { From a9d2e73c1a249bc3e62886ff85f5c32decc43573 Mon Sep 17 00:00:00 2001 From: Saivann Date: Fri, 28 Nov 2014 20:38:27 -0500 Subject: [PATCH 3/4] Allow links in anchor affordance titles --- Makefile | 8 -------- _less/screen.less | 4 ++-- js/main.js | 2 +- 3 files changed, 3 insertions(+), 11 deletions(-) diff --git a/Makefile b/Makefile index 8b7fe4af..a53a898e 100644 --- a/Makefile +++ b/Makefile @@ -128,11 +128,3 @@ check-for-duplicate-header-ids: ## report a false positive if we legitimately have an id ending in '-1', ## but that should be easy to work around if it ever happens. $S grep ']\+id="[^"]\+-1"' _site/en/developer-* | eval $(ERROR_ON_OUTPUT) - -check-for-headers-with-hrefs: -## Subheadings with Kramdown-generated id tags break anchor link -## affordance if their text includes any links (hrefs), so error if any -## links are detectd between and header tags. If we -## ever do need a header with a link, we can revise the pattern below to -## only match Kramdown-generated id tags - $S grep '<\(h[2-6]\).*\?>[^>]\+href=.*' _site/en/developer-* | eval $(ERROR_ON_OUTPUT) diff --git a/_less/screen.less b/_less/screen.less index 76b68260..6f015877 100644 --- a/_less/screen.less +++ b/_less/screen.less @@ -833,7 +833,7 @@ table td,table th{ .anchorAf{ position:relative; } -.anchorAf a{ +.anchorAf a:first-child{ display:none; position:absolute; width:24px; @@ -842,7 +842,7 @@ table td,table th{ top:0; background:url(/img/icons/mini_ico_anchor.svg) no-repeat center center; } -.anchorAf:hover a{ +.anchorAf:hover a:first-child{ display:block; } diff --git a/js/main.js b/js/main.js index 84c33f78..66ad9d96 100644 --- a/js/main.js +++ b/js/main.js @@ -408,7 +408,7 @@ for (var i = 0, n = tags.length; i < n; i++) { } for (var i = 0, n = nodes.length; i < n; i++) { if (!nodes[i].id) continue; - if (nodes[i].getElementsByTagName('A').length > 0) return; + if (nodes[i].getElementsByTagName('A').length > 0 && nodes[i].getElementsByTagName('A')[0].innerHTML == '') return; addClass(nodes[i], 'anchorAf'); var anc = document.createElement('A'); anc.href = '#' + nodes[i].id; From 37c4295fb662ce637475b937d9b3f254cceda7ee Mon Sep 17 00:00:00 2001 From: "David A. Harding" Date: Fri, 28 Nov 2014 21:29:40 -0500 Subject: [PATCH 4/4] Dev Docs: Revise Makefile Test To Check For Auto Links In Subheadings --- Makefile | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/Makefile b/Makefile index a53a898e..ff8bf1c3 100644 --- a/Makefile +++ b/Makefile @@ -39,7 +39,7 @@ pre-build-tests-fast: check-for-non-ascii-urls post-build-tests-fast: check-for-build-errors ensure-each-svg-has-a-png check-for-liquid-errors \ check-for-missing-anchors check-for-broken-markdown-reference-links \ check-for-broken-kramdown-tables check-for-duplicate-header-ids \ - check-for-headers-with-hrefs + check-for-headers-containing-auto-link ## All pre-build tests, including those which might take multiple minutes pre-build-tests: pre-build-tests-fast @@ -128,3 +128,9 @@ check-for-duplicate-header-ids: ## report a false positive if we legitimately have an id ending in '-1', ## but that should be easy to work around if it ever happens. $S grep ']\+id="[^"]\+-1"' _site/en/developer-* | eval $(ERROR_ON_OUTPUT) + +check-for-headers-containing-auto-link: +## The autocrossref plugin can mess up subheadings (h2, etc), so ensure +## none of the generated subheadings contain the string +## 'class="auto-link"' produced by autocrossref + $S grep '<\(h[2-6]\).*\?>[^>]\+class="auto-link".*' _site/en/developer-* | eval $(ERROR_ON_OUTPUT)