saivann/bitcoin.org — pull request #74 by harding (2014-04-19 04:31:13+00:00)
Title: Split Up Big Payment Protocol Code Blocks

Split Up Big Payment Protocol Code Blocks

Preview:

Four big code blocks in the payment protocol section have been split up into many smaller blocks, with almost all of the comments being converted into regular paragraph text. This provides several usability improvements:

* In highlighted code blocks, comments were dark grey text on light grey background---which is fine for an occassional comment but less than ideal for reading big blocks of comments.

* Code comments couldn't contain anchors (id tags), so when a comment defined a term, we had to link to the top of the code block.

* Code comments couldn't be autocrossreferenced, making them less useful than text in the rest of the document.

* To keep code comments short(ish), I explained the details below the code blocks, which lead to (1) important information not being available to the reader when needed most and (2) redundant information being provided in both the code and details parts.

Splitting it up does have one small usability disadvantage: it's harder for someone to copy-and-paste the code to get a working Python program. I tried putting a copy of the CGI code below the explaination but it seemed gratuitous, so I pulled it back out. Besides, people shouldn't be using that code as-is.

Specific changes include:

* Adding subsections (h6) for each of the previous four code blocks.

* Within each subsection, dividing up each logical unit of the program code by prefixing it with a HTML break (br) tag. I initially tried using a list, but Markdown lists didn't play well with the Liquid syntax highlighting tag.

* Interweaving the descriptions which followed each code block into the paragraphs created from the old code comments. Redundant information was deleted.

* Changed a few occurances of [CGI] "script" to "program" to avoid autocrossrefs.

* Changed one line of code to be less wide than the pre box so the left-right slider doesn't appear. This required changing a variable name, so the corresponding lines of code were changed.

To me, the result seems much easier to read.